根本原因是注册中心反注册滞后于HTTP服务关闭,正确顺序应为先 deregister 再 shutdown;若 deregister 失败需重试,否则导致“假下线”并引发 No instance 或 Connection refused。

Kratos 服务在节点下线时仍被调用,根本原因不是“没关服务”,而是注册中心反注册动作滞后于连接关闭 —— 你看到的 No instance 或 Connection refused 错误,几乎都源于这个时间差。
为什么 SIGTERM 后立刻 shutdown http.Server 还会丢请求
Kratos 底层用的是 Go 标准库的 http.Server,它的 Shutdown() 只阻塞新连接,但不会强制中断已建立的长连接(比如 keep-alive、streaming、gRPC bidi 流)。如果反注册晚于 Shutdown 启动,注册中心还在心跳续约,消费者就仍会把新请求打过来,而此时监听器可能已停止接收,或正在 drain 中来不及响应。
- 常见现象:
curl或 gRPC 客户端报connection refused,但日志里没看到请求进到 handler - 关键陷阱:很多人在
app.WithBeforeStop里先调srv.Shutdown(),再调registry.Deregister()—— 这顺序错了 - 正确顺序必须是:收到
SIGTERM→ 立即调registry.Deregister()(带重试)→ 等成功返回 → 再调srv.Shutdown()或grpc.Server.GracefulStop() - 如果
Deregister()失败(如网络抖动、Consul 不可用),不能跳过;应记录 ERROR 日志,并最多等待 3 秒后重试一次,否则就是“假下线”
Consul 反注册失败的典型原因和验证方式
consul.New() 返回的 *consul.Registry 必须显式检查 error,忽略它会导致 kratos.New() panic;但更隐蔽的问题是:即使 registry 构造成功,Deregister() 也可能因 Consul 集群状态异常而静默失败。
- 检查点 1:确认 Consul agent 在目标节点上运行正常,且能连通 server 节点(
curl http://127.0.0.1:8500/v1/status/leader) - 检查点 2:查看 Kratos 启动日志中是否输出
registered instance,以及下线前是否有deregistered instance成功日志 - 检查点 3:手动查 Consul API:
curl "http://<consul-addr>/v1/health/service/<service-name>?passing"</service-name></consul-addr>,看下线后该服务是否还出现在返回列表中 - 易踩坑:多个 package 的
init()函数里重复调用resolver.Register(),导致实际生效的 registry 实例不是你预期的那个
如何验证 draining 是否真正生效
HTTP 层的 draining 表现为:新请求被拒绝,但已有连接继续处理直到超时或主动关闭。如果你发现下线窗口内仍有大量请求进来,大概率是 draining 没起作用,或者超时设置太宽松。
- 给
http.Server显式配置ReadTimeout和WriteTimeout(例如 5s),避免单个慢请求拖垮整个 shutdown 流程 - 不要依赖默认的
IdleTimeout,它只管空闲连接;draining 关键是控制活跃请求的生命周期 - 实操验证:下线前用
ab -n 100 -c 10 http://svc/health发一批请求,观察 shutdown 过程中是否所有请求都得到响应(而非直接断连) - 对于 gRPC,建议启用
KeepaliveParams并设MaxConnectionAge(如 30m),让客户端主动重连,减少 shutdown 时待 drain 的连接数
最常被忽略的一点:Kratos 的 app.Run() 默认不接管信号生命周期,WithBeforeStop 插入的逻辑只有在你显式调用 app.Stop() 时才触发 —— 如果你靠系统 signal 杀进程,又没在 signal.Notify 里手动触发 app.Stop(),那所有优雅退出逻辑根本不会执行。


















