当前位置：首页 > 文章列表 > Golang > Go教程 > Go 服务优雅停机运行手册：SIGTERM 后如何停接流量并等待请求完成

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

来源：17golang原创 2026-06-30 13:12:54 0浏览收藏

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

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

触发信号：发布后出现少量 502 和连接重置
快速判断：确认进程是否直接退出
处理步骤：用 http.Server.Shutdown 接住 SIGTERM
回滚路径：优雅停机异常时先恢复接流量
告警确认：观察退出耗时、失败请求和实例状态
复盘项：把停机流程固化到发布检查里

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

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

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

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

Go 服务收到 SIGTERM 后如果直接退出，请求链路被中断并产生 502 的控制台加流程图

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

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

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 做强制收尾，避免进程一直挂住。

Go 服务接住 SIGTERM 后停止监听新流量，等待活跃请求完成并在超时内退出的控制台加流程图