STOPSIGNAL 是什么
STOPSIGNAL 声明容器停止时应当发送哪个信号，不写时默认是 SIGTERM。它有实际意义场景：某些应用用特定信号触发优雅退出，例如 nginx 收到 SIGQUIT 会先处理完已有请求再关闭，收到其他信号则直接断开。把信号写进镜像，停止行为就不再依赖调用方记参数，编排平台与命令行都会遵循这个声明。
基本信息
| 语法 | STOPSIGNAL SIGQUIT（也可写信号编号，如 3） |
|---|---|
| 默认值 | SIGTERM（编号 15） |
| 优先级 | docker run --stop-signal 覆盖镜像内的声明 |
| 宽限期 | docker stop -t 秒数 决定发出信号后等多久再强杀 |
| 生效场景 | docker stop、docker compose stop、编排平台停止容器 |
| 适用平台 | Linux 容器；Windows 容器的信号语义不同 |
典型使用场景
- nginx 等用专用信号触发平滑退出的应用
- 需要先落盘再退出的服务：用信号提示应用进入收尾流程
- 统一编排行为：让所有平台按同一信号停止容器，避免环境差异
- 缩短停机时间：应用能快速响应信号时减少等待宽限期
- 排查退出异常：确认应用实际支持哪个信号，而非套用默认值
声明与验证
声明与验证
# 声明平滑退出信号（nginx 官方镜像采用该配置）
STOPSIGNAL SIGQUIT
# 也可以在运行时覆盖，不影响镜像内容
# docker run -d --stop-signal SIGINT nginx:1.27-alpine观察停止行为
观察停止行为
# 停止并观察耗时：能优雅退出的服务应在宽限期内结束
time docker stop web
# 查看退出码：143 表示收到 SIGTERM，其他值对应别的信号
docker inspect -f 'exit={{.State.ExitCode}}' web
# 确认镜像声明的信号与运行时参数
docker image inspect -f '{{.Config.StopSignal}}' nginx:1.27-alpine
# 事件流里可以看到停止过程的时间点
docker events --filter container=web --since 10m | tail -10信号与行为对照
| 信号 | 典型行为 | 备注 |
|---|---|---|
| SIGTERM（默认） | 请求应用优雅退出 | 多数应用的默认约定 |
| SIGQUIT | nginx 等平滑关闭 | 先处理完已有请求 |
| SIGINT | 等价于中断 | 常被应用视作立即退出 |
| SIGKILL | 无法捕获，立即终止 | 宽限期结束后由引擎发送 |
信号要与应用的实际处理逻辑匹配：应用没有实现对应信号的处理器时，容器会一直等到宽限期结束被强杀，看起来像停止很慢。
容器内 PID 1 的进程才接收这些信号，因此启动命令不要用 shell 包裹：shell 会拦截信号且通常不转发，停止就退化成等待超时。