快速单机部署指南

操作系统：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。

---

📌 部署流程总览

整个部署有 5 大步：

步骤	做什么
第 1 步	准备环境（Docker、MySQL、Node、Git）
第 2 步	安装 OpenPartner 程序（NPM 一条命令 或 官方下载手动安装，二选一）
第 3 步	初始化（图形向导 或 无人值守，二选一）
第 4 步	启动后台服务
第 5 步	浏览器登录验证

两处「二选一」怎么选：

选择点	场景	选哪个
安装程序	机器能联网	NPM 一条命令（推荐）
安装程序	内网 / 离线	官方下载手动安装
初始化	单人部署	图形向导（推荐）
初始化	脚本 / CI	无人值守

部署多节点：主节点按本篇完成；添加节点看《多节点部署指南》。

---

目录

• 📌 部署流程总览
• 第 1 步 · 准备环境
• 第 2 步 · 安装 OpenPartner 程序
• 第 3 步 · 初始化
• 第 4 步 · 启动后台服务
• 第 5 步 · 浏览器登录验证
• 常用命令
• 附录 A · JSON 配置参数目录
• 附录 B · JSON 示例
• 附录 C · 配置文件位置
• 附录 D · 常见问题

---

第 1 步 · 准备环境

这一步装 4 样东西：Docker、MySQL、Node.js（npm）、Git。已经装好的直接跳过对应小节，最后用「验证环境」确认。

Windows

1.1 安装 Docker

从 docker.com 下载 Docker Desktop 安装包，按提示装好并重启电脑。

⚠️ 需开启 CPU 虚拟化与 WSL2；需能访问 Docker Hub（https://hub.docker.com）。

1.2 安装 MySQL

到 dev.mysql.com 下载 MySQL 8.x 安装包，按向导装好，root 密码记下来（第 3 步要填）。

1.3 安装 Node.js（内置 npm）

仅第 2 步选「NPM 安装」时才需要。

装好 Node.js（nodejs.org 下载 LTS 版；已内置 npm，无需单独安装）。装完重开终端。

1.4 安装 Git

装好 Git（git-scm.com 下载安装）。

1.5 验证环境

docker --version    # 应显示版本号
node --version      # 应显示 ≥ 18
npm --version       # 应显示版本号
git --version       # 应显示版本号
Get-NetTCPConnection -LocalPort 3306 -State Listen   # 3306 在监听 = MySQL 已启动

每条命令都有输出，说明环境就绪。

Linux

1.1 安装 Docker

到 docs.docker.com/engine/install/ 选择你的发行版，按页面步骤装好 Docker。

⚠️ 需能访问 Docker Hub（https://hub.docker.com）。

1.2 安装 MySQL

打开 dev.mysql.com 下载 MySQL 8.x 并安装，root 密码记下来（第 3 步要填）。

1.3 安装 Node.js（内置 npm）

仅第 2 步选「NPM 安装」时才需要。

装好 Node.js（nodejs.org 下载 LTS 版；已内置 npm，无需单独安装）。

1.4 安装 Git

装好 Git（git-scm.com 下载安装）。

1.5 验证环境

docker --version    # 应显示 ≥ 20.10
node --version      # 应显示 ≥ 18
npm --version       # 应显示版本号
git --version       # 应显示版本号
ss -tlnp | grep 3306   # 3306 在监听 = MySQL 已启动

1.6 普通用户（目录授权）

普通用户安装需 root 账户先在目标服务器完成一次目录授权。

在 目标服务器 由 root 执行，<普通用户名> 替换为实际登录账号：

NORMAL_USER="<普通用户名>"
NORMAL_GROUP="$(id -gn "$NORMAL_USER")"
NORMAL_HOME="$(getent passwd "$NORMAL_USER" | cut -d: -f6)"

install -d -o "$NORMAL_USER" -g "$NORMAL_GROUP" -m 750 \
  "$NORMAL_HOME/.local" \
  "$NORMAL_HOME/.local/bin" \
  "$NORMAL_HOME/ocw" \
  "$NORMAL_HOME/openpartner" \
  "$NORMAL_HOME/openpartner/workspace" \
  "$NORMAL_HOME/openpartner/logs"

