Go 服务收不到 SIGTERM 的运行环境排查

Go 服务“收不到 SIGTERM”时，先不要把问题归咎于 signal.Notify。更常见的分叉是：信号发给了错误的 PID，容器的 shell 入口没有把信号转发给 Go 子进程，或者程序虽然接到了信号，却没有把它接入正在等待的服务生命周期。排查顺序应固定为“目标 PID → 容器入口 → Go 接收代码”。

官方地址：https://pkg.go.dev/os/signal。本文只讨论这三个边界，不展开编排平台的探针、权限策略或强制终止时限。

为了避免把三类原因混成一句“优雅退出失败”，下面把它们当成三个候选方案来比较：先确认谁收到信号，再确认入口是否转发，最后确认 Go 代码是否把信号转换成 Context 取消。

先把 SIGTERM 和目标 PID 对上

在主机上，kill -TERM 只针对给定 PID；它不会因为某个进程的命令行里出现了 Go 二进制名称，就自动寻找真正的服务进程。容器场景也一样，停止动作首先作用于容器的主进程，也就是 PID 1。若 Go 程序只是它启动的子进程，第一步就要确认这两个 PID 是否相同。

诊断记录只保留四项即可：发送者、目标 PID、目标进程名、Go 服务 PID。不要把完整环境变量或命令行中的密钥写入日志。若目标 PID 已退出，或服务重启后 PID 已变化，继续改 Go 代码并不能解释当前现象。

比较直接入口和 shell 入口

如果入口直接执行 Go 二进制，容器主进程与 Go 服务通常是同一个进程；如果入口先启动 shell，再由 shell 启动 Go，信号可能只到达 shell。这里不要把“用了脚本”简单等同于错误，关键是脚本最后是否用 exec 替换自身，以及它是否还要负责多个子进程的生命周期管理。

可以把入口设计分成三种选择：

因此，看到容器里存在 shell 并不是结论；看到 Go 进程不是 PID 1 也不是单独结论。要把入口形式与实际父子关系放在同一份记录里，再决定是否修正启动命令。

用 NotifyContext 把信号接入服务生命周期

signal.NotifyContext 会返回一个可取消的 Context。当列出的信号到达、父 Context 结束或调用返回的 stop 时，返回 Context 的 Done 会关闭。收到信号后，主流程必须真的等待这个 Context，不能只在旁路 goroutine 中打印一行日志。

package main

import (
    "context"
    "errors"
    "fmt"
    "os"
    "os/signal"
    "syscall"
)

func main() {
    if err := run(context.Background()); err != nil {
        // 只输出可诊断的错误，不打印环境变量或令牌。
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

func run(parent context.Context) error {
    // NotifyContext把SIGTERM转换为服务根Context的取消事件。
    ctx, stop := signal.NotifyContext(parent, syscall.SIGTERM, os.Interrupt)
    defer stop() // 主循环退出后解除注册，避免继续截获默认信号行为。

    // 启动HTTP服务、消费者等组件时，把同一个ctx向下传递。
    if err := serveUntil(ctx); err != nil && !errors.Is(err, context.Canceled) {
        return fmt.Errorf("serve: %w", err)
    }
    return nil
}

func serveUntil(ctx context.Context) error {
    // 示例只等待生命周期事件；真实服务应在这里管理组件退出。
    

这段代码的关键不在于打印“收到信号”，而在于 serveUntil 使用了同一个 ctx。实际项目中，HTTP 服务、消息消费和后台刷新任务都应有明确的停止路径；如果其中一个组件仍阻塞在没有 Context 的调用上，根函数收到取消也不代表进程已经结束。

官方文档还特别说明了 stop 会解除信号行为并释放相关资源，所以它应在生命周期完成后尽快调用。若只创建 Context 而从不调用 stop，可能让后续信号继续被转发到这个上下文。

按证据选择修复点

如果目标 PID 错了，修发送命令或进程定位；如果 PID 1 是 shell 且未转发，修容器入口或脚本的进程接管方式；如果 Go 进程确实接到信号但组件不退出，修 Context 传递和等待逻辑。三种修复不能互相替代：在错误 PID 上增加 NotifyContext，或者把入口问题改成更复杂的业务清理，都只会增加排查噪音。

我会留下这样的最小决策记录：目标 PID 是否为 Go、入口是否直接执行或 exec、代码是否调用 NotifyContext、主循环是否等待 ctx.Done()、停止后是否调用 stop。有了这五项，下一次遇到“收不到 SIGTERM”时，可以快速判断是信号没有到达，还是到达后没有形成退出链路。

为什么本地 Ctrl+C 有效，容器停止却无效？两者可能发送到不同的进程组或目标 PID。先记录容器主进程与 Go 进程的父子关系，再看入口是否接管信号。

为什么收到了 SIGTERM 但服务仍然卡住？检查主循环是否监听返回 Context，以及数据库、HTTP 或消费组件是否收到同一个取消信号；日志里只写阶段，不要写敏感配置。

是否一定要自己创建 signal channel？单一服务生命周期可以优先使用 NotifyContext；需要区分多类信号或自定义分发时再使用 signal.Notify，同时承担 channel 缓冲和停止注册的管理责任。

参考入口：https://pkg.go.dev/os/signal、https://pkg.go.dev/os。信号默认行为、NotifyContext 的取消语义和目标平台差异应以当前 Go 官方文档为准。