Go服务在Kubernetes中需严格区分/healthz(绕中间件、查进程状态)与/readyz(查依赖、限时≤1s、用缓存快照),并确保路径、端口、状态码精确匹配探针配置,否则将触发CrashLoopBackOff。

Go 服务在 Kubernetes 里不是“能返回 200 就算健康”,而是必须让 /healthz 和 /readyz 各司其职、绕过中间件、控制超时、并用原子状态反映真实运行意图——否则探针一抖,Pod 就进 CrashLoopBackOff。
为什么 /healthz 必须绕过所有中间件
鉴权、日志、CORS、panic recover 这些中间件对业务请求是刚需,但对每秒一次的 /healthz 是负担:JWT 解析可能耗时几十毫秒;recover 中间件捕获 panic 是好意,可健康端点本就不该 panic;日志中间件会把高频探针打爆日志卷。
- Gin 中注册顺序最关键:
r.GET("/healthz", healthHandler)必须放在r.Use(...)之前,否则全被拦截 - 若已全局注册中间件,改用
r.NoRoute拦截路径判断:if c.Request.URL.Path == "/healthz" { healthHandler(c); return } - Echo 要显式跳过:
e.GET("/healthz", healthHandler).SkipMiddleware = true(注意不是Use().Skip) - 别把
promhttp.Handler()和健康端点混在同一个路由组——/metrics和/healthz语义不同,不该共享中间件
/healthz 和 /readyz 的检查项必须物理隔离
很多人共用一个 handler,结果 DB 挂了但 livenessProbe 仍返回 200,Kubernetes 认为进程活着就继续发流量,最终雪崩。两个端点回答的是完全不同的问题。
-
/healthz只查进程自身:用atomic.LoadInt32(&healthy)看主 goroutine 是否 panic 重启过、runtime.NumGoroutine()是否突增、监听 socket 是否还在Accept -
/readyz才查依赖:调db.PingContext(ctx, 2*time.Second)、redisClient.Ping(ctx).Err()、grpcConn.GetState() == connectivity.Ready - 绝对不要在
/readyz里 reload 配置或预热缓存——这些必须在main()启动阶段完成,否则探针一来就卡住 - Kubernetes 默认探针超时是 1 秒,
/readyz响应必须 ≤ 1s,否则直接判失败
依赖探测不能每次请求都连一次
高频探针(如 periodSeconds: 2)下,每次 /readyz 都执行 db.Ping(),会迅速打爆数据库连接池,并因超时触发反复重启。
立即学习“go语言免费学习笔记(深入)”;
- 启动一个后台 goroutine,用
time.Ticker每 5 秒执行一次全量依赖检查 - 结果存进线程安全结构体,用
sync.RWMutex保护读写 -
/readyzhandler 只读快照,不触发新连接——避免脉冲压力和 goroutine 泄漏 - 缓存结构体至少包含
status("UP"/"DEGRADED"/"DOWN")、timestamp、各依赖明细(如{"db": "OK", "redis": "failed"})
响应体和状态码必须严格匹配探测器预期
Kubernetes 探针只认 HTTP 状态码,不解析响应体。写成 w.Write([]byte("OK")) 却忘记 w.WriteHeader(http.StatusOK),就会导致探测失败、Pod 反复重启。
- 必须显式设置状态码:
w.WriteHeader(http.StatusOK)或 Gin 的c.Status(200) - 路径大小写敏感:
/healthz≠/Healthz,必须与 YAML 中httpGet.path完全一致 - 建议返回轻量 JSON:
{"status":"ok","timestamp":1712345678},方便人工curl验证,也利于日志追踪 - 别在健康端点里打 info 日志——高频探针会让日志量翻倍;error 级别可打到 stderr,但仅限真实异常
最易被忽略的其实是端口对齐:http.ListenAndServe(":8080", nil) 和 Deployment 中 containerPort: 9000 不一致,Service 就永远拿不到 endpoints,/readyz 再准也没用。硬编码端口比环境变量推导更稳,8080 是事实标准。


















