節點前置檢查
變更模板或鎖檔前，每台 MeshMac 節點都當生產對等機檢查，避免「A 正常 B 異常」的長期比對。
- OS／工具鏈／OpenClaw 次版本全網格對齊。
- 主機名、DNS、NTP可靠；時鐘漂移會打壞分散式鎖與權杖 TTL。
- 磁碟與 inode預留技能與快取空間。
- 網路：各節點可達祕密庫、構件倉與佇列（見任務佇列同步）。
模板與密鑰注入
版控維護單一環境模板（如 openclaw.env.tpl）列出所需變數；密鑰不入 Git，部署時由祕密庫或掛載渲染為 .env。
模板變數步驟清單
- ☐
NODE_ROLE（入口／工作者／簽章／網關等）與MESH_NODE_ID，供日誌關聯。 - ☐ 佇列與 API 端點：單一真實來源，禁止在各節點硬編碼多組位址。
- ☐ 技能倉庫 URL 與唯讀權杖範圍（能 pull 即可者勿給寫入）。
- ☐ 功能旗標用明確
0/1或枚舉，避免「未設定即視為開啟」。 - ☐ 輪換友善的密鑰命名，並在模板旁註明責任人與輪換週期。
渲染後做 diff；缺變數應啟動即失敗。憑證見祕密最小權限。
技能包鎖定與校驗
版本鎖定＝可稽核鎖檔（套件、版本／摘要、安裝順序）；各節點依同一鎖檔部署。
技能包版本檔（鎖檔）步驟清單
- ☐ 版控中僅一份
skills.lock.json（或團隊約定檔名）；CI 在與鎖檔不一致時應失敗。 - ☐ 記錄來源：倉庫 URL＋digest 或 semver；生產網格禁用浮動
@latest。 - ☐ 安裝後鉤子將解析結果印到 stdout，並寫入機器可讀的
skills.resolved.json供節點間比對。
校驗：各節點跑 doctor 或乾跑載入技能；skills.resolved.json 不一致即阻斷發布。
| 現象 | 可能原因 | 處理 |
|---|---|---|
| 僅單節點任務 schema 錯誤 | 技能次版本不同或安裝不完整 | 依鎖檔重裝；清除快取 wheel／構件 |
| A 節點認證正常、B 節點 401 | 模板未渲染或角色環境錯綁 | 比對渲染後 env；修正分角色密鑰綁定 |
| 間歇「找不到技能」 | 滾動重啟競態 | 佇列暫停或 drain；入口健康後再滾工作者 |
灰度與回滾
先灰度再全量；系統保留上一版模板與鎖檔標籤，回滾＝指標切回。
滾動發布與校驗步驟清單
- 凍結佇列或開 drain，避免長任務在切換中途開始。
- 灰度節點：下發新渲染 env＋鎖定技能；重啟 OpenClaw；跑煙霧（讀設定、入佇列、執行、回報）。
- 以相同
trace_id或任務前綴，比對灰度與對照節點日誌。 - 擴至約 25%／50%／100% 工作者；觀察錯誤率與任務 p95。
- 任一校驗失敗：還原上一版模板雜湊與鎖檔；依依賴反向順序重啟（若共用入口，注意工作者先後）。
有流量調度時，健康檢查應含技能就緒（見負載與故障轉移）。
日誌對齊與排錯
統一日誌欄位（含 node_id、skill_version、template_revision）並匯入同一後端。發布期全節點共用 deployment_id；管線脫敏、勿在 CI 印出完整 env。失敗時先比對各機 skills.resolved.json 與建置字串再改碼。
驗收清單
模板或技能變更後，在標記網格健康前請逐項確認：
- ☐ 各節點啟動日誌中 OpenClaw 版本字串與
template_revision一致。 - ☐ 各節點
skills.resolved.json位元組級相同，或符合團隊定義的語意相等政策。 - ☐ 部署後每種
NODE_ROLE至少通過一次煙霧任務。 - ☐ 每季至少演練一次回滾：在時限內還原上一版鎖檔＋模板。