install -d -o "$NORMAL_USER" -g "$NORMAL_GROUP" -m 700 /tmp/openpartner-init-ui
install -d -o "$NORMAL_USER" -g "$NORMAL_GROUP" -m 750 /var/cache/git-edit
install -d -o "$NORMAL_USER" -g "$NORMAL_GROUP" -m 700 /etc/openpartner
chown -R "$NORMAL_USER:$NORMAL_GROUP" \
  /tmp/openpartner-init-ui /var/cache/git-edit /etc/openpartner
chmod -R u+rwX,go-rwx /tmp/openpartner-init-ui /etc/openpartner
chmod -R u+rwX,go-rwx /var/cache/git-edit

usermod -aG docker "$NORMAL_USER"

管理员完成授权后，普通用户退出并重新登录，先执行 cd "$HOME/openpartner"；后续步骤全程在同一个普通用户终端执行，不使用 sudo。

---

第 2 步 · 安装 OpenPartner 程序

这一步把 OpenPartner 装到机器上，就像装一个普通软件。装完得到两个命令：openpartner（后台服务与命令行）和 openpartner-init-ui（图形向导）。两种方式二选一：

方式一：NPM 一条命令（推荐，需联网）

Windows（管理员 PowerShell）：

# 指定版本：npm i -g @sogood360/openpartner@<版本号>
npm i -g @sogood360/openpartner@beta

Linux：

# 指定版本：npm i -g @sogood360/openpartner@<版本号>
npm i -g @sogood360/openpartner@beta

⚠️ 普通用户：npm i -g --prefix "$HOME/.local" @sogood360/openpartner@beta（前提：第 1 步已完成目录授权）；命令装在 $HOME/.local/bin，PATH 中没有该目录时请手动加入。

⚠️ 装完若提示「不是内部或外部命令 / command not found」：见附录 D。

✅ 确认装好了：openpartner version 显示版本号（形如 1.5.x）。

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

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

Windows：解压 zip，然后在管理员 PowerShell 进入解压目录，执行包内安装脚本（脚本自动完成安装）：

Expand-Archive -Path "openpartner-windows-setup.zip" -DestinationPath "C:\openpartner"
cd C:\openpartner\openpartner-windows-setup
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process   # 若提示「禁止运行脚本」先执行这行
.\install-windows.ps1

Linux：解压 zip 后进入解压目录执行安装脚本：

unzip openpartner-linux-setup.zip   # 解压得到 openpartner-linux-setup/ 目录
cd openpartner-linux-setup
sudo ./install-linux.sh   # 管理员：装到 /usr/local/bin

⚠️ 普通用户：./install-linux.sh --target-dir=$HOME/.local/bin（装到用户目录，需确保该目录在 PATH 中）。

⚠️ 卸载：./install-linux.sh --uninstall；只预览不实际写入：--dry-run。

⚠️ 官网下载仅提供最新版；需要指定历史版本请用方式一并指定版本号。

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

---

第 3 步 · 初始化

初始化 = 第一次运行前的设置：告诉 OpenPartner 数据库在哪、管理员密码设什么。两种方式二选一：

方式一：图形向导（推荐）

执行：

openpartner-init-ui   # Windows 管理员 PowerShell / Linux 终端

界面操作：Tab 切换，↑ ↓ 选择，Enter 确认。 ⚠️ 必须在真实终端运行（Windows Terminal / PowerShell / SSH 终端）；Git Bash、IDE 内置终端会因无 TTY 直接退出。

向导会问的问题（按顺序）：

1. 数据库连接：地址默认 127.0.0.1:3306（可更改；远程填 <公网IP>:<端口>）；
2. 用户名：默认 root（需读写、建库权限）；
3. 密码：填 MySQL 密码（<MySQL密码>，示例 openpartner2049）；
4. 管理员账号：设置 admin 密码（<admin密码>，至少 6 位，重复确认一次）；
5. 访问及端口：服务地址默认内网 IP，公网访问改为公网 IP（<公网IP>）；服务端口保持默认即可（最大 65535）；
6. 工作目录：默认 D:\openpartner\workspace（Windows）/ /var/lib/openpartner/workspace（Linux），可更改；
7. 镜像来源：默认联网拉取镜像，如本地有可更换使用本地镜像；
8. 执行安装：核对无误按 Enter，出现「OpenPartner 初始化完成」即成功，按 Ctrl+C 退出。

✅ 确认做好了：看到「OpenPartner 初始化完成」。

完成页各行的意思：

