发版重启 Java 服务时,你有没有遇到过这些现象:明明是新旧交替,监控上却冒出一批 502;用户在支付或下单的瞬间,请求被硬生生掐断,报了个 connection reset;重启后日志里出现一堆 "Connection closed by peer"。这些问题的根源,多半是停机的姿势不对——进程收到停止信号后直接被杀,正在处理的请求、排队中的任务、到一半的事务全被粗暴截断。
优雅停机(Graceful Shutdown)要解决的就是这件事:让服务在退出前先把"该做的事"做完。具体包括三个层面——从注册中心/负载均衡摘除自己(让别人不再把新请求发过来)、等待在途请求处理完(不打断正在进行的业务)、关闭线程池和资源(释放连接、落盘、提交或回滚事务)。这篇文章就从这三个层面展开,讲清楚 Spring Boot 的配置方式、接不到信号时怎么办、以及发布重启的完整流程和回滚手段。
文中涉及的等待时间、线程池大小都是常见经验值,需要结合你的请求耗时和业务特性调整。所有涉及改配置、改启动脚本的地方,都会强调测试和回滚,因为停机配错,轻则发布期间报错,重则数据不一致。
一、为什么"直接 kill"会出问题
Java 进程收到 SIGTERM(kill 默认信号)时,默认行为并不总是"优雅退出"。如果应用没有注册停机的处理逻辑,JVM 会直接结束进程,带来几个后果:
- 在途请求被中断:线程正在处理 HTTP 请求、正在写数据库,进程一没,客户端收到连接重置。
- 注册中心仍有节点:如果还没来得及把实例从注册中心摘除,网关还在往这台"将死"的机器发请求,全部失败。
- 后台任务丢失:线程池里排队但未执行的任务直接消失,若涉及异步通知、对账,可能造成业务遗漏。
- 资源未释放:数据库连接、文件句柄、临时资源没有清理。
所以优雅停机要按顺序做三件事,顺序很重要:先摘流量,再等在途,最后关资源。顺序错了(比如先关资源再等请求),在途请求照样失败。
这里要澄清一个常见误解:很多人以为"优雅停机"是 Java 独有的高级功能,其实它是所有长时间运行服务都需要的通用能力,只不过 Java 生态提供了比较完善的框架支持。判断一个服务是否真的优雅停机,有个很朴素的标准——停机过程中,用户有没有感知。如果发布时监控上一条错误都没有、用户无感,说明你的停机是优雅的;如果总有零星 5xx,那就还有环节没做对。另一个容易被忽略的点是"时间预算":优雅停机让服务退出变慢,如果发布流程没有相应放宽等待时间,运维可能等不及就直接强杀,前功尽弃。所以优雅停机的配置要和发布流程、编排平台的超时设置一起考虑,单改应用一处往往不够。
二、Spring Boot 的优雅停机配置
Spring Boot 从 2.3 起内置了优雅停机支持,配置很简单:
# application.yml
server:
shutdown: graceful # 开启优雅停机
spring:
lifecycle:
timeout-per-shutdown-phase: 30s # 每个停机阶段最长等待时间(经验值)
开启后,当应用收到 SIGTERM 或调用 SpringApplication.exit() / context.close() 时,Spring 会:
- 停止接收新的 HTTP 请求(不再 accept 新连接)。
- 等待已接收的请求处理完成,最长等
timeout-per-shutdown-phase。 - 依次关闭 Bean,执行
@PreDestroy里的清理逻辑。
配合自定义的销毁钩子,可以在停机时主动"下线":
import org.springframework.stereotype.Component;
import javax.annotation.PreDestroy;
@Component
public class ShutdownHandler {
@PreDestroy
public void onShutdown() {
// 1. 主动从注册中心注销(如 Nacos/Eureka/Consul)
// deregisterFromRegistry();
// 2. 关闭自定义线程池,等待任务完成
// executor.shutdown();
// 3. 释放其他资源
System.out.println("服务正在优雅停机,资源清理中...");
}
}
关键:timeout-per-shutdown-phase 要覆盖你的最长请求耗时。 例如某个导出接口最长要 20s,那这个值至少要 25~30s(经验值),否则请求还没跑完就被强制结束。
三、让进程真正收到停止信号
配置了优雅停机,还得确保 systemd/容器把信号正确送达 Java 进程,否则配置形同虚设。这里有两个经典坑。
坑一:用 java -jar 但 shell 包装导致信号没传给 Java。 如果启动脚本是 sh -c "java -jar app.jar",SIGTERM 可能只发给 shell,Java 收不到。解决:让 Java 成为 PID 1,或用 exec:
# 启动脚本里用 exec,确保 Java 接替 shell 成为主进程
exec java -jar -Xms512m -Xmx512m app.jar
坑二:systemd 的 KillSignal 与 TimeoutStopSec。 默认 systemd 发 SIGTERM,超时后发 SIGKILL(无法被捕获,必杀)。要让优雅停机有足够时间:
# /etc/systemd/system/myapp.service
[Unit]
Description=My Java App
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/java -jar /opt/app/app.jar
SuccessExitStatus=143 ; 143 = 128+15,表示正常响应 SIGTERM 退出,避免被判定为失败
KillSignal=SIGTERM
TimeoutStopSec=40 ; 比应用优雅停机超时略大(经验值)
Restart=on-failure
[Install]
WantedBy=multi-user.target
# 改完重载 systemd 并重启服务
sudo systemctl daemon-reload
sudo systemctl restart myapp
# 观察停机行为,确认不是被 SIGKILL 强杀
sudo journalctl -u myapp -n 100 --no-pager
风险提示:TimeoutStopSec 设得比应用优雅停机时间短,会导致 Java 还没清完就被 SIGKILL,优雅停机白配。两者要匹配;改 unit 文件后必须 daemon-reload,否则改动不生效。回滚方式:备份原 unit 文件,还原后 daemon-reload && systemctl restart。
四、Docker / Kubernetes 场景
容器里 PID 1 的行为同样关键:
# 推荐:直接用 exec 形式启动,让 java 成为 PID 1
ENTRYPOINT ["java", "-jar", "/app/app.jar"]
# 避免 CMD ["sh", "-c", "java -jar ..."],那样信号可能传给 sh 而非 java
Kubernetes 下要配合两个设置:
spec:
terminationGracePeriodSeconds: 45 # Pod 删除时给的总宽限时间
containers:
- name: app
lifecycle:
preStop:
exec:
command: ["sh", "-c", "sleep 5"] # 先睡几秒,等 Endpoint 摘除生效
这里的 sleep 5(经验值)是为了等控制面把 Pod 从 Service 的 Endpoint 里摘掉。因为 K8s 删除 Pod 和更新 Endpoint 是并发的,如果不睡,网关可能还在转发请求,Pod 已经开始拒收,就会有一小段 5xx。terminationGracePeriodSeconds 要大于 preStop 时间 + 应用优雅停机时间,形成完整的等待链条。
传统虚拟机部署没有 K8s 的自动摘除,要自己动手。做法通常是:先把这台机器从 Nginx upstream 里标记 down 或从注册中心注销,nginx -s reload 让它不再被选中;等几秒确认没有新流量进来,再 systemctl stop 触发优雅停机;换完包、启动、健康检查通过后,再把节点加回 upstream。这一套动作养成脚本化、流程化,能极大减少人工操作失误——尤其别在高峰期手动改配置,一个手抖就可能把生产流量指错。把"摘流量、停机、换版、启动、加回"写成一个带校验的发布脚本,是健壮运维的基本功。
五、完整发布重启流程
把上面的点串成一套可执行的发布流程:
# 1. 从负载均衡/注册中心把这台机器摘除(或依赖 preStop 自动摘)
# 2. 向应用发送 SIGTERM,触发优雅停机
sudo systemctl stop myapp # 或 kubectl delete pod(滚动更新自动做)
# 3. 等待进程真正退出(systemd 会等,K8s 看 grace period)
watch -n1 "systemctl is-active myapp"
# 4. 部署新版本
sudo cp app-new.jar /opt/app/app.jar
# 5. 启动并确认健康
sudo systemctl start myapp
curl -sf http://127.0.0.1:8080/actuator/health || echo "健康检查未通过"
# 6. 重新挂回负载均衡/注册中心(或依赖自动注册)
回滚方式:保留上一版本的 jar 和配置,新版发布后如健康检查不通过,立即停机换回旧 jar 启动即可;用 systemd 的话,把 ExecStart 指回旧包路径或还原备份文件再 restart。关键是"新版健康检查通过前,不把全量流量切过去",最好用滚动更新按批次替换。
六、几类特殊资源的处理
优雅停机不止是"等 HTTP 请求",还有几类资源要专门处理:
| 资源类型 | 风险 | 优雅处理方式 |
|---|---|---|
| 数据库事务 | 提交到一半被中断 | 控制请求耗时,配置合理的停机等待 |
| 消息队列消费者 | 消息处理中被杀,触发重投 | 先停止拉取新消息,处理完手上这批再退出 |
| 定时任务 | 突发中断导致任务状态异常 | 停机前检查是否有运行中任务并等待 |
| 线程池 | 排队任务丢失 | shutdown() 后再 awaitTermination 等待 |
| 缓存/连接池 | 连接未归还 | 在 @PreDestroy 中显式关闭 |
线程池的正确关闭方式:
ExecutorService pool = Executors.newFixedThreadPool(8);
// 停机时
pool.shutdown(); // 不再接受新任务
if (!pool.awaitTermination(30, TimeUnit.SECONDS)) {
pool.shutdownNow(); // 超时后强制中断
}
常见问题
Q1:配了 server.shutdown: graceful 但重启时还是有 502?
多半是流量没先摘除。优雅停机只保证"已收到的请求处理完",不保证"上游不再发新请求"。配合注册中心注销或 K8s preStop 先摘流量。
Q2:timeout-per-shutdown-phase 设多大合适?
要大于你最长请求的耗时。普通接口 30s 足够,有长任务接口的要按最长任务时长加缓冲(经验值多加 5~10s)。
Q3:kill -9 和 kill(SIGTERM)有什么区别?
kill 发 SIGTERM,可被捕获,触发优雅停机;kill -9 发 SIGKILL,不可捕获,进程立即死,优雅停机无从谈起。发布脚本里务必用 SIGTERM。
Q4:systemd 里服务停不下来,最后被强杀?
TimeoutStopSec 太小,早于应用停机完成就发了 SIGKILL。把它调大到大于优雅停机时间即可。
Q5:滚动更新时怎么做到用户无感?
让"摘流量 → 停机 → 换版 → 启动 → 加回流量"按序发生;K8s 用 preStop sleep + terminationGracePeriodSeconds,传统部署用手动摘除节点再重启。
总结
- 优雅停机的正确顺序是"先摘流量、再等在途请求、最后关资源",顺序错了在途请求照样失败。
- Spring Boot 用
server.shutdown: graceful+timeout-per-shutdown-phase开启,超时要覆盖最长请求耗时(经验上 30s 起步)。 - 确保
SIGTERM真正送达 Java 进程:脚本用exec、Docker 用 exec 形式、systemd 设KillSignal=SIGTERM且TimeoutStopSec足够大。 - K8s 场景用
preStop sleep等 Endpoint 摘除 +terminationGracePeriodSeconds兜底,避免滚动更新期间的 5xx。 - 数据库事务、消息队列、定时任务、线程池要专门处理;发布保留旧版本,健康检查通过再切流量,随时可回滚。
企业QQ咨询




