Consul集群未启动是Golang服务注册失败的主因，需检查节点间gossip通信（8301/8302端口）、绑定IP、防火墙及consul members状态；注册应延迟至Agent就绪、设超时上下文、用唯一ID、显式填Address和健康检查，并通过client.Health().Service()查询健康实例。
Consul 集群没起来，Golang 服务注册必失败——90% 的“注册失败”问题根本不在 Go 代码里，而在 Consul 节点之间连不通。
consul members 显示 failed 或空列表
这是最直接的信号：Consul 集群根本没建立成功，后续所有服务注册、发现都无从谈起。
- 检查每个节点启动命令是否含
-bind和-client：必须指定内网可互通的 IP（如10.0.1.10），不能只写0.0.0.0或127.0.0.1 - 确认防火墙放行三个关键端口：
8300（RPC）、8301（LAN gossip，TCP+UDP）、8302（WAN gossip，TCP+UDP）；光开8500毫无意义 - 在任一节点执行
consul members，所有节点状态必须是alive；若出现failed，说明 gossip 通信中断，优先查网络连通性与端口 - 多可用区部署时，
consul join -wan <ip:8302>必须用对方节点的-wan-addr（默认即:8302），不是:8500
Go 客户端调用 client.Agent().ServiceRegister() panic: context deadline exceeded
这不是注册逻辑写错了，而是 HTTP 请求卡在了网络层或 Consul Agent 响应慢——本质是超时，不是失败。
- 默认超时 5 秒太长且不可控，生产环境必须显式设置：
ctx, _ := context.WithTimeout(context.Background(), 3*time.Second) - 别在
init()或main()开头就注册：Consul Agent 可能还没 ready，建议先做轻量健康检查：client.Status().Leader()返回非 nil 再注册 - 使用
consul-apiv1.14+时，client.Register()已弃用，必须改用AgentServiceRegistration+client.Agent().ServiceRegister() - 注册失败不应 panic 或退出进程，应降级为日志告警，避免整个微服务启动被阻塞
同名服务在 Consul UI 中只显示一个实例
说明多个 Go 服务实例用了相同 ID，Consul 把后注册的当作了前者的覆盖更新。
立即学习“go语言免费学习笔记（深入）”；
- 每个服务实例必须配置唯一
ID：推荐组合主机名 + 进程 PID + 端口，例如"goods-server-192.168.1.111-8080" - 服务名（
Name）可以相同（如都叫"goods"），这是实现负载均衡的前提 - 注册时务必传入
Address字段：不能依赖默认回环地址，要填实际监听的 IP（如"192.168.1.111"），否则服务发现查到的是错的地址 - 健康检查路径（
Check.HTTP）需真实可访问，且返回 200；若用TCP类型，端口必须和Port一致
客户端查不到健康服务实例
常见于误用查询接口或健康检查未生效，不是服务没注册，而是没被判定为“可用”。
- 不要用
client.Health().Node()或client.Catalog().Services()：它们不做过滤，返回的是原始注册数据，不含健康状态 - 必须用
client.Health().Service("goods", "", true, nil)—— 第三个参数true表示只返回通过健康检查的实例 - 如果服务刚注册就立刻查，可能因 Consul 健康检查周期（默认 10s）尚未完成，建议首次查询加短延迟或重试
- 客户端应缓存结果并定期刷新（如每 5 秒调一次
Service()），避免高频直连 Consul API 成为瓶颈
最容易被忽略的是：Consul 的 client 模式节点不参与 Raft 投票，也不保存服务目录；所有 Go 服务必须连本地 agent（http://127.0.0.1:8500），而不是直连远端 server 节点——后者会导致请求被拒绝或超时，且无法利用本地 agent 的健康检查代理能力。
