Kratos服务注册必须显式传入kratos.Registrar实例,且ServiceInstance.Endpoints非空、健康检查配置正确,否则服务不会出现在Consul/Nacos中,客户端调用直接失败。

kratos.New() 必须传入 kratos.Registrar 实例
服务注册不是自动开启的,kratos.New() 不接收 registry.Registrar 就等于没注册。漏掉这一步,Consul 或 Nacos 里根本看不到服务条目,客户端也完全查不到——不是“注册失败”,而是“压根没发起注册”。
常见错误现象:
• 启动后访问 http://localhost:8500/ui/dc1/services/blog 显示空列表或 “No healthy nodes”
• 日志里没有任何关于 “registering instance” 或 “consul: registered” 的输出
• 客户端报 rpc error: code = Unavailable desc = service blog not found
- 确认
newApp函数中调用了kratos.Registrar(rr),且rr是非 nil 的registry.Registrar实例 - 别把
registry.Discovery(用于客户端发现)和registry.Registrar(用于服务端注册)混用,二者接口不同、用途不同 - 若用 Wire 注入,确保
ProviderSet包含了注册中心实例的构造函数(如NewConsulRegistry),且未被条件编译剔除
ServiceInstance.Endpoints 字段必须显式设置
Kratos 不会自动推导端点地址。registry.ServiceInstance 的 Endpoints 字段为空切片时,注册中心只存服务名和元数据,不暴露可连地址——客户端解析后拿到的是空列表,后续连接直接失败。
使用场景:
• HTTP 服务需填 ["http://0.0.0.0:8000"]
• gRPC 服务需填 ["grpc://0.0.0.0:9000"]
• 混合服务则两个都写,用协议前缀区分
- 地址别写
localhost:容器或 CI 环境下 DNS 解析可能失败,统一用0.0.0.0 - 端口必须与
http.Server或grpc.Server实际监听端口一致,否则健康检查失败 - 如果项目只启了 HTTP server,就别往 Endpoints 里塞
grpc://地址;协议不匹配会导致客户端连接立即失败且不重试其他地址
Consul/Nacos 客户端初始化必须早于 kratos.New()
注册中心客户端(如 consul.Registry 或 nacos.Registrar)内部依赖底层 SDK 连接,若连接未就绪就传给 kratos.New(),服务启动时会 panic 或静默丢弃注册请求。
典型错误:
• panic: failed to create consul client: Get "http://127.0.0.1:8500/v1/status/leader": dial tcp 127.0.0.1:8500: connect: connection refused
• 日志无报错但 Consul UI 中服务状态为 “critical”,点进去看是 “CheckID: service:blog — status: critical”
- 确保
conf.Load()已完成,且配置中consul.address或nacos.ip等字段已正确加载 - Consul 客户端初始化时传入的
api.Config.Address必须带端口(如"127.0.0.1:8500"),不能只写 IP - Nacos 初始化需同时提供
ServerConfig和ClientConfig,缺一不可;NamespaceId若为空,实例会注册到 public 命名空间,容易与其他服务冲突
注册内容必须包含有效 Health Check 配置
Consul 默认对未声明健康检查的服务标记为 critical。Kratos 不主动注入 check,需在 ServiceInstance 中手动设置 HealthCheck 字段,否则服务虽注册成功但不可用。
性能影响:
• 缺失健康检查 → 所有客户端认为该节点永久不可用 → 流量 0 分发
• 错误配置超时或路径 → 频繁触发 check 失败 → 节点反复上下线 → selector 负载不均
- HTTP 服务推荐用
http.Head探活,路径设为/health并确保路由已注册 - gRPC 服务可用
grpc_health_v1.Health.Check方法,但需在 server 中启用 health check interceptor - 别依赖默认值:Consul 的
Interval默认是 10s,太长;建议设为5s,Timeout设为3s


















