stop_grace_period 是 Docker Compose 中为容器预留的 SIGTERM 到 SIGKILL 的等待时长，用于支持应用自主完成优雅停机；它不自动实现优雅停机，需服务代码监听 SIGTERM、暂停新请求、处理活跃连接并释放资源，配合健康检查与反向代理摘流方可达成。
在 Docker Compose 环境中，stop_grace_period 是保障微服务优雅停机的关键配置之一，但它本身不直接实现优雅停机，而是为应用预留“安全退出窗口”——即容器收到 SIGTERM 后，允许其自行处理未完成请求、释放资源、关闭连接等操作的时间上限。
理解 stop_grace_period 的作用机制
stop_grace_period 定义的是从发送 SIGTERM 信号到强制发送 SIGKILL 的等待时长。Docker Compose 停止服务时默认流程是：
- 向容器主进程（PID 1）发送
SIGTERM - 等待
stop_grace_period指定的时间（默认 10s） - 若进程仍未退出，则发送
SIGKILL强制终止
⚠️ 注意：这个配置只控制“等待时间”，不保证应用一定优雅退出——前提是你的服务必须正确响应 SIGTERM 并主动清理。
配合应用层实现优雅停机的关键动作
仅设置 stop_grace_period 不够，还需服务代码层面配合：
- 监听 SIGTERM 信号：在 Java（Spring Boot）、Go、Node.js 等框架中注册 shutdown hook 或 signal handler
-
暂停接收新请求：如反向代理（Nginx / Traefik）下线该实例健康检查；或 Spring Boot Actuator 的
/actuator/health主动返回 DOWN -
等待活跃请求完成：例如 HTTP 服务器停止接受新连接，并等待现有连接超时或自然结束（如设置
server.shutdown=gracefulin Spring Boot 2.3+） - 释放外部资源：关闭数据库连接池、取消定时任务、提交或回滚事务、清理临时文件等
在 docker-compose.yml 中正确配置
示例（以 Spring Boot 微服务为例）：
services:
user-service:
image: myapp/user-service:1.2.0
stop_grace_period: 30s # 给足时间处理长事务或慢查询
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
timeout: 5s
interval: 10s
retries: 3
? 建议值：根据业务特性设定，常见为 15–60 秒。若服务常有 10s+ 的数据库事务或文件上传，至少设为 45s。
验证是否真正生效
不要只看日志有没有 “Received SIGTERM”。可结合以下方式确认：
- 在服务中打印 shutdown 开始与结束时间戳，对比是否在 grace period 内完成
- 用
docker-compose stop -t 0 user-service强制跳过 grace period，观察是否有连接拒绝或事务中断异常 - 压测场景下模拟滚动更新，检查调用方是否出现 502/503 或超时，间接反映下线是否平滑
真正可靠的优雅停机 = 正确的信号处理 + 合理的健康检查 + 足够的 stop_grace_period + 反向代理配合摘流。
