基于SpringBoot Actuator与Kubernetes的优雅停机策略优化实践

1. 为什么优雅停机在Kubernetes里是个“老大难”？

大家好，我是老张，在微服务和云原生这块摸爬滚打十来年了。今天想和大家掏心窝子聊聊一个看似简单、实则坑多的问题：在Kubernetes（后面咱就简称k8s了）里，怎么让Spring Boot应用“体面”地关掉？

你可能遇到过这种场景：半夜收到告警，某个服务实例挂了，k8s自动拉起一个新Pod。这本是好事，但一看日志，老Pod关停的时候，一堆正在处理的请求被硬生生掐断，用户支付订单失败了，数据同步到一半出错了，甚至把数据库连接池搞得一团糟。这感觉，就像你正写着文档没保存，突然被人拔了电源，别提多憋屈了。

这就是“优雅停机”没做好。简单说，优雅停机就是让应用在收到关闭信号后，别急着立刻“死掉”，而是先完成手头的工作：比如把还没响应的HTTP请求处理完，把数据库事务安全提交，把线程池里的任务有序结束，最后再释放资源、关闭端口。在传统的虚拟机或物理机部署时，我们可能写个脚本，发个SIGTERM信号，应用自己处理一下也就差不多了。但到了k8s这个动态编排的世界里，事情就复杂多了。

k8s有自己的“生杀大权”。当你滚动更新、缩容或者节点维护时，k8s会向Pod里的容器发送SIGTERM信号，然后给一个宽限期（默认30秒），超时后就直接发SIGKILL强制干掉了。问题就出在这：Spring Boot应用默认的停机行为，和k8s的这个生命周期，经常对不上节奏。

我踩过的坑主要有三个：第一，请求丢失。Tomcat或Netty在收到停止信号后，可能立刻停止接收新请求，但正在处理的请求如果耗时较长（比如调用了外部慢接口），没等处理完，宽限期就到了，进程被杀，请求自然失败。第二，资源泄露。数据库连接、Redis连接、文件句柄这些资源，如果没有在应用上下文关闭的钩子里正确释放，就会一直占着，时间长了能把中间件拖垮。第三，服务发现滞后。应用虽然开始关了，但服务注册中心（比如Nacos、Eureka）还没及时把它摘掉，流量还会继续打过来，导致部分请求失败。

所以，光靠Spring Boot那点默认的停机能力，在k8s环境里是远远不够的。我们需要一套更精细、更主动的策略，而Spring Boot Actuator和k8s的生命周期钩子，就是为我们量身定制的“手术刀”。接下来，我就带你一步步优化，打造一个既稳健又灵活的优雅停机方案。

2. Spring Boot Actuator：你的应用“管理后台”

要优化停机，首先得能“指挥”应用。Spring Boot Actuator就是这样一个内置的监控和管理模块。你可以把它理解成应用自带的一个“管理后台”，通过HTTP或JMX端点（Endpoint），我们能查看健康状态、监控指标、审计日志，当然，也能触发停机。

Actuator功能很丰富，但我们今天只聚焦和优雅停机最相关的几个端点：

• /actuator/health：健康检查。在k8s里，就绪探针（Readiness Probe）和存活探针（Liveness Probe）都靠它。
• /actuator/info：应用基本信息。
• /actuator/shutdown：这就是我们今天的主角。通过向这个端点发送一个POST请求，可以触发应用的优雅停机流程。注意，这个端点默认是禁用的，出于安全考虑。

2.1 快速启用与配置Shutdown端点

启用它非常简单。在你的application.yml（或application.properties）里加上几行配置就行：

management: endpoints: web: exposure: include: "health,info,shutdown" # 明确暴露shutdown端点，不建议用'*' endpoint: shutdown: enabled: true # 关键！启用shutdown端点 server: port: 8081 # 建议将管理端口与应用业务端口分离，更安全

这里有个我强烈建议的操作：把管理端口（management.server.port）和你的应用业务端口分开。比如业务跑在8080，Actuator的管理端点跑在8081。这样做有两个巨大好处：一是安全，可以把管理端口的访问权限严格控制在内网；二是在k8s配置探针和预停止钩子时，目标非常清晰，不会干扰正常业务流量。

配置好后，启动应用，用curl命令测试一下：

curl -X POST http://localhost:8081/actuator/shutdown

