Consul 是 Kratos 最常用服务发现注册中心,但常见问题集中在初始化顺序、健康检查配置及 resolver.Register() 调用时机;需确保 consul.New() 非 nil、Consul 服务可达、scheme 匹配、resolver.Register() 在 main 开头且仅调用一次,并显式配置 HTTP 健康检查路径且等待检查通过后再使用服务。

Consul 是 Kratos 服务发现最常用、文档最全的注册中心,只要 consul.New() 成功返回非 nil 实例,并正确调用 resolver.Register(),服务就能被发现——但多数 panic 和“找不到服务”问题,都卡在初始化顺序或健康检查配置上。
consul.New() 返回 nil 却没检查,直接传给 kratos.New()
Kratos 启动时若 kratos.New() 的 kratos.Registrar(rr) 参数是 nil,会立即 panic,错误信息不提示具体哪个值为空。而 consul.New() 在 Consul 服务未启动、地址连不通、或配置 scheme 错误(比如配成 https 但 Consul 没开 TLS)时,会返回 (nil, error)。
常见错误现象:
- 控制台只输出
panic: runtime error: invalid memory address,无上下文 - 日志里看不到 “consul client created” 类提示
实操建议:
- 不要只判
err != nil,必须检查返回的 registry 实例是否为 nil:rr, err := consul.New(&consul.Config{Address: "127.0.0.1:8500"})<br>if err != nil || rr == nil {<br> log.Fatal("failed to create consul registry", "error", err)<br>} - 确保 Consul 进程已运行:
curl -s http://127.0.0.1:8500/v1/status/leader应返回类似"127.0.0.1:8300" - 配置中的
scheme必须与 Consul 实际监听协议一致:默认是http,不是https或空字符串
resolver.Register() 调用时机不对或重复注册
resolver.Register() 是全局生效的,且 Kratos 的 gRPC 客户端 resolver 依赖它来解析 consul:// 前缀的 target。如果它没在任何 client 初始化前调用,或在多个地方重复调用不同注册中心实例,会导致服务发现失效或 panic。
常见错误现象:
- gRPC Dial 时报
rpc error: code = Unavailable desc = connection closed before server preface received - Consul UI 里能看到服务注册成功,但客户端始终 resolve 不到实例
- 程序启动时报
register resolver twice(来自 resolver 包内部 panic)
实操建议:
- 必须在
main()函数最开始、任何grpc.Dial()之前调用一次:func main() {<br> rr := consul.New(...)<br> resolver.Register(rr) // ✅ 放这里<br> app := kratos.New(...)<br> app.Run()<br>} - 不要在 service 层、dao 层或 init() 里调用;尤其避免在多个微服务共用的公共包中调用
- 一个进程内只注册一个 registry 实例;混用 Consul + Etcd 会冲突
服务注册后状态显示 critical,导致无法被发现
Consul 默认对注册的服务做健康检查,如果检查失败(HTTP 状态码非 2xx、TCP 端口不可达、gRPC probe 超时),服务状态会变成 critical,此时 discovery.GetInstances() 或 gRPC resolver 默认不会返回该实例。
常见错误现象:
- Consul UI 中服务条目显示红色
critical,而非绿色passing - 调用方 resolve 到空列表:
instances: [] - 日志出现
health check failed: Get "http://.../health": dial tcp ...: connect: connection refused
实操建议:
- 注册时显式配置健康检查路径(推荐 HTTP):
ins := &naming.Instance{<br> ID: "svc-01",<br> Name: "user.service",<br> Addrs: []string{"http://127.0.0.1:8000"},<br> Metadata: map[string]string{<br> "health": "/health", // Consul 会 GET 这个路径<br> },<br>} - 确保该路径在你的 HTTP Server 上真实存在、返回 200,且不校验 Authorization
- 如用 gRPC 服务,Consul 不支持原生 gRPC health probe,需额外起一个 HTTP 健康端点,或改用 TCP 检查(配置
"tcp": "127.0.0.1:9000")
真正容易被忽略的是:Consul 的健康检查是异步触发的,注册成功不等于立刻 ready;哪怕配置全对,也要等首次检查通过(默认 10 秒间隔)后状态才变 green。别在注册后立刻发起 discover 请求,加个 time.Sleep(15 * time.Second) 或轮询 discovery.GetInstances() 直到非空,才是生产可用的做法。











