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 与裸机，可把本节矩阵当作「同版本、双轨道」验收的母版。
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。
| 维度 | 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 镜像发布，减少探针与绑定类事故。