如果返回一段JSON消息{"message": "Shutting down, bye..."}，并且应用开始有序关闭，那就说明基础功能通了。

2.2 深入理解：Shutdown端点背后做了什么？

你可能好奇，调用这个端点，和直接kill -15（SIGTERM）有啥区别？本质上，它们最终都会触发Spring的ContextClosedEvent事件。但通过HTTP端点触发，给了我们更多的控制权和灵活性。

当我们调用/actuator/shutdown时，Spring Boot会按顺序做这几件事：

1. 停止接收新请求：内嵌的Web服务器（Tomcat/Netty/Undertow）会停止接受新的连接。
2. 等待当前请求完成：这是优雅的核心。它会有一个等待期，让正在执行的请求处理完毕。这个等待时间可以通过server.shutdown属性配置，例如server.shutdown=graceful（Spring Boot 2.3+）并配合spring.lifecycle.timeout-per-shutdown-phase=30s来设置最长等待时间。
3. 发布ContextClosedEvent：通知所有监听了该事件的Bean，应用上下文即将关闭。
4. 执行销毁回调：所有实现了DisposableBean接口或定义了@PreDestroy方法的Bean，会按依赖关系的相反顺序执行清理逻辑。这里就是你释放数据库连接池、关闭线程池、清理临时文件的关键位置！
5. 关闭应用上下文：正式关闭Spring容器。
6. 退出JVM：最终进程结束。

你看，这个过程是可控、可观测的。而我们接下来要做的，就是让k8s在决定删除Pod时，自动、可靠地触发这个流程。

3. 与Kubernetes深度集成：不只是配置一个preStop钩子

很多文章讲到k8s优雅停机，就只说在Pod的lifecycle里配一个preStop钩子，里面执行curl命令调用shutdown端点。这思路没错，但太粗糙，在实际生产环境里很容易翻车。我们必须考虑得更周全。

3.1 配置就绪探针（Readiness Probe）：先让流量“刹车”

优雅停机的第一步，不是立刻开始关，而是先告诉外界“我准备要关了，别再给我新活了”。在k8s里，这个“外界”就是Service背后的负载均衡器。实现这个的，就是就绪探针（Readiness Probe）。

当k8s决定终止一个Pod时，它会第一时间把这个Pod的IP从Service的端点列表（Endpoints）里摘除。而判断一个Pod是否“就绪”的依据，就是你的Readiness Probe。所以，我们的优化策略是：在preStop钩子执行之前，先让Readiness Probe失败。

怎么做到呢？我们需要一个能动态改变健康状态的机制。Spring Boot Actuator的/actuator/health端点支持自定义健康指示器（Health Indicator）。我们可以写一个简单的，比如叫GracefulShutdownHealthIndicator：

