Docker 本地部署

适合需要二次开发或定制镜像的场景。在本地从源码构建镜像后启动。

1. 适用场景

• 需要修改源码并验证效果
• 内网环境无法拉取官方镜像
• 想要自定义镜像(增减依赖、改配置)

2. 前置条件

除了 Docker 部署 中的 Docker 环境外,本地构建还需要:

组件	版本	用途
JDK	17	编译后端
Maven	3.8+	后端依赖管理
Node.js	v22.17.0(建议)	编译前端
NPM	10.9.2(建议)	前端依赖管理
Git	任意	拉取源码

💡 本地构建镜像本质上是用 Docker 执行构建过程,JDK/Node 等只用于本地调试或验证;若完全交给 Docker 构建,本机可只装 Docker。

3. 拉取源码

源码仓库:

• 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

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

4. 准备构建产物

4.1 后端打包

cd server
mvn clean package -DskipTests
cd ..

打包完成后会在 server/target/ 下生成 sparkx-server.jar(或类似名称)。

4.2 前端打包

cd admin
npm install
npm run build
cd ..

产物输出到 admin/dist/。

💡 如果想完全跳过本地构建,直接用仓库提供的 Dockerfile(内部已封装构建步骤),可省略本节,直接进入下一步。

5. 本地构建镜像

仓库的 docker/ 目录下提供了 Dockerfile,在仓库根目录执行:
1、将 构建出来的 spark-server.jar 放到 docker下的 backend 目录下 2、将 前端构建出来 dist 放到 docker 下的 front 目录下 config.js 可以单独修改admin访问的地址

6. 启动服务

cd docker
docker compose -f docker-compose-local.yml up -d

启动的服务与 Docker 部署 完全一致(postgres / redis / minio / server / web),只是 server 和 web 镜像来自上一步本地构建的结果。

7. 访问

http://localhost:8189

账号 admin / 密码 123456。

8. 修改代码后的更新流程

本地部署的镜像是基于 docker/ 目录下的构建产物(jar / dist)打包的,所以改完代码后,需要重新打包并替换对应产物,再重建重启。

8.1 改后端代码

# 1. 重新打包后端
cd server
mvn clean package -DskipTests

# 2. 用新的 jar 替换 docker/backend 下的旧产物
cp target/sparkx-server.jar ../docker/backend/

# 3. 回到 docker 目录,重建并重启 server
cd ../docker
docker compose -f docker-compose-local.yml up -d --build sparkx-server

服务名 sparkx-server 以 docker-compose-local.yml 中实际定义为准,下同。

8.2 改前端代码

# 1. 重新构建前端
cd admin
npm run build

# 2. 用新的 dist 替换 docker/front 下的旧产物
rm -rf ../docker/front/dist
cp -r dist ../docker/front/

# 3. 回到 docker 目录,重建并重启 web
cd ../docker
docker compose -f docker-compose-local.yml up -d --build sparkx-web

9. 自定义配置

如需修改端口、数据库密码等,编辑 docker/docker-compose-local.yml 或 docker/.env(若存在),常用配置项:

配置	位置	示例
对外端口	docker-compose-local.yml 的 ports	8189:80
数据库密码	docker-compose-local.yml 环境变量	POSTGRES_PASSWORD
MinIO 凭证	docker-compose-local.yml 环境变量	MINIO_ROOT_USER

修改后需要 docker compose -f docker-compose-local.yml down && docker compose -f docker-compose-local.yml up -d 才生效。

10. 常见问题

10.1 Maven 下载依赖极慢

为 Maven 配置国内镜像(如阿里云),编辑 ~/.m2/settings.xml 加入 <mirrors> 配置。

10.2 npm install 慢或失败

npm config set registry https://registry.npmmirror.com

10.3 构建报内存不足

为 Docker 分配更多资源(Docker Desktop:Settings → Resources,内存调到 6GB 以上)。

---

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