Go Web 服务怎么配置优雅关机

文章导读
Go Web 服务做优雅关机,核心是两件事:收到停止信号后不再接受新连接,并把已经进来的请求处理完。标准库 http.Server 自带 Shutdown 方法,不需要额外框架,但如果只写一句 srv.Shutdown(ctx),实际效果往往不达预期,因为关机时机、超时设置、与容器或进程管理器的宽限期是否匹配,都会影响最终结果。判断标准很简单:进程收到 SIGTERM 之后,正在处理的请求仍能正常
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

Go Web 服务做优雅关机,核心是两件事:收到停止信号后不再接受新连接,并把已经进来的请求处理完。标准库 http.Server 自带 Shutdown 方法,不需要额外框架,但如果只写一句 srv.Shutdown(ctx),实际效果往往不达预期,因为关机时机、超时设置、与容器或进程管理器的宽限期是否匹配,都会影响最终结果。判断标准很简单:进程收到 SIGTERM 之后,正在处理的请求仍能正常返回,空闲的 keep-alive 连接被关闭,进程最终自行退出而不是被杀掉。

建议在 main 中监听 SIGTERM 与 os.Interrupt,用带超时的 context 调用 srv.Shutdown,并把关机超时设为小于部署环境的终止宽限期,例如容器或 systemd 配置的停止等待时间。验证方式是发起一个耗时的请求,再发送 SIGTERM,观察该请求是否完整返回、进程是否以正常状态退出。存在 WebSocket 等长连接或自行启动的后台任务时,Shutdown 覆盖不到,需要单独处理。

先确认当前场景和目标

并不是所有 Go 服务都需要复杂的关机流程。先确认下面几项,再决定配置到什么程度:

  • 请求是否可能长时间占用连接。存在大文件上传下载、流式响应、慢查询、外部接口调用时,粗粒度地杀掉进程会截断这些请求;如果接口都是毫秒级,配置的紧迫性会低很多。
  • 进程由谁管理、发的是什么信号。Kubernetes 在 Pod 删除时先发 SIGTERM,等待 terminationGracePeriodSeconds 后发 SIGKILL;systemd 默认发送 SIGTERM,TimeoutStopSec 到期后发送 SIGKILL;直接在前台运行的服务,停止方式取决于你按的键或终端的行为。
  • 服务前面有没有负载均衡或反向代理。如果有,也要确认在摘除实例之前,请求是否还会继续打进来,这决定了关机逻辑里能否加一步主动下线。
  • 是否存在长连接或后台任务。http.Server.Shutdown 不会等待被 hijack 的连接(典型是 WebSocket),也不会等待你自己用 goroutine 启动的任务。

目标可以先设定为:收到终止信号后停止 accept 新连接,已进入的 HTTP 请求在限定时间内完成,超时则强制关闭,进程退出码为 0。这个目标对绝大多数短请求服务已经够用。

按这个顺序处理

建议按“构造 Server → 启动监听 → 等待信号 → 关闭”的顺序组织代码,避免在 ListenAndServe 阻塞的写法里再塞入信号处理。下面是一段可直接替换的通用骨架,超时和地址需要按环境调整:

Go Web 服务怎么配置优雅关机
package main

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

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/slow", func(w http.ResponseWriter, r *http.Request) {
		time.Sleep(5 * time.Second)
		w.Write([]byte("done"))
	})

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           mux,
		ReadHeaderTimeout: 5 * time.Second,
		IdleTimeout:       60 * time.Second,
	}

	// 信号上下文,Ctrl+C 或 kill -TERM 时取消
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	errCh := make(chan error, 1)
	go func() {
		errCh <- srv.ListenAndServe()
	}()

	select {
	case err := <-errCh:
		// ListenAndServe 在 Shutdown 后返回 ErrServerClosed,属正常情况
		if err != nil && !errors.Is(err, http.ErrServerClosed) {
			log.Fatalf("listen failed: %v", err)
		}
	case <-ctx.Done():
		// 恢复默认信号处理,让第二次信号可以立即结束进程
		stop()

		// 如需主动下线,可在这里把健康检查标记为不健康,或从注册中心摘除

		shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
		defer cancel()

		if err := srv.Shutdown(shutdownCtx); err != nil {
			log.Printf("graceful shutdown timeout: %v", err)
			_ = srv.Close() // 超时后强制断开,避免进程挂住
		}
		log.Println("server exited")
	}
}

