Go 为什么服务收不到 SIGTERM

Go 服务收不到 SIGTERM，先不要急着改业务代码。最常见的故障是信号发给了错误的 PID，或者容器、shell 包装脚本没有把信号转给真正的 Go 进程；其次才是程序没有调用 signal.Notify、channel 没有缓冲，或清理逻辑已经卡住。按“目标进程—Go 接收—外部转发—退出清理”的顺序查，通常能很快定位。

一、先确认 SIGTERM 的发送目标和实际进程

在 Linux 上，kill -TERM 1234 的 1234 是一个明确的进程号，不是“某个服务”。先检查服务树：

# 查看目标进程、父进程和完整启动命令
ps -o pid,ppid,stat,cmd -p "$PID"
pstree -ap "$PID"

# 仅验证当前用户是否有权限向目标进程发送信号
kill -0 "$PID"

如果 PPID 对应的是 shell、supervisor 或容器入口脚本，直接杀它未必等于通知 Go 主进程。还要确认发送方没有把停止动作变成 SIGKILL：SIGKILL 不能被 Go 捕获，也不会进入清理代码。若服务马上消失而没有任何清理日志，先记录发送命令、目标 PID 和退出码。

二、用带缓冲的 channel 注册 SIGTERM 并阻塞等待

Go 运行时默认会让 SIGTERM 促使进程退出；如果希望自己执行优雅关闭，就必须显式注册通知并保持主 goroutine 等待。官方文档还特别说明，通知发送不会阻塞在 channel 上，因此单信号场景使用容量为 1 的缓冲 channel 更稳妥。

package main

import (
	"fmt"
	"os"
	"os/signal"
	"syscall"
	"time"
)

func main() {
	// 缓冲 1 个信号，避免清理 goroutine 尚未开始接收时丢掉通知。
	signals := make(chan os.Signal, 1)
	signal.Notify(signals, syscall.SIGTERM, os.Interrupt)
	defer signal.Stop(signals) // 退出前解除注册，避免后续代码继续收到通知。

	// 真实服务应在这里启动 HTTP、数据库和消息消费等资源。
	fmt.Println("service ready")
	sig := 

测试时可在同一环境里记录 echo $! 返回的 PID，再执行 kill -TERM 。若代码直接退出却没有打印“shutdown by”，优先回到第一步检查 PID；若打印了日志但服务仍拖住，问题已经从“收不到”转成“清理不完整”。

三、检查 Docker、systemd 和 wrapper 的信号转发边界

外部管理器决定“第一束信号送到哪里”。Docker 文档规定，docker stop 默认先向容器主进程发送 SIGTERM，等待超时后再发送 SIGKILL；镜像的 STOPSIGNAL 或运行参数也能改变第一束信号。因此容器里的 PID 1 必须就是 Go 服务，或者入口脚本要用 exec 形式替换自身。

# 用 exec 形式让 Go 进程成为容器主进程，直接接收停止信号
ENTRYPOINT ["/app/server"]

# 只有应用确实按其他信号设计时才修改默认值
STOPSIGNAL SIGTERM

systemd 同样可能通过 KillSignal= 改变终止信号；检查 unit 配置和主进程 PID，不要只看服务名。shell 形式的 sh -c、错误的后台启动（例如把 Go 进程放到脚本后面再退出）和进程组转发，都会让“我执行了 stop”与“Go 收到了 SIGTERM”变成两件不同的事。

四、把退出清理做成有上限的生命周期

收到信号后应先让服务停止接收新任务，再关闭监听器、等待在途请求，最后释放数据库和消息消费者。每一步都设置超时，并在超时后记录当前阶段；否则 Docker 或 systemd 的宽限期耗尽，外部管理器会用 SIGKILL 结束进程，读者看到的就像“SIGTERM 没有生效”。

常见问题

SIGTERM 和 SIGKILL 可以用同一段 Go 代码处理吗？

不可以。SIGTERM 可以通过 os/signal 接收并执行清理，SIGKILL 不能被捕获、阻塞或忽略。

为什么本地 kill 有效，部署到 Docker 后无效？

两处的目标 PID 可能不同。容器中先确认 Go 是否是 PID 1，以及入口脚本是否使用 exec 形式启动它。

channel 不缓冲一定会丢 SIGTERM 吗？

不应把它当成绝对结论，但无缓冲 channel 会增加接收方尚未就绪时的风险。单信号通知使用容量 1 的缓冲 channel 是更清晰的默认选择。

排查这类问题的关键不是反复发送 SIGTERM，而是把信号链路拆成四段：发送者、目标 PID、Go 的通知 channel、退出清理阶段。每段都有明确的日志或进程信息后，才能判断是信号没有到达，还是服务已经收到但没有按时退出。