Golang优雅停机脚本及K8s配置指南

本文深入解析了Go服务在Kubernetes环境中实现真正优雅停机的关键实践：从捕获SIGTERM信号、合理使用http.Server.Shutdown配合带超时的context，到preStop钩子中exec与httpGet方案的选型权衡；强调必须手动关闭数据库连接、Redis/Kafka客户端及所有长期goroutine，并统一通过context.Done()驱动退出，避免因任意资源未释放导致Pod卡在Terminating状态；同时指出常见陷阱——如误用os.Exit、忽略Shutdown阻塞特性、遗漏非HTTP资源清理等，为构建高可靠、可预测终止行为的Go微服务提供了一套完整、可落地的技术指南。

Go 服务如何响应 SIGTERM 实现优雅停机

Go 程序默认收到 SIGTERM 会立即退出，没机会关闭监听、释放连接、刷缓存。必须手动捕获信号并协调 shutdown 流程。

核心是用 signal.Notify 监听 SIGTERM（K8s preStop 默认发的就是它），再调用 HTTP server 的 Shutdown 方法，配合 context 控制超时。

• 别直接用 os.Exit(0) 或 panic 退出，这会跳过 cleanup
• http.Server.Shutdown 是阻塞的，需另起 goroutine 调用，否则主 goroutine 卡住无法继续处理信号逻辑
• 务必给 Shutdown 传带超时的 context.Context，否则可能无限等待空闲连接
• 所有长期运行的 goroutine（比如消息消费、定时任务）都得监听同一个 ctx.Done() 来主动退出

srv := &http.Server{Addr: ":8080", Handler: mux}
go func() {
    if err := srv.ListenAndServe(); err != http.ErrServerClosed {
        log.Fatal(err)
    }
}()

sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGTERM, syscall.SIGINT)
<strong>sig := </strong><code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">sigChan</span></span></span></strong></code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px"></span></span></span></strong><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">接收信号后，启动 Shutdown</span></span></span></strong>
<code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)</span></span></span></strong></code>
<code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">if err := srv.Shutdown(ctx); err != nil &amp;&amp; err != context.DeadlineExceeded {</span></span></span></strong></code>
<code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">&nbsp;&nbsp;log.Printf("shutdown error: %v", err)</span></span></span></strong></code>
<code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">} else {</span></span></span></strong></code>
<code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">&nbsp;&nbsp;log.Println("server gracefully stopped")</span></span></span></strong></code>
<code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">}</span></span></span></strong></code>
<code><strong><span style="color:#000000"><span style="font-family:monospace"><span style="font-size:14px">cancel()</span></span></span></strong></code>

K8s preStop Hook 中 exec 和 httpGet 的选择差异

preStop 是容器终止前执行的钩子，目标是让 Go 进程有时间完成优雅停机。选 exec 还是 httpGet，取决于你是否暴露了 shutdown 接口。

• exec：适合直接向进程发信号，例如 kill -TERM 1（假设 Go 进程 PID=1）。简单，但要求容器里有 kill 命令，且必须确保信号能被正确捕获
• httpGet：需要你在 Go 里额外暴露一个 shutdown endpoint（比如 POST /shutdown），然后 preStop 调用它。更可控，但多一层 HTTP 交互，要防重复触发、鉴权、超时
• 无论哪种，preStop 默认有 30 秒超时（可通过 terminationGracePeriodSeconds 调整），必须确保 Go 的 shutdown 总耗时小于它，否则 K8s 强杀
• 别在 preStop 里做重试或长耗时操作——它只执行一次，失败即结束

HTTP Server Shutdown 容易漏掉的资源清理点

http.Server.Shutdown 只管 HTTP 连接，其他资源得自己关。常见遗漏包括：

• database/sql.DB：调用 db.Close()，否则连接池可能卡住，影响下次启动
• redis.Client 或 kafka.Consumer：必须显式调用 Close()，不然后台 goroutine 持续运行，Shutdown 不会返回
• 自定义 long-running goroutine：比如日志 flusher、指标上报器，都要监听统一的 ctx.Done() 并退出
• 文件句柄、临时目录：如果用了 os.CreateTemp 或 os.OpenFile，记得 Close() 或 os.RemoveAll

建议把所有可关闭资源抽象成一个 Closer 接口，在 main 函数里统一注册，shutdown 时遍历调用。

为什么 preStop 执行完，Pod 还卡在 Terminating 状态

最常见原因是 Go 进程没真正退出，K8s 等超时后强制 kill。排查方向很明确：

• 检查 http.Server.Shutdown 是否被调用——加日志确认
• 看是否有 goroutine 死锁或阻塞在 channel receive / mutex / network I/O 上，用 pprof/goroutine dump 查看存活 goroutine
• 确认所有第三方 client（如 gRPC conn、DB conn）都已 Close()，有些 client 的 Close() 是阻塞的，要设 timeout
• preStop 的命令是否实际生效？比如 exec: ["sh", "-c", "kill -TERM 1"]，但容器里 PID=1 的进程不是你的 Go 二进制（可能是 dumb-init 或 tini），导致信号发错对象

复杂点在于 shutdown 是个协同过程：HTTP server、DB、cache、background jobs 都得按顺序、带超时地退出。任意一环卡住，整个流程就挂住。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~