Consul HTTP健康检查必须指向/health而非/readyz,因其默认承担livenessProbe语义,仅验证进程监听与无panic;/health应极轻量、禁用DB/Redis调用,而/readyz专供K8s readinessProbe使用。

Consul HTTP健康检查必须指向/health还是/readyz?
Consul 的 AgentServiceCheck.HTTP 字段只能配一个路径,它默认承担的是 livenessProbe 语义——即只确认服务进程是否在监听、主 goroutine 是否 panic。所以这里必须用 /health,不能填 /readyz。
填 /readyz 的后果是:数据库连不上时 Consul 立即标记服务为 Critical 并触发 DeregisterCriticalServiceAfter 自动下线,而此时服务本身可能只是短暂抖动,还没来得及恢复连接。
-
/health响应应极轻量:仅检查http.Server是否 Accept、无 panic、能写响应头 - 禁止在
/health中调用db.Ping()或redis.Ping() - 若需依赖感知,请单独起一个
/readyz端点供 KubernetesreadinessProbe使用,Consul 不消费它
注册时AgentServiceCheck.Timeout和Interval怎么设才不误杀?
Consul 健康检查失败不是“一次就下线”,而是累计失败时间超过 DeregisterCriticalServiceAfter 才注销。但很多人把 Timeout 和 Interval 设得太激进,导致 GC STW 或网络抖动时服务被误剔除。
-
Timeout必须小于Interval,建议设为Interval的 1/2~2/3(例如Interval="10s"→Timeout="6s") -
Interval别低于10s;DeregisterCriticalServiceAfter至少设为Interval × 3(如"30s"),否则两次连续超时就下线 - Gin 的
/healthhandler 内部也要加context.WithTimeout(c.Request.Context(), 3*time.Second),防止 handler 卡住拖垮 Consul 检查周期
Gin路由里如何让/health绕过JWT和日志中间件?
Consul 发起的 HTTP 请求没带 token,也没走网关,如果 /health 被 JWT 中间件拦截,会返回 401,Consul 就判定服务不健康。
最稳妥的方式是在注册路由时跳过所有中间件:
r := gin.New()
// 先注册健康端点,不走任何 Use()
r.GET("/health", func(c *gin.Context) {
c.Status(200)
})
// 再挂中间件
r.Use(jwtMiddleware(), loggerMiddleware())
// 最后注册业务路由
r.GET("/api/users", userHandler)
- 不要用
r.Group("/").Use(...)包住/health - 别在
NoRoute里做路径判断再分发——那已经晚了,中间件已执行 - 如果必须复用中间件逻辑(比如统一 trace ID 注入),请在中间件内显式放行:
if c.Request.URL.Path == "/health" { c.Next(); return }
Consul注册时HTTP地址填localhost:8080为什么总连不上?
Consul agent 运行在独立节点(宿主机或另一容器),它发起的 HTTP 请求目标是 AgentServiceCheck.HTTP 字段值。填 localhost:8080 或 127.0.0.1:8080 意味着 Consul agent 去连自己本地的 8080 端口,而不是你的 Gin 服务。
- 填真实可路由地址:Docker 环境下用容器名 + 端口(如
http://gin-service:8080/health),前提是二者在同一个自定义 bridge network - Kubernetes 环境下填 ClusterIP Service 名称(如
http://gin-svc.default.svc.cluster.local:8080/health) - 裸机部署时填本机非 loopback IP(用
localIP()函数获取,排除127.0.0.1) - 确保 Gin 启动时绑定的是
:8080(即0.0.0.0:8080),不是127.0.0.1:8080
最易忽略的一点:Consul 的健康检查只管 HTTP 层通不通,它不校验响应 body 内容。哪怕 /health 返回 {"status":"down"},只要 HTTP 状态码是 200,Consul 就认为健康。所以状态码比 JSON 字段更重要。











