多节点部署指南

操作系统：Windows 10、11、Server 2022，Ubuntu 22.04、24.04，RHEL 9、Rocky 9、Debian 12 ✅
软件要求：Docker、MySQL、npm、Git
信创操作系统：银河麒麟高级服务器 V10 SP3、openEuler 22.03 LTS SP4 ✅
其他未经验证的系统无法安装运行 OpenPartner。

📌 部署流程总览

多节点 = 一台主节点（网页 + 后台 + 数据库）+ 若干添加节点（只跑智能体，连主节点的数据库）。

步骤	做什么
第 1 步	服务器要求（规格与前置依赖）
第 2 步	部署主节点（直接按《快速单机部署指南》）
第 3 步	新节点准备环境（Docker、Node、Git，无需本地 MySQL）
第 4 步	新节点安装程序（NPM 或官方下载手动安装，二选一）
第 5 步	新节点初始化（连主节点数据库）
第 6 步	主节点更新前端路由（把新节点登记进网页）
第 7 步	新节点启动 → 主节点「节点管理」确认在线

⚠️ 主节点需放行 TCP 3306（供新节点连 MySQL）；所有节点之间内网互通（TCP 3306 / 3001 / 9620）。

📌 部署流程总览
第 1 步 · 服务器要求
第 2 步 · 部署主节点
第 3 步 · 新节点准备环境
第 4 步 · 新节点安装程序
第 5 步 · 新节点初始化
第 6 步 · 主节点更新前端路由
第 7 步 · 启动与确认在线
常用命令
附录 A · JSON 配置参数目录
附录 B · JSON 示例
附录 C · 配置文件位置
附录 D · 常见问题

第 1 步 · 服务器要求

服务器规格

资源	最低	推荐
CPU	4 核	8 核+
内存	8 GB	16 GB+
磁盘	100 GB	500 GB+（用户文件占大头）
网络	1 Gbps 内网	1 Gbps 内网

通用前置

依赖	最低版本	说明
Docker	≥ 20.10	Windows 用 Docker Desktop，Linux 用 Docker Engine
Node.js / npm	≥ 18	仅 NPM 安装方式需要
MySQL	≥ 8.0	只需主节点安装；添加节点连主节点库
Git	最新版	技能脚本编辑

信创环境（银河麒麟高级服务器 V10 SP3、openEuler 22.03 LTS SP4）已支持的版本组合，见《快速单机部署指南》。

第 2 步 · 部署主节点

请直接按《快速单机部署指南》完成主节点部署。

第 3 步 · 新节点准备环境

Windows

权限说明：命令统一使用管理员 PowerShell 执行。

添加节点需要 Docker、Node.js / npm（仅 NPM 安装需要）、Git，无需本地 MySQL（数据库用主节点的）。

安装 Docker、Node.js（npm）、Git：步骤见《快速单机部署指南》第 1 步；
验证环境：

powershell

docker --version    # 应显示版本号
node --version      # 应显示 ≥ 18（仅 NPM 安装需要）
npm --version       # 应显示版本号（仅 NPM 安装需要）
git --version       # 应显示版本号

Linux

普通用户部署前，先由管理员按《快速单机部署指南》第 1 步完成目录授权并加入 docker 组，重新登录后再操作。添加节点的安装、初始化和启动全程在同一终端执行；主节点上的操作除外。

添加节点需要 Docker、Node.js / npm（仅 NPM 安装需要）、Git，无需本地 MySQL。

安装 Docker、Node.js（npm）、Git：步骤见《快速单机部署指南》第 1 步；
验证环境：

bash

docker --version    # 应显示 ≥ 20.10
node --version      # 应显示 ≥ 18（仅 NPM 安装需要）
npm --version       # 应显示版本号（仅 NPM 安装需要）
git --version       # 应显示版本号

第 4 步 · 新节点安装程序（二选一）

方式一：NPM 一条命令

Windows（管理员 PowerShell）：

powershell

npm i -g @sogood360/openpartner@beta

Linux：

bash

npm i -g @sogood360/openpartner@beta

