Consul服务注册需严格遵循健康检查路径返回200、Client Agent与Gin同宿主机、禁用DNS缓存、Server至少3节点跨可用区部署等核心规范。
服务注册时 health check 路径必须返回 200
Consul 不会信任你声明的“服务已启动”，它只认 /health（或你指定的路径）是否真实返回 HTTP 200。Gin 中常见错误是：路由写了但没加 c.Status(200)，或者用了 c.JSON(200, ...) 却忘了在 handler 开头加 c.Header("Content-Type", "application/json") —— 某些 Consul 版本对响应头敏感，非 JSON 响应可能被判定为失败。
实操建议：
- 健康检查端点必须是独立 HTTP GET，不依赖数据库连接或外部服务；否则 Consul 会误判服务下线
- 不要复用业务路由逻辑，例如把
/api/v1/users当作健康检查路径 —— 它可能带鉴权、DB 查询，导致抖动误报 - 推荐写法：
r.GET("/health", func(c *gin.Context) { c.Status(200) })
Client Agent 必须和 Gin 服务同宿主机或同 Pod
Consul Client Agent 的作用是上报本机服务信息。如果 Gin 服务跑在容器里，而 Agent 跑在宿主机上，localhost 或 127.0.0.1 就无法被正确解析 —— 它会上报自己的 IP，而不是容器内服务的真实监听地址。
实操建议：
- Kubernetes 场景下，用 DaemonSet 部署 Consul Client，确保每个 Node 上都有一个 Agent
- Docker Compose 场景下，用
network_mode: host或显式设置extra_hosts把宿主机 IP 映射进容器 - Gin 启动时读取环境变量
HOST_IP（由 initContainer 或 Downward API 注入），注册服务时填这个值，而不是0.0.0.0或localhost
调用方解析 service-name.service.consul 时 DNS 缓存要关
Gin 服务作为消费者，若用 net.Resolver 直接解析 user-service.service.consul，默认会缓存结果 —— 这会导致服务上线/下线后长达数分钟仍打到已宕机的实例。
实操建议：
- 禁用 Go 默认 DNS 缓存：
resolver := &net.Resolver{ PreferGo: true, Dial: func(ctx context.Context, network, addr string) (net.Conn, error) { d := net.Dialer{Timeout: time.Second * 5} return d.DialContext(ctx, network, addr) }, } - 每次请求前重新解析，或搭配
time.AfterFunc定期刷新记录列表（非轮询 Consul API） - 更稳妥的做法是绕过 DNS，直接调用 Consul HTTP API：
http://consul-server:8500/v1/health/service/user-service?passing，自己做负载均衡
Consul Server 节点数不能少于 3 个且跨可用区部署
单节点 Consul 看似能跑通注册/发现，但 Raft 无法达成多数派，任意网络波动都会触发 Leader 重选，导致服务目录短暂不可读 —— Gin 服务在重试窗口内反复失败，表现为“偶发性 503”。
实操建议：
- 生产环境至少部署 3 个 Server，分别落在不同物理机、云厂商可用区（如 cn-shanghai-a / cn-shanghai-b / cn-shanghai-c）
- Client Agent 的
-retry-join参数必须指向全部 3 个 Server 地址，而非仅一个；否则部分 Client 可能因单点故障失联 - 别在一台机器上起多个 Server 进程 —— 即便测试环境也容易触发端口冲突和 Raft 日志错乱
Consul 的服务发现不是“配置一次就完事”的功能，它的稳定性高度依赖底层集群拓扑和健康检查的语义严谨性。最容易被忽略的是：Gin 服务启动顺序和 Consul Agent 就绪状态之间的竞态 —— Agent 没 ready 就注册，会导致服务条目缺失，但日志里没有任何报错。
