在容器化系统中，“启动成功”只是第一步，“停止得体”同样重要。应用若在退出前没有完成请求、刷新缓冲区、提交事务或关闭连接，可能造成请求中断、数据不一致和恢复时间延长。Docker 的优雅停止并不是简单地结束进程，而是一套由 Linux 信号、容器主进程和超时策略共同决定的退出流程。理解这套机制，有助于我们构建更可靠的服务。🛑
一、什么是容器的优雅停止
优雅停止是指应用收到终止通知后，不立即中断，而是进入“准备退出”状态：停止接收新任务，等待正在处理的任务完成，释放数据库连接、文件句柄和网络套接字，最后以可预期的状态退出。对于 Web 服务、消息消费者、定时任务和数据处理程序，这一过程尤其重要。
与之相对的是强制终止。强制终止不会等待应用清理资源，进程可能在任意执行位置被结束。因此，优雅停止的核心不是“退出速度越快越好”，而是在规定时间内完成必要的善后工作。✅
二、docker stop 背后的信号流程
执行 docker stop 容器名 时，Docker 会先向容器的主进程发送停止信号。若镜像和容器没有特别配置，这个信号通常是 SIGTERM。随后 Docker 进入等待期；如果主进程在超时前退出，容器正常停止，否则 Docker 将发送不可捕获的 SIGKILL，强制结束进程。具体行为可参考 Docker 官方文档。
SIGTERM 表达的是“请尽快结束”，应用可以捕获它并执行清理逻辑；SIGKILL 则由操作系统直接执行，应用无法捕获、忽略或延迟它。正因如此，应用必须在 Docker 的等待时间内完成退出，否则再完善的清理代码也没有机会继续运行。
可以通过 docker stop -t 30 容器名 调整等待时间，也可以使用 docker stop -s SIGINT 容器名 指定首次发送的信号。等待时间应结合最长请求耗时、事务提交时间和连接排空时间制定，而不应盲目设置得过短或无限延长。
三、PID 1 为什么如此关键
Docker 会把停止信号发送给容器内的主进程，也就是 PID 1。这个进程是否能够正确接收和处理信号，直接决定容器能否优雅退出。常见问题来自 Dockerfile 中 CMD 或 ENTRYPOINT 的写法。
Shell 形式例如 CMD node app.js，通常会启动 /bin/sh -c 作为 PID 1，业务程序则成为它的子进程。如果这个 Shell 没有转发信号，业务程序就可能收不到 SIGTERM，只能等到超时后被 SIGKILL 结束。
Exec 形式例如 CMD ["node", "app.js"]，可以让业务程序直接成为 PID 1，更容易正确接收 Docker 发来的信号。因此，生产镜像通常应优先采用 Exec 形式。若确实需要启动脚本，应在脚本最后使用 exec 替换当前 Shell 进程，而不是简单地创建一个子进程。🔧
四、PID 1 还要负责回收子进程
容器里的 PID 1 不只负责接收信号，还承担回收孤儿进程和僵尸进程的职责。某些应用会频繁创建子进程，但自身没有实现完整的回收机制，长期运行后可能积累僵尸进程。
对于这类场景，可以在启动容器时使用 docker run --init，让一个轻量级 init 进程负责转发信号并回收子进程。需要注意的是，init 进程只能帮助信号正确传递，无法代替应用编写真正的关闭逻辑。
五、应用应该如何处理终止信号
业务程序收到 SIGTERM 后，应按照明确顺序执行退出流程，避免多个组件互相等待或过早释放资源。推荐采用以下步骤：
- 设置“正在关闭”状态，保证退出逻辑只执行一次。
- 从服务发现或负载均衡中摘除实例，并停止接收新请求。
- 等待正在处理的 HTTP 请求、后台任务或消息消费完成。
- 停止定时器、线程池和新的异步任务调度。
- 刷新日志与内存缓冲区，提交或回滚未完成事务。
- 关闭数据库、缓存、消息队列和网络连接。
- 在应用自身的安全超时到达前退出，并返回合理的退出码。
应用内部的退出超时最好略短于 Docker 的强制终止时间。例如外层允许等待 30 秒，应用可以在 25 秒左右主动结束剩余工作，为日志刷新和进程退出预留空间。⏱️
六、docker stop 与 docker kill 的区别
docker stop 面向正常关闭场景，它先发送可处理的停止信号，再在超时后强制终止。docker kill 默认发送 SIGKILL，主要用于进程失去响应、无法正常停止等紧急情况；不过它也可以通过 --signal 发送其他信号。
日常发布、扩缩容和维护操作应优先使用 docker stop；只有在进程无法响应且必须立即结束时，才考虑默认行为下的 docker kill。
七、通过 STOPSIGNAL 定义合适的停止信号
并非所有应用都把 SIGTERM 作为最佳关闭入口。Dockerfile 可以通过 STOPSIGNAL 指令声明镜像期望接收的停止信号，创建容器时也可以使用 --stop-signal 覆盖该配置。相关语法可查阅 来源链接 官方说明。
修改停止信号必须建立在应用文档和实际测试基础上。随意把 STOPSIGNAL 设置为 SIGKILL 会完全绕过优雅关闭机制，通常不适合作为生产环境的默认方案。
八、如何验证优雅停止是否真正生效
- 使用 docker top 容器名 或容器内的进程查看工具，确认谁是 PID 1。
- 执行 docker stop，观察应用是否立即记录收到终止信号以及资源清理日志。
- 在停止过程中持续发送请求，检查新请求是否被拒绝、已有请求是否能够完成。
- 检查容器退出耗时和退出码，判断是否因为等待超时而被强制终止。
- 模拟慢请求、长事务、队列积压和外部依赖超时，验证关闭流程的边界情况。
- 连续执行多次启动与停止，检查是否存在数据丢失、重复消费或资源未释放问题。
总结
Docker 容器的优雅停止，本质上是一条完整的信号链路：Docker 向 PID 1 发送停止信号，主进程捕获信号并通知业务组件停止接收新工作，应用在允许时间内完成清理并主动退出；只有流程超时，Docker 才使用 SIGKILL 强制结束。
要让这条链路可靠工作，应优先使用 Exec 形式的 CMD 或 ENTRYPOINT，确保 PID 1 能正确处理和转发信号，为应用实现可重复执行的关闭逻辑，并根据真实业务耗时设置合理超时。只有把“如何退出”与“如何启动”放在同等重要的位置，容器服务才能在发布、扩缩容和故障恢复中真正做到稳定、可控。🚀