普通用户：按《快速单机部署指南》第 2 步的普通用户安装说明操作。

方式二：官方下载手动安装（内网 / 离线）

打开下载页 https://openpartner.sogood360.com/download.html；找到官方下载手动安装，下载对应平台的压缩包： Windows：openpartner-windows-setup.zip Linux：openpartner-linux-setup.zip

解压后进入解压目录，执行包内安装脚本（Windows：install-windows.ps1，Linux：install-linux.sh；命令见《快速单机部署指南》第 2 步方式二）。

✅ 确认：openpartner version 显示版本号。

第 5 步 · 新节点初始化（无人值守）

Windows

无人值守方式：把参数写进配置表 params.json，命令自动执行。

⚠️❗ 【必做】动手前先阅读【附录 A · JSON 配置参数目录】，了解每个参数的含义再填写。

powershell

$params = @{
  server   = @{ port = <后端端口> }
  frontend = @{ port = <网页端口> }
  database = @{ host = "<主节点所连数据库的IP>"; port = <数据库端口>; user = "<数据库账号>"; password = "<主节点所连数据库密码>"; name = "<库名>" }
  workspace = @{ root = "<工作目录>" }
  images   = @{ frontend = "" }
  secrets  = @{ jwt_secret = ""; encryption_key = ""; encryption_salt = ""; internal_token = "" }
  admin    = @{ password = "<admin密码>" }
  cell     = @{ id = "<添加节点ID>"; name = "<添加节点ID>"; cell_url = "http://<本机IP>:<后端端口>" }
  mode     = "auto"
  container_api_url = ""
  public_base_url = "http://<主节点IP>:<主节点网页端口>"
  actions  = @{ pull_images = $true; create_frontend_container = $false; register_autostart = $true; reset_db = $false }
}
[System.IO.File]::WriteAllText((Join-Path $PWD "params.json"), ($params | ConvertTo-Json -Depth 10), (New-Object System.Text.UTF8Encoding($false)))

<添加节点ID> = 新节点代号（cell_<short_id>，如 cell_b），不能与已有节点重名。
mode 填 auto（自动检测）：cells 表已有主节点记录时会自动按子节点初始化，主/子节点可用同一份参数。

执行：

powershell

openpartner init --from-json params.json

✅ 确认：出现「OpenPartner 初始化完成」。

初始化后人工比对本地 config.yaml 的密钥（jwt.secret、encryption.key、encryption.salt）与主节点是否一致。

Linux

无人值守方式：把参数写进配置表 params.json，命令自动执行。

⚠️❗ 【必做】动手前先阅读【附录 A · JSON 配置参数目录】，了解每个参数的含义再填写。

bash

sudo mkdir -p /var/lib/openpartner/workspace /var/log/openpartner /tmp/ocw
sudo chown $USER:$USER /var/lib/openpartner/workspace /var/log/openpartner

cat > /tmp/ocw/params.json <<EOF
{
  "server": { "port": <后端端口> },
  "frontend": { "port": <网页端口> },
  "database": { "host": "<主节点所连数据库的IP>", "port": <数据库端口>, "user": "<数据库账号>", "password": "<主节点所连数据库密码>", "name": "<库名>" },
  "workspace": { "root": "<工作目录>" },
  "images": { "frontend": "" },
  "secrets": { "jwt_secret": "", "encryption_key": "", "encryption_salt": "", "internal_token": "" },
  "admin": { "password": "<admin密码>" },
  "cell": { "id": "<添加节点ID>", "name": "<添加节点ID>", "cell_url": "http://<本机IP>:<后端端口>" },
  "mode": "auto",
  "container_api_url": "",
  "public_base_url": "http://<主节点IP>:<主节点网页端口>",
  "actions": { "pull_images": true, "create_frontend_container": false, "register_autostart": true, "reset_db": false }
}
EOF

⚠️ <添加节点ID> = 新节点代号（cell_<short_id>，如 cell_b），不能与已有节点重名。
⚠️ 普通用户：跳过两条 sudo mkdir / sudo chown；路径 cat > /tmp/ocw/params.json 改为 cat > "$HOME/ocw/params.json"；workspace.root 改为 $HOME/openpartner/workspace；register_autostart 改为 false。

