K8s下Go长连接Pod优雅下线方案

本文深入剖析了Kubernetes环境下Go语言构建的长连接服务（如WebSocket）在Pod下线时面临的平滑退出难题：由于net/http.Server.Shutdown()天然不感知升级后的长连接，若不手动接管连接生命周期管理，将导致连接被粗暴强杀、客户端收到1006错误；文章系统性地给出了可落地的解决方案——通过sync.Map自主追踪连接、主动发送CloseMessage并设置独立超时，结合preStop hook触发优雅拒绝新请求、readinessProbe动态摘流，合理错开K8s terminationGracePeriodSeconds与Go各层超时时间，并同步强制刷新本地有状态数据（缓存、日志、会话等），真正实现“不断连、不丢数、不误判”的生产级平滑下线。

Go HTTP Server.Shutdown() 为什么等不到 WebSocket 连接关闭

http.Server.Shutdown() 只跟踪标准 HTTP handler 的生命周期，对已升级的 WebSocket 连接、text/event-stream 响应、HTTP/2 流等完全无感——它们复用底层 TCP 连接，但 net/http 不维护其引用。结果就是：调用 Shutdown() 后，只要还有活跃 WebSocket 客户端，连接不会断，也不会阻塞退出，超时后直接被 SIGKILL 强杀，客户端收到 1006 错误。

必须自己管理长连接生命周期：

• 用 sync.Map 或带锁 map 存储所有活跃连接（key 为 conn ID 或 remote addr）
• 在 Upgrade 成功后立即存入；在 conn.Close() 或 ctx.Done() 触发时主动删除
• 在收到 SIGTERM 后，遍历 map 调用 conn.WriteMessage(websocket.CloseMessage, ...) 主动通知关闭，并等待 conn.ReadMessage() 返回 error 或超时
• 给长连接清理单独设 timeout（比如 15 秒），别和 HTTP server shutdown 共用一个 context

preStop hook 和 readinessProbe 怎么配合才能真正“先断流”

K8s 确实会在发 SIGTERM 前移除 Endpoints，但这个动作依赖 EndpointController 的同步周期（默认秒级），存在小窗口期；而 preStop 是同步执行、无延迟的——这才是你可控的“断流开关”。

推荐做法是让 preStop 触发一个本地 HTTP 请求，把服务切到“拒绝新连接”状态：

• preStop 配置为：curl -X POST http://localhost:8080/shutdown（注意加 timeout 参数防卡住）
• Go 里 /shutdown handler 设置全局 shuttingDown = true，后续所有新请求返回 503 Service Unavailable
• readinessProbe 改为探测 /readyz，且逻辑里检查 shuttingDown，为 true 就立刻失败
• 这样 K8s 在几秒内就会把 Pod 从 Endpoints 摘掉，比纯靠 controller 同步更及时

terminationGracePeriodSeconds 和 Go shutdown timeout 必须错开

默认 terminationGracePeriodSeconds: 30，但如果你在 Go 里也设 context.WithTimeout(ctx, 30*time.Second)，就等于没留余量。K8s 从发 SIGTERM 到最终发 SIGKILL 是刚性倒计时，而 Go 层要花时间做三件事：响应信号 → 关闭 listener → 等待长连接退出。任一环节超时都会被强杀。

安全配法：

• K8s 层设 terminationGracePeriodSeconds: 45
• Go 层 Shutdown() 用 context.WithTimeout(ctx, 35*time.Second)
• 长连接单独清理用 context.WithTimeout(ctx, 15*time.Second)
• 预留 10 秒缓冲给 kernel 关闭 socket、TCP FIN 交换等底层耗时

有状态服务下线时，本地缓存/内存数据怎么保不丢

长连接服务常带会话态、本地缓存、未 flush 日志 buffer。这些不是 HTTP 连接本身，但用户感知一样：连接断了，数据就没了。

关键动作不是“等”，而是“确认”：

• 收到 SIGTERM 后，立即禁写新数据（如关掉 log.SetOutput()、停掉定时 cache refresh）
• 触发一次强制 flush：调用 log.Sync()、cache.SaveToDisk()、db.Close()（如果用的是带 buffer 的 driver）
• 不要等异步 goroutine 完成——比如 go flushCache() 后就返回，Shutdown() 会认为请求已结束，但实际还在跑
• 所有 flush 操作必须同步、带超时、失败即 log.Warn，不能 panic 或阻塞

真正的难点不在代码怎么写，而在你是否清楚哪些数据路径是“有状态”的：WebSocket 消息队列？内存 session store？未 commit 的本地事务？这些地方漏一个，平滑下线就变成“假装平滑”。

终于介绍完啦！小伙伴们，这篇关于《K8s下Go长连接Pod优雅下线方案》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布Golang相关知识，快来关注吧！