Java 微服务优雅停机：从踩坑到最佳实践
Java 微服务优雅停机：从踩坑到最佳实践
博客标签：
JavaSpring Boot微服务优雅停机Kafka
阅读时长：约 10 分钟
一、从一次半夜告警说起
凌晨两点，运维发来消息：
“刚刚发布了一个版本，线上有几十条订单状态异常，用户投诉了。”
排查之后发现，问题出在服务重启的那 3 秒——Kafka 消费者正在处理一批消息，kill命令一下去，JVM 直接退出，消息处理到一半，数据库写了一半，状态就永远停在了中间态。
这就是没有优雅停机的代价。
二、什么是优雅停机？
优雅停机（Graceful Shutdown）是指：服务在接收到停止信号后，不立即强制退出，而是先完成正在处理的请求/任务，再有序释放资源，最后退出进程。
对比两种停机方式：
| 方式 | 命令 | 行为 | 风险 |
|---|---|---|---|
| 强制停机 | kill -9 <pid> | 内核直接终止进程，JVM 无感知 | 数据丢失、状态不一致 |
| 优雅停机 | kill -15 <pid> | JVM 捕获 SIGTERM，触发 ShutdownHook | 可控，推荐 |
kill -9是 SIGKILL，操作系统层面强杀，任何代码钩子都无法拦截。生产环境禁止使用。
三、Spring Boot 优雅停机原理
Spring Boot 2.3+ 内置了优雅停机支持，核心是两个配置项：
server:shutdown:graceful# 启用优雅停机（默认 immediate）spring:lifecycle:timeout-per-shutdown-phase:30s# 最大等待时间触发流程如下：
kill -15 │ ▼ JVM ShutdownHook │ ▼ Spring 发布 ContextClosedEvent │ ▼ 各组件有序销毁（HTTP容器 → Bean → 连接池） │ ▼ JVM 退出启用server.shutdown=graceful后，Tomcat/Undertow 会拒绝新请求，等待已有请求处理完毕，再关闭。
四、实战：三层资源的优雅关闭
生产环境中，一个微服务通常有三类需要优雅处理的资源：
4.1 HTTP 请求层
只需 YAML 配置，零代码：
server:shutdown:gracefulspring:lifecycle:timeout-per-shutdown-phase:30sSpring Boot 会自动为 Tomcat/Undertow 注入GracefulShutdown回调，停机时不再接收新请求，等待存量请求完成。
4.2 线程池层
业务线程池需要主动等待任务完成，否则线程池一关，正在跑的任务直接中断：
@ConfigurationpublicclassThreadPoolConfig{@Bean(name="bizExecutor")publicThreadPoolTaskExecutorbizExecutor(){ThreadPoolTaskExecutorexecutor=newThreadPoolTaskExecutor();executor.setCorePoolSize(20);executor.setMaxPoolSize(50);executor.setQueueCapacity(200);executor.setThreadNamePrefix("biz-thread-");// 关键：停机时等待任务完成executor.setWaitForTasksToCompleteOnShutdown(true);executor.setAwaitTerminationSeconds(20);// 最多等 20sreturnexecutor;}}参数约束：
awaitTerminationSeconds（20s）<timeout-per-shutdown-phase（30s），保证线程池有足够时间收尾。
4.3 Kafka 消费者层
Kafka 消费者是最容易踩坑的地方。以@KafkaListener为例：
问题：Spring Kafka 的消费者在收到停机信号后，会调用consumer.wakeup()中断poll()，但正在业务线程池里处理的消息不会等待。
解决方案：消费者业务线程池同样使用 Spring Bean 管理，让 Spring 容器负责生命周期：
@ConfigurationpublicclassConsumerThreadPoolConfig{@Bean(name="kafkaBizExecutor")publicThreadPoolTaskExecutorkafkaBizExecutor(@Value("${kafka.consumer.thread-pool-size:50}")intpoolSize){ThreadPoolTaskExecutorexecutor=newThreadPoolTaskExecutor();executor.setCorePoolSize(poolSize);executor.setMaxPoolSize(poolSize);executor.setQueueCapacity(0);// SynchronousQueue 语义，防止积压executor.setThreadNamePrefix("kafka-biz-");executor.setRejectedExecutionHandler(newThreadPoolExecutor.CallerRunsPolicy());// Spring 停机时自动 shutdown 并等待executor.setWaitForTasksToCompleteOnShutdown(true);executor.setAwaitTerminationSeconds(20);returnexecutor;}}消费者注入并使用：
@Component@RequiredArgsConstructorpublicclassOrderConsumer{privatefinalThreadPoolTaskExecutorkafkaBizExecutor;@KafkaListener(topics="order-topic",groupId="order-group")publicvoidonMessage(ConsumerRecord<String,String>record){// 提交到业务线程池异步处理kafkaBizExecutor.submit(()->handleOrder(record));}privatevoidhandleOrder(ConsumerRecord<String,String>record){// 真正的业务逻辑log.info("处理订单消息: {}",record.value());}}五、微服务注册中心配合：Nacos 反注册
在微服务体系中，停机还需要配合注册中心下线，否则上游服务还会把请求打过来：
@Component@Slf4jpublicclassGracefulShutdownHandlerimplementsApplicationListener<ContextClosedEvent>{privatefinalNacosAutoServiceRegistrationnacosRegistration;privatefinalAtomicBooleanstopped=newAtomicBoolean(false);@OverridepublicvoidonApplicationEvent(ContextClosedEventevent){// AtomicBoolean 防止 Feign 子上下文事件冒泡重复触发if(!stopped.compareAndSet(false,true)){return;}log.info("[优雅停机] 开始执行...");// 第一步：Nacos 取消注册，上游立即感知下线if(nacosRegistration.isRunning()){nacosRegistration.destroy();log.info("[优雅停机] Nacos 反注册完成");}// 第二步：等待上游 Ribbon 缓存刷新（通常 30s 周期）log.info("[优雅停机] 等待 30s，让上游感知下线...");ThreadUtil.sleep(30_000);log.info("[优雅停机] 等待结束，进入 Bean 销毁阶段");}}为什么要 sleep 30s？
Ribbon 客户端的服务列表缓存默认 30s 刷新一次。Nacos 反注册后，上游不会立刻知道你下线了，这 30s 的等待是给上游缓存过期的时间窗口。
六、完整停机时序
kill -15 │ ▼ [GracefulShutdownHandler] 监听 ContextClosedEvent ├─ ① Nacos 反注册（上游秒级感知） └─ ② sleep(30s)（等待上游缓存刷新） │ ▼ [Spring 自动销毁 Bean] ├─ kafkaBizExecutor.shutdown()（等待 ≤ 20s） ├─ bizExecutor.shutdown()（等待 ≤ 20s） ├─ DataSource 连接池关闭 └─ Redis 连接池关闭 │ ▼ JVM 退出（全程约 30s + Bean 销毁时间）七、常见踩坑汇总
| 坑 | 原因 | 解决方案 |
|---|---|---|
kill -9无效 | SIGKILL 绕过 JVM | 改用kill -15 |
| 停机日志打印 N 遍 | Feign 子上下文ContextClosedEvent冒泡 | 用AtomicBoolean.compareAndSet防重 |
| 线程池不等待 | 忘记设置setWaitForTasksToCompleteOnShutdown(true) | 见 §4.2 |
| 上游仍打流量 | 未做 Nacos 反注册 | 见 §5 |
Spring Boot 2.2 不支持server.shutdown=graceful | 该配置 2.3 才引入 | 自实现ApplicationListener<ContextClosedEvent> |
八、总结
优雅停机的核心是三层协同：
- 容器层（HTTP）：
server.shutdown=graceful，拒绝新请求，等待存量完成 - 线程池层：
setWaitForTasksToCompleteOnShutdown=true，等待异步任务完成 - 注册中心层：主动 Nacos 反注册 + sleep，给上游感知时间
做到这三点，就能把停机风险从"数据损坏"降到"业务无感知"。
本文示例基于 Spring Boot 2.3+ + Spring Cloud Alibaba + Nacos，完整代码已在生产环境验证。
如果本文对你有帮助，欢迎点赞收藏！有问题欢迎评论区交流。