页面显示	含义
节点模式	primary = 主节点（网页、后台、数据库都在这一台机器上）
cell URL	本节点的后台服务地址（加机器时用）
浏览器访问	网页登录地址 http://<IP>:9620
config	配置文件位置（以后改设置改这里）
数据库	本次用到的 MySQL 地址和库名
workspace	工作目录（用户数据存在这里）
常用命令	start 启动 / stop 停止 / status 看状态 / upgrade 升级
管理员	网页登录账号 admin

方式二：无人值守

无人值守方式：不弹向导，把参数写进配置表（JSON），命令自动执行，适合脚本 / CI 场景。

⚠️❗ **【必做】动手前先阅读【附录 A · JSON 配置参数目录】，了解每个参数的含义再填写。 cell.id 留空 = 自动使用 cell_a（主节点）；添加节点时才需填 cell_<short_id>（如 cell_b），且不能与已有节点重名。

也可把 mode 写成 auto：cells 表已有主节点记录时会自动按子节点初始化，主/子节点可用同一份参数。

Windows（管理员 PowerShell）：

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

Linux：

普通用户：将本节命令中所有 /tmp/ocw 改为 $HOME/ocw；将 /var/lib/openpartner/workspace 改为 $HOME/openpartner/workspace；将 register_autostart 改为 false。

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

⚠️ register_autostart = true 表示注册开机自启（默认开）：重启电脑后后台服务会自动启动；不需要可改为 false。

执行：

# Windows（管理员 PowerShell）
openpartner init --from-json .\params.json --non-interactive

# Linux
openpartner init --from-json /tmp/ocw/params.json --non-interactive

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

---

第 4 步 · 启动后台服务

这句命令启动 OpenPartner 的后台服务（已注册开机自启，以后每次开机自动启动，不用再管）。

openpartner start   # 默认后台启动

✅ 确认启动了：几秒后命令结束、没有报错即可。

---

第 5 步 · 浏览器登录验证

1. 浏览器打开 http://<本机IP>:9620。
2. 输入 admin 和初始化时设置的密码，点击登录。
3. 登录成功后即可使用。

✅ 登录进去 = 部署成功。

---

常用命令

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

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

---

附录 A · JSON 配置参数目录

区块	键	默认	说明
server	port	3001	后端 API 端口，整个系统的后台服务都在这上面。改它会影响 cell_url、container_api_url 和防火墙放行，通常保持默认
frontend	port	9620	网页端口，浏览器登录用的就是它。改了要同步放行防火墙
database	host	127.0.0.1	数据库地址。本机部署填 127.0.0.1；多节点时子节点填主节点的 IP
	port	3306	数据库端口，一般不用改
	user	root	数据库账号，需有建库、建表和读写权限
	password	空	数据库密码，替换为真实值；填错会报 Access denied
	name	openpartner	库名。仅当 reset_db=true 时才会清空重建，否则保留现有数据
workspace	root	平台默认	工作空间根目录 = 所有用户工作区的存放位置。Windows 默认 D:\openpartner\workspace，Linux 默认 /var/lib/openpartner/workspace；普通用户用 $HOME/openpartner/workspace
images	frontend	当前 tag	前端镜像。默认与安装版本一致；填具体版本号可锁版本，latest 表示最新
cell	id	cell_a	节点 ID，格式 cell_<short_id>（如 cell_a、cell_t2）。集群内唯一；主节点留空自动为 cell_a，添加节点必须指定且不能重名
	name	同 id	节点显示名（后台「节点管理」里显示的名字）
	cell_url	—	本节点对外可达的后端地址（http://<IP>:3001）。必须是其它机器能访问的真实 IP，填 127.0.0.1 会导致其它节点连不上