执行：

bash

openpartner init --from-json /tmp/ocw/params.json

✅ 确认：出现「OpenPartner 初始化完成」。

初始化后人工比对本地 config.yaml 的密钥（jwt.secret、encryption.key、encryption.salt）与主节点是否一致，并修正 backend_url 为 docker0 网关：

bash

ip addr show docker0 | grep inet          # 通常 172.17.0.1
sudo sed -i "s#^\(\s*backend_url:\s*\).*#\1http://172.17.0.1:<后端端口>#" /etc/openpartner/config.yaml

第 6 步 · 主节点更新前端路由（在主节点上做）

这一步把新节点登记进主节点的网页（CELL_ROUTES 地址簿）。

先确认新节点已写入主节点数据库：

bash

mysql -h'<主节点所连数据库的IP>' -uroot -p'<主节点所连数据库密码>' openpartner -e "SELECT id,name,cell_url FROM cells WHERE id='<添加节点ID>';"

主节点是 Windows

然后在主节点终端更新前端路由（一条一条粘贴，别整段贴）：

powershell

$existing = (docker inspect openpartner_frontend --format '{{range .Config.Env}}{{println .}}{{end}}' | Select-String CELL_ROUTES).Line -replace '^CELL_ROUTES=',''
docker stop openpartner_frontend
docker rm openpartner_frontend
docker run -d --name openpartner_frontend --restart unless-stopped -p <网页端口>:<网页端口> -e "CELL_ROUTES=$existing,<添加节点ID>=<新增节点IP>:<后端端口>" sogood360/openpartner-frontend:<当前已装版本>

<网页端口> = 主节点网页端口（默认 9620）；<后端端口> = 新节点后端 API 端口（默认 3001）。
若 $existing 为空（第一个节点），CELL_ROUTES 直接写 <添加节点ID>=<新增节点IP>:<后端端口>，不要留前导逗号。
<当前已装版本>：主节点执行 docker images | grep frontend 看到的版本号。

✅ 确认：主节点网页还能正常打开。

主节点是 Linux

然后在主节点终端更新前端路由（一条一条粘贴）：

bash

