Go 服务优雅停机运行手册：SIGTERM 后如何停接流量并等待请求完成

Go 服务发布或容器滚动重启时，如果进程收到 SIGTERM 后直接退出，正在处理的 HTTP 请求可能被中断，调用方看到的就是连接重置、偶发 502 或超时。优雅停机的目标很明确：先停止接收新流量，再给正在处理的请求一段收尾时间，最后在超时内退出。

这篇按运维运行手册组织，适合放进发布流程或值班文档里：触发信号、快速判断、处理步骤、回滚路径、告警确认和复盘项都写清楚。

触发信号：发布后出现少量 502 和连接重置

优雅停机问题通常不是全站故障，而是发布窗口内出现一小段毛刺。典型信号包括：

• 滚动发布期间 502 或连接重置短暂升高。
• 慢接口在实例重启时更容易失败。
• 网关日志显示后端连接被提前关闭。
• 容器状态已经结束，但请求日志缺少完整响应。

如果你的 Go 服务只用了 http.ListenAndServe，没有捕获退出信号，进程收到 SIGTERM 后很可能直接结束，正在处理的请求没有机会完成。

快速判断：确认进程是否直接退出

先从日志确认服务是否收到退出信号，以及收到信号后有没有进入等待流程。建议在服务启动、收到信号、停止监听、请求收尾、最终退出几个点打印结构化日志。

2026-06-30T13:07:10Z level=info msg="server started" addr=:8080
2026-06-30T13:12:33Z level=info msg="signal received" signal=SIGTERM
2026-06-30T13:12:33Z level=info msg="start graceful shutdown" timeout=15s
2026-06-30T13:12:40Z level=info msg="server stopped" elapsed=7s

如果只有启动日志和进程退出日志，中间没有 start graceful shutdown，基本可以判断服务没有接住停机流程。

处理步骤：用 http.Server.Shutdown 接住 SIGTERM

下面是一个可直接改造的最小版本。它会监听 SIGINT 和 SIGTERM，收到信号后调用 Shutdown，给正在处理的请求最多 15 秒完成。

package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("ok"))
    })
    mux.HandleFunc("/api/work", func(w http.ResponseWriter, r *http.Request) {
        time.Sleep(3 * time.Second)
        _, _ = w.Write([]byte("done"))
    })

    srv := &http.Server{
        Addr:    ":8080",
        Handler: mux,
    }

    go func() {
        log.Println("server started addr=:8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            log.Fatalf("listen failed: %v", err)
        }
    }()

    stop := make(chan os.Signal, 1)
    signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
    sig := 

Shutdown 会停止监听新连接，并等待活跃请求结束。它不是无限等待，所以必须给上下文设置超时。超时后可以调用 Close 做强制收尾，避免进程一直挂住。

回滚路径：优雅停机异常时先恢复接流量

如果改造后发布期间仍然出现失败请求，先按运维优先级处理：

• 暂停滚动发布，避免继续扩大影响。
• 把新版本实例从流量池摘除，确认旧版本是否稳定。
• 检查健康检查是否过早变为不可用，导致网关切流和进程退出顺序错位。
• 如果停机超时过短，先回滚到已知稳定版本，再调整超时和预停机流程。

不要在高峰期一边扩大发布，一边调停机参数。优雅停机属于发布基础能力，异常时先恢复服务稳定性，再复查细节。

告警确认：观察退出耗时、失败请求和实例状态

发布后至少确认这些指标：

• 退出耗时：从收到 SIGTERM 到进程退出的时间是否在预算内。
• 失败请求：滚动发布窗口内 502、499、连接重置是否下降。
• 活跃请求：停机期间是否仍有长请求被强制打断。
• 实例状态：负载均衡或网关是否先停止转发，再让进程退出。
• 超时次数：Shutdown 是否经常走到超时分支。

如果 Shutdown 经常超时，说明业务处理时间、停机预算和网关摘流顺序至少有一项不匹配。

复盘项：把停机流程固化到发布检查里

最后把优雅停机变成固定检查项：

• 服务必须捕获 SIGTERM，并有停机开始和停机结束日志。
• 停机超时要大于主要接口的 P99，但不能无限放大。
• 健康检查、摘流、停机信号、进程退出要有明确顺序。
• 发布压测包含“请求处理中发送 SIGTERM”的场景。
• 慢请求要支持上下文取消，避免停机时拖住进程。
• 发布看板展示停机耗时、失败请求和强制关闭次数。

总结一下：Go 服务优雅停机不是只写一个信号监听。它需要和网关摘流、健康检查、请求超时、日志指标一起设计。只要能做到停止接新流量、等待活跃请求、超时后可控退出，滚动发布期间的偶发 502 就会明显减少。