升级文档

前置条件：

1. OpenPartner 已部署完成（单机见《快速单机部署指南》，多节点见《多节点部署指南》），并能登录管理后台；
2. 网络：方案一需能访问更新源（默认 https://openpartner.sogood360.com/update 或自建更新服务器）；方案二需能访问 npm 源与官方镜像源；方案三需能访问官网下载页；方案四的客户端需能访问更新服务器 TCP 3101；
3. 仓库地址：Docker Hub（https://hub.docker.com/）。

---

📌 升级流程总览

整个升级有 5 大步：

步骤	做什么
第 1 步	登录管理后台
第 2 步	升级后台程序 + 智能体镜像（命令行 / npm / 官网下载包 / 本地升级服务器，四选一）
第 3 步	数据库结构同步（新版本有表结构变动时）
第 4 步	更新前端（网页）
第 5 步	验证版本号

第 2 步怎么选：

场景	选哪个
1.5.8 及以上、能访问更新源（推荐）	方案一：命令行升级（openpartner upgrade，自动备份 + 失败回滚）
能联网、想手动一步步来	方案二：npm 联网升级
能访问官网、不想装 npm 依赖	方案三：官方下载手动安装（官网下载包）
内网 / 离线环境	方案四：本地升级服务器

---

目录

• 📌 升级流程总览
• 一、登录
• 二、升级后台程序与智能体镜像（四选一）
• 三、数据库结构同步（有变动时）
• 四、前端更新（四种方案都要执行）
• 五、验证
• 六、常见问题

---

一、登录

1. 浏览器打开 http://<服务器IP>:9620（<服务器IP> 替换为 OpenPartner 实际 IP）。
2. 输入 admin 和部署时设置的密码，点击登录。

---

二、升级后台程序与智能体镜像（四选一）

⚠️ 四种方案四选一。

方案一：本地命令行升级（openpartner upgrade，推荐）

适合 1.5.8 及以上、能访问更新源的机器。在服务器上执行一条命令，升级器自动完成「预检 → 备份 → 下载校验 → 加载镜像 → 同步数据库 → 换新程序 → 健康检查」，任何一步失败自动回滚。

升级源（新版本从哪下载）写在 config.yaml 的 update: 段，默认官方地址；自建过升级服务器的改成自己的地址（如 http://<服务器IP>:3101），改完重启后端：

update:
  server_url: "https://openpartner.sogood360.com/update"

执行：

openpartner upgrade --dry-run   # 先预检：只打印计划，不改任何东西
openpartner upgrade             # 正式升级：自动升到最新版，按提示确认

升级器会自动备份（config.yaml + 全库，存在安装目录 backups/<时间戳>/）、下载后做 sha256 校验（假包会被拦下）、换程序时旧程序留 .old，任一步失败自动回滚。

⚠️ 前端不参与自动升级：升级完成后按第四节手动更新前端。

✅ 确认升级成功：出现「升级完成」提示，openpartner version 显示新版本号。

方案二：npm 联网升级（能联网，手动方式）

以下命令在部署 OpenPartner 的服务器上执行。第一句升级程序本身，第二句下载新版智能体镜像。

Windows（管理员 PowerShell）：

# 默认装最新版；指定版本：npm i -g @sogood360/openpartner@<版本号>
npm i -g @sogood360/openpartner
docker pull sogood360/openpartner-agent:<版本号>

Linux：

# 默认装最新版；指定版本：npm i -g @sogood360/openpartner@<版本号>
npm i -g @sogood360/openpartner
docker pull sogood360/openpartner-agent:<版本号>

⚠️ 普通用户：npm i -g --prefix "$HOME/.local" @sogood360/openpartner。

重启后台服务使新版本生效（后台会自动停掉旧任务容器、用新镜像启动新容器）：

openpartner stop
openpartner start

✅ 确认：命令无报错。

方案三：官方下载手动安装（官网下载包）

在部署 OpenPartner 的服务器上，从官网下载最新版压缩包，解压后执行包内安装脚本即可完成升级（保数据，脚本覆盖安装新版本）。

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

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

