Docker 部署

适合快速体验。直接拉取官方镜像,一条命令拉起整套服务。

1. 前置条件

组件	最低版本	说明
Docker	20.10+	容器引擎
Docker Compose	v2.0+	多容器编排(docker compose 子命令)
可用内存	≥ 4GB	服务较多,内存太小可能起不来
可用磁盘	≥ 10GB	镜像 + 数据卷

检查环境:

docker --version
docker compose version

2. 一键启动

源码仓库:

• Gitee(推荐):https://gitee.com/shop-sparker/spark-x
• GitHub(国外镜像):https://github.com/nick-bai/SparkX

# Gitee(国内访问更快)
git clone https://gitee.com/shop-sparker/spark-x.git
cd spark-x/docker

# 或 GitHub(国外)
git clone https://github.com/nick-bai/SparkX.git
cd SparkX/docker

docker compose up -d

执行后,Docker 会自动拉取镜像并启动以下服务:

服务	说明	默认端口
sparkx-server	后端(Spring Boot)	8189
sparkx-web	前端(Nginx 托管)	8189(经 Nginx)
postgres	数据库(带 vector 扩展)	5432
redis	缓存 / 分布式锁	6379
minio	对象存储	9000 / 9001

3. 查看启动状态

docker compose ps

看到所有容器 STATUS 为 Up 即表示启动成功。后端首次启动需要初始化数据库,稍等约 30 秒。

4. 访问系统

浏览器打开:

http://localhost:8189

默认账号:

项	值
账号	admin
密码	123456

5. 常用运维命令

docker compose logs -f sparkx-server   # 查看后端实时日志
docker compose restart sparkx-server   # 重启后端
docker compose down                    # 停止并移除所有容器
docker compose pull && docker compose up -d   # 升级到最新镜像

6. 数据持久化

数据保存在 Docker 数据卷中,不会因为 docker compose down 丢失:

卷	作用
sparkx_postgres	数据库文件
sparkx_redis	Redis 持久化
sparkx_minio	MinIO 对象存储

⚠️ 如需彻底清空数据,需显式删除数据卷:docker compose down -v

7. 常见问题

7.1 端口被占用

修改 docker/.env 或 docker-compose.yml 中的端口映射,例如把 8189:80 改成 8190:80。

7.2 后端启动失败

docker compose logs sparkx-server   # 查看具体报错

最常见原因是数据库未就绪就连接,后端有重试机制,通常会自动恢复。

7.3 拉取镜像超时

国内网络可配置镜像加速器,编辑 /etc/docker/daemon.json:

{
  "registry-mirrors": ["https://docker.1ms.run"]
}

修改后重启 Docker:systemctl restart docker。

---

部署完成后,前往 完成第一个智能体 开始使用。