在发布、扩缩容或宿主机维护时，Docker 容器通常需要先停止接收请求，再释放连接、刷新缓存并保存必要状态。然而，部分容器执行停止命令后长时间不退出，最终被强制终止；另一些容器虽然很快退出，却没有完成清理工作。此类问题往往与停止超时设置、PID 1、信号转发以及应用关闭逻辑有关。下面提供一套可直接执行的排查方法。🔍
一、理解 Docker 的停止流程
执行 docker stop 容器名 时，Docker 会先向容器主进程发送停止信号。未单独配置时，该信号通常是 SIGTERM。Docker 随后等待一段宽限时间；如果容器仍未退出，则发送 SIGKILL 强制结束进程。SIGKILL 无法被捕获或忽略，因此应用来不及继续保存数据和释放资源。具体行为及参数可参考 Docker 官方文档。
需要注意，停止超时并不代表 Docker 会帮助应用执行清理。它只是提供一个时间窗口。真正的优雅停止要求信号能够抵达业务进程，而且业务进程已经实现对应的关闭逻辑。
二、先确认是否发生了强制终止
排查时不要只观察 docker stop 是否返回。可以先执行 docker inspect 容器名，检查容器状态、退出码、启动命令和停止信号配置；再查看 docker logs 容器名，确认日志中是否出现“收到 SIGTERM”“停止接收请求”“关闭连接池”或“退出超时”等信息。
- 日志完全没有收到信号的记录，优先检查 PID 1 和启动脚本。
- 能够收到 SIGTERM，但一直无法退出，重点检查线程、子进程和阻塞任务。
- 清理流程已经开始，却在宽限期结束前未完成，应定位耗时环节并调整超时。
- 容器秒退但数据没有刷新，可能是应用捕获信号后过早调用了退出函数。
还可以使用 docker stop -t 30 容器名 临时设置等待时间进行验证。若延长时间后可以正常退出，说明信号处理链路大概率有效，但清理过程耗时过长。若无论等待多久都没有响应，则不应只靠继续增大超时解决。⚠️
三、检查容器中的 PID 1
Docker 将停止信号发送给容器的主进程，也就是 PID 1。若 Dockerfile 使用 shell 形式启动，例如由 sh -c 间接运行应用，那么 PID 1 可能是 shell，而不是 Java、Node.js、Python 或 Go 服务。部分 shell 不会按预期把 SIGTERM 转发给子进程，业务进程自然无法执行关闭逻辑。
建议进入容器执行 ps 或读取 /proc/1/cmdline，确认 PID 1 究竟是谁。Dockerfile 中应优先使用 exec 形式的 ENTRYPOINT 或 CMD，让业务程序直接成为主进程。如果确实需要启动脚本，脚本最后应使用 exec 应用命令 替换 shell 进程，而不是把应用作为普通子进程留在后台。
对于会派生多个子进程的服务，可考虑在启动容器时加入 --init，或使用轻量 init 进程负责信号转发和僵尸进程回收。不过，引入 init 只能改善信号和进程管理，不能替代应用自身的优雅关闭实现。
四、验证应用是否正确处理 SIGTERM
应用收到 SIGTERM 后，通常应按顺序执行：停止接收新请求、等待正在处理的请求结束、停止定时任务和消费者、刷新缓冲区、提交必要状态、关闭数据库与消息队列连接，最后以正常状态退出。整个流程还应设置内部截止时间，避免某个清理步骤永久阻塞。🧩
常见异常包括：主线程捕获信号后直接退出，异步清理尚未完成；线程池存在非守护线程，导致进程无法结束；HTTP 长连接持续占用；消息消费者仍在拉取新任务；子进程没有收到终止通知；数据库请求无超时；关闭钩子之间相互等待而形成死锁。
建议在信号处理入口、每个清理步骤的开始与结束、最终退出位置分别记录时间和结果。这样可以判断问题是“没有收到信号”，还是“收到了但关闭流程卡住”。
五、核对停止信号和超时配置
某些软件并不使用 SIGTERM 作为推荐停止信号，此时可在 Dockerfile 中通过 STOPSIGNAL 指定，也可以在创建容器时设置 --stop-signal。修改前应查阅该应用的官方说明，避免使用含义不同的信号，更不要把 SIGKILL 当成优雅停止方案。
超时时间应覆盖正常清理所需的高位耗时，并保留合理余量。单次调试可以使用 docker stop -t 秒数；创建容器时可以设置 --stop-timeout；在 Compose 中则可配置相应的停止宽限期。超时不能无限放大，否则故障进程会拖慢发布、回滚和节点关机。
六、按顺序执行排查
- 记录停止开始时间、结束时间、退出码和容器日志。
- 确认容器实际使用的停止信号与等待时间。
- 检查 PID 1、ENTRYPOINT、CMD 以及启动脚本。
- 手动向容器主进程发送 SIGTERM，观察是否生成关闭日志。
- 逐项测量请求排空、线程池关闭、数据刷新和连接释放耗时。
- 检查是否存在僵尸进程、后台子进程、死锁或无超时的网络调用。
- 修复信号处理后进行重复停止测试，并覆盖空闲与高负载场景。
总结
Docker 容器优雅停止异常，本质上通常是“信号发送、信号转发、应用响应、资源清理、超时控制”中的某一环断裂。有效的排查方式不是盲目延长等待时间，而是先确认 SIGTERM 是否到达正确的 PID 1，再检查应用是否按时完成关闭流程。通过规范启动命令、补全信号处理、限制清理耗时并记录关键日志，才能让容器在发布和运维操作中稳定退出，降低请求中断、数据丢失与强制终止的风险。✅
