操作指南
升级与版本兼容
本文目录
本文提供控制台、命令行和离线升级方式,并说明版本不一致时的限制与回退方法。
适用场景:已部署 GPUWorks 集群,需要更新控制面(server)或已接入的节点(agent),或处理两者版本不一致的情况。首次部署见安装和升级控制面。集群升级时,先升级 server,再逐个升级 agent。
升级前检查
- 已安排维护窗口。升级会短暂中断控制台、网关和相应节点的连接,在途请求会断开,节点上的推理容器通常保留。
- 尽量等模型下载、节点间同步和镜像同步等长动作结束后再升级。
- 确认评测的发压位置与访问入口。server 重启会将尚未完成的 server 发压评测标为失败;agent 发压不受这条恢复规则影响,但网关、目标节点或发压节点中断仍可能影响评测。
- 升级 server 时,控制面安装目录需有足够的备份空间。升级会自动备份主数据库、配置、主密钥和二进制,其他数据不全在备份中,详见备份范围。
升级 server
使用控制台或命令行在线升级;控制面无法访问发布源时,使用离线包。以下方式任选一种,完成后继续升级 agent。server 已是目标版本时,直接检查 agent。
通过控制台升级
使用管理员账号登录控制台。
- 打开设置 → 通用 → 版本与更新,查看服务端的当前版本。
- 选择更新渠道,点击检查更新,核对目标版本。
- 点击服务端行的升级,在确认框核对版本和中断提示,再点击升级。
- 等待页面恢复,确认当前版本与目标一致,再打开计算节点,等待原本在线的节点恢复在线。
页面提示不支持控制台升级时,按提示处理,或使用下面的命令行方式。
通过命令行升级
在控制面主机的实际安装目录中,用有权维护该安装的账户执行。systemd 安装先按安装摘要取得组权限,停启服务仍需 sudo;容器主进程场景请先看容器限制,不要在容器内执行升级命令。
-
检查更新,核对目标安装和版本:
./gpuworks upgrade --check -
确认后执行,等待命令完成:
./gpuworks upgrade -
访问控制面的
/healthz,确认version为目标版本;命令报错时先检查日志与实际版本,再决定是否重试或回退。
更换更新渠道、使用内网发布站或限制目标版本时,按 CLI 参数设置,检查与执行使用相同参数。从发布渠道降级或替换本地构建时,需明确使用 --force;降级前先核对下文的版本兼容。
使用离线包升级
-
在可联网的机器上下载匹配控制面系统、架构的发布包及同一版本的
SHA256SUMS,核对包的 SHA-256。 -
选择一种执行方式:
-
控制台上传:在设置 → 通用 → 版本与更新 → 服务端点击上传升级包,选择已校验的发布包。选择文件后即开始上传和升级,没有第二次确认。
-
命令行执行:将发布包和校验文件传到控制面主机,再次校验成功后,按上节要求进入安装目录。将下列占位符替换为该包的绝对路径,先检查包内版本:
./gpuworks upgrade --archive '<发布包绝对路径>' --check确认后执行:
./gpuworks upgrade --archive '<发布包绝对路径>'
-
-
等待服务恢复,在控制台或
/healthz核对运行版本与目标一致。
发布包无需解压;不要用新包中的 install 替代升级,否则没有升级备份与回滚。校验命令见离线安装包校验。
升级 agent
控制面升级不会自动更新 agent。节点页升级支持 Linux 和 macOS,安装的版本取自当前 server。
多机推理和 PD 分离的节点逐个升级,每次等待节点恢复在线。 多机节点离线超过 2 分钟会使当前一代实例整体失败。
通过控制台升级
使用管理员账号操作。节点须在线;较早的 agent 还需能访问 server 的下载地址。
- 打开计算节点,勾选需要更新的节点,点击批量升级 Agent。预览中的「本次目标」展示版本类型、构建时间、来源和发布记录匹配结果,可打开「版本与更新」查看详情。勾选可跨页保留,工具栏显示已选数量并可清空;预览仅包含已选节点,显示目标版本和每台节点的可升级、已是目标版本、离线、不支持或需手工处理原因。
- 核对目标是当前 server 的版本,确认业务允许短暂中断后开始。版本字符串不同不代表目标更新,也可能是降级;
dev等无法识别的目标构建不能批量升级。 - 在升级进度中查看总数、已处理、成功、失败、跳过与待确认数量,展开查看逐节点结果。全平台同时只升级一台;单节点详情中的升级 Agent也使用同一队列。通过工具栏的最近 Agent 升级查看历史记录,刷新页面后仍可查看;保留最近 20 个已结束批次,仍有队列或未解除占用的批次不清理。
- 系统只有观察到新版本 agent 正式重新连接并上报正常状态,才计为成功。传输或重连超时会暂停队列;“待确认”表示结果未知,不表示失败或可以安全重试。先检查节点上的进程、版本、服务日志和连接状态;管理员确认旧进程已退出、无升级仍在进行后,可填写处理说明解除阻塞,再预览并确认继续剩余节点。继续会创建关联的新批次,保留原始结果。
- 停止后续升级只取消尚未开始的节点,正在升级的节点仍继续观察。存在运行中或未解除的待确认任务时,控制台拒绝升级 server,避免目标版本中途变化。
较早的 agent 使用下载方式时,下载期间固定使用该批次的升级包。旧版 Server 发起连接节点如果不能通过连接接收升级包,需按下节手工更新。升级不自动驱逐工作负载,也不保证请求不中断;多机推理和 PD 分离节点仍应逐台确认业务恢复。
Kubernetes 集群的节点
以 DaemonSet 接入的节点与其他节点一样批量升级:agent 运行在节点状态目录(默认 /opt/gpuworks)里的 agent/gpuworks-agent,升级原地替换这份程序,不改 DaemonSet,也不访问镜像仓库,所以私有仓库和离线集群同样适用。
- 预览中显示「状态目录不可执行」的节点没能从状态目录启动(例如目录挂载为 noexec),只能运行镜像自带的程序,批量升级跳过它们;检查节点上的状态目录后删除该节点的 agent Pod,让它重新启动。
- 镜像的 tag 是运行环境版本,很少变化。某个版本升了它时,发布说明会写明,升级 server 后重新 apply 一次 manifest(
kubectl apply或「应用到集群」),DaemonSet 换到新 tag;集群用私有仓库或离线导入的镜像时,先把新 tag 的镜像推到仓库或导入各节点。 - 新加入集群的节点先运行镜像自带的程序,注册前自动换成 server 当前版本的 agent,不需要再升级。
在节点上重新运行安装脚本
可登录节点时,也可以重新运行 /install.sh 更新 agent;节点已离线或旧版不支持自升级时使用此方式。
- 保留旧二进制,核对原节点身份和连接配置。重装会按传入参数重写配置,没有自升级的自动回滚。
- 按接入指南,沿用原接入参数重新运行安装脚本;Server 发起连接的节点使用离线包。
- 确认节点重新在线、版本与 server 一致,再处理下一个节点。
gpuworks-agent upgrade 仅适用于没有常驻 agent 的手工运行环境,参数见 CLI 参考。它会进入前台运行,不会重启原服务;已有常驻 agent 时不要另起该命令。Server 发起连接的节点不能用它下载升级。
验证结果
- 控制面已运行目标版本,原本在线的节点已恢复在线,已升级的 agent 与 server 版本一致。
- 调用原有模型,确认能正常响应;没有部署模型的环境只核对版本和节点状态。
版本不一致时会怎样
server 和 agent 目前没有强制的最低发行版本检查,能连接不代表全部功能兼容。升级期间可以逐节点处理,完成后应统一到目标版本。
新 server + 老 agent 时,各功能按下列条件判断;遇到升级提示,先更新对应节点:
- Web 终端:agent 需声明宿主机终端能力;容器终端还需声明对应运行时的容器终端能力。缺少对应能力时,终端无法打开,提示不支持或升级 agent。
- 拉取镜像、从 URL 加载镜像:agent 需支持对应操作;不支持时拉取或加载失败,提示升级 agent。
- 从 HTTP 目录下载模型:可解析的发行版本需不低于
1.0.0;低于该版本时拒绝下载,返回MODEL_SOURCE_REQUIRES_NEWER_AGENT。dev、裸 commit 等不可解析版本不按此门槛拒绝,仍以实际下载结果为准。 - 评测的 tokenizer 文件探测:agent 不支持文件检查时,仍尝试记录的路径;加载失败时给出 tokenizer 警告,允许估算的负载按估算模式继续。
- dGPU:agent 需上报所需安全能力或当前格式的分区探测结果;缺少所需报告时,dGPU 显示不可用并提示升级 agent。上报后仍须通过对应后端的能力检查。
老 server + 新 agent 时,新功能未必可用,不建议长期保持;先升级 server。
节点列表默认显示 Agent 版本。保存过列布局的用户可在列设置中开启该列。离线 Agent 的版本号旁显示“离线前版本”标签。从未上报版本时只显示“未上报”标签。重连后按实际上报的版本判断。
在计算节点页,符合升级条件的旧版 Agent 显示“待升级”,高于目标版本的显示“待对齐”,无法判断先后的 nightly 或定制构建显示“构建不同”。在线但缺少适配包等情况归入“暂不可升级”,筛选后可查看原因。点击提示中的数量或使用表格工具栏的 Agent 状态 筛选,选择“全部”恢复完整列表。“忽略本次提示”只收起当前目标版本的提示条,同一浏览器记住当前账号的选择。
通过控制台在线升级服务端或上传离线升级包成功后,如果有上述在线 Agent,版本与更新会在服务端行下方显示数量。点击“查看计算节点”打开完整列表,自行选择维护范围。只有离线或已同版的 Agent 时,设置页保持安静。提示最多保留 30 分钟,刷新沿用剩余时间。关闭、离开、没有节点或全体确认同版时结束。CLI 升级后可直接到计算节点核对版本。首次从尚未提供此提示的旧控制台升级时,也可到计算节点核对。批量预览显示可执行节点的当前和目标版本或构建号,并列出同版和离线节点的跳过原因。
数据库迁移随 server 启动自动执行,无需另跑命令。迁移只向前,不支持反向迁移;降级需恢复升级前快照,不能仅替换旧二进制。观测库 ux.db 不在升级备份中,旧版不兼容时需单独处理,见回滚。
遇到问题时
| 现象 | 处理 |
|---|---|
| 页面提示升级超时 | 先核对实际运行版本、在线状态及日志。server 页面等待 5 分钟,agent 页面等待 2 分钟;页面超时不等于升级失败或已回滚。控制面按安装篇排查检查,节点查看 agent.log |
| 升级报错、服务没有恢复,或新版运行异常 | 查看错误与日志,按下面的回退说明处理;不要仅凭“已回滚”提示判断恢复成功 |
回滚
仅在升级失败后服务未恢复,或新版出现问题时使用。恢复快照会丢失快照之后写入的数据。
恢复控制面到升级前快照
以下命令在控制面主机的实际安装目录中执行,使用有权维护该安装的账户。容器主进程场景先看容器限制,不要在容器内执行这里的停服、重启命令。
- 执行
./gpuworks stop,确认 server 已退出。二进制无法运行或旧版不支持stop时,按原服务管理方式停服;未确认退出前,不修改数据库。 - 从安装目录的
backups/选择目标旧版的备份,解压到临时目录。确认备份属于这套安装,并用其中的server.yaml核对实际数据目录。 - 删除实际数据目录中当前的
gpuworks.db-wal、gpuworks.db-shm,再将备份的data/成员恢复到数据目录、bin/gpuworks恢复为安装目录中的gpuworks、server.yaml恢复到安装目录。保留程序执行权限,确保原服务账户能读写恢复的文件。 - 只在旧版不支持现有
ux.db时处理观测库。 若日志提示uxstore: file schema version N is newer than M,在停服状态下把实际数据目录中的ux.db及存在的ux.db-wal、ux.db-shm移到独立目录保留。它们不在升级备份中,自动回滚也不会处理;旧版将新建空观测库,原有请求观测记录不会显示在新库中。兼容时无需移动。 - 执行
./gpuworks restart,检查/healthz的version为目标旧版;登录控制台,确认节点在线和模型响应恢复。
Agent 的自动回滚和手工回退
- 下载或校验阶段失败时保留旧二进制。新进程超过 6 分钟仍未完成注册,或前三次启动都未注册、到第 4 次启动时,会尝试恢复旧版本。崩溃重启依赖 systemd、launchd 等服务管理器;server 暂时不可达也可能触发回滚。恢复后查看节点失败原因,解决后再重试。
- 新版本已成功注册后,不再自动回滚。需要手工回退时,停止该节点的 agent,将保留的
<bin>.old恢复为原二进制,再按原服务方式启动,核对版本、在线状态和模型响应。
这篇文档有帮助吗?