2026 年 OpenClaw Gateway Kubernetes 部署與驗收 Runbook：版本固定、Resource 配額、bind=lan、port-forward 與典型 OOM/NotReady 回滾（FAQ + 與遠端實體 Mac 裸機對照）
平台與 SRE 團隊在把 OpenClaw Gateway 放進 Kubernetes 時，常被「鏡像漂移、探針誤殺、綁定位址與 Service 不一致、port-forward 與真實流量路徑脫節，以及 OOM/NotReady 該回滾還是該調參」拖住簽字。本文給出可掃描的 K8s 與遠端實體 Mac 裸機對照矩陣、七步 Runbook、可寫進變更單的 閾值與參數清單，以及依症狀分診的 FAQ。
1. 導語：為什麼 K8s 上的閘道驗收要比裸機多一層「網路與 cgroup 證據」
裸機上你聽見的「埠起來了」往往等價於行程綁定成功；在 Kubernetes 裡，同樣一行日誌背後還要經過 Service Endpoints、kube-proxy（或 CNI）、NetworkPolicy 與 cgroup memory 四層解釋。OpenClaw Gateway 若仍沿用開發機上的 127.0.0.1 心智，很容易在叢集裡出現「curl 進 Pod 能通、經 Service 全掛」或「就緒永遠紅但行程明明活著」的假陰性。
本文把驗收拆成可簽字的證據鏈：鏡像 digest 與 Helm values 雜湊、requests/limits 與 OOM 事件對齊、bind=lan 與 targetPort 一致、port-forward 冒煙與叢集內探測對照。若你同時在 遠端 Mac 上評估 Docker Compose 與裸機，可把本節矩陣當作「同版本、雙軌道」驗收的母版。若要先把 ZoneMac 實體節點上的 OpenClaw 業務流跑通，亦可參考 ZoneMac 物理節點 24/7 AI 智能體部署指南 的落地順序。
2. 三類痛點：版本漂移、綁定與探針、配額與雜訊流量
- 版本漂移與不可複現：生產使用
:latest或「只記 tag 不記 digest」，兩週後同 tag 重建即行為變化；回滾時無法證明舊副本與目前 incidents 是否同一二進位。 - 綁定位址、Service 與探針三者打架：閘道監聽回環而 readiness 去敲 Pod IP；或 bind=lan 但 NetworkPolicy 只放行來自 Ingress 網段，健康檢查源不在白名單，導致 NotReady 與流量中斷並存。
- Resource 配額與隱性成本：未設 requests 時排程看似成功，節點擠爆後觸發延遲 OOM；limits 過小則在工具呼叫高峰被 cgroup 直接殺行程，日誌只剩 Exit 137，若無指標很難區分洩漏與正常尖峰。
3. 決策矩陣：Kubernetes 與遠端實體 Mac 裸機
用一張表對齊「誰在什麼約束下更省事」，避免把裸機 launchd 的經驗原樣貼進 Pod。多區域延遲與節點選址也可一併對照 Mac 雲端伺服器地區選擇（含延遲對比）。
| 維度 | Kubernetes（Deployment + Service） | 遠端實體 Mac 裸機／launchd |
|---|---|---|
| 監聽綁定 | 需 bind=lan（或 0.0.0.0）以便 Service 命中；回環僅適合同 Pod sidecar |
可配合反代只綁 127.0.0.1，由 nginx／Caddy 終止 TLS |
| 版本固定 | 鏡像 digest + chart version + values 雜湊歸檔 | 安裝包校驗和 + brew／pnpm 鎖檔 + launchd plist 版本欄位 |
| 資源隔離 | cgroup OOMKilled、CPU throttle 可稽核 | 依賴統一記憶體與系統交換策略，需額外看記憶體壓力與溫控降頻 |
| 臨時驗收 | kubectl port-forward 適合冒煙，不等價叢集內全鏈路 |
curl 本機環回或 SSH 隧道，路徑更短但缺少多副本視角 |
| 典型故障回滾 | kubectl rollout undo 或固定上一 digest |
替換二進位／鏡像標籤 + launchctl kickstart -k，注意單實例鎖 |
4. 七步落地 Runbook（含 bind=lan 與 port-forward）
- 釘死版本：CI 在部署工單裡寫入鏡像
repo@sha256:…、Helm chart 版本與values.yaml的 git SHA；禁止生產流水線依賴浮動 tag。 - 宣告 Resource：為閘道設定
requests.memory接近 P95 常駐工作集，limits.memory留出工具呼叫與 JSON 緩衝峰值；CPU requests 避免排程到已飽和節點。 - 對齊 bind 與埠：若流量經 Service／Ingress 進入，閘道設定使用
bind=lan（或文件規定的雙堆疊監聽），並核對containerPort、targetPort、探針埠三者一致。 - 設定探針：readiness 使用與真實流量相同的三元組（協定、主機、路徑）；為冷啟動設定
initialDelaySeconds／startupProbe，避免 NotReady 誤殺正在載入 skills 的行程。 - port-forward 冒煙：維運機執行
kubectl port-forward deploy/openclaw-gateway 18789:18789（埠依實際替換），完成最小健康檢查與單條工具呼叫；同時在叢集內 Pod 發起一次同源探測，記錄兩條路徑是否一致。 - 觀測與告警：將重啟次數、OOMKilled、就緒=false 持續時間、5xx 與閘道佇列深度綁定到同一儀表板；變更視窗前後各保留 24h 對照。
- 裸機對照簽字：在遠端實體 Mac 上以同 digest 的本機執行方式（或 用戶端到 macOS 閘道的聯調 Runbook）重複關鍵健康訊號，差異寫入交付說明。長期無人值守場景可參考 Mac mini 上 OpenClaw 穩定性最佳化 的基線。
5. 可引用閾值與參數清單
- 鏡像釘死：生產工單必須同時包含 digest 與建置號；回滾目標與 incident 時間戳可交叉驗證。
- 記憶體緩衝：在觀測到工具呼叫尖峰的前提下，limits 建議至少高於 P95 常駐 25%–40% 的可解釋緩衝，否則優先限流而非盲目加倍。
- 探針起步：冷啟動超過 30s 的閘道，readiness 應配 startupProbe 或不少於 40–60s 的寬限期，與 OpenClaw 載入 workspace／skills 的耗時同量級。
- port-forward：僅作冒煙；簽字級 SLO 須包含叢集內 Service 名稱解析與 Ingress／TLS 全路徑。
6. FAQ：OOM、NotReady 與回滾
bind=lan 會不會擴大暴露面？
在 Pod 內監聽非回環位址並不等於對公網開放；暴露面由 Service type、Ingress、NetworkPolicy 與叢集出口策略共同決定。應把「行程監聽」與「誰能路由到 Pod」分層稽核。
OOMKilled 第一步看什麼？
看 kubectl describe pod 的 Last State、節點記憶體壓力事件與容器退出碼 137；對照同一時間段的閘道併發與單請求體大小，避免把正常尖峰誤判為洩漏。
NotReady 但日誌已印出 listening，優先改什麼？
優先核對探針 URL 是否指向錯誤埠或路徑、是否缺少 startupProbe，以及 NetworkPolicy 是否放行 kubelet 探針源；再考慮應用層路由是否在就緒後才掛載。
回滾策略怎麼寫才合規？
保留上一版本的 digest 與 Helm revision；kubectl rollout undo 後立刻跑一次叢集內健康探測與最小業務握手，並把證據鏈附在變更單上。
7. 在 Mac mini 上對齊同版本閘道為什麼更省事
Kubernetes 路線解決的是多副本、滾動發佈與配額稽核；而遠端實體 Mac（例如 Mac mini M4）仍是許多團隊做簽名、螢幕共享與 Apple 生態聯調的事實標準環境。把同 digest 的閘道先在 macOS 上跑通 launchd 基線，再推進叢集鏡像，能顯著減少「叢集裡才暴露的綁定與探針問題」在變更後期集中爆發。
macOS 上 Unix 工具鏈與 SSH 開箱即用，Apple Silicon 的統一記憶體在長時間閘道行程下往往比同價位小主機更穩，待機功耗約 4W 量級也適合 7×24 對照實驗而不心疼電費。若你希望同一套 OpenClaw 版本在「叢集 + 裸機」兩條軌道上都拿到可簽字的健康訊號，一台靜音、低功耗、長期執行穩定的 Mac mini M4 是非常划算的對照台。
如果你正要把本文 Runbook 落到真實硬體上驗證，不妨現在就把 Mac mini M4 當作標準對照節點，再與生產叢集並行簽字。
用 Mac mini 做叢集外的「黃金對照」節點
同版本閘道先在遠端 macOS 上簽字，再推進 K8s 鏡像發佈，減少探針與綁定類事故。