发布期 5xx 尖峰不是偶发：K8s 优雅下线的时序陷阱与一份可直接抄的 preStop 配置

结论先行：滚动发布期间那波「每次都来、但每次又只持续几十秒」的 5xx，根因几乎都是优雅下线的时序没配对，而不是代码 bug。这篇文章给一份我能直接抄的 preStop + terminationGracePeriodSeconds 配置，以及一个反直觉的点：terminationGracePeriodSeconds 是从收到 SIGTERM 开始计时，不包含 preStop 之前的摘流时间。

一、现象与背景：每次发布，5xx 必然涨一波

先交代规模。一个 40 节点（8C16G，Kubernetes 1.29.3，containerd 1.7.13）的 Java 服务集群，单 Pod 4 副本起步、高峰期 60 副本，走 Ingress → Service → Pod，上游是长连接池（HTTP keep-alive）。

过去半年，每次滚动发布，Grafana 上都会出现一个非常规律的现象：

• 5xx 在发布开始的 30~90 秒内集中出现，单次发布大约 1800~4200 条（按 QPS 高低的接口波动）；
• 发布结束后立刻归零；
• 错误几乎全是 502 Bad Gateway 和 504 Gateway Timeout，不是 500；
• 关键反直觉点：Pod 的 CPU、内存、GC 全程健康，应用日志里几乎没有异常栈。

502/504 这两个码其实已经把方向指出来了：这不是应用算错了，而是请求被路由到了一台正在死掉的 Pod——连接被对端 RST，或新连接直接连不上。

二、根因：摘流、SIGTERM、连接断开三者的时序错配

把一次「下线一个 Pod」的过程拆开，理想顺序应该是：

1. Endpoint 摘除：Service 不再把新流量路由给这个 Pod（这是秒级，但 DNS/客户端连接池里可能还残留）；
2. 上游把存量在途请求处理完；
3. 收到 SIGTERM，应用优雅停机（拒绝新请求、等在途请求结束）；
4. 超时后 SIGKILL。

我们原来的配置只做了两件事：terminationGracePeriodSeconds: 30，应用里注册了一个 SIGTERM handler「等 20 秒再退出」。看起来挺标准，但漏了两环：

坑 1：Endpoint 摘除 ≠ 流量立即停。 K8s 里 Endpoint 更新后，kube-proxy/IPVS 的同步是有延迟的，而上游客户端的 keep-alive 长连接池里，那条 TCP 连接还指着这个 Pod 的 IP。新来的请求会复用这条旧连接直接打过去——此时 Pod 已经开始优雅停机、不再 accept，于是 connection reset → 502。这就是为什么 502/504 是主力，而不是 500。

坑 2：terminationGracePeriodSeconds 的计时起点被普遍误解。 这是最反直觉的一点。很多人以为它是「Pod 从开始下线到结束的总时长」。实际上，它从 kubelet 向容器发 SIGTERM 那一刻才开始计时，而 preStop hook 的执行时间是包含在这 30 秒之内的，不是额外赠送的。更麻烦的是：发 SIGTERM 之前，K8s 还会先做 Endpoint 摘除 + 等待，这段时间根本不进 grace 的倒计时，但上游连接池里的旧连接此时还在灌流量。

结果就是：摘流还没真正生效，SIGTERM 已经发了，应用开始拒新请求，可长连接里的在途请求还在飞——这批请求就成了 502/504。

三、具体做法：一份可复现的配置

核心思路：用 preStop 的 sleep 给「摘流 + 上游连接池收敛」留出时间，再让应用优雅停机，且把 grace 时间给足。

spec:
  terminationGracePeriodSeconds: 60   # 总预算，含 preStop + 优雅停机
  containers:
  - name: app
    lifecycle:
      preStop:
        exec:
          command: ["sh", "-c", "sleep 10"]   # 先睡 10s 等 Endpoint/连接池收敛
    readinessProbe:
      httpGet: { path: /ready, port: 8080 }
      periodSeconds: 2
      failureThreshold: 1               # readiness 一旦失败，立刻摘流
    livenessProbe:
      httpGet: { path: /live, port: 8080 }
      periodSeconds: 10

应用侧（以 Spring Boot 为例）配合两点：

1. 优雅停机开关打开，并显式给停机一个上限，避免在途请求卡死把 grace 耗光：

   server.shutdown=graceful
   spring.lifecycle.timeout-per-shutdown-phase=30s
   

2. SIGTERM handler 不要自己 sleep 固定 20 秒——preStop 的 sleep 已经承担了「等摘流」的职责，应用收到 SIGTERM 后应立刻停止接新请求、只等在途请求结束。两处都 sleep 会把时间算重，反而更容易撞穿 grace 被 SIGKILL。

时序对齐后（grace 60s = preStop 10s + 优雅停机 30s + 余量 20s），我们观察到单次发布 5xx 从 4200 条降到 20~60 条，剩下的基本都是个别长连接里恰好卡着的慢请求，属于可接受长尾。

四、踩过的坑与反直觉之处

1. terminationGracePeriodSeconds 不含 preStop 之前的摘流时间——这是最多人算错的地方。它从 SIGTERM 开始计时，preStop 的耗时是扣在这段里的，不是额外的。
2. 别在 preStop 和应用 handler 里双重 sleep。两边都想「等一等」，结果总耗时超出 grace，Pod 直接被 SIGKILL，5xx 反而更惨。要么 preStop 睡、应用快停，要么反之。
3. readinessProbe 的 failureThreshold 要设 1。默认 3 意味着 readiness 挂了还要再等 3 个周期才真正摘流，发布窗口被拉长。设为 1，一失败立刻摘。
4. 502/504 多而 500 少，是「路由到死 Pod」的指纹。如果发布期大量 500，那才更可能是应用本身没优雅停机（比如直接 System.exit 把在途请求全打断）。
5. DNS 客户端缓存是隐藏杀手。如果上游是用域名（而非 Service IP）直连，且本地 DNS 有 TTL 缓存，Endpoint 摘了它也不知道。能走 IPVS/kube-proxy 就尽量别走裸域名。

五、结论与可复用清单

发布期 5xx 尖峰，90% 是「摘流—SIGTERM—连接断开」三者时序没对齐，而不是业务代码问题。可复用清单：

• [ ] terminationGracePeriodSeconds 给足（建议 ≥ 60s），并记住它从 SIGTERM 起算、包含 preStop；
• [ ] preStop 里 sleep 5~10s 给摘流和上游连接池收敛留时间；
• [ ] 应用侧开 graceful shutdown，并设 timeout-per-shutdown-phase 上限，不要再叠加固定 sleep；
• [ ] readinessProbe failureThreshold: 1，让摘流尽量快；
• [ ] 用 5xx 的错误码分布定位问题：502/504 多 → 时序/连接问题；500 多 → 应用没优雅停机；
• [ ] 上游走 Service IP / IPVS，避免域名 DNS 缓存残留。

这套配置我们已经在 3 个 Java 服务上验证，发布 5xx 基本压到个位数~几十条的长尾水平。它不解决代码问题，但它能保证「发布这个动作本身」不再制造 5xx。