企业官网建设流程全解析

1. 为什么一个 stop 命令值得单独研究

很多人学 Docker 的时候，注意力基本都放在run、build、ps这些命令上，docker stop往往被当成一个“没什么好说”的收尾动作——容器跑完了，停一下，完事。我一开始也是这么想的，直到有一次在预发环境做批量重启，脚本里清一色docker stop之后接docker rm，结果某个处理队列的容器每次都要卡满十秒才退出，整个发布窗口被硬生生拖长了好几分钟。那次之后我才认真去翻stop的行为细节，发现这个命令背后牵扯的东西比想象中多：信号机制、进程树、超时窗口、退出码、和kill的分工，每一条都直接影响线上操作的体感。

docker stop的本质是向容器内主进程发送终止信号，并给一段宽限期等待其自行退出，超时后再强制杀掉。它解决的问题是“如何优雅地关闭一个容器”，而不是“如何立刻弄死它”。适合谁来读这篇内容？如果你只是偶尔跑个单容器玩玩，知道它能停容器就够了；但只要你写过发布脚本、做过容器编排、处理过数据落盘或者连接池释放的问题，那stop的每一个参数和每一个默认行为都值得掰开看。下面我按自己踩坑的顺序，把这个命令从设计思路到实操细节完整拆一遍，涉及的操作都可以直接照着复现。

2. 命令整体设计与信号机制拆解

2.1 stop 到底做了什么：两步走的设计

先给结论：docker stop是一个两阶段操作。第一阶段，它向容器内的 1 号进程（PID 1，也就是启动命令对应的主进程）发送SIGTERM信号，然后进入等待；第二阶段，如果在指定的超时时间内主进程没有退出，它就补一发SIGKILL，强制终止。

这个设计背后的逻辑很朴素：SIGTERM是“请你收拾一下自己退出”的礼貌通知，进程收到后可以保存状态、关闭文件句柄、把缓冲区数据刷到磁盘、通知下游服务自己要走；而SIGKILL是“立刻消失”，进程没有任何反应机会，内核直接回收。先礼后兵，既给了应用优雅退出的窗口，又保证了最终一定能停下来，不会出现“停不掉”的僵尸状态。

为什么不是一上来就SIGKILL？因为强制杀进程的代价很实在：数据库可能丢最后一批未提交的事务，消息队列消费者可能重复消费，日志可能缺尾巴，临时文件可能残留。我见过一个写本地缓存的容器被直接杀掉后，缓存文件处于半写状态，下次启动读取时直接报解析错误，排查了半天才发现是停机方式的问题。所以stop的“先 TERM 后 KILL”不是啰嗦，是给有状态应用留的体面。

2.2 默认十秒宽限期是怎么来的

docker stop的默认超时是10 秒，对应参数--time（老版本叫-t）。这个数字不是随便定的，它是个折中值：足够大多数 Web 服务处理完手头请求、关闭连接池；又不至于让批量操作等太久。你可以这样理解——十秒是“大多数应用能在不慌不忙的情况下完成收尾”的经验阈值。

但这个默认值对两类场景并不友好。一类是启动慢、收尾也慢的应用，比如要 flush 大量内存数据到磁盘的批处理任务，十秒根本不够，结果就是 TERM 还没处理完就被 KILL，等于优雅退出白做了。另一类是无状态、响应极快的服务，比如一个纯转发的网关，它收到 TERM 后几十毫秒就退出了，你却要等它“确认退出”，虽然实际不会等满十秒（进程退出后 stop 立即返回），但在某些脚本逻辑里如果误用了固定 sleep，就会白白浪费时间。

所以我的习惯是：凡是自己写的镜像，都在启动脚本里明确处理 SIGTERM，并且根据应用特性显式指定--time。有状态、收尾重的给 30 到 60 秒，无状态的给 3 到 5 秒，别让默认值替你做决定。

2.3 stop 与 kill 的分工，别用混了

很多人把docker stop和docker kill当成“温和版”和“暴力版”，这个理解方向对，但细节容易错。docker kill默认发的是SIGKILL，但它其实支持--signal参数指定任意信号，也就是说docker kill --signal=SIGTERM在信号层面和stop的第一阶段是一样的。两者的真正区别在于：stop自带“发信号 + 等待 + 超时补刀”的完整流程，而kill只发一次信号就返回，不管后续。

