Kubernetes健康检查探针失败主因是Go服务未对齐其生命周期模型:需用独立http.Server暴露轻量探针端点(/livez仅查进程存活,/readyz带缓存查依赖),严控超时(代码context超时≤timeoutSeconds−1),并确保镜像与运行时兼容。

健康检查失败不是探针配错了,而是 Go 服务没对齐 Kubernetes 的生命周期模型——probe 只是“裁判”,你得先让服务具备被裁判的资格。
Go 服务必须暴露原生 HTTP 探针端点,别走框架路由
用 Gin/Echo/Chi 等框架把 /healthz 或 /readyz 注册在主 router 里,等于把探针请求塞进业务处理链:中间件可能加日志、鉴权、超时控制,甚至 panic 恢复逻辑还没跑完,probe 就已超时。Kubernetes 的 timeoutSeconds: 1 不等你打完日志。
- 用
http.ServeMux单独起一个轻量http.Server,只注册探针 handler,完全绕过框架中间件 - 监听独立端口(如
:8081),并在 Service YAML 中声明该端口为appProtocol: http - handler 内不要调
db.Ping()或redis.Ping()——这些留给/readyz,/healthz只查atomic.LoadInt32(&healthy)或srv.Addr是否非空
readinessProbe 和 livenessProbe 必须语义分离且路径不同
两个 probe 指向同一个 handler(比如都用 /health),会导致滚动更新卡死或误杀:DB 抖动时 readinessProbe 失败,流量被摘,但 livenessProbe 也跟着失败,直接重启 Pod,新实例又因 DB 未恢复继续失败,形成雪崩。
-
livenessProbe路径设为/livez,只检查进程是否存活:runtime.NumGoroutine()是否突增、关键 channel 是否阻塞、http.Server是否还在 Accept 连接 -
readinessProbe路径设为/readyz,才做真实依赖探测,但必须带缓存和超时:db.PingContext(ctx, 2*time.Second)结果存进sync.RWMutex保护的结构体,handler 只读快照 - K8s 配置中,
initialDelaySeconds对livenessProbe设 30,对readinessProbe设 10;periodSeconds均设为 10,failureThreshold设 3,避免单次抖动触发动作
镜像构建和运行时参数不匹配会静默破坏健康检查
镜像里二进制是 macOS 编译的,或用了 musl libc(Alpine)但运行时 base 镜像却是 glibc(Ubuntu),会导致容器启动后连 http.ListenAndServe 都执行失败——根本没机会暴露任何端点,probe 自然 connection refused。
- Dockerfile 多阶段构建中,build 阶段必须显式指定:
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 - 运行阶段 base 镜像选
gcr.io/distroless/static-debian12或scratch,杜绝 libc 兼容问题 - 确认最终镜像内二进制可执行:
docker run --rm -it,若报/app/server --help no such file or directory,99% 是链接问题
Probe 超时时间必须严丝合缝对齐 Go 代码里的上下文超时
K8s 默认 timeoutSeconds: 1,但你的 db.PingContext(ctx, 5*time.Second) 在 /readyz 里一跑,就必然超时失败。更糟的是,如果没设 context,goroutine 泄漏会让整个 server 卡住,后续所有 probe 请求全积压。
-
/readyzhandler 中所有依赖调用,context 超时值必须 ≤timeoutSeconds - 1(比如 K8s 设 3 秒,代码里用2*time.Second) - 所有顶层 goroutine(包括
http.Server.Serve)必须包recover,否则 panic 会终止 server,probe 连接直接被拒绝 - 收到
SIGTERM后,先原子置isReady = 0,再调srv.Shutdown(),确保 readinessProbe 下次就返回 503,让 Endpoint Controller 主动摘流
最常被忽略的一点:probe 失败日志不在应用 stdout 里,而在 kubelet 日志中。别只盯 kubectl logs,要看 kubectl describe pod 的 Events,以及节点上 journalctl -u kubelet | grep healthz ——那里才有 probe 真实被拒的原因。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











