固定页：2026-openclaw-clustervps-rolling-upgrade-peer-deps-canary.html。姊妹篇：多 AZ 网关与 Webhook、金丝雀与技能切片、租户 Doctor 与失败摘要、rsync 矩阵；索引见技术博客首页。
步骤清单（含回滚点）
按顺序执行；任一回滚点触发则停止滚动，先恢复再排因。
- 0 冻结：记录
openclaw.lock、LB 权重、技能 symlink；回滚点 R0——未备份不动包。 - 1 金丝雀节点：仅一台先走
npm -g序列（见下节）；每步后openclaw doctor --json。R1——单台 doctor 非绿则npm -g回退到快照版本并广播。 - 2 合并探针：在金丝雀上跑合并
readyz（Doctor + 队列 + webhook digest）。R2——合并 JSON 任一硬失败则停。 - 3 流量：约 5% 新会话切入金丝雀网关，跨越至少两个探针周期；放大前重复合并探针。R3——SLO 回退则恢复权重快照。
- 4 同伴滚动：其余节点重复 1→2；全程保持「不得领先已验证网关」的 worker 约束（见多 AZ 文）。
- 5 收尾：写审计行（actor、工单、semver、
probe_sha256）。
npm -g 升级顺序（模式）
2026.4.x 起，全局安装顺序应压平半升级状态：先升级CLI / 核心运行时（发行说明中列为「必须先于插件」的包），再按依赖拓扑安装官方插件包；若团队使用内部镜像，请在金丝雀上先验证 npm view 与缓存一致性，再推广到同伴节点。每完成一层安装，执行一次 openclaw doctor --json 与 npm ls -g --depth=0，把 peer 警告截屏进工单。
# 示意：顺序与包名以你方 lockfile / 发行说明为准 npm install -g openclaw@2026.4.x # 然后按文档列出顺序安装 @openclaw/* 插件，例如： # npm install -g @openclaw/plugin-foo@^2026.4.0 openclaw doctor --json | tee /tmp/doctor-after-core.json npm ls -g --depth=0 2>&1 | tee /tmp/npm-global.txt
npm config get prefix；混用 Homebrew 与官方 pkg 的前缀是 peer 解析漂移的常见根因。插件 peer 依赖与 2026.4.x 变更的中立说明
近期主线在插件 peer 依赖的元数据与文档链接上有多项修订，并同步调整了镜像/制品生成流水线中与全局包解析相关的步骤——具体行为以对应版本的 CHANGELOG 与发行说明为准。本文不评价优劣：滚动前请在只读环境对照发行说明核对「peer 范围、推荐安装顺序、破坏性变更」；若使用私有 registry，确认镜像层仍包含与 CLI 对齐的插件清单。遇到 ERESOLVE 时，优先用发行说明推荐的版本区间解决，而不是强行 --force。
每节点 Doctor 与健康探针合并
每台参与流量的 Mac 在升级后都要跑 openclaw doctor；对外 LB 仍建议只暴露一条合并就绪路由，由网关在本地拼装：本机 doctor 摘要、队列水位、以及 webhook digest（失败面聚合）。这与租户拆分文中的「单一就绪 JSON」一致——digest 是字段，不是唯一晋升依据。
#!/usr/bin/env bash
set -euo pipefail
TENANT="${TENANT:-acme}"
/usr/local/bin/openclaw doctor --tenant "${TENANT}" --json >/tmp/doctor.json
/usr/bin/curl -fsS --max-time 3 "http://127.0.0.1:8088/readyz" -o /tmp/readyz.json
/usr/bin/curl -fsS --max-time 3 "http://127.0.0.1:9099/v1/webhook-digest" -o /tmp/digest.json
/usr/bin/python3 - <<'PY'
import hashlib, json, pathlib
parts = [pathlib.Path(p).read_bytes() for p in ("/tmp/doctor.json","/tmp/readyz.json","/tmp/digest.json")]
print(json.dumps({"merged_sha256": hashlib.sha256(b"".join(parts)).hexdigest()}))
PY
semver / lockfile 与磁盘解析不一致时须硬失败；可接受降级用 degraded 显式标出，避免 LB 误绿。
失败广播与金丝雀回滚协奏
滚动途中任一节点 doctor 失败、合并探针失败或队列背压超标，应通过已配置的 Notifier 发送去重后的失败摘要（节点 id、semver、错误码、最近一条 digest 片段），避免聊天工具刷屏。广播与 LB 回滚并行：先撤流量（R3），再回包（R1/R2），最后对同伴节点暂停滚动直至根因写入工单。完整 Webhook 与令牌实践仍见网关篇。
常见问题
能否跳过金丝雀直接全集群 npm？不建议——peer 解析与镜像层问题往往在首台才暴露，全量升级会把回滚成本乘上节点数。
镜像生成能力更新会影响滚动吗？若 CI 产出的全局包清单与运行时预期不一致，会在 doctor 或插件加载阶段暴露；请在 promote 前用与生产相同的前缀跑一次「干跑」安装。
最少验证几台？一台金丝雀 + 两台稳定网关仍是最小诚实拓扑；再少则无法演练权重回滚与同伴镜像。