这个区别在脚本里很关键。如果你用docker kill -s SIGTERM然后立刻docker rm，很可能 rm 的时候进程还没退完，操作失败或者行为不确定。而docker stop会阻塞到容器真正停止（或超时被杀）才返回，语义上更安全。我现在的原则很简单：正常停机一律用 stop，只有在明确知道要立即中断、且能接受数据损失时才用 kill。这个边界划清楚，能省掉很多“为什么数据没落盘”的追问。

3. 核心细节解析与实操要点

3.1 主进程必须是“会听话”的那个

stop的优雅退出能不能生效，有一个前提经常被忽略：容器内的 1 号进程必须真的接收并处理 SIGTERM。这里有两个常见的坑。

第一个坑是PID 1 的特殊性。在 Linux 里，PID 1 进程对信号的默认处理方式和普通进程不同——它不会因为收到没有注册处理函数的信号就自动退出。如果你的容器启动命令是bash -c "xxx"这种形式，bash 作为 PID 1 往往不会把信号转发给真正的业务进程，结果就是 TERM 发出去了，业务进程根本没收到，十秒后照样被 KILL。解决办法是用exec形式启动，让业务进程直接成为 PID 1，比如CMD ["node", "server.js"]而不是CMD node server.js（后者在某些基础镜像里会经过 shell）。

第二个坑是应用自己没注册信号处理。有些框架默认不处理 SIGTERM，收到就按默认行为退出，看起来“停了”，但实际上没做任何清理。这种情况 stop 会很快返回，你以为优雅退出了，其实和 kill 没区别。判断方法很简单：看应用日志里有没有停机时的收尾记录，没有就说明它没处理。

提示：验证一个镜像是否支持优雅停机，最直接的办法是docker stop之后看退出码和日志。退出码 143 表示被 SIGTERM 终止，137 表示被 SIGKILL 强杀。如果每次都是 137，说明你的宽限期根本没用上。

3.2 --time 参数的取值逻辑与计算

--time的单位是秒，可以传小数（部分版本支持），也可以传 0 表示“发完 TERM 立刻 KILL”，等价于直接强杀。取值不是拍脑袋，我一般按这个思路算：

先估算应用最坏情况下的收尾耗时。比如一个消费者服务，停机时要等当前批次处理完（单批最长 8 秒）、提交 offset（1 秒）、关闭连接池（2 秒），那最坏就是 11 秒左右，宽限期给到 15 秒比较稳妥，留一点余量。再比如一个纯 API 服务，停机只需等在途请求结束，P99 延迟 500 毫秒，那给 5 秒绰绰有余。

这里有个反直觉的点：宽限期给太长也有坏处。如果应用其实已经卡死、永远不会自己退出，那长宽限期只会让你多等。所以我的经验是“够用加一点余量”，而不是“往大了给”。批量操作时这个差异会被放大——一百个容器每个多等十秒，就是十几分钟的差距。

3.3 退出码是判断停机质量的窗口

docker stop执行完，容器的退出码藏着很多信息。除了前面说的 143（TERM）和 137（KILL），还有 0（正常退出）、1（应用自身报错退出）等。我排查停机问题时，第一步永远是docker inspect看State.ExitCode和State.FinishedAt，再结合StartedAt算一下实际存活时间。

如果退出码是 137，基本可以断定优雅退出没生效，要么应用没处理 TERM，要么宽限期不够。这时候别急着调大--time，先确认应用到底有没有在收尾——有可能它压根没注册处理函数，调多大都没用，只是让 KILL 来得晚一点而已。这个判断顺序很重要，我见过有人一遇到 137 就无脑加时间，结果加了也没用，因为问题根本不在时间上。

3.4 批量停止时的并发与顺序

docker stop支持一次传多个容器名，它会并发地对这些容器执行停止。这个行为在批量场景下很实用，但要注意两点。一是并发停止对宿主机资源有瞬时压力，如果容器里有大量磁盘写入，同时停可能造成 IO 尖峰；二是有依赖关系的容器不能无脑一起停，比如应用容器依赖数据库容器，应该先停应用再停数据库，否则应用在收尾时发现数据库没了，可能报一堆错甚至写坏状态。

我的做法是：无依赖的一批用一条命令并发停，有依赖的按拓扑顺序分批停，每批之间留一点间隔。这个间隔不用长，几秒就够，目的是让上游真正退完再动下游。

