Golang Echo框架结合Consul实现健康检查-Golang-PHP中文网

consul健康检查要求health_check路径必须被consul agent所在机器直接访问，echo需监听所有接口（如":8080"）而非localhost，注册时填真实可达地址；/health端点应轻量、无依赖、不带中间件；必须配置deregistercriticalserviceafter="90s"并使用http类型检查而非ttl。

golang echo框架结合consul实现健康检查

Consul注册时 health_check 路径必须可被 Consul Agent 访问到

Echo 应用注册到 Consul 后，Consul Agent 会主动向你指定的 health_check 地址发起 HTTP 请求（默认 GET），如果返回非 200 状态码或超时，服务会被标记为 critical。关键点在于：这个地址必须是 Consul Agent 所在机器能直接访问的，不是 localhost 或容器内网地址。

常见错误是 Echo 启动时绑定 localhost:8080，然后在 Consul 注册里填 http://localhost:8080/health —— 这会导致 Consul Agent 去它自己的 localhost 找，自然失败。

Echo 启动时用 ":8080"（即监听所有接口），而非 "localhost:8080"
Consul 注册中的 http 字段填真实可达地址，例如 "http://172.17.0.3:8080/health"（Docker 容器 IP）或 "http://host.docker.internal:8080/health"（Mac/Win Docker Desktop）
本地开发调试时，可临时设为 "http://127.0.0.1:8080/health"，前提是 Consul Agent 和 Echo 运行在同一宿主机

用 Echo 的 `GET("/health")` 实现轻量健康检查端点

Consul 默认只关心 HTTP 状态码，不解析响应体，所以 /health 只需快速返回 200 即可。不需要查 DB、调下游、做复杂逻辑 —— 否则反而拖慢 Consul 的探测节奏，甚至触发误下线。

推荐写法是纯内存判断，例如检查服务是否已初始化、关键配置是否加载成功：

Echo框架 5.1.0

Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。

下载

e.GET("/health", func(c echo.Context) error {
    // 示例：确认某个全局变量已就绪（如 config loaded, db conn pool ready）
    if !isAppReady.Load() {
        return echo.NewHTTPError(http.StatusServiceUnavailable, "app not ready")
    }
    return c.NoContent(http.StatusOK)
})

避免在 /health 中调用 db.Ping() 或 http.Get("other-service") —— 这会让健康检查变成链路依赖检查，违背“本服务自身状态”的原则
若真要包含依赖状态（如 DB 可用性），应单独暴露 /healthz?verbose=true，并让 Consul 仍走基础 /health
路径名不强制叫 /health，但 Consul 配置里 http 字段必须和 Echo 路由完全一致（含前导斜杠）