节点与升级
适用角色：管理员
前置条件：节点已入网登记，参见多节点部署
一个节点（cell）= 一台服务器 + 一个后端进程 + 本机 Docker + 一块本地盘。三者必须同台物理机。
一、节点列表
| 列 | 说明 |
|---|---|
| 节点 | 显示名与节点 ID |
| 状态 | 在线／离线 |
| 运行容器数 | 该节点上正在运行的容器数，由节点每 60 秒自报 |
| 前端→后端 URL | 浏览器侧容器访问本节点后端的地址 |
| 镜像加载设置 | 启动容器时使用哪个镜像版本 |
| 操作 | 编辑、健康、终端、更新 |
注意 · 「运行容器数」是自报的。节点离线时该数字会停止更新，属于正常现象，不代表容器还在跑。
1.1 编辑节点
| 字段 | 必填 | 说明 |
|---|---|---|
| 显示名 | ✅ | 如「主楼机房 1」 |
| 前端→后端 URL | ✅ | 前端容器内访问本节点后端的地址，如 http://host.docker.internal:22052 或内网 IP。不是浏览器访问地址 |
| 后端→后端 URL | ❌ | 节点之间直连地址，如 http://10.10.6.x:22052。留空则回退到前端→后端 URL |
注意 · 这两个 URL 极易混淆：
- 前端→后端 URL 是「从浏览器所在的前端容器，去找后端」→ 用宿主机可达的地址
- 后端→后端 URL 是「从别的节点的后端，直连本节点后端」→ 优先填内网 IP，避免 nginx 跳转
填错会导致登录后无法路由、节点间健康检查失败。
1.2 健康检查
| 检查项 | 判定 |
|---|---|
| 磁盘空间 | 可用空间与阈值 |
| Docker daemon | 连接状态与版本 |
| 磁盘可写性 | 是否可写 |
提示 · 节点离线时「健康」按钮不可用，平台会提示「节点不可达，无法查看健康」。
1.3 节点终端
进入该节点的后端进程环境，用于排查节点级问题。
二、镜像加载策略
该策略决定本节点启动用户容器时使用哪个版本的智能体镜像。
| 策略 | 行为 | 适用 |
|---|---|---|
| 镜像（自动） | 始终使用最新版本镜像 | 常规环境。推荐 |
| 镜像（锁定） | 固定使用指定版本 | 生产环境需要版本一致、避免自动变更时 |
| 标签 | 含义 |
|---|---|
| 镜像(自动):v1.5.3 | 自动模式，当前解析到的版本 |
| 镜像(自动):探测中… | 正在探测本节点 Docker 上可用的镜像 |
| 镜像(锁定):v1.5.2 | 已锁定到指定版本 |
注意 · 切换策略不影响正在运行的容器，只对新启动的容器生效。
2.1 找不到镜像时
| 提示 | 原因 | 处理 |
|---|---|---|
| 未找到镜像 | 该节点 host 上没有对应 tag | 进入「更新 → 智能体镜像」下载并加载 |
| docker 不可达 | Docker daemon 未运行 | 检查节点上的 Docker 服务 |
| 探测失败 | 镜像格式异常 | 重新下载该版本 |
三、升级本节点
点节点行的「更新」或「自动更新」按钮打开升级对话框。
对话框有两个页签：
| 页签 | 内容 |
|---|---|
| 后端服务程序 | 升级节点上的后端服务 |
| 智能体镜像 | 升级用户容器使用的 opencode 运行时镜像 |
3.1 升级后端服务程序
切换版本
注意 · 切换后端版本会重启该节点的后端服务，期间该节点服务中断几秒，正在使用该节点的用户需要重新登录。
删除版本
| 删除类型 | 影响 |
|---|---|
| 删除文件 | Docker 镜像与暂存文件一并移除，需重新下载才能恢复 |
3.2 升级智能体镜像
加载镜像
把下载好的镜像 tar 加载进本节点 Docker。
切换版本
注意 · 锁定到新版本只影响新启动的用户容器，运行中的容器不受影响。
卸载镜像
从 Docker daemon 移除镜像，暂存 tar 保留，可再加载回来。
注意 · 若卸载的是当前生效版本，平台会先自动解除锁定（回到自动模式），新容器将使用剩余的最高版本。
删除镜像
Docker 镜像与暂存 tar 都将移除，需重新下载才能恢复。同样地，删除当前生效版本前会先自动解除锁定。
3.3 版本状态
| 状态 | 含义 |
|---|---|
| 可下载 | 更新服务器上有该版本，可下载 |
| 下载中 / 已下载 | 文件已在本地暂存 |
| 已加载 / 加载中 | 已导入本节点 Docker |
| 卸载中 / 删除中 | 异步任务进行中 |
| 当前运行 | 该节点正在使用 |
| 生效中 | 策略已锁定到该版本 |
| 切换中 | 正在切换 |
| 失败 | 任务失败，可点「重试」 |
四、常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 登录时反复跳转 | 前端→后端 URL 填错 | 编辑节点 |
| 节点间健康检查失败 | 后端→后端 URL 未填或不通 | 填内网 IP |
| 「未找到镜像」 | 节点上没有该 tag | 进入镜像页下载并加载 |
| 切换版本后服务中断几秒 | 后端重启，属预期 | 无需处理 |
| 卸载镜像失败 | Docker 任务仍在执行 | 稍等后重试 |
| 运行容器数不更新 | 节点离线，自报停止 | 先恢复节点 |
| 无法升级 | 系统配置中禁用了该项升级 | 检查系统配置 |
| 升级后界面行为异常 | 前端与后端版本不匹配 | 同步升级两者 |
五、相关页面
| 页面 | 内容 |
|---|---|
| 用户与权限 | 分配节点、管理用户容器 |
| 基础配置 | public_base_url 与节点 URL 的区别 |
| 多节点部署 | 节点入网与共享密钥 |