---
name: graceful-shutdown
when: '优雅停机, 服务下线, 优雅关闭, shutdown, 健康检查, readiness, liveness, 启停, 灰度发布, 滚动更新'
scope:
  - backend
products:
  - '*'
id: ka-pattern-graceful-shutdown
asset_kind: pattern
lifecycle_status: active
owner_mechanism_id: mc-backend-pattern
authority: supporting
routes:
  - '*'
primary_triggers:
  - 优雅停机
  - 服务下线
  - 优雅关闭
  - shutdown
  - 健康检查
  - readiness
  - liveness
  - 启停
  - 灰度发布
  - 滚动更新
priority: P2
specificity: 3
version: 1.1.0
last_reviewed: '2026-06-01'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
stages: ["*"]
---

## 决策规则
- 服务必须实现优雅停机：收到 SIGTERM 后停止接收新请求，等待正在处理请求完成（建议超时 30s）
- 必须提供健康检查端点：liveness（进程存活）和 readiness（服务就绪，依赖全部可用）
- 滚动更新期间必须先从注册中心摘除再停机，禁止直接 kill 导致请求丢失
- 启动时必须等待依赖组件就绪（DB 连接池、Redis、MQ）后再注册到服务发现
- 定时任务必须在停机时中断执行并记录中断点，重启后可恢复
- 连接池必须配置合理的超时和最大连接数，防止资源泄漏
- Spring Boot 应用必须配置 server.shutdown=graceful + spring.lifecycle.timeout-per-shutdown-phase
- 停机时必须等待正在处理的请求完成（graceful shutdown），设置等待超时（如 30s）
- 线程池必须在停机时执行 shutdownNow() + awaitTermination()，确保任务不丢失
- 定时任务必须在停机时停止调度，正在执行的任务必须完成或中断
- 停机前必须从注册中心（如 Nacos/Eureka）注销，停止接收新流量
- Spring Boot 必须配置 server.shutdown=graceful 和 spring.lifecycle.timeout-per-shutdown-phase

## 验收项
- [AC-01] 服务实现优雅停机（等待请求完成）
- [AC-02] 健康检查区分 liveness/readiness
- [AC-03] 滚动更新先摘除再停机
- [AC-04] 启动时等待依赖就绪
- [AC-05] 请求优雅完成
- [AC-06] 线程池正确关闭
- [AC-07] 从注册中心注销
