2026 OpenClaw Gateway 健康檢查與滾動更新
Docker Compose／Kubernetes 探測與零停機 Runbook

約 20 分鐘閱讀 · MACCOME

在 Docker 或 Kubernetes 上運行 OpenClaw Gateway 的團隊，2026 年常快速迭代，卻仍把「容器在跑」當成「健康」。若同一張變更單沒有對齊 HTTP 探測路徑、就緒語意與滾動參數，就容易出現冷啟動時被存活探測誤殺、depends_on 只等容器不等就緒，或把 供應商 429 誤判成 Gateway 死掉而無限重啟。本文與《Docker 生產向部署》《版本升級與執行態遷移》《多模型 provider 路由與故障降級》分工，並提供 六條可寫進 RCA 的探測陷阱、存活／就緒／啟動矩陣、Compose 與 Kubernetes 對照、可貼上 YAML 片段、六步上線 Runbook、三條儀表板硬指標，以及如何把 Gateway 放在 穩定的遠端 Mac 執行平面。

從「埠有開」到正確語意：六種探測陷阱

近期 OpenClaw 版本會提供便於編排器使用的 HTTP 端點（實際路徑與埠請依 您鎖定的映像標籤與發行說明；生態中常見 /health、/ready、/healthz 等命名）。請把下列六種模式寫進 RCA，並沿用《doctor 與裝後排錯》的用語。

  1. 存活探測打到「行程在、業務未就緒」：冷啟動載入路由表或本地狀態——過早回 200 會放流量進來；過早失敗會被 kubelet 殺掉。
  2. 就緒探測綁死外部模型：節流可能讓整個叢集卸載流量——請確認是否符合 SLO，而非誤當全域故障。
  3. Compose 的 depends_on 沒有 health 條件：依賴服務在 Gateway 尚未接住後端 socket 時就起來——間歇 502。
  4. localhost 探測與 Service 路徑不一致：Pod 內 127.0.0.1 可用、ClusterIP 不可用——常被誤判成應用掛掉。
  5. maxUnavailable 過於激進：舊 Pod 排空時新 Pod 尚未通過就緒——出現短暫全紅窗口。
  6. 日誌分層混雜：TLS 終止、Proxy 逾時與 Gateway 錯誤疊在一起——探測被盲目收緊。

相對《三平臺安裝部署指南》：安裝篇處理首次開機；生產篇處理長期維運；本篇處理 編排器如何判定健康；升級篇處理 映像切換與回滾。

表一：存活、就緒與啟動探測——如何切分職責

Kubernetes 探測類型與 Docker healthcheck 的重啟語意並非一一對應；架構評審時請用此表。

檢查典型失敗效果驗證內容OpenClaw 取向建議
startupProbe在成功前抑制存活失敗慢但有限的冷啟動首次拉設定、索引或依賴需數分鐘時使用
livenessProbe重啟容器／Pod死鎖、行程無回應避免依賴外部 LLM；僅做最小自檢
readinessProbe從 Service endpoints 移除尚未能接流量可含輕量模型 ping 或設定載入信號——與降級政策對齊
Docker healthcheck標記 unhealthy；是否重啟視政策單機 Compose搭配 depends_on: condition: service_healthy（語法依 Compose v2 文檔）

表二：同一條「健康」需求在 Compose 與 Kubernetes 的寫法

把「健康」翻成具體欄位，可減少半夜爭論。

維度Docker Compose（模式）Kubernetes Deployment
探測指令healthcheck.test 搭配 curl／wgethttpGet 或 exec
啟動寬限start_periodstartupProbe 或較大的 initialDelaySeconds
卸載流量Proxy／LB 層或僅 health 標籤readinessProbe 控制 Endpoints
滾動手動 compose 順序或外部 CDmaxSurge／maxUnavailable／minReadySeconds
yaml
# 示例——請依您標籤的文檔替換 PORT 與路徑
# Docker Compose（片段）
healthcheck:
  test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:${GATEWAY_PORT}/health || exit 1"]
  interval: 15s
  timeout: 3s
  retries: 5
  start_period: 120s

# Kubernetes（片段）
readinessProbe:
  httpGet:
    path: /ready
    port: http
  initialDelaySeconds: 10
  periodSeconds: 10
livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 20
warning

注意：上游在 2026.3.x 類版次可能新增或更名 /health、/ready、/healthz。複製片段前請確認 您 digest／標籤對應的官方文檔，並在測試環境用 curl -v 驗證。

六步上線 Runbook：從容器內 curl 200 到可回滾的滾動更新

  1. 鎖定版次錨點：記錄映像 digest 或次版本標籤，以及文檔中的健康路徑與埠。
  2. 在容器內驗證：先對 127.0.0.1 用 docker compose exec 或 kubectl exec 探測，再經 Service 驗證。
  3. 先就緒、後存活：穩定就緒與啟動探測後，再收緊存活，避免啟動期被誤殺。
  4. 調整滾動參數：部署期間至少保留一個可服務副本；將 maxUnavailable 與維護窗口寫進 Runbook。
  5. 對齊 provider 降級：外部模型故障時要卸載、降級模型或僅告警——依 provider 路由文檔寫清楚。
  6. 演練回滾：依升級清單重標映像並還原卷；確認探測仍與舊版行為一致。

三條硬指標：儀表板與值班

  1. 探測三件套：HTTP 狀態碼、延遲分位數、連續失敗次數——與 Ingress 502 比率並列。
  2. 部署中就緒副本／期望副本：就緒長時間低於 100% 要告警；頻繁小版本會壓縮該窗口。
  3. 外部依賴錯誤占比：供應商 429／5xx 對 Gateway 內部錯誤——欄位與 provider 路由文共用。

走《Linux systemd 與 Cloudflare Tunnel》路線時，請對齊隧道健康、loopback 監聽與上游 LB 檢查，否則易出現「隧道通、Gateway 未監聽」的假陽性。

將 kubectl rollout status 或 compose 升級日誌與 Git 變更對照，以區分探測過嚴與映像迴歸。

為何消費級 NAS 或備用筆電難以支撐生產級探測語意

消費設備受睡眠、磁碟抖動與非計畫系統更新影響，啟動時間與探測門檻會漂移；搭配滾動窗口會大量消耗值班時間。要以 可預期 SLA 運行 OpenClaw 與代理程式，需要專用算力、穩定出口與可承受峰值的節點。

分散自託管也讓多地區延遲與合約營運更難收斂：筆電上探測調優與主機重啟綁在一起很痛苦。若要 7×24 可觀測、可滾動、可回滾 的 Gateway，專業多地區 Apple Silicon 雲端 Mac 通常勝過臨時硬體。MACCOME 提供 Mac Mini M4／M4 Pro 裸金屬與彈性租期，可作 Gateway 或混合自動化主機；請先從《協助中心》了解接入語言，再對照《租賃價格》與《多地區節點指南》敲定 SKU。

試點建議：在目標區域短租，跑容器探測、Service 探測與一次完整滾動演練，再決定月租或季租。

常見問題

探測失敗但介面能開，以哪個為準？

以編排器設定的 URL 與狀態碼為準。計費與周期見 租賃價格說明；探測請在測試環境用容器內 curl 復現。

與 Docker 生產篇如何一起用？

生產篇講卷與令牌；本篇講探測與滾動。請把兩篇與《升級遷移》附在同一變更單。

429 該不該讓存活探測失敗？

一般不要——退避與路由請讀《多模型 provider 路由與故障降級》；就緒是否綁外部模型是明確的 SLO 選擇。接入細節亦可查 幫助中心。