Java应用如何配置优雅停机?服务下线、请求处理与重启流程详解

发版重启 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 会:

  1. 停止接收新的 HTTP 请求(不再 accept 新连接)。
  2. 等待已接收的请求处理完成,最长等 timeout-per-shutdown-phase。
  3. 依次关闭 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。
  • 数据库事务、消息队列、定时任务、线程池要专门处理;发布保留旧版本,健康检查通过再切流量,随时可回滚。