Kratos 优雅启停需手动协调注册与下线顺序:先初始化资源再注册,下线时先反注册再关闭服务;实现健康检查;注册中心操作加重试;HTTP/gRPC 配置超时与连接驱逐;客户端必须配置重试并容忍发现延迟。

注册时机必须晚于资源初始化完成
服务一启动就向注册中心上报实例,但 DB 连接池、Redis 客户端、gRPC 依赖还没 ready,会导致刚注册就被流量打挂。Kratos 不自动控制注册顺序,得靠你显式协调。
- 在
main.go中不要直接调用registry.Register,而是封装startService函数,按顺序:初始化 DB → 初始化 Redis → 启动 HTTP/gRPC Server → 最后才调用registry.Register - 实现
health.Checker接口,把资源 readiness 状态暴露为/health端点,供 K8s liveness probe 或 Istio 调用 - 若用
contrib/registry/nacos或contrib/registry/etcd,注意其Register方法默认无重试,建议包装一层带指数退避的逻辑(比如用backoff.Retry)
下线前必须先反注册再关闭监听器
直接 kill 进程或先调 http.Server.Shutdown 再反注册,会导致注册中心元数据残留数秒到数十秒(取决于心跳间隔),消费者仍会路由请求过去,报错 Connection refused 或 No instance。
- 在
signal.Notify捕获SIGTERM后,立即执行registry.Deregister;仅当成功后,才调用http.Server.Shutdown或grpc.Server.GracefulStop -
registry.Deregister失败不能跳过——应加日志并最多重试 3 秒,避免“假下线” - Kratos 的
app.Run默认不处理优雅退出,需手动接管生命周期:用app.WithServer注册服务,再用app.WithBeforeStop插入反注册逻辑,app.WithAfterStop做资源清理
HTTP/gRPC 层要支持连接 draining
Go 标准库的 http.Server 和 grpc.Server 虽支持 graceful shutdown,但默认行为不够激进:新连接被拒绝,但已建立的长连接(如 streaming、keep-alive)可能还在传数据,超时后被强制断开。
- 给
http.NewServer配置http.Server.ReadTimeout和WriteTimeout,防止单个慢请求拖垮整个 shutdown 流程 - 对 gRPC 服务,启用
KeepaliveParams并设置合理MaxConnectionAge,让客户端主动重连,减少 shutdown 时待 drain 的连接数 - 在
app.WithBeforeStop中可调用http.Server.Close()(非Shutdown)快速终止监听,再等活跃连接自然结束——适用于对一致性要求不高、但希望更快释放端口的场景
客户端必须配置重试与服务发现容忍
Kratos 不兜底客户端行为。哪怕服务端完全优雅,若客户端没做容错,照样会报错。
- HTTP 客户端必须配置重试(如用
retryablehttp),且重试间隔 > 注册中心心跳周期(如 Nacos 默认 5s) - gRPC 客户端需启用
WithBlock()+WithTimeout(),并在连接失败时 fallback 到其他实例 - 所有客户端都应容忍服务发现延迟:K8s Endpoint 更新、注册中心同步、DNS 缓存都有几秒抖动,不能假设“反注册成功 = 流量立刻消失”
Kratos 的优雅停机不是开个开关就能生效的机制,它是一组需要你亲手串起来的契约:注册时机、反注册顺序、连接 draining 策略、客户端重试行为,缺一不可。最容易被忽略的是客户端侧的配合——服务端做得再完美,只要上游调用方没重试,用户照样看到 503。