@Component public class GracefulShutdownHealthIndicator implements HealthIndicator { private final AtomicBoolean shuttingDown = new AtomicBoolean(false); public void setShuttingDown(boolean isShuttingDown) { this.shuttingDown.set(isShuttingDown); } @Override public Health health() { if (shuttingDown.get()) { // 当处于关闭中状态时，报告OUT_OF_SERVICE return Health.outOfService() .withDetail("message", "Application is shutting down gracefully") .build(); } return Health.up().build(); } }

然后，在你的停机事件监听器里，在真正开始停机流程前，先调用这个setShuttingDown(true)。这样，/actuator/health端点的状态就会变为OUT_OF_SERVICE。把你的Readiness Probe指向/actuator/health，k8s检测到状态不健康，就会立刻将Pod从服务发现中摘除，新的流量就不会再进来了。

3.2 优化preStop钩子：确保请求完全排空

摘除流量后，Pod里可能还有正在处理的请求。这时，我们再执行preStop钩子。一个基础的配置长这样：

apiVersion: apps/v1 kind: Deployment spec: template: spec: containers: - name: my-springboot-app image: my-app:latest lifecycle: preStop: exec: command: - /bin/sh - -c - | # 先标记为关闭中，使就绪探针失败 curl -s -X POST http://localhost:8081/actuator/graceful/shutdown/mark # 等待一段时间，确保流量完全排空。这个时间需要根据你的应用平均请求耗时来定。 sleep 20 # 最后，触发真正的应用关闭 curl -X POST http://localhost:8081/actuator/shutdown

这里我引入了两个关键点：

1. 自定义端点：我增加了一个自定义的Actuator端点（/actuator/graceful/shutdown/mark），它的作用就是触发前面提到的GracefulShutdownHealthIndicator状态变更。这比直接调用shutdown更精细。
2. 睡眠等待：在标记关闭后，等待20秒（具体时间你根据业务调整）。这给了网关和负载均衡器足够的时间更新路由表，也确保了正在进行的短请求有足够时间完成。

特别注意：你的Docker镜像里必须包含curl工具，否则preStop命令会执行失败。可以在Dockerfile里用RUN apt-get update && apt-get install -y curl（对于Debian系）来安装。

3.3 协调terminationGracePeriodSeconds

k8s给Pod的spec下有一个关键字段叫terminationGracePeriodSeconds（默认30秒）。它定义了从发送SIGTERM到发送SIGKILL之间的宽限期。

我们的preStop钩子执行时间，是包含在这个宽限期内的！所以，你必须算好总账：preStop执行时间（等待+curl）+Spring Boot自身优雅关闭最大等待时间（spring.lifecycle.timeout-per-shutdown-phase）<terminationGracePeriodSeconds

如果总时间超过了宽限期，k8s会不耐烦地发SIGKILL，一切优雅都白费了。我建议把这个值适当调大，比如60秒或90秒，并在preStop脚本里做好超时控制。

apiVersion: apps/v1 kind: Deployment spec: template: spec: terminationGracePeriodSeconds: 90 # 延长宽限期 containers: - name: my-springboot-app ...

4. 构建你的自定义优雅停机“插件”

理解了原理，我们可以把上述最佳实践封装成一个可复用的组件，也就是所谓的“插件”或“Starter”。这样，团队里的每个Spring Boot应用只需要引入这个依赖，就能获得一套增强的优雅停机能力，无需重复配置。

4.1 项目结构与核心Bean

我们来创建一个简单的Spring Boot Starter项目，结构如下：

graceful-shutdown-spring-boot-starter ├── src/main/java/com/yourcompany/graceful/ │ ├── autoconfigure/ │ │ └── GracefulShutdownAutoConfiguration.java # 自动配置类 │ ├── endpoint/ │ │ ├── CustomGracefulShutdownEndpoint.java # 自定义端点 │ │ └── GracefulShutdownHealthIndicator.java # 健康指示器 │ ├── event/ │ │ └── GracefulShutdownEventListener.java # 事件监听器 │ └── properties/ │ └── GracefulShutdownProperties.java # 配置属性类 └── src/main/resources/META-INF/ └── spring.factories # Spring Boot自动配置注册文件

核心代码拆解：

1. 配置属性类 (GracefulShutdownProperties)：让用户可以通过application.yml自定义等待时间等参数。

   @ConfigurationProperties(prefix = "graceful.shutdown") @Data public class GracefulShutdownProperties { /** * 从标记关闭到真正开始关闭的等待时间（秒），用于排空请求。 */ private Integer waitBeforeShutdown = 20; /** * 是否启用增强的优雅停机功能 */ private Boolean enabled = true; }

2. 健康指示器 (GracefulShutdownHealthIndicator)：上面已经写过，用于动态控制就绪状态。

3. 自定义端点 (CustomGracefulShutdownEndpoint)：提供一个额外的HTTP端点，用于触发“准备关闭”状态，而不仅仅是最终关闭。

   @Endpoint(id = "gracefulshutdown") // 端点ID会映射为 /actuator/gracefulshutdown @Component public class CustomGracefulShutdownEndpoint { private final GracefulShutdownHealthIndicator healthIndicator; public CustomGracefulShutdownEndpoint(GracefulShutdownHealthIndicator healthIndicator) { this.healthIndicator = healthIndicator; } @WriteOperation // 对应POST方法 public Map<String, String> markShuttingDown() { healthIndicator.setShuttingDown(true); return Collections.singletonMap("message", "Application is now marked as shutting down. Readiness probe will fail."); } }

4. 事件监听器 (GracefulShutdownEventListener)：监听Spring上下文关闭事件，执行一些自定义的清理逻辑，比如记录更详细的日志，或者确保某些异步任务完成。

