/healthz 和 /readyz 必须分开暴露:/healthz 仅检查进程存活(如原子变量或监听能力),不依赖外部服务;/readyz 才检查 DB、缓存等依赖,且超时≤1s;二者均需绕过鉴权/日志中间件,推荐独立端口监听,并用原子变量动态控制就绪状态。

/healthz 和 /readyz 必须分开暴露,不能共用一个 handler
很多人把两个探针写成同一个 http.HandlerFunc,结果数据库挂了但 livenessProbe 仍返回 200,Kubernetes 就不会重启 Pod;而 readinessProbe 失败又没做,流量照打进来,直接雪崩。真正的区分逻辑是:
-
livenessProbe对应/healthz:只检查进程是否卡死(比如用atomic.LoadInt32(&healthy)或能否 Accept 新连接),不碰 DB、Redis、gRPC 等任何外部依赖 -
readinessProbe对应/readyz:才查 DB 连接池是否满、本地缓存是否加载完成、下游 gRPCCheck()是否响应——但超时必须 ≤1s,否则 K8s 默认 1 秒超时会判失败 - 别用
/health:某些中间件(如 Gin 的 JWT 中间件)默认劫持该路径;/healthz和/readyz是社区事实标准,Kubernetes、Envoy、Nginx 都认
Gin/Echo 注册健康端点时,必须绕过全局中间件
框架的鉴权、日志、panic recover 中间件对每秒一次的探针是纯负担:JWT 解析可能触发远程校验,recover 捕获 panic 是好意,但健康端点本就不该 panic,日志中间件还会撑爆日志卷。正确做法不是“在中间件里加白名单”,而是注册时跳过:
- Gin:用
r.Any("/healthz", healthzHandler)并确保它在r.Use(...)之前注册;或者用r.NoRoute()拦截后手动分发 - Echo:必须写成
e.GET("/healthz", healthzHandler).SkipMiddleware = true,注意不是e.Use(...).Skip—— 后者无效 - 更稳妥的做法是:用原生
http.ServeMux单独起一个监听地址(如:8081),只挂健康端点,彻底和业务路由解耦
Kubernetes 探针配置必须和代码行为严格对齐
光写对 handler 不够,livenessProbe 和 readinessProbe 的 YAML 参数稍配错,就会导致滚动更新卡住、或反复 CrashLoopBackOff。关键参数要匹配真实行为:
-
initialDelaySeconds:Go 启动慢(比如加载大配置、初始化 gRPC client),livenessProbe至少设 15–30s,readinessProbe可设 10s,但不能比initialize()实际耗时还短 -
timeoutSeconds必须 ≤1s,且 handler 内部 DB Ping 要用ctx.WithTimeout(ctx, 900*time.Millisecond),留出网络缓冲余量 -
failureThreshold和periodSeconds要配合:比如 DB 抖动通常持续 2s,若periodSeconds: 5+failureThreshold: 1,一次抖动就杀 Pod;应设为failureThreshold: 3
就绪状态要用原子变量控制,不能靠启动完成就一劳永逸
服务运行中可能动态失能:比如收到 SIGTERM 后要 drain 流量、DB 连接池被上游限流打穿、本地缓存因 OOM 被清空。这些场景下,/readyz 必须能实时反映状态,而不是“启动时 ok 就永远 ok”:
- 声明
var isReady int32 = 0,在initialize()成功后atomic.StoreInt32(&isReady, 1) -
/readyzhandler 开头加if atomic.LoadInt32(&isReady) == 0 { http.Error(w, "not ready", http.StatusServiceUnavailable); return } - 收到
SIGTERM时,先atomic.StoreInt32(&isReady, 0),等所有 in-flight 请求结束再os.Exit(0)
最常被忽略的是:探针路径和 handler 行为必须可验证、可调试。上线前用 curl -v http://localhost:8080/healthz 看状态码和耗时,别等进 K8s 才发现超时或 401。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











