架构与系统设计 / 系统课时
执行优雅下线与连接 Drain
执行优雅下线与连接 Drain
gRPC 服务下线不能只做“收到 SIGTERM 就退出”。安全路径要同时处理服务发现和已有 HTTP/2 连接:先停止新的流量进入,再让现有连接进入排空,等待在途 RPC 完成,并用强制停止超时保证进程最终能退出。
学习目标
- 能区分 Endpoint 摘流与 gRPC 连接 Drain 两个层次
- 能说明 GOAWAY、在途 RPC 和新 RPC 在优雅下线中的关系
- 能用
GracefulStop()加超时兜底实现可控退出
把下线拆成两个 Drain
滚动发布至少涉及两个层面。第一层是流量入口:服务发现、负载均衡器或编排器不应再把新连接或新的选址结果指向待下线实例。第二层是现有连接:已经建立的 gRPC HTTP/2 连接可能仍承载多个 RPC,需要进入 transport drain,避免客户端继续在旧连接上创建新调用。
安全顺序通常是先把实例标记为不可接收新流量,并给路由状态留出传播窗口,再启动 gRPC graceful shutdown。GracefulStop() 会停止接受新的连接和 RPC,并等待已经在途的 RPC 结束;grpc-go 会在底层 HTTP/2 transport 上执行排空,其中会使用 GOAWAY。应用层不需要自行构造 GOAWAY 帧。
GOAWAY 只解决“这条 HTTP/2 连接不要再承接新 stream”的问题,不负责发现其他实例。新 RPC 能否迁移到别的 Endpoint,还取决于客户端的 resolver、负载均衡策略以及是否存在其他健康地址。

安排安全的下线顺序
生产下线可以按以下顺序执行:
- 先让服务发现或负载均衡层把实例置为不可接收新流量,例如触发 not-ready、deregister 或 drain 状态。
- 等待路由变更传播到客户端、代理或负载均衡器,避免刚摘流就立即关闭监听端口。
- 调用 gRPC graceful shutdown,让现有连接进入排空状态,不再继续承接新的 RPC。
- 给在途 RPC 一个有限的完成窗口;窗口内正常返回的调用不应被人为中断。
- 到达 drain 超时仍未结束时调用强制停止,随后释放进程级资源并退出。
这个顺序的关键是先减少新增流量,再处理旧连接。如果先杀进程、再等 Endpoint 被摘除,传播窗口内仍可能有客户端连向已经消失的实例;如果只有 GracefulStop() 而没有最大等待时间,长流或卡死 Handler 又可能让发布永久悬挂。
用 GracefulStop 设置有上限的排空
下面的本地示例注册一个故意耗时 200 ms 的 gRPC Health RPC。调用进入 Handler 后立刻执行 GracefulStop(),可以看到在途 RPC 仍正常完成;stopWithTimeout 同时设置 1 秒上限,超时后改用 Stop() 强制结束。
package main
import (
"context"
"fmt"
"net"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
healthpb "google.golang.org/grpc/health/grpc_health_v1"
)
type slowHealth struct {
healthpb.UnimplementedHealthServer
started chan struct{}
}
func (s *slowHealth) Check(ctx context.Context, _ *healthpb.HealthCheckRequest) (*healthpb.HealthCheckResponse, error) {
// Simulate an RPC that is already in flight when draining begins.
close(s.started)
select {
case <-time.After(200 * time.Millisecond):
return &healthpb.HealthCheckResponse{Status: healthpb.HealthCheckResponse_SERVING}, nil
case <-ctx.Done():
return nil, ctx.Err()
}
}
func stopWithTimeout(s *grpc.Server, timeout time.Duration) bool {
// GracefulStop blocks until in-flight RPCs finish, so run it separately.
done := make(chan struct{})
go func() {
s.GracefulStop()
close(done)
}()
select {
case <-done:
return true
case <-time.After(timeout):
// Force termination if a stuck RPC exceeds the drain budget.
s.Stop()
<-done
return false
}
}
func main() {
lis, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
panic(err)
}
srv := grpc.NewServer()
service := &slowHealth{started: make(chan struct{})}
healthpb.RegisterHealthServer(srv, service)
go func() { _ = srv.Serve(lis) }()
conn, err := grpc.NewClient(
"passthrough:///"+lis.Addr().String(),
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
panic(err)
}
defer conn.Close()
client := healthpb.NewHealthClient(conn)
rpcResult := make(chan string, 1)
go func() {
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
resp, err := client.Check(ctx, &healthpb.HealthCheckRequest{})
if err != nil {
rpcResult <- "ERROR"
return
}
rpcResult <- resp.Status.String()
}()
// Start draining only after the slow RPC has entered its handler.
<-service.started
fmt.Println("server: drain started")
stopResult := make(chan bool, 1)
go func() { stopResult <- stopWithTimeout(srv, time.Second) }()
fmt.Println("rpc:", <-rpcResult)
if <-stopResult {
fmt.Println("server: graceful stop complete")
} else {
fmt.Println("server: forced stop")
}
}在空目录中把代码保存为 main.go,再初始化 module、拉取依赖并运行:
go mod init example.com/grpc-drain-demo
go get google.golang.org/grpc@latest
go run .预期结果:依赖安装阶段可能打印下载信息;程序本身应输出:
server: drain started
rpc: SERVING
server: graceful stop complete示例中的 RPC 在排空启动前已经进入 Handler,因此 GracefulStop() 会等待它完成。若某个真实 RPC 长时间不退出,超时分支会调用 Stop();业务 Handler 仍应响应 context 取消并及时停止下游工作,不能把 graceful shutdown 当成无限等待机制。
对齐滚动发布的时间预算
一次安全滚动发布至少要给三段时间留预算:Endpoint 或路由变更传播时间、gRPC 在途请求排空时间、进程清理余量。编排器允许的总终止时间必须覆盖这些阶段,否则外层平台可能在 gRPC 自己的 drain 窗口结束前直接杀掉进程。
对长生命周期 streaming RPC 还要单独定策略。无限流通常不能靠“等它自然结束”完成发布,应在应用协议中支持重连、会话恢复或服务端主动结束流,并确保客户端能重新连接到新的 Endpoint。Unary RPC 则更适合直接依赖 GracefulStop() 的在途完成语义。
优雅下线的验收标准不是“Pod 或进程最终退出”,而是发布期间新 RPC 能迁移到健康实例、在途 RPC 尽量完成、超时后又能确定性退出。把 Endpoint 摘流、GOAWAY/连接排空和强制停止放在同一条时间线上,才能避免滚动发布中的瞬时错误尖峰。