Consul客户端初始化失败的根本原因是Address未带http://协议头或网络不可达，必须设为"http://IP:8500"并用curl验证可达性；启用ACL需显式传Token；健康检查地址须Consul可访问，查询需加passingOnly:true；服务退出须主动注销并续租TTL。
Consul客户端初始化总失败，api.NewClient返回nil
根本原因几乎都是配置没传对——Address字段漏了协议头，或网络路径不通。Consul默认监听127.0.0.1:8500，但Docker容器、K8s Pod或远程Consul时这个地址基本不可用。
-
Address必须带http://前缀，写成"http://192.168.1.100:8500"，不能只写"192.168.1.100:8500" - 用
curl http://YOUR_IP:8500/v1/status/leader先确认Consul服务可达 - 若启用了ACL，必须显式传
Token字段，否则注册静默失败（服务列表里看不到，也无报错） - 超时设太短容易误判：
config.Timeout = 10 * time.Second是安全下限，尤其在CI或K8s DNS解析慢的环境
服务注册后健康检查一直critical，但HTTP接口明明能访问
Consul健康检查不是从你的Gin服务本地发起的，而是从Consul Agent所在机器发起请求。localhost、127.0.0.1、甚至容器内网IP，在Consul视角下往往不可达。
-
Check.HTTP地址必须填Consul能直接访问的地址，比如宿主机IP、K8s Service DNS名，或Pod IP（需网络策略放行） - 别依赖
localhost或127.0.0.1——这在跨节点部署时100%失效 -
Check.Timeout和Check.Interval要匹配真实响应：Gin handler实际耗时800ms，就别设Timeout: 500 * time.Millisecond - TTL模式下，仅注册不够：必须另起goroutine，每
TTL/2调一次client.Agent().PassTTL("service:<service-id>")</service-id>，否则30秒后直接被踢
Gin服务启动后查不到其他实例，client.Health().Service返回空
不是服务没注册，而是查询逻辑没对上——Consul服务发现依赖精确的Name匹配，且默认不返回passing状态以外的实例。
- 查服务时加
passingOnly: true参数：client.Health().Service("user-service", "", true, nil) - 确保目标服务注册时
Name字段与你查询的字符串完全一致（区分大小写、无空格） - 如果要用前缀批量查，得用
client.Health().Services(nil)再自己过滤，Consul原生不支持模糊匹配 - 注意Gin服务本身也要暴露健康端点（如
/health），否则别的服务没法反向探测你
服务退出时没注销，流量还在打进来
Go进程收到SIGTERM后若没主动调Deregister，Consul会等TTL过期或健康检查失败才下线，这段时间请求照常转发，导致500或超时。
立即学习“go语言免费学习笔记（深入）”；
- 用
signal.Notify捕获os.Interrupt和syscall.SIGTERM，在回调里执行注销 - 注销前先调
client.Agent().FailTTL("service:<service-id>", "")</service-id>，让Consul立即标记为critical，避免新流量进入 - 别把
Deregister写在main()末尾的defer里——有goroutine在跑时main返回≠进程退出 - 注销操作建议加日志：
log.Printf("deregistering service %s", serviceID)，方便核对是否真正执行
TTL续期和租约KeepAlive这两件事，一个都不能少；而服务ID唯一性、健康检查地址可达性、注销时机，这三个点只要漏掉一个，线上就会出雪崩式故障。