   @Slf4j @Component public class GracefulShutdownEventListener implements ApplicationListener<ContextClosedEvent> { @Override public void onApplicationEvent(ContextClosedEvent event) { log.info("应用上下文开始关闭，执行自定义清理..."); // 例如：关闭自定义的线程池、清理缓存客户端连接等 // 这里可以注入你自己的Bean来做清理 log.info("自定义清理完成。"); } }

5. 自动配置类 (GracefulShutdownAutoConfiguration)：将上述所有Bean按条件装配起来，并确保Actuator的shutdown端点被启用。

   @Configuration @ConditionalOnClass(Endpoint.class) // 当Actuator存在时生效 @EnableConfigurationProperties(GracefulShutdownProperties.class) @AutoConfigureAfter(WebEndpointAutoConfiguration.class) public class GracefulShutdownAutoConfiguration { @Bean @ConditionalOnMissingBean public GracefulShutdownHealthIndicator gracefulShutdownHealthIndicator() { return new GracefulShutdownHealthIndicator(); } // ... 其他Bean的定义 }

6. spring.factories文件：让Spring Boot能发现我们的自动配置。

   org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ com.yourcompany.graceful.autoconfigure.GracefulShutdownAutoConfiguration

4.2 打包与使用

将项目打包成JAR，发布到公司的Maven私服。其他业务应用只需要引入这个依赖：

<dependency> <groupId>com.yourcompany</groupId> <artifactId>graceful-shutdown-spring-boot-starter</artifactId> <version>1.0.0</version> </dependency>

然后在application.yml里做最小化配置（如果需要覆盖默认值）：

graceful: shutdown: wait-before-shutdown: 25 management: endpoints: web: exposure: include: "health,shutdown,gracefulshutdown" # 暴露我们的自定义端点 endpoint: shutdown: enabled: true server: port: 8081

最后，就是按照我们前面优化过的k8s Deployment配置去部署即可。

5. 避坑指南与版本差异

在实际落地过程中，我遇到过不少坑，这里分享几个最重要的。

坑一：Spring Boot版本差异Spring Boot 2.3是一个重要的分水岭。在这个版本，官方正式引入了对优雅停机的内置支持（server.shutdown=graceful）。如果你用的是2.3及以上版本，可以更简单地配置：

server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 30s # 设置优雅关闭超时时间

这个机制会和Actuator的shutdown端点协同工作。但在2.3之前，我们需要更多地依赖自定义事件监听和preStop钩子来模拟这个过程。我们的“插件”最好能兼容不同版本，可以通过条件注解@ConditionalOnProperty或@ConditionalOnWebApplication的不同类型来实现适配。

坑二：长连接和WebSocket如果你的应用有WebSocket或SSE（服务器发送事件）这种长连接，优雅停机会更棘手。因为连接可能一直保持，不会像HTTP请求那样快速结束。对于这种情况，需要在ContextClosedEvent监听器中，主动遍历并关闭这些长连接。Netty或Undertow等Web服务器提供了相应的API来获取活动连接列表。

坑三：异步任务与消息队列应用可能正在处理来自Kafka、RabbitMQ的消息，或者在执行@Async注解的异步方法。停机时，必须确保这些任务不被强行中断。对于消息队列，要确保在消费端逻辑里做好幂等处理，并可能在关闭前暂停消费。对于Spring的@Async任务，可以注入ThreadPoolTaskExecutor，在关闭时调用shutdown()并awaitTermination。

坑四：健康检查的误杀配置了存活探针（Liveness Probe）指向/actuator/health。当我们的GracefulShutdownHealthIndicator报告OUT_OF_SERVICE时，如果存活探针也用它，可能会导致k8s误认为Pod不健康而重启它！切记，存活探针和就绪探针要分开。存活探针应该指向一个更稳定、更基础的检查，比如只检查应用进程是否存活，或者一个极其简单的自定义端点（如/actuator/health/liveness，仅检查内存、磁盘等基础资源）。在Spring Boot 2.3+，你可以直接使用management.endpoint.health.group.liveness.include=ping来创建一个简单的存活检查组。

把这些坑都考虑到，你的优雅停机策略才算真正具备了生产级的韧性。这套组合拳打下来，虽然不能保证100%零中断（在分布式系统中这是不可能的），但足以将因发布、伸缩导致的服务中断影响降到最低，用户体验和系统稳定性都会有质的提升。