几个替换点需要明确。第一,15*time.Second 是关机等待上限,需要小于部署环境的停止宽限期,例如 Kubernetes 的 terminationGracePeriodSeconds 与 systemd 的 TimeoutStopSec,留出几秒余量给进程退出和日志落盘。第二,如果服务前有负载均衡,建议在调用 Shutdown 前先把就绪状态置为失败,并等待一小段时间,让流量真正停止进来;这段等待用固定时长即可,不必精确。第三,ReadHeaderTimeout 和 IdleTimeout 用于避免空闲连接和慢速请求长期占用,与关机超时是两回事,但会直接影响 Shutdown 能否按时结束。

如果进程里还有后台任务,例如消费队列、定时刷新缓存的 goroutine,需要给这些任务一套自己的退出机制,比如共用 ctx、在 Shutdown 之后等待 WaitGroup。把后台任务的退出交给 http.Server.Shutdown 处理不会有任何效果。

改完后怎么验证

验证要比对两件事:请求是否完整返回,进程是否自行退出。可以先在本地用上面带 /slow 的示例做一次端到端观察:

Go Web 服务怎么配置优雅关机
  1. 启动服务,记录进程号,例如 ps -ef | grep 你的二进制名。
  2. 在另一个终端发起一个耗时请求:curl -v http://127.0.0.1:8080/slow。
  3. 请求还在进行时,发送信号:kill -TERM <pid>。
  4. 观察 curl 输出:预期是在数秒后收到完整的 200 响应和预期的响应体,而不是连接被重置。
  5. 观察进程:预期进程在请求结束后自行退出,退出码为 0,终端能看到你打印的退出日志。

还要补两个反向检查。一是关机期间新请求的表现:在发出信号后立刻再执行一次 curl,预期是连接被拒绝或无法建立,而不是排队等待。二是超时路径:把 /slow 的休眠时间改到大于关机超时,确认进程仍能在超时后退出,而不是卡住。这两项能暴露大部分配置错误,比如信号没接住、超时设得比宽限期还长、错误地忽略 http.ErrServerClosed。

如果部署在容器里,可以再走一遍真实流程:触发一次滚动更新或删除 Pod,同时用客户端持续请求,然后查看实例日志里的关机记录与请求完成情况。观察点仍是那两条:请求有没有被截断,进程是被 SIGKILL 结束还是自己走完的。

Go Web 服务怎么配置优雅关机

容易忽略的边界

Shutdown 的行为有明确范围,越界部分需要单独安排。http.Server.Shutdown 会关闭监听、关闭空闲连接、等待活跃请求结束,但不会等待被 hijack 的连接,WebSocket 和老式长轮询通常属于这一类;这些连接需要在关机流程中自行关闭,例如注册一个连接集合,在关机时逐个 Close。同理,直接用 net.Listen 或其他协议自己起端口的服务,不在 http.Server 的管理范围内。

平台差异也要留意。信号语义在 Linux 和类 Unix 环境比较一致;Windows 上 syscall.SIGTERM 的可用性有限,通常只能依赖 os.Interrupt,在 Windows 上验证时不要照搬 kill -TERM 的步骤。另外,如果直接用 go run 启动,收到的信号可能先被工具链进程接住,验证时建议先 go build 再运行编译产物。

如果服务部署在 Kubernetes 中,且 Pod 会在收到信号的同时被移出 Service 端点,往往会出现“信号到了、流量还没停”的短暂窗口,此时可以在容器里配置 preStop 做短暂等待,或者在代码里先下线再关闭。还有一个保守做法值得保留:关机超时触发后显式调用 srv.Close(),避免因为某个请求卡死导致进程一直拖到被 SIGKILL,那样日志和退出状态都会变得难以判断。若环境不支持自定义信号处理,回退方案只能是缩短宽限期、让进程尽快退出,并接受少量请求失败,这个取舍需要结合业务能否容忍重试来判断。