Docker 容器 PID 1 与信号处理：docker stop 超时强制 kill 的成因与写法

发布时间：2026-09-27 04:31 更新时间：2026-09-27 04:31 阅读量：0

很多站长在维护容器化服务时都遇到过这样的场景：执行 docker stop 之后命令迟迟不返回，等上十几秒才结束，日志里看不到任何优雅退出的痕迹，容器状态却已经变成 Exited。用 docker inspect 查看退出码，往往能看到 137 或 143 这类与信号相关的数字。这通常不是 Docker 出了问题，而是容器里的 1 号进程没有正确接收或处理停止信号，Docker 等满宽限期后只能强制发 SIGKILL 收场。本文从 PID 1 的特殊性讲起，把成因、判断方法和几种可落地的写法一次说清。

为什么容器里的 PID 1 如此特殊

在普通 Linux 主机上，PID 1 是 init 或 systemd，它承担了两项内核不会自动代劳的工作：一是回收被孤儿化的子进程（reap），二是把收到的信号转发给对应的子进程。容器启动时，你在 Dockerfile 里写的 ENTRYPOINT 或 CMD 所启动的那个进程，就直接占据了容器命名空间内的 PID 1。它拿到的是一份“init 的职责”，却未必具备 init 的能力。

这里有两个常见误区。第一，进程会以为自己是被内核直接启动的，于是不再按惯例为收到的信号注册处理函数。以 shell 为例，如果 CMD 写成 shell 形式，实际执行的往往是 /bin/sh -c "..."，sh 可能把子进程放在前台跑，也可能不转发信号，导致真正的业务进程收不到 SIGTERM。第二，内核只会把信号投递给 PID 1，如果 PID 1 没有为某个信号安装处理函数，该信号的默认动作对 PID 1 是“忽略”，而不是“终止”。这就是为什么你在容器里手动 kill -15 业务进程能退出，docker stop 却像是没反应。

Docker 的停止流程本身并不复杂：先给 PID 1 发送 STOPSIGNAL（默认 SIGTERM），然后等待，默认 10 秒；如果进程仍未退出，就发送 SIGKILL 强制结束。因此“docker stop 超时后被 kill”的本质，是容器主进程在这段宽限期内没有完成优雅退出。要确认这一点，最快的方式是看退出码和信号：

# 查看容器退出码与是否被信号终止
docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}}' myapp

查看容器配置的停止信号与入口命令
docker inspect -f '{{.Config.StopSignal}} {{.Config.Cmd}} {{.Config.Entrypoint}}' myapp

实时观察主进程收到的信号（需容器内有 strace 或宿主上执行）
docker exec -it myapp ps -o pid,ppid,stat,comm -p 1

退出码 143 一般对应 128+15，也就是被 SIGTERM 终止；137 对应 128+9，即被 SIGKILL 强制杀死。看到 137 且 stop 耗时接近或超过超时时间，基本可以判定为宽限期内没退出。注意不同运行时与版本对退出码的记录方式可能有差异，具体以实际环境为准。

让主进程正确接收信号的几种写法

核心原则只有一条：让业务进程自己成为 PID 1，并且以前台方式运行。下面按从简单到复杂的顺序给出四种常见做法。

第一种，把 CMD 或 ENTRYPOINT 改成 exec 形式。JSON 数组形式不会经过 shell 解析，进程直接成为 PID 1，信号可以原样送达。对比一下：

# 不推荐：shell 形式，中间多了一层 sh，信号容易被吞
CMD node server.js

推荐：exec 形式，node 直接成为 PID 1
CMD ["node", "server.js"]

第二种，如果确实需要 shell 做变量展开或条件判断，用 exec 把业务进程替换掉当前 shell，让 shell 不再作为父进程存在：

CMD ["/bin/sh", "-c", "exec node server.js"]

第三种，如果应用是 Java、Python 这类需要额外包装的启动方式，或者你希望有一个轻量 init 帮忙回收僵尸进程并转发信号，可以使用 Docker 自带的 --init 参数，它会注入 tini 作为 PID 1：

docker run -d --init --name myapp -p 8080:8080 myimage:latest

用 docker compose 时在服务里开启
services:
app:
image: myimage:latest
init: true

第四种，在镜像层面固定一个 init 入口。tini 体积很小，适合放进基础镜像，Dockerfile 里可以这样写：

FROM debian:12-slim
RUN apt-get update && apt-get install -y --no-install-recommends tini \
    && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["node", "server.js"]

需要提醒的是，tini 只负责转发信号和回收子进程，它不会替你的应用做优雅关闭。真正的关闭逻辑，比如停止接收新请求、等待在途任务结束、刷新缓冲区、关闭数据库连接，仍然要在应用的信号处理函数里实现。以 Node.js 为例，至少要监听 SIGTERM 并主动退出：

process.on('SIGTERM', () => {
  server.close(() => {
    // 关闭数据库连接、刷新日志等收尾动作
    process.exit(0);
  });
});

另外，宽限期可以通过 -t 参数或 compose 的 stop_grace_period 调整，让它与应用的关闭耗时相匹配，而不是盲目调大：

# 给应用 30 秒完成优雅退出
docker run -d --init -t 30 --name myapp myimage:latest

查看当前容器实际使用的宽限期配置
docker inspect -f '{{.HostConfig.StopTimeout}}' myapp

排查顺序与常见坑

遇到 stop 超时，建议按下面的顺序逐项确认。先看 PID 1 到底是谁：docker exec myapp ps -ef，如果 1 号是 sh 或 bash 而业务进程是它的子进程，问题基本就定位了。再看进程有没有注册信号处理：可以用 docker exec 进入容器，对 1 号进程发一个 SIGTERM，观察是否退出，这一步不会影响宿主机上其他容器。最后确认应用日志里有没有收到关闭信号，很多框架默认只处理 SIGINT 或 SIGTERM 中的一个，写错就会一直等到被强杀。

还有几个容易被忽略的点。一是 STOPSIGNAL：某些镜像（例如部分基于 nginx 的镜像）会把停止信号设为 SIGQUIT，如果你在 Dockerfile 里又改回了 SIGTERM，而应用只处理 SIGQUIT，同样会超时；可以用 STOPSIGNAL SIGQUIT 显式声明，保持与官方镜像一致。二是僵尸进程：如果主进程会 fork 子进程却不回收，日积月累会出现大量 Z 状态进程，tini 或 --init 能缓解这个问题。三是不要把 stop 超时简单等同于“Docker 太慢”，宽限期到了才 kill 是设计行为，缩短或延长都要基于应用真实的关闭耗时。

一句话总结：容器里 PID 1 收不到信号，多半是 shell 包装或前台运行方式不对；用 exec 形式启动业务进程，必要时加 tini 或 --init 做信号转发与进程回收，再让应用实现 SIGTERM 的优雅关闭，docker stop 自然就能在秒级干净退出，不会再走到强制 kill 那一步。下一步不妨挑一个正在跑的生产容器，用 docker inspect -f '{{.Config.Cmd}}' 看它的启动形式，顺手把不规范的地方改掉。

继续阅读