2026 OpenClaw Gateway 健康检查与滚动更新
Docker Compose / Kubernetes 探活、就绪与零停机清单

约 20 分钟阅读 · MACCOME

已用 Docker 或 Kubernetes 承载 OpenClaw Gateway 的团队在 2026 年发版节奏加快时，如果只关注「容器能起」，却未把 HTTP 探活路径、就绪语义与滚动策略写进同一套变更单，常见事故是：启动期被 liveness 误杀、depends_on 只等容器起不等业务就绪、或把模型供应商 429误当成 Gateway 本体崩溃而无限重启。📌 本文与《Docker 生产向部署》《版本升级与迁移》《provider 降级》分工，给出六类可写进 RCA 的痛点、liveness/readiness/startup 对照表、Compose 与 K8s 映射、可复制 YAML/Compose 片段、六步发布 Runbook、三条面板口径；并说明如何把 Gateway 落在可值班的远程 Mac执行面上。

先把「探活」从端口通升级成语义正确：六类高频坑

Gateway 在 2026.x 周期内持续补齐面向编排的 HTTP 端点（具体路径与端口以你锁定的镜像 tag / Release Notes为准，常见命名包括 /health、/ready、/healthz 等变体）。下列痛点建议直接写进 RCA，并与《doctor 与装后排错》中的症状分诊共用同一词汇表。

  1. liveness 探到「进程在但业务未就绪」：冷启动要加载模型路由或迁移本地状态，过早 200 会让流量涌入；过早失败又会被 kubelet 杀掉。
  2. readiness 依赖外部模型可用：供应商限流时全集群摘流量，可能优于无限重启，但若与业务 SLO 不匹配会「全局不可用」。
  3. Compose 的 depends_on 不含健康条件：依赖服务容器已起但 Gateway 仍连不上后端 socket，表现为间歇 502。
  4. 探针走 localhost 与走 Service 不一致：Pod 内 127.0.0.1 通而 ClusterIP 不通时，误判为应用故障。
  5. 滚动 maxUnavailable 过激进：旧 Pod 已摘流、新 Pod 尚未 ready，出现短窗口全红。
  6. 日志分诊错位：把 TLS 终止、反向代理超时与 Gateway 内部报错混为一谈，探针越调越激进。

与《三平台安装入门》对照：安装篇解决「第一次跑起来」；生产篇解决「长期值班」；本篇解决编排层如何判定健康；升级迁移篇解决换镜像时的窗口与回滚。

表 1：liveness、readiness、startup 探针该怎么分工（评审版）

Kubernetes 三类探针与 Docker healthcheck 的「是否重启容器」语义并不完全相同；下表给出可放进架构评审附件的读法。

检查类型失败时典型动作适合验证什么OpenClaw 场景建议
startupProbe在成功前不触发 liveness 失败冷启动很慢但有终点首次拉配置、建本地索引、连依赖耗时分钟级时优先加
livenessProbe重启容器/Pod进程死锁、无响应避免依赖外部 LLM；只反映 Gateway 进程自身能否响应最小自检
readinessProbe从 Service 摘流暂不可接流量可包含「最小模型 ping」或「配置加载完成」；与 provider 降级策略对齐
Docker healthcheck（无 K8s）标记 unhealthy，是否重启取决于策略单机 Compose 编排与 depends_on: condition: service_healthy 组合使用（Compose v2 语法以文档为准）

表 2：同样一条「健康」需求在 Compose 与 K8s 下的落地差异

把「健康」翻译成具体字段，可减少上线夜里的口头对齐成本。

维度Docker Compose（示例思路）Kubernetes Deployment
探测命令healthcheck.test 内嵌 curl/wgethttpGet 或 exec 探针
启动宽限start_periodstartupProbe 或较大的 initialDelaySeconds
摘流语义依赖反向代理/上层 LB 自建；或仅用 health 标记readinessProbe 直接控制 Endpoints
滚动手工 compose up 顺序或外部 CDmaxSurge / maxUnavailable / minReadySeconds
yaml
# 片段示例：务必替换 PORT 与 path 为当前版本文档中的值
# 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/tag 对应的官方文档为准，并在 staging 用 curl -v 复现状态码。

六步发布 Runbook：从「能对 curl 返回 200」到「可回滚的滚动」

  1. 锁定版本锚点：镜像 digest 或次要版本号写入变更单；同步记录文档中的 health 路径与端口。
  2. 在容器内验证：docker compose exec / kubectl exec 内对 127.0.0.1 探测，再验证 Service 路径。
  3. 先 readiness 后 liveness：调通 readiness 与 startup，再收紧 liveness，避免启动期误杀。
  4. 配置滚动参数：至少保证任一时刻有一条可服务副本；记录 maxUnavailable 与发布窗口关系。
  5. 对齐 provider 降级：外部模型故障时的期望行为写清：摘流、降级模型还是仅告警——见《provider 降级》篇。
  6. 演练回滚：按《升级迁移》清单执行镜像回指与卷还原，验证探针在旧版本仍成立。

三条应写进面板与值班的「硬核」口径

  1. 探针结果三元组：状态码、延迟分位、连续失败次数；与 Nginx/Ingress 502 率同屏，避免只看应用日志。
  2. 发布窗内「就绪副本数 / 期望副本数」：滚动期低于 100% 的持续时间应可告警；2026 年常见「小步快发」会把该窗口压到分钟级，更需要自动化阈值。
  3. 外部依赖错误占比：429/5xx 来自供应商 vs Gateway 自身；与《provider 降级》中的路由统计共用字段。

若 Gateway 跑在《Linux systemd + Tunnel》路径，探针还应与隧道进程、本机回环地址及上游 LB 健康检查三层一致，否则会出现「隧道进程活着、Gateway 未监听」的假健康。

补充：将 rollout status 或 Compose 升级日志与 Git 变更关联，可在事后复盘时快速判断是探针过紧还是镜像回归。

为什么「家里 NAS / 闲置笔记本」难承载生产级 Gateway 探针语义

消费级设备上的睡眠、磁盘波动与不可控的系统更新，会让启动时间与探针阈值持续漂移；一旦与滚动发布窗口叠加，误杀与误流量会消耗值班人时。要把 OpenClaw 与自动化代理跑在可预期 SLA 的执行面，需要独占算力、稳定网络出口与可按峰值扩展的节点。

碎片化自管机也难做到多地区低延迟与合同化运维：探针调参、隧道与宿主机重启的耦合在笔记本上更难标准化。对需要7×24 可观测、可滚动、可回滚的 Gateway 而言，把执行层落在专业多地区 Apple Silicon 云 Mac 上，通常比临时设备更符合生产节奏。MACCOME 提供 Mac Mini M4 / M4 Pro 物理节点与弹性租期，可作为 Gateway 常驻或构建/自动化混合负载的执行面；先查 帮助中心 对齐接入与账单表述，再结合 租赁价格 与《多地区节点与租期指南》落单。

试点建议：在目标区域短租一台节点，跑满「容器内探针 + Service 探针 + 一次完整滚动」三步验收，再绑定月租/季租。

常见问题

探活失败但 UI 能开，该信谁？

以编排层配置的 URL 与返回码为准；需要对照价格与区域时打开 租赁价格说明，但探针问题应先在 staging 用容器内 curl 复现。

和 Docker 生产篇如何一起用？

生产篇写卷、令牌与常驻；本篇写探针与滚动。升级时两篇与《升级迁移》同附在变更单上。

429 要不要写进 liveness？

一般不要；应走《provider 降级》的分流与退避，readiness 是否感知外部依赖由 SLO 决定。