Go服务在K8s启动失败主因是未配startupProbe或参数不匹配;它专用于启动期健康检查,需设initialDelaySeconds=0、periodSeconds=5/10、failureThreshold≥最坏启动耗时/periodSeconds+余量,/startupz handler应仅检查启动标记且避开中间件。

Go 服务在 Kubernetes 中启动阶段就挂掉,八成是 startupProbe 没配,或者配了但 initialDelaySeconds 和 failureThreshold 没对上实际启动耗时。
startupProbe 为什么必须单独配(而不是只靠 liveness)
Go 程序启动慢很常见:加载大配置、预热缓存、建立 gRPC 连接、初始化数据库连接池……这些操作可能耗时 10–30 秒。如果只配 livenessProbe,K8s 会在启动后几秒就开始杀 Pod——因为此时服务根本没 Listen,HTTP 探针连不上,直接判定失败重启,形成“启动→探针失败→重启→再启动”的死循环。
startupProbe 就是专治这个的:它接管启动期的健康判断,只有它成功后,livenessProbe 和 readinessProbe 才开始工作。没它,滚动更新大概率卡在 ContainerCreating 或反复 CrashLoopBackOff。
- 必须显式声明,K8s 不会自动 fallback 到 liveness
- 不能和 liveness 共用同一个 handler——startup 阶段依赖可能还没 ready,但进程已存活,/livez 应该能通;而 /startupz 只需确认主 goroutine 已进入事件循环或监听端口即可
- 推荐用
httpGet+/startupz路径,语义明确,避免和 /healthz /readyz 混淆
startupProbe 参数怎么设才不踩坑
关键不是“设多大”,而是让 periodSeconds × failureThreshold ≥ 实际最坏启动耗时,同时留出余量。比如你的 Go 服务平均启动 12 秒,P99 是 22 秒,那就按 30 秒兜底。
立即学习“go语言免费学习笔记(深入)”;
-
initialDelaySeconds: 设为 0 —— 启动立刻开始探测,别等 -
periodSeconds: 用 5 或 10(别用 1 或 2,太激进,日志刷屏还无意义) -
failureThreshold: 计算方式:ceil(最大启动耗时 / periodSeconds),再加 1~2。例如最大 30 秒、period=10 → 至少设 4 -
timeoutSeconds: 必须 ≤periodSeconds,否则探测会堆积。设 2 或 3 即可,超时说明真卡住了
错误示范:periodSeconds: 2 + failureThreshold: 3 → 总容忍仅 6 秒,远不够 Go 服务冷启。
Go 代码里怎么配合 startupProbe
不要在 /startupz handler 里做任何耗时操作。它的唯一职责是:确认服务主线程已越过初始化阶段,且 HTTP server 已 ListenAndServe(或至少调用了 http.Serve)。
- 用原子变量标记启动完成:
var started int32,main 函数末尾atomic.StoreInt32(&started, 1) -
/startupzhandler 只读这个变量:if atomic.LoadInt32(&started) == 1 { w.WriteHeader(http.StatusOK) },其余全 bypass - 别检查 DB、Redis、下游 gRPC——那是
/readyz的事;startup 阶段连不上这些很正常,不该导致 Pod 被杀 - 路径必须和 K8s YAML 里写的完全一致,大小写、尾部斜杠都不能错(
/startupz≠/startupz/)
Startup 阶段的 handler 容易被中间件劫持
如果你用 Gin/Echo 等框架,且注册了全局 JWT 或日志中间件,/startupz 很可能被拦截返回 401 或卡住——这不是 bug,是中间件执行顺序问题。
- Gin:必须把
/startupz注册在r.Use(...)之前,或用r.NoRoute特殊处理 - Echo:用
e.GET("/startupz", startupHandler).SkipMiddleware = true,注意不是e.Use().Skip - 原生
net/http最省心:http.HandleFunc("/startupz", ...)不受任何中间件影响 - 千万别把
/startupz和/metrics放进同一个路由组共享中间件——语义冲突,可观测性混乱
最隐蔽的坑是:本地 curl http://localhost:8080/startupz 成功,但 K8s 里一直失败——八成是 Service 或 NetworkPolicy 拦截了探针流量,或者容器内 localhost 解析异常(尤其用 hostNetwork 时)。优先用 exec 进容器 curl -v http://127.0.0.1:8080/startupz 验证。


















