consul服务注册必须显式配置health_check字段，否则即使注册成功也被视为不健康；需补全checks（如http探针），并确保依赖检查、本地agent运行、独立健康端口及代理避坑。
Consul服务注册时必须显式配置health_check字段
不配health_check，服务就算注册成功，Consul也认为它“不健康”，永远进不了服务发现列表。这不是bug，是Consul的设计逻辑：注册≠健康，健康必须由明确的检查机制担保。
常见错误是只写Service{Name: "api", Address: "127.0.0.1", Port: 8080}就以为完事了。实际必须补全Checks字段——哪怕只是个最简单的HTTP探针：
Checks: []*api.AgentServiceCheck{{
HTTP: "http://127.0.0.1:8080/health",
Timeout: "5s",
Interval: "10s",
DeregisterCriticalServiceAfter: "30s",
}}
-
DeregisterCriticalServiceAfter不是可选安慰项：一旦服务连续失联（比如进程挂了但Consul没及时感知），超时后会自动从注册表剔除，否则下游调用会持续失败 - 如果用TCP检查（
TCP: "127.0.0.1:8080"），无法验证应用层逻辑是否正常，比如DB连不上、缓存雪崩时端口仍通，但服务已不可用 - HTTP检查路径建议独立为
/health，不要复用/ping或/status——前者可能没做依赖检查，后者可能带副作用（如触发日志刷盘）
Go里实现/health接口别直接return 200
硬编码http.StatusOK返回，等于把健康判断权交给了网络层。真正的健康必须包含关键依赖的实时状态，比如数据库连接、Redis心跳、下游gRPC服务连通性。
典型反模式：w.WriteHeader(200)然后w.Write([]byte("ok"))。这种写法在DB宕机时依然返回200，Consul就认为服务健康，流量照常打进来，结果全量超时。
立即学习“go语言免费学习笔记（深入）”；
- 每个依赖检查应设合理超时（如
db.PingContext(ctx, 2*time.Second)），避免单个慢依赖拖垮整个健康接口 - 建议用并行检查+上下文控制：
ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)，超时即判为不健康 - 返回体里带上失败项（如
{"db": "failed", "redis": "ok"}），方便运维快速定位，Consul本身不消费这个内容，但对人工排查极有用
Consul Agent本地运行是前提，别依赖远程API直连
很多Go服务试图用api.NewClient(&api.Config{Address: "http://consul-server:8500"})直接连远端Consul集群做注册和健康上报。这会导致两个问题：网络抖动时注册失败、健康检查由远端发起造成延迟和误判。
正确做法是确保本机（或同Pod）运行Consul Agent，并指向它：api.NewClient(&api.Config{Address: "http://127.0.0.1:8500"})。Agent负责与Server集群通信，同时本地执行HTTP/TCP检查，响应更快、更可靠。
- Agent必须启用
enable_local_script_checks = true（默认false），否则自定义脚本类检查会被忽略 - 如果用Docker部署，别把Agent和业务容器拆太开——推荐sidecar模式，共享network namespace，避免localhost不通
- 检查日志看
consul agent是否输出Synced service 'xxx'，没这句说明注册根本没成功，别急着查Go代码
Health Check路径被反向代理劫持是高频坑
Nginx、Traefik或K8s Ingress经常对/health做特殊处理：缓存响应、跳过鉴权、甚至直接返回静态200。结果Consul看到的永远是“健康”，而真实服务早已OOM。
验证方式很简单：curl本机http://127.0.0.1:8080/health和curl网关地址（如curl https://api.example.com/health）对比响应体和状态码。两者不一致，基本就是代理层动了手脚。
- Nginx里禁用缓存：
location /health { add_header Cache-Control "no-store"; proxy_cache_bypass 1; } - K8s readinessProbe若也指向同一路径，注意它默认不走Ingress，而是直连Pod IP，所以不会受代理影响——但这反而掩盖了线上真实问题
- 最稳方案：健康检查用独立端口（如
:8081/health）并禁止对外暴露，只供Consul Agent访问
Consul的健康检查机制本身不复杂，难的是让每一环都按预期工作：注册字段不漏、检查逻辑不假、网络路径不绕、代理规则不干扰。漏掉其中一环，服务就变成“注册了但没人敢调”的幽灵实例。