4. 实操过程与核心环节实现

4.1 从零复现一次优雅停机

下面这套流程我用了很多次，可以直接抄。先准备一个会处理 SIGTERM 的最小应用，用 Node 写最直观：

// server.js const http = require('http'); const server = http.createServer((req, res) => { res.end('ok'); }); server.listen(3000, () => { console.log('server started on 3000'); }); process.on('SIGTERM', () => { console.log('received SIGTERM, starting graceful shutdown'); server.close(() => { console.log('all connections closed, exiting'); process.exit(0); }); // 兜底：5 秒内没关完也强制退出 setTimeout(() => { console.log('forced exit after timeout'); process.exit(1); }, 5000); });

对应的 Dockerfile 关键行用 exec 形式，保证 node 是 PID 1：

FROM node:20-slim WORKDIR /app COPY server.js . CMD ["node", "server.js"]

构建并启动：

docker build -t graceful-demo . docker run -d --name demo graceful-demo

然后执行停止并观察日志：

docker stop demo docker logs demo

正常情况下你会看到received SIGTERM和all connections closed两行，退出码是 0。如果只看到第一行没有第二行，说明server.close没等到连接关闭就超时了，这时候要么调大应用内的兜底时间，要么检查是不是有长连接没释放。

4.2 对比实验：宽限期到底起没起作用

想直观感受--time的影响，可以做一组对照。把上面的应用改一下，让它在收到 TERM 后故意睡 8 秒再退出：

process.on('SIGTERM', () => { console.log('received SIGTERM, sleeping 8s'); setTimeout(() => { console.log('done sleeping, exiting'); process.exit(0); }, 8000); });

然后分别用不同的--time停它：

# 宽限期 3 秒，不够，会被 KILL docker run -d --name t3 graceful-demo time docker stop -t 3 t3 docker inspect -f '{{.State.ExitCode}}' t3 # 宽限期 15 秒，够用，优雅退出 docker run -d --name t15 graceful-demo time docker stop -t 15 t15 docker inspect -f '{{.State.ExitCode}}' t15

实测下来，t3大约 3 秒返回，退出码 137，日志里只有received SIGTERM没有done sleeping；t15大约 8 秒返回（不是 15 秒，因为进程提前退出了），退出码 0，两行日志都在。这个对比最能说明问题：stop 的等待是“最多等这么久”，不是“一定等这么久”，进程一退出就立即返回。

4.3 在脚本里安全地批量停止

批量场景我一般这么写，核心是“先查状态、再分批停、最后校验”：

#!/bin/bash # 停止所有带 app=web 标签的容器，宽限期 10 秒 containers=$(docker ps -q --filter "label=app=web") if [ -z "$containers" ]; then echo "no running containers" exit 0 fi docker stop -t 10 $containers # 校验是否全部停止 still_running=$(docker ps -q --filter "label=app=web") if [ -n "$still_running" ]; then echo "warning: some containers still running: $still_running" exit 1 fi echo "all stopped"

这段脚本的价值在于最后的校验。docker stop本身在超时强杀后也会返回成功，所以你不能只看命令返回值就认为“停干净了”，必须再查一次运行状态。我踩过一次坑：某个容器因为挂载的存储无响应，KILL 之后进入了一种半死状态，ps里还能看到，脚本却以为成功了，后续的rm和重建全乱套。加了校验之后这类问题当场暴露。

4.4 停止后立即删除的正确姿势

docker stop之后接docker rm是常见组合，但有个细节：stop返回时容器已经停止，rm一般能成功；但如果容器处于异常状态（比如前面说的半死），rm可能失败。稳妥的写法是docker rm -f，它会先确保停止再删除，一步到位。不过-f的语义是“强制”，在需要保留现场排查问题的场景下不要用，先stop看日志、看退出码，确认没问题再删。

另外，如果你用的是docker run --rm，容器停止后会自动删除，这时候就别再手动rm了，否则会报“no such container”。这个自动删除的行为在调试时挺烦的——容器一停日志就没了，所以调试阶段我一般不加--rm，等稳定了再加。

5. 常见问题与排查技巧实录

5.1 为什么 stop 总是卡满十秒