同时从官网下载智能体镜像包（openpartner_agent-<版本号>.tar，官网下载页提供），在本机加载：

docker load -i openpartner_agent-<版本号>.tar   # Windows 管理员 PowerShell 同命令

✅ 确认：openpartner version 显示新版本号，docker images 里 agent 镜像为新 tag。

⚠️ 前端不参与：升级完成后按第四节手动更新前端。

方案四：本地升级服务器（内网 / 离线）

适合内网 / 离线环境：先部署一台本地更新服务器，再把 OpenPartner 的更新源指向它。

权限说明：Windows 命令统一使用管理员 PowerShell 执行（创建符号链接必须管理员权限）。

2.4.1 部署升级服务器（Linux）

以下命令中 <版本号> 替换为实际发布版本（如 1.5.6）；<服务器IP> 替换为更新服务器实际 IP。

⚠️ 普通用户：全程在同一终端执行。将 sudo install -d -m 755 /opt/update_server/update_server 换成 mkdir -p "$HOME/update_server/update_server"；将两处 cd /opt/update_server/update_server、cd /opt/update_server 分别换成 cd "$HOME/update_server/update_server"、cd "$HOME/update_server"。下方 Docker 挂载目录仍以 /opt/update_server/update_server 为例，运行前须与实际发布目录一致。

创建目录

sudo install -d -m 755 /opt/update_server/update_server
cd /opt/update_server/update_server
mkdir -p dist/images/latest dist/images/<版本号>
mkdir -p dist/linux/latest dist/linux/<版本号>
mkdir -p dist/windows/latest dist/windows/<版本号>

启动更新服务器

# -d=后台；--restart=开机自启；宿主 3101 → 容器 80；更新目录只读挂载
docker run -d --name openpartner_update_server --restart unless-stopped \
  -p 3101:80 \
  -v /opt/update_server/update_server:/usr/share/nginx/html:ro \
  nginx:latest

docker ps | grep openpartner_update_server

放置 agent 镜像

docker pull sogood360/openpartner-agent:<版本号>   # <版本号> 替换为实际版本，如 1.5.6
# 导出镜像 tar 到版本目录
docker save sogood360/openpartner-agent:<版本号> -o dist/images/<版本号>/openpartner_agent-<版本号>.tar

放置服务端程序

sudo npm i -g @sogood360/openpartner   # 安装后从 node_modules 提取服务端程序
# linux 服务端程序
cp "$(npm root -g)/@sogood360/openpartner/node_modules/@sogood360/server-linux-x64/bin/openpartner-server" dist/linux/<版本号>/openpartner-server-<版本号>-linux-x64
# windows 服务端程序：从 Windows 机器同法提取（server-win32-x64\bin\openpartner-server.exe）后放入 dist/windows/<版本号>/openpartner.exe

建立 latest 软链接

cd dist/images/latest
ln -s ../<版本号>/openpartner_agent-<版本号>.tar .                        # 相对路径软链接
cd ../../linux/latest
ln -s ../<版本号>/openpartner-server-<版本号>-linux-x64 .
cd ../../windows/latest
ln -s ../<版本号>/openpartner.exe .
cd /opt/update_server

软链接必须用相对路径（../<版本号>/...），否则容器里会找不到文件（报 404）。

验证更新服务器

# 预期：HTTP/1.1 200
curl -I http://<服务器IP>:3101/dist/images/latest/openpartner_agent-<版本号>.tar
# 预期：HTTP/1.1 200
curl -I http://<服务器IP>:3101/dist/linux/latest/openpartner-server-<版本号>-linux-x64
curl -I http://<服务器IP>:3101/dist/windows/latest/openpartner.exe   # 预期：HTTP/1.1 200

端口 3101 可更改，防火墙需同步放行。

常用命令

docker restart openpartner_update_server   # 重启
docker logs openpartner_update_server      # 看报错
docker stop openpartner_update_server && docker rm openpartner_update_server   # 停止并移除

2.4.2 部署升级服务器（Windows）