container_api_url	—	留空自动	用户容器（智能体）访问后端的地址。留空自动推算：Windows 为 host.docker.internal，Linux 为 172.17.0.1（docker0 网关）。一般不要手填
mode	—	auto	auto = 自动检测（cells 表有记录→secondary，无→primary），主/子节点可用同一份参数；也可显式指定 primary = 主节点（部署网页 + 数据库）或 secondary = 添加节点（连主节点库，不建前端）
public_base_url	—	填写	浏览器视角的后端地址（生图等返回的图片 URL 用它拼接）。建议显式填写 http://<本机IP>:<网页端口>
secrets	jwt_secret 等	留空自动生成	登录 token 签名、数据加密等密钥。留空 = 自动生成；primary 初始化会把 jwt_secret 写入数据库，其余节点运行态以数据库为准，本地 config.yaml 无需人工比对，勿手动修改（改了会导致登录失效 / 节点失联）
admin	password	—	管理员初始密码（至少 6 位，可更改）
actions	reset_db	false	⚠️ true = 删除并重建整个数据库（清空所有数据）。仅首次部署用 true，其余情况必须 false。1.5.9 另有等效 CLI 参数 --reset-db
	register_autostart	true	是否注册开机自启。true = 重启机器后后台服务自动启动；普通用户部署填 false
	create_frontend_container	true	是否创建前端容器。主节点 true；添加节点 false（前端只在主节点）
	pull_images	true	初始化时自动拉取镜像，tag 与安装版本一致；离线环境已手动加载镜像时可填 false

---

附录 B · JSON 示例

普通用户使用以下示例时，按第 3 步初始化说明替换工作目录，并将 register_autostart 改为 false。

{
  "mode": "auto",
  "server": { "port": 3001 },
  "frontend": { "port": 9620 },
  "database": { "host": "127.0.0.1", "port": 3306, "user": "root", "password": "<MySQL密码>", "name": "openpartner" },
  "workspace": { "root": "/var/lib/openpartner/workspace" },
  "images": { "frontend": "sogood360/openpartner-frontend:<版本号>" },
  "secrets": { "jwt_secret": "", "encryption_key": "", "encryption_salt": "", "internal_token": "" },
  "admin": { "password": "admin123456" },
  "cell": { "id": "", "name": "", "cell_url": "http://<本机IP>:3001", "region": "", "zone": "" },
  "container_api_url": "",
  "public_base_url": "http://<本机IP>:9620",
  "actions": { "pull_images": true, "create_frontend_container": true, "register_autostart": true, "reset_db": true }
}

---

附录 C · 配置文件位置

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

---

附录 D · 常见问题

Q：运行 openpartner-init-ui 向导直接退出，提示 stdio.isTTY === false？

1. openpartner-init-ui 是交互式向导，必须在支持交互（TTY）的终端里运行。换 Windows Terminal / PowerShell（Windows）或 SSH 登录后的终端（Linux）重新运行；Git Bash、IDE 内置终端不支持交互，会直接退出。

Q：MySQL 连接失败 "Access denied for user 'root'"？

1. 确认 root 密码正确；
2. MySQL 在远程时，确认防火墙放行 3306 且允许远程连接。

Q：Docker 拉镜像失败 permission denied？

1. Windows：确认 Docker Desktop 已启动；
2. Linux：由管理员执行 sudo usermod -aG docker <普通用户名>，普通用户随后退出并重新登录。

Q：网页打不开（9620 不通）？

1. Windows：New-NetFirewallRule -DisplayName "OpenPartner-9620" -Direction Inbound -Protocol TCP -LocalPort 9620 -Action Allow -Profile Any；
2. Linux：Ubuntu / Debian 用 sudo ufw allow 9620/tcp，RHEL / Rocky 用 sudo firewall-cmd --zone=public --add-port=9620/tcp --permanent && sudo firewall-cmd --reload；
3. 云服务器另在控制台「安全组」放行。

Q：用户 AI 容器起不来，日志报 port already in use？

1. 原因：每个用户的 AI 容器默认占用从 5097 开始的一段连续端口（5097+），被其它进程占用时容器无法启动；
2. 打开 config.yaml（Linux 通常位于 /etc/openpartner/config.yaml），把 OPENPARTNER_USER_BASE_PORT 改为新的起始端口（例如 6097）；
3. 重启后端使配置生效：openpartner stop && openpartner start；
4. 重新拉起对应用户的 AI 容器，确认日志不再报端口冲突。

Q：openpartner: command not found？

1. 把 npm 安装目录加入 PATH 并写入 shell 配置后立即生效：先执行 echo 'export PATH=$PATH:$(npm config get prefix)/bin' >> ~/.bashrc，再执行 source ~/.bashrc；
2. 仍提示找不到则重装：npm i -g @sogood360/openpartner@beta --force。

Q：openpartner: Permission denied？

1. 执行 chmod +x "$(npm config get prefix)/bin/openpartner"；
2. 仍不行则重装：npm i -g @sogood360/openpartner@beta --force。

Q：忘记管理员密码？

1. 执行 openpartner reset-admin-password（交互式重置）。