EXISTING=$(docker inspect openpartner_frontend --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^CELL_ROUTES=' | cut -d= -f2-)
docker stop openpartner_frontend && docker rm openpartner_frontend
docker run -d --name openpartner_frontend --restart unless-stopped -p <网页端口>:<网页端口> -e "CELL_ROUTES=$EXISTING,<添加节点ID>=<新增节点IP>:<后端端口>" sogood360/openpartner-frontend:<当前已装版本>

主节点是 Windows 时，改用上方「主节点是 Windows」的 PowerShell 命令。
若 $EXISTING 为空（第一个节点），CELL_ROUTES 直接写 <添加节点ID>=<新增节点IP>:<后端端口>，不要留前导逗号。

✅ 确认：主节点网页还能正常打开。

第 7 步 · 启动与确认在线

Windows

回到新节点机器：

powershell

openpartner start
# 验证（预期：200）
(Invoke-WebRequest "http://127.0.0.1:3001/api/health" -UseBasicParsing -TimeoutSec 5).StatusCode
# 放行本节点端口
New-NetFirewallRule -DisplayName "OpenPartner-Agent-3001" -Direction Inbound -Protocol TCP -LocalPort 3001 -Action Allow -Profile Any

登录主节点后台 → 节点管理，新节点状态「在线」= 完成 ✅

Linux

回到新节点机器：

bash

openpartner start
curl -s --max-time 10 http://127.0.0.1:3001/api/health   # 预期：{"status":"ok",...}
sudo ufw allow 3001/tcp   # 放行本节点端口

普通用户：直接执行 openpartner start。sudo ufw 由管理员执行。

登录主节点后台 → 节点管理，新节点状态「在线」= 完成 ✅

常用命令

bash

openpartner start     # 启动
openpartner stop      # 停止
openpartner status    # 查看运行状态
openpartner version   # 查看版本号
openpartner upgrade   # 升级
openpartner help      # 查看帮助

如需升级 OpenPartner，请转看《升级文档》。

附录 A · JSON 配置参数目录

本附录只列添加节点（secondary）的参数；主节点参数见《快速单机部署指南》附录 A。

区块	键	默认	说明
`server`	`port`	`3001`	本节点后端 API 端口。改它会影响 `cell_url` 和防火墙放行，通常保持默认
`frontend`	`port`	`9620`	网页端口。添加节点不创建前端容器，保持默认即可
`docker`	`host`	留空（Windows `npipe:////./pipe/docker_engine`；Linux `unix:///var/run/docker.sock`）	Docker 连接方式，本机部署留空即可
	`tls`	`null`（本机留空）	远程 Docker 守护进程才需要（ca / cert / key 证书）
`database`	`host`	无（必填，如 `10.10.6.132`）	⚠️ 主节点所连数据库的 IP（添加节点连的是主节点所连的库，不能填本机地址）
	`port`	`3306`	数据库端口
	`user`	`root`	数据库账号，需有建库、建表和读写权限
	`password`	无（必填，替换为真实值）	⚠️ 主节点所连数据库的密码；填错会报 Access denied
	`name`	`openpartner`	库名，必须与主节点一致（不要改）
`workspace`	`root`	Windows `D:\openpartner\workspace`；Linux `/var/lib/openpartner/workspace`	本节点工作空间根目录（存放分配到本节点的用户工作区）。普通用户用 `$HOME/openpartner/workspace`
`images`	`frontend`	`""`（固定留空）	添加节点只跑 agent 镜像，不装前端
	`agent`	与主节点一致（如 `sogood360/openpartner-agent:1.5.10`）	agent 镜像。填具体版本号可锁版本
`secrets`	`jwt_secret` 等	留空自动生成	登录 token 签名、数据加密等密钥。留空 = 自动生成；初始化后人工比对本地 config.yaml 与主节点是否一致，勿手动改
`admin`	`password`	无（必填，示例 `admin123456`）	管理员初始密码（至少 6 位，可更改）
`cell`	`id`	无（必填，如 `cell_b`）	⚠️ 新节点唯一标识（`cell_<short_id>`，如 `cell_b`、`cell_t2`），不能与系统其它节点重名
	`name`	同 `id`	节点显示名
	`cell_url`	无（必填，如 `http://10.10.6.152:3001`）	本节点对外可达地址。用真实 IP，不能用 `127.0.0.1`
	`region`	`""`（可选）	机房标识（如 `beijing` / `shanghai`）
	`zone`	`""`（可选）	区域标识（如 `zone-a` / `zone-b`）
`container_api_url`	—	留空自动（Windows `http://host.docker.internal:3001`；Linux `http://172.17.0.1:3001`）	用户容器（智能体）访问后端的地址，留空自动推算
`public_base_url`	—	填写（如 `http://<主节点IP>:9620`）	浏览器访问地址 = 主节点前端地址。建议显式填写
`primary_public_url`	—	留空（推荐填 `http://<主节点IP>:9620`）	主节点前端地址，用于跨节点 WebSocket 白名单，填写后跨节点访问更全
`mode`	—	`auto`	填 `auto`（自动检测：cells 表已有主节点记录时自动判定为 secondary）；也可显式填 `secondary`
`update`	`server_url`	`https://openpartner.sogood360.com/update`	更新源地址（1.5.8 起）。自建升级服务器时填其地址（如 `http://<服务器IP>:3101`）
	`auto_check`	`true`	是否自动检查更新
`actions`	`pull_images`	`true`	初始化时自动拉取镜像（tag 与安装版本一致）；离线环境已手动加载镜像时可填 `false`
	`create_frontend_container`	`false`	固定：不创建前端容器（前端只在主节点）
	`register_autostart`	`true`	是否注册开机自启。普通用户部署填 `false`
	`skip_pull`	`false`	跳过拉取镜像（等价于 `pull_images=false`）；本地已有镜像时用
	`reset_db`	`false`	固定：不重建数据库（连的是主节点的库，绝不能设 true，否则会清掉主节点数据）。1.5.9 另有等效 CLI 参数 `--reset-db`，同样严禁使用

附录 B · JSON 示例

json

{
  "mode": "secondary",
  "server": { "port": 3001 },
  "frontend": { "port": 9620 },
  "database": { "host": "<主节点所连数据库的IP>", "port": 3306, "user": "root", "password": "<主节点所连数据库密码>", "name": "openpartner" },
  "workspace": { "root": "/var/lib/openpartner/workspace" },
  "images": { "frontend": "" },
  "secrets": { "jwt_secret": "", "encryption_key": "", "encryption_salt": "", "internal_token": "" },
  "admin": { "password": "admin123456" },
  "cell": { "id": "<添加节点ID>", "name": "<添加节点ID>", "cell_url": "http://<本机IP>:3001", "region": "", "zone": "" },
  "container_api_url": "",
  "public_base_url": "",
  "actions": { "pull_images": true, "create_frontend_container": false, "register_autostart": true, "reset_db": false }
}

附录 C · 配置文件位置

平台	路径
Windows	`C:\ProgramData\openpartner\config.yaml`
Linux	`/etc/openpartner/config.yaml`

附录 D · 常见问题

部署类常见问题（TTY 退出、数据库连接、镜像拉取、端口冲突、命令找不到、忘记密码等）见《快速单机部署指南》附录 D；以下只列添加节点相关的问题。

Q：新节点加完，但「节点管理」里看不到？

检查新节点能否连接主节点所连数据库（mysql -h <主节点所连数据库的IP> -uroot -p）；
检查 jwt.secret 是否同步（主节点改 secret 后要等 60s 缓存过期，或手动重启所有节点）；
看新节点后端日志：openpartner logs 或 journalctl -u openpartner -n 100。

Q：用户登录后反复跳转？

确认 MySQL 里 users.cell_id 已正确设置（前端按节点归属路由）；
按 F12 打开浏览器开发者工具 → Network（网络），看登录请求返回的 cell_redirect 里的 cell_url 字段。

Q：一个节点故障了，其他节点还能用吗？

能——故障节点上的用户访问会失败，但其他节点不受影响；
修复故障节点后，用户重新登录即可。

多节点部署指南 ​

📌 部署流程总览 ​

目录 ​

第 1 步 · 服务器要求 ​

服务器规格 ​

通用前置 ​

第 2 步 · 部署主节点 ​

第 3 步 · 新节点准备环境 ​

Windows ​

Linux ​

第 4 步 · 新节点安装程序（二选一） ​

方式一：NPM 一条命令 ​

方式二：官方下载手动安装（内网 / 离线） ​

第 5 步 · 新节点初始化（无人值守） ​

Windows ​

Linux ​

第 6 步 · 主节点更新前端路由（在主节点上做） ​

主节点是 Windows ​

主节点是 Linux ​

第 7 步 · 启动与确认在线 ​

Windows ​

Linux ​

常用命令 ​

附录 A · JSON 配置参数目录 ​

附录 B · JSON 示例 ​

附录 C · 配置文件位置 ​

附录 D · 常见问题 ​

多节点部署指南

📌 部署流程总览

目录

第 1 步 · 服务器要求

服务器规格

通用前置

第 2 步 · 部署主节点

第 3 步 · 新节点准备环境

Windows

Linux

第 4 步 · 新节点安装程序（二选一）

方式一：NPM 一条命令

方式二：官方下载手动安装（内网 / 离线）

第 5 步 · 新节点初始化（无人值守）

Windows

Linux

第 6 步 · 主节点更新前端路由（在主节点上做）

主节点是 Windows

主节点是 Linux

第 7 步 · 启动与确认在线

Windows

Linux

常用命令

附录 A · JSON 配置参数目录

附录 B · JSON 示例

附录 C · 配置文件位置

附录 D · 常见问题