根本原因是readiness状态变更、LB摘流、HTTP连接排空、依赖关闭四环节未协同;需用原子变量控制readiness端点、设IdleTimeout并异步调Shutdown、Consul反注册须在Shutdown后os.Exit前、gRPC用GracefulStop、DB先限连再关闭、signal监听SIGTERM且Go进程须为PID 1。

Go 服务在 Kubernetes 中下线时出现 502/503 或连接拒绝,根本原因不是代码没写 Shutdown(),而是 readiness 状态变更、LB 摘流、HTTP 连接排空、依赖关闭这四件事没串起来——任何一环脱节,流量就丢。
readiness 端点必须可变且不查外部资源
很多服务把 /health 同时当 liveness 和 readiness 用,这是平滑下线失败的起点。liveness 只能检查进程是否卡死(比如 runtime.NumGoroutine() 阈值),readiness 必须能被主动置 false。
- 用
atomic.StoreInt32(&ready, 0)控制状态,别用 mutex 或 channel,避免 handler 阻塞 -
readinessHandler里只读这个变量,不查 DB、Redis、不调下游——否则摘流延迟不可控 - Kubernetes 的
readinessProbe必须指向这个端点,failureThreshold: 1,periodSeconds设为 3~5 秒(必须小于整个 shutdown 耗时)
srv.Shutdown() 必须设 IdleTimeout 且异步调用
http.Server.Shutdown() 默认不等活跃连接结束,它只发信号停收新请求。没设 IdleTimeout,正在写的 response 很可能被截断。
- 提前设置
srv.IdleTimeout = 30 * time.Second,不能依赖默认值(0) - 必须异步调用:
go srv.Shutdown(ctx),否则主 goroutine 卡住,后续 Consul 反注册、gRPC 关闭全失效 -
ctx要用context.WithTimeout(context.Background(), 35*time.Second),超时值得比 K8s 的terminationGracePeriodSeconds小至少 5 秒 - 检查返回 error:
context.DeadlineExceeded是超时(有请求卡住),http.ErrServerClosed是正常,其他 error(如net.OpError)要记录
Consul 反注册和 gRPC/DB 关闭顺序不能错
srv.Shutdown() 只管 HTTP 层,gRPC、DB、消息消费者这些全得你亲手关,而且顺序错了会 panic 或丢数据。
- Consul 反注册必须在
srv.Shutdown()返回后、os.Exit(0)前执行;早了——LB 已摘流但 HTTP 还在收请求;晚了——进程已退出,反注册发不出去 - 反注册前先调
client.Agent().ServiceByID(serviceID)校验服务是否存在,避免静默 404 掩盖注册失败 -
client.Config.HttpClient.Timeout必须设为1500 * time.Millisecond,默认 30 秒会卡死主线程 - gRPC server 用
grpcServer.GracefulStop(),不是Stop();DB 关闭前建议先db.SetMaxOpenConns(1)加速连接归还,再db.Close()
preStop 钩子和 signal.Notify 必须协同
Kubernetes 发 SIGTERM 后,你的 Go 进程必须立刻响应。如果容器主进程不是 PID 1,或者被 shell 包了一层,信号根本收不到。
-
signal.Notify必须同时监听syscall.SIGTERM和os.Interrupt:K8s 发前者,本地Ctrl+C发后者 - channel 必须带缓冲:
make(chan os.Signal, 1),否则第一个信号可能丢失 - preStop 钩子不是万能的——它只是给你一个“提前执行命令”的机会,真正靠得住的还是应用自身对信号的响应
- Dockerfile 中避免
command: ["sh", "-c", "exec ./myapp"],要用exec ./myapp确保 Go 进程是 PID 1,能直接收到信号
最容易被忽略的其实是 readiness 状态的可见性延迟:哪怕你原子变量改了,如果 Envoy 或 Nginx 的健康检查间隔比你的 shutdown 总耗时还长,就会出现“已置 false 但 LB 还没轮到它”的窗口期。这不是代码问题,是配置节奏没对齐。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