这是最高频的问题。表现是每次docker stop都要等满默认的十秒才返回，日志里也没有优雅退出的痕迹。原因基本锁定在“应用没处理 SIGTERM”或者“信号没传到业务进程”。排查顺序我固定为三步：先看启动命令是不是 shell 形式（是的话改成 exec 形式），再看应用代码有没有注册 SIGTERM 处理，最后看退出码是不是 137。三步走完，九成情况能定位。

有一种隐蔽情况值得单独说：应用确实注册了处理函数，但处理函数里做了阻塞操作（比如同步写大文件），导致十秒内没完成。这种不是“没收到信号”，而是“收到了但没处理完”，日志里通常能看到“starting shutdown”却没有“done”。解决办法要么优化收尾逻辑，要么调大--time，两者选其一，别混着来。

5.2 容器停了但端口还被占用

偶尔会遇到容器已经stop，但宿主机上对应端口还是被占着，重新启动报端口冲突。这通常不是 stop 的问题，而是容器内进程虽然退了，但某个子进程变成了孤儿进程还在跑，或者内核的连接处于 TIME_WAIT 状态还没释放。前者用docker top在停止前看一眼进程树能提前发现，后者等几十秒自然消失。如果反复出现，检查应用是不是 fork 了子进程却没管理好，容器里出现“主进程退了子进程还在”是很典型的信号处理缺陷。

5.3 停止时数据丢失的排查思路

数据丢失的锅经常被甩给docker stop，但实际原因多半是应用没做好收尾。排查时我会按这个顺序看：第一，退出码是不是 137，是的话说明被强杀，数据没落盘很正常；第二，应用日志里有没有收尾记录，没有说明它没处理 TERM；第三，宽限期是不是太短，收尾没做完就被打断。这三条对应三种不同的修法，别一上来就怀疑 Docker 本身。

5.4 常见问题速查表

注意：排查停机问题时，不要急着删容器。容器一旦删除，日志和退出码都没了，现场就丢了。先 inspect、先看日志，确认原因再清理，这个顺序能救你很多次。

5.5 几个容易被忽略的实操心得

第一个心得：在 CI/CD 里显式指定--time。默认值在不同 Docker 版本里虽然都是 10 秒，但依赖默认值意味着你的发布时长不可控。显式写出来，脚本行为就确定了，换环境也不会变。

第二个心得：给关键应用加停机日志。在信号处理函数的第一行和最后一行各打一条日志，停机时一眼就能看出“收到了”和“做完了”之间的耗时，这个数据是调--time的直接依据，比拍脑袋靠谱得多。

第三个心得：测试环境模拟一次强制断电。用--time 0停一次，看看应用在没有任何收尾机会时会不会留下坏状态。如果会，说明你的应用对非优雅停机没有容错，这在真实故障场景下很危险，值得提前加固。

6. 信号处理与应用侧配合的深层逻辑

6.1 为什么应用侧才是优雅停机的真正主角

绕了一圈你会发现，docker stop本身能做的其实很有限——它只负责“发信号”和“等”，真正决定停机质量的，是容器里的应用怎么响应这个信号。这个认知很重要，因为它把问题的责任边界划清楚了：Docker 提供了机制，应用负责实现。很多人把 stop 当成一个“配置一下参数就万事大吉”的命令，结果应用侧什么都没做，参数调得再精细也是空转。

我在实际项目里推过一个约定：每个自研服务上线前必须通过“停机验收”，验收标准就三条——收到 TERM 后打日志、在宽限期内完成收尾、退出码为 0。这三条不过，不允许进生产。这个约定推行之后，因停机导致的数据问题和发布超时少了非常多，因为问题在开发阶段就被逼出来了，而不是等到线上批量重启时才暴露。

6.2 有状态服务的收尾清单

对于有状态的服务，收尾不是一句“处理一下信号”能概括的，它有一份具体的动作清单。我一般按这个顺序要求应用实现：先停止接收新请求（关闭监听端口或从负载均衡摘除），再等待在途请求处理完，然后提交或回滚未完成的事务，接着把缓冲区数据刷到持久化存储，再关闭数据库连接和消息队列连接，最后释放临时资源并退出。这个顺序不能乱，比如先关连接再刷数据，数据就写不进去了。

这份清单看起来繁琐，但每一条都对应过真实的故障。我印象最深的是一个统计服务，停机时没等缓冲区刷完就退出，导致每次发布都丢最后几分钟的统计数据，量不大但很烦人，查了两周才定位到是停机顺序的问题。后来按清单整改，问题消失。所以别嫌清单长，它是用故障换来的。