以下命令中 <版本号> 替换为实际发布版本（如 1.5.6）；<服务器IP> 替换为更新服务器实际 IP。

以管理员身份运行 PowerShell（创建符号链接需要权限）。全程使用同一个窗口；$Root 变量只在当前窗口有效。

创建目录

$Root = "C:\update_server"    # 可更改为任意盘符/路径，后续命令自动跟随
New-Item -ItemType Directory -Force -Path $Root | Out-Null
foreach ($d in @("$Root\update_server\dist\images","$Root\update_server\dist\linux","$Root\update_server\dist\windows")) {
  New-Item -ItemType Directory -Force -Path "$d\<版本号>","$d\latest" | Out-Null
}

启动更新服务器

# -d=后台；--restart=开机自启；-p=宿主 3101 → 容器 80；-v=更新目录只读挂载
docker run -d --name openpartner_update_server --restart unless-stopped `
  -p 3101:80 `
  -v "$Root\update_server:/usr/share/nginx/html:ro" `
  nginx:latest
docker ps | Select-String openpartner_update_server

放置 agent 镜像

docker pull sogood360/openpartner-agent:<版本号>   # <版本号> 替换为实际版本，如 1.5.6
# 导出镜像 tar 到版本目录
docker save sogood360/openpartner-agent:<版本号> -o "$Root\update_server\dist\images\<版本号>\openpartner_agent-<版本号>.tar"

放置服务端程序

npm i -g @sogood360/openpartner   # 安装后从 node_modules 提取服务端程序
# windows 服务端程序
Copy-Item "$(npm root -g)\@sogood360\openpartner\node_modules\@sogood360\server-win32-x64\bin\openpartner-server.exe" "$Root\update_server\dist\windows\<版本号>\openpartner.exe"
# linux 服务端程序：从 Linux 机器同法提取（server-linux-x64/bin/openpartner-server）后放入 dist\linux\<版本号>\openpartner-server-<版本号>-linux-x64

建立 latest 软链接

# 相对路径软链接
cmd /c mklink "$Root\update_server\dist\images\latest\openpartner_agent-<版本号>.tar" "..\<版本号>\openpartner_agent-<版本号>.tar"
cmd /c mklink "$Root\update_server\dist\linux\latest\openpartner-server-<版本号>-linux-x64" "..\<版本号>\openpartner-server-<版本号>-linux-x64"
cmd /c mklink "$Root\update_server\dist\windows\latest\openpartner.exe" "..\<版本号>\openpartner.exe"

链接目标必须用相对路径（..\<版本号>\...），不能用带盘符的完整路径（如 C:\update_server\...）。用 cmd /c mklink 创建。

验证更新服务器

# 预期：200
(Invoke-WebRequest -Method Head -Uri "http://<服务器IP>:3101/dist/images/latest/openpartner_agent-<版本号>.tar").StatusCode
# 预期：200
(Invoke-WebRequest -Method Head -Uri "http://<服务器IP>:3101/dist/linux/latest/openpartner-server-<版本号>-linux-x64").StatusCode
# 预期：200
(Invoke-WebRequest -Method Head -Uri "http://<服务器IP>:3101/dist/windows/latest/openpartner.exe").StatusCode

常用命令

docker restart openpartner_update_server   # 重启
docker logs openpartner_update_server      # 看报错
docker stop openpartner_update_server; docker rm openpartner_update_server   # 停止并移除

2.4.3 配置更新源

进入 设置 > 系统配置 > 新增配置（菜单路径以实际版本为准）：

• 配置键：system_update_url
• 配置值（<服务器IP> 替换为更新服务器实际 IP）：

{
  "update_server_url": "http://<服务器IP>:3101",
  "update_config": {
    "allow_backend": true,
    "allow_agent_image": true,
    "backend_path": "",
    "agent_image_path": ""
  }
}

点击保存配置，客户端应能发现新版本。

⚠️ 1.5.8 及以上的客户端更新源改在 config.yaml 的 update: 段（update.server_url 指向 http://<服务器IP>:3101），后台此配置只对老版本生效；且更新服务器根目录需要有 dist/capabilities.json（内容 {"artifacts":["backend","agent_image"]}），否则新版客户端视为「不提供升级」。新版客户端配好后直接跑方案一的 openpartner upgrade。

2.4.4 触发更新

在管理后台进入更新页面（入口以实际版本为准）：

⚠️ 更新后若提示重启服务，按界面提示操作即可。

---

三、数据库结构同步（有变动时）

新版本数据库表结构有变动时，所有方案升级后都需重新初始化以同步表结构（幂等、保数据；reset_db 绝不能设为 true，否则会清空数据库）：

params.json 的写法与参数含义见《快速单机部署指南》第 3 步方式二及附录 A · JSON 配置参数目录。

openpartner init --from-json params.json   # 无人值守；reset_db 必须为 false

✅ 确认：命令执行完成、无报错。

---

四、前端更新（四种方案都要执行）

在运行 OpenPartner 前端的服务器上执行以下步骤：

拉取新镜像

docker pull sogood360/openpartner-frontend:<版本号>   # <版本号> 替换为实际版本，如 1.5.6

记下旧容器的子节点地址（多节点必须做，单节点跳过）

多节点部署时，前端靠 CELL_ROUTES 记录各子节点的地址；删除旧容器后这份记录会丢失，所以先复制下来：

Linux：

docker inspect openpartner_frontend --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^CELL_ROUTES='

Windows（管理员 PowerShell）：

docker inspect openpartner_frontend --format '{{range .Config.Env}}{{println .}}{{end}}' | Select-String CELL_ROUTES

把输出里 CELL_ROUTES= 等号后面的内容完整复制下来。

删除旧容器，用新镜像重建

把上一步复制下来的内容原样粘贴在 <原值> 处；单节点删掉 -e CELL_ROUTES="<原值>"。

Linux：

docker stop openpartner_frontend && docker rm openpartner_frontend   # 停掉并删除旧容器
docker run -d --name openpartner_frontend -p 9620:9620 -e CELL_ROUTES="<原值>" sogood360/openpartner-frontend:<版本号>

Windows（管理员 PowerShell）：

docker stop openpartner_frontend; docker rm openpartner_frontend   # 停掉并删除旧容器
docker run -d --name openpartner_frontend -p 9620:9620 -e CELL_ROUTES="<原值>" sogood360/openpartner-frontend:<版本号>

验证

docker ps --filter name=openpartner_frontend   # 状态 Up 即正常

浏览器打开 http://<服务器IP>:9620，确认前端显示新版本。

✅ 确认：网页能打开、版本号是新版。

---

五、验证

1. 更新完成后刷新页面，关于 / 版本信息 显示最新版本号（预期：<新版本号>，替换为实际新版本号）。
2. 重新登录后各功能正常使用。

✅ 升级完成。

---

六、常见问题

Q：创建符号链接时提示「文件已存在」？

1. 先 Remove-Item "<链接完整路径>" -Force 再执行；
2. 无法创建符号链接时改用复制方案（不建链接，直接把文件复制到 latest 目录）。

Q：符号链接异常？

1. 删除原链接后，用 cmd /c mklink 重建链接；
2. 或 docker restart openpartner_update_server，仍异常用复制方案。

Q：访问 3101 报 404？

1. 检查 -v 挂载目录是否正确；
2. latest 拉不到文件时检查软链接目标是否为相对路径。

Q：之前配置过本地更新源，想改回官方更新源？

1. 1.5.8 及以上：编辑 config.yaml，把 update.server_url 改回 https://openpartner.sogood360.com/update（或删除 update: 段），重启后端；
2. 1.5.7 及以下：在 设置 > 系统配置 中删除 system_update_url（恢复默认联网镜像源）。

Q：openpartner upgrade 中途失败会弄坏环境吗？

1. 不会。升级器任一步失败都会自动回滚到升级前（旧程序保留为 .old）；
2. 退出码：0 成功、1 没有可升级内容、2 已回滚、3 回滚失败需人工处理（此时从安装目录 backups/<时间戳>/ 手动恢复）。