Go 服务优雅关闭：收到 SIGTERM 后，排队清完再退出

Go 服务优雅关闭收到 SIGTERM 后排队清完再退出一、粗暴关闭为什么丢请求Kubernetes 中 Pod 终止流程是这样的kubelet 发送 SIGTERM等待terminationGracePeriodSeconds默认 30 秒超时后发 SIGKILL 强杀。如果 Go 服务收到 SIGTERM 直接os.Exit(0)正在处理的请求会被截断HTTP 连接中断、数据库事务半提交、消息队列消费未确认。这些请求在客户端侧表现为超时或错误在服务端侧表现为数据不一致。基础设施不需要漂亮话丢请求就是丢请求日志里的 5xx 率不会因为服务重启了而消失。优雅关闭的目标是收到终止信号后停止接收新请求排队处理完已有请求再退出进程。这个流程在 Go 中需要手动实现标准库的http.Server提供了Shutdown()方法但业务层的清理逻辑需要自行编排。二、优雅关闭的时序与机制优雅关闭涉及四个阶段顺序执行任何阶段出错都不能跳过。sequenceDiagram participant K8s as kubelet participant Sig as 信号处理 participant Srv as HTTP Server participant Wk as 工作队列 participant DB as 数据库连接 participant Log as 日志缓冲 K8s-Sig: SIGTERM Sig-Srv: 1. 停止接收新请求 Sig-Wk: 2. 等待在途任务完成 Wk--Sig: 任务全部完成 Sig-DB: 3. 关闭数据库连接池 Sig-Log: 4. 刷新日志缓冲区 Log--Sig: 日志已落盘 Sig-Sig: os.Exit(0) K8s-Sig: (未超时则不发 SIGKILL)每个阶段的超时控制至关重要。如果terminationGracePeriodSeconds设为 30 秒优雅关闭的总时间必须小于 30 秒。各阶段分配建议停接收新请求即时完成在途请求等待 20 秒资源清理 5 秒日志刷新 3 秒。预留 2 秒缓冲防止被 SIGKILL。三、Go 优雅关闭完整实现// server.go — 生产级优雅关闭实现 package main import ( context errors log net/http os os/signal sync syscall time ) // GracefulServer 封装优雅关闭逻辑 type GracefulServer struct { httpServer *http.Server wg sync.WaitGroup // 等待在途请求完成 shutdownCtx context.Context // 关闭超时控制 shutdownCancel context.CancelFunc } func NewGracefulServer(addr string, handler http.Handler, gracePeriod time.Duration) *GracefulServer { ctx, cancel : context.WithTimeout(context.Background(), gracePeriod) return GracefulServer{ httpServer: http.Server{ Addr: addr, Handler: handler, // 关闭阶段超时控制 ReadHeaderTimeout: 10 * time.Second, WriteTimeout: 30 * time.Second, IdleTimeout: 60 * time.Second, }, shutdownCtx: ctx, shutdownCancel: cancel, } } // Start 启动服务并监听终止信号 func (gs *GracefulServer) Start() error { // 信号通道监听 SIGTERM 和 SIGINT sigChan : make(chan os.Signal, 1) signal.Notify(sigChan, syscall.SIGTERM, syscall.SIGINT) // 启动 HTTP 服务 go func() { log.Printf(服务启动监听 %s, gs.httpServer.Addr) if err : gs.httpServer.ListenAndServe(); err ! nil { if !errors.Is(err, http.ErrServerClosed) { log.Printf(HTTP 服务异常退出: %v, err) } } }() // 等待终止信号 sig : -sigChan log.Printf(收到信号 %v开始优雅关闭, sig) gs.shutdownCancel() // 通知业务逻辑停止新任务 // 阶段一停止接收新请求 log.Println(阶段一停止接收新连接) shutdownResult : make(chan error, 1) go func() { // Shutdown 会等待在途请求完成但受 timeout 控制 shutdownResult - gs.httpServer.Shutdown(gs.shutdownCtx) }() // 阶段二等待业务层在途任务完成 log.Println(阶段二等待在途业务任务完成) done : make(chan struct{}) go func() { gs.wg.Wait() // 等待所有在途请求处理完成 close(done) }() select { case -done: log.Println(所有在途请求已处理完成) case -gs.shutdownCtx.Done(): log.Println(等待超时强制关闭在途请求) } // 阶段三清理资源数据库连接等 log.Println(阶段三清理外部资源) if err : gs.cleanupResources(); err ! nil { log.Printf(资源清理失败: %v, err) } // 等待 HTTP Shutdown 结果 if err : -shutdownResult; err ! nil { log.Printf(HTTP 关闭出错: %v, err) return err } log.Println(优雅关闭完成) return nil } // cleanupResources 清理外部连接和缓冲区 func (gs *GracefulServer) cleanupResources() error { // 关闭数据库连接池实际项目中替换为真实连接池 // dbPool.Close() // 刷新日志缓冲区如果使用了缓冲日志 // logBuffer.Flush() // 关闭消息队列连接 // mqConn.Close() return nil } // TrackRequest 追踪在途请求用于 WaitGroup func (gs *GracefulServer) TrackRequest() { gs.wg.Add(1) } // FinishRequest 标记请求完成 func (gs *GracefulServer) FinishRequest() { gs.wg.Done() } // IsShuttingDown 检查是否正在关闭 func (gs *GracefulServer) IsShuttingDown() bool { return gs.shutdownCtx.Err() ! nil }业务层使用 GracefulServer 的示例// main.go — 业务路由与优雅关闭集成 package main import ( encoding/json log net/http time ) func main() { // 优雅关闭超时 28 秒小于 K8s 的 30 秒 gracePeriod gracePeriod : 28 * time.Second gs : NewGracefulServer(:8080, nil, gracePeriod) // 业务路由每个请求通过 WaitGroup 追踪 mux : http.NewServeMux() mux.HandleFunc(/api/process, func(w http.ResponseWriter, r *http.Request) { // 关闭阶段不再接受新请求HTTP 层已停止但业务层可二次检查 if gs.IsShuttingDown() { w.WriteHeader(http.StatusServiceUnavailable) json.NewEncoder(w).Encode(map[string]string{ error: 服务正在关闭不接受新请求, }) return } // 追踪请求生命周期 gs.TrackRequest() defer gs.FinishRequest() // 模拟业务处理 result, err : processRequest(r) if err ! nil { w.WriteHeader(http.StatusInternalServerError) json.NewEncoder(w).Encode(map[string]string{ error: err.Error(), }) return } w.Header().Set(Content-Type, application/json) json.NewEncoder(w).Encode(result) }) gs.httpServer.Handler mux if err : gs.Start(); err ! nil { log.Fatalf(服务退出: %v, err) } } func processRequest(r *http.Request) (map[string]interface{}, error) { // 模拟耗时业务处理 // 实际项目中包含数据库查询、外部调用等 return map[string]interface{}{ status: completed, request: r.URL.Path, }, nil }Kubernetes Deployment 配置中的关键参数# deployment.yaml — 优雅关闭相关配置 spec: terminationGracePeriodSeconds: 30 # K8s 等待时间 containers: - name: app-server lifecycle: preStop: exec: # preStop 钩子给应用额外时间K8s 在发 SIGTERM 前执行 command: [sh, -c, sleep 3]preStop钩子的作用kubelet 在删除 Pod 时先执行 preStop再发 SIGTERM。sleep 3让服务在 Service 端点摘除后才收到 SIGTERM避免新请求路由到正在关闭的 Pod。四、优雅关闭的边界情况场景一长耗时请求。如果业务请求处理超过 gracePeriod如批量导出任务优雅关闭无法等待完成。解法将长耗时任务拆分为异步模式请求只触发任务结果通过回调或查询获取。同步请求的处理时间必须小于 gracePeriod。场景二gRPC 服务。gRPC 的优雅关闭需要调用grpc.Server.GracefulStop()逻辑与 HTTP 类似但独立实现。同时监听 HTTP 和 gRPC 时需要分别管理两者的关闭流程统一编排超时。场景三多实例关闭顺序。滚动更新时多个 Pod 依次关闭每个 Pod 都要完整走完优雅关闭流程。terminationGracePeriodSeconds设得太短会导致未完成请求被强杀太长则拖慢更新速度。根据业务 P99 响应时间设定gracePeriod P99 × 1.5 资源清理时间。场景四SIGKILL 不可避免。节点宕机、OOM Kill 等场景下 SIGKILL 无法被捕获优雅关闭失效。这属于不可控故障需要客户端侧的重试机制兜底服务端侧只能尽力而为。五、总结Go 服务的优雅关闭分为四个阶段停止接收新请求、等待在途请求完成、清理外部资源、刷新日志缓冲。每个阶段有独立的超时控制总时间必须小于 Kubernetes 的 terminationGracePeriodSeconds。实现要点用 WaitGroup 追踪在途请求用 context 传递关闭信号用 Shutdown 方法替代 Close。preStop 钩子确保 Service 端点摘除后再关闭避免请求路由到终止中的 Pod。长耗时请求应改为异步模式处理时间必须小于 gracePeriod。优雅关闭是服务可靠性的基础环节不是可选优化。