6.3 无状态服务也别完全放飞

有人觉得无状态服务反正没数据要保，停机随便点无所谓。这个想法在单机场景下问题不大，但在集群里会出问题。无状态服务停机时如果不处理在途请求，那些请求会直接失败，用户侧看到的就是偶发的 502。正确做法是停机时先把自己从服务发现里摘掉，等一小段时间让流量切走，再处理完手头请求退出。这个“先摘流量再退出”的动作，靠docker stop是做不到的，得应用自己或者编排层配合实现。

这也是我想强调的一点：docker stop是停机链条上的一环，不是全部。理解它在链条里的位置，比孤立地研究它的参数更有价值。它负责发出“该走了”的信号，至于怎么走得体面，是应用和编排层共同的事。

7. 版本差异与参数演进中容易踩的坑

7.1 -t 与 --time 的写法差异

老版本的 Docker 里，超时参数写作-t，新版本统一为--time，-t作为简写仍然可用。这个差异本身不大，但在跨版本脚本里会出问题：某些精简版或者旧版客户端对--time的支持不完整，只认-t。我的习惯是脚本里统一用--time，因为可读性好，同时在文档里注明如果遇到不识别的情况换成-t。这种小兼容问题不值得花太多精力，但知道它存在能省一次莫名其妙的报错。

7.2 信号转发的版本行为差异

不同版本的 Docker 在处理“信号是否转发给容器内所有进程”这件事上，行为有过调整。早期某些版本只把信号发给 PID 1，由 PID 1 自己决定要不要转发；后来的版本在信号处理上更完善。这个差异对用 shell 启动的应用影响很大——同样的镜像，在旧环境里 stop 能优雅退出，换到新环境反而卡满十秒，或者反过来。遇到这种“换环境行为就变”的情况，先怀疑信号转发，用docker top看进程树，确认 PID 1 到底是谁，比盲目调参数有效。

7.3 编排环境下的 stop 语义

在单机docker stop之外，如果你用的是编排工具，停止容器的动作往往由编排层发起，它内部可能调用的就是类似 stop 的机制，但宽限期参数的名字和默认值可能不同。这时候要分清“我敲的命令”和“编排层实际做的事”。我的经验是：不管上层怎么封装，底层判断标准不变——看退出码、看日志、看实际耗时。这三个指标在任何封装下都成立，是排查停机问题的通用抓手。

8. 把 stop 纳入日常运维习惯

8.1 停机演练应该成为常规动作

我现在的习惯是，任何新服务上线前，在测试环境做一次完整的停机演练：正常 stop 一次看日志和退出码，用短宽限期 stop 一次看强杀表现，再模拟一次异常情况看恢复能力。这套演练花不了多少时间，但能把停机相关的隐患提前暴露。演练记录我会简单记一下每次的实际耗时和退出码，作为后续调参的基线。这个习惯坚持下来之后，线上因停机引发的问题基本绝迹。

8.2 监控里加上停机指标

如果条件允许，把容器的退出码和停机耗时纳入监控。退出码 137 的比例突然升高，往往意味着某次发布后应用不再优雅退出了；停机耗时异常增长，可能是收尾逻辑变重了或者有资源泄漏。这些指标平时不起眼，但出问题时是很好的线索。我自己就在一次版本升级后靠这个指标发现新版本的应用忘了注册信号处理，及时回滚避免了线上数据问题。

8.3 一个容易被低估的小技巧

最后分享一个我常用的小技巧：在调试停机问题时，用docker stop的同时另开一个终端跑docker logs -f，能实时看到应用收到信号后的每一步动作。比事后翻日志直观得多，尤其是收尾过程中卡在哪一步，一眼就能看出来。这个技巧没什么技术含量，但在定位“为什么收尾没做完”这类问题时特别好用，比反复猜参数高效多了。

停机这件事，说到底是对“如何体面地结束”的理解。docker stop给了机制，应用给了实现，运维给了习惯，三者凑齐，容器才能真正停得干净、停得可控。我踩过的那些坑，大多是因为只盯着命令本身，忽略了它和应用、和环境之间的配合。把视角从“一条命令”拉到“一条停机链路”，很多问题自然就通了。