Spring Boot优雅停机与Kubernetes探针实践指南

Spring Boot 2.3.0把优雅停机（Graceful Shutdown）、Readiness和Liveness这些以前要靠“外部脚本+黑科技”才能搞定的事情，第一次作为一等公民放进了框架里。我当年在2.2.x版本上做滚动发布，为了不让流量打到正在关停的节点上，还得自己写一堆Shell脚本去摘流量、等连接池排空，再关进程，最后让网关把流量切回来。整个过程又脆又容易出幺蛾子。所以2.3.0刚发布我就追着升级了，这次把配置、踩坑、和Kubernetes的联动一起讲清楚，给需要的人省点时间。

这篇文章适合谁看？正在用Spring Boot做微服务、打算上容器化，或者已经上了Kubernetes但对探针和停机流程一头雾水的人。看完你至少能回答三个问题：怎么让旧请求在处理完后再停机，怎么让平台知道你当前能不能接流量，怎么让平台知道你只是暂时忙不过来做不了心跳响应。这三个问题不解决，线上发布迟早会出事故。

1. 为什么2.3.0的优雅停机值得单独写一篇

1.1 之前的停机方式有多粗暴

我最早做发布的时候，流程是通知运维手动停服务，运维直接kill掉进程。Spring Boot默认的停机方式大家应该也知道：调用/actuator/shutdown（还得专门开shutdown.endpoint.enabled=true），或者直接发SIGTERM。问题是这两种方式都是立刻丢弃所有未处理完的连接，Tomcat会直接拒绝新请求并把正在跑的请求拽下来，数据库事务可能已经执行了一半，消息队列里的消息可能消费了但没提交。然后你就得处理各种奇怪的业务异常：订单状态不一致、对账不平、数据重复消费。

这里的根本原因不是开发者不细心，而是框架层面压根没给停机流程留出“排空”的时间窗。2.3.0版直接把这个能力内置了，从配置到生效只需要改一行server.shutdown=graceful，这在我眼里是那一个版本最重要的一次更新，真不是为了赶时髦才写的。

1.2 优雅停机到底在解决什么问题

优雅停机（graceful shutdown）解决的问题说白了就一句话：让正在处理的请求有足够时间干完活，然后进程再退出。你用Tomcat、Jetty、Netty或者Undertow的时候，Spring Boot 2.3.0都会在收到SIGTERM信号后进入一个“停止接收新请求，但等待存量请求处理完毕”的阶段。这个阶段不是无限等的，默认30秒超时，超时后强制退出。

注意这里的关键点：所谓“优雅”不是让你无限拖延进程退出，而是给你一个有限的缓冲期。如果你有一批长任务接口，平时一个请求要跑几分钟，那默认30秒根本不够用，你得根据自己接口的耗时特征重新设置spring.lifecycle.timeout-per-shutdown-phase。这个参数很多人不知道，后面实操部分我会具体讲怎么配。

1.3 适合谁看

这篇内容面向两类人。第一类是刚接触微服务和容器的开发，需要搞清楚Spring Boot在2.3.0之后到底多出来哪些配置、每个配置对应哪些行为。第二类是已经在搞Kubernetes的运维和SRE，需要把Spring Boot的探针状态和Kubernetes的存活探针、就绪探针正确对接，避免发布期出现流量空白或者节点被误杀，这部分人光靠看官方文档往往不够，官方文档只会告诉你“有这个功能”，不会告诉你“你和编排系统对接的时候还有这些坑”。

2. 三个核心概念一次讲清楚

2.1 优雅停机：进程的“软着陆”

优雅停机对应的英文是Graceful Shutdown，Spring Boot 2.3.0支持的配置值有两个：immediate和graceful，默认还是immediate。如果你不手动改，那行为和以前一样，收到停止信号后立刻把当前请求全部掐断。改成graceful之后，应用会先通知Web容器关闭对外端口，让新请求无法再进来，已经进来的请求则在队列里继续处理。

这里有个许多人误解的地方：优雅停机不只是等Web请求处理完，像Actuator的探针请求、消息监听器（如Kafka消费者）正在处理的消息也都算在内。2.3.0版本的实现会对SmartLifecycle的各个阶段做控制，Web服务器和外部的后台任务都纳入停机阶段管理。我在某次线上升级中遇到过一个问题：Web请求已经排空了，但后台的一个定时任务刚好在写数据，进程被强制退出了，最后数据只写了一半。后来分析发现是那个任务本身执行超过了超时时间，不是框架没管它。

2.2 Readiness：我准备好接收流量了吗

Readiness（就绪状态）解决的是“应用能不能接收新请求”的问题。Spring Boot 2.3.0在Actuator里新增了readiness端点，它返回的状态有ACCEPTING_TRAFFIC和REFUSING_TRAFFIC两种。状态由一组ReadinessState贡献者来维护，默认情况下就绪状态一开始就是ACCEPTING_TRAFFIC。

但在实际场景中，如果你依赖了数据库连接池、Redis、消息队列，启动时这些东西连不上，其实应用并不应该接收流量。那个时候你需要自定义就绪状态。比如我经手的一个项目，应用启动时如果Redis没连上，默认的Readiness还是返回ACCEPTING_TRAFFIC，流量进去了，结果每个请求都在Redis操作上超时。后来自己注册了一个ReadinessStateContributor，把关键依赖的健康检查结果映射成就绪状态，连不上就把状态置为REFUSING_TRAFFIC。

2.3 Liveness：我还活着吗

Liveness（存活状态）解决的是“进程要不要被重启”的问题。如果一个应用死锁了、线程池耗尽了、内存泄漏到一直Full GC，进程看起来还在，但已经不能正常处理请求，这时候需要Liveness探针把它标记为不健康，让容器编排系统杀掉重启。

Spring Boot 2.3.0的liveness端点返回CORRECT和BROKEN两种状态。默认情况下它始终是CORRECT，除非你主动往里注册状态贡献者。我见过不少团队直接把Liveness和数据库健康检查绑在一起，这个操作其实很危险。数据库一抖动，应用进程本身没事，但Liveness错误导致Kubernetes疯狂重启Pod，整个服务变成重启循环。Liveness状态应该只反映那种“进程无法通过自我恢复解决的问题”，而不是依赖外部服务的短时抖动。

2.4 三者怎么配合

优雅停机负责“退出的时候把旧请求处理完”，Readiness负责“新流量能不能进来”，Liveness负责“进程是否需要被重启”。三者的配合在滚动发布里是这样演的：

• Pod启动后，Liveness先通过，Readiness变成ACCEPTING_TRAFFIC，Kubernetes才把旧Pod的流量切一部分过来。
• 发布时新Pod全部就绪，旧Pod开始停，优雅停机触发，旧Pod的Readiness自动变成REFUSING_TRAFFIC，Kubernetes把流量全部摘掉。
• 旧Pod的存量请求在超时时间内处理完，进程退出，原本挂在这个Pod上的连接全部关闭。
• 如果新Pod因为启动慢一直没就绪，Kubernetes不会把流量打给它，而是等它就绪后再切流。

这一套流程如果没有Readiness/Liveness做前置判断，只靠优雅停机，那依然会出现“进程还在排空旧请求，但负载均衡又给它塞了几个新请求”的尴尬局面。优雅停机只能拒绝新连接，架不住别人硬塞。

3. 实操：配置优雅停机

3.1 基础配置

先把依赖写清楚，2.3.0以上版本的Web应用基本都是自动集成的。核心配置如下，放在application.yml里：

server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 30s

这里的server.shutdown=graceful让应用进入优雅停机模式，spring.lifecycle.timeout-per-shutdown-phase设置每个停机阶段的最大等待时间。注意这里说的是“每个阶段”，不是“全部阶段的总和”。如果Web容器的停机阶段用了30秒，后续的Bean销毁阶段还会有自己的30秒，整个进程停止可能需要更长时间。我在压测环境测过，Tomcat排空连接池可能很快，但自定义的SmartLifecycle任务如果也在停机期间执行，总时间会超过你的直觉预期。

有人会问，这个超时时间是设置成一个总体时间好，还是每个阶段都是30秒好？如果你有多个阶段，每个阶段都各等30秒，累加下来发布一个服务可能要等一分钟以上，这在快速迭代的场景下不可接受。我自己一般会把执行时间长的任务单独拎出来，放在停机阶段之外，或者在timeout-per-shutdown-phase上按业务能接受的最大等待时间配置，而不是默认值硬顶。

3.2 验证配置

配好之后怎么确认真生效了？最简单的办法是用kill -TERM直接给本地启动的进程发信号。观察日志，如果进入了优雅停机，你会看到类似“Commencing graceful shutdown”的日志。然后再发一个请求，让请求持续处理3秒，同一时刻给进程发SIGTERM，看进程是否等到请求完成才退出。

我本地测试的步骤大概是这样的：

1. 启动应用，确认ACTUATOR端点能访问。
2. 在浏览器或curl发起一个慢请求，比如一个睡5秒的接口。
3. 立即执行kill -TERM <pid>。
4. 观察日志和进程退出时间。

如果配置生效，请求会在第5秒正常返回，进程随后退出。如果配置没生效，请求会在你执行kill的瞬间被掐断。用这个办法可以快速确认当前环境的Spring Boot是否按预期执行了优雅停机。

3.3 配置中的常见认知误区

第一，不是配了graceful就能处理所有类型的停止信号。如果你用kill -9强制杀死进程，再怎么优雅都没用，系统不会给你清理时间。这就像让一个人收拾东西准备下班，结果你直接把工位电源断了，谁也没办法。

第二，如果项目里用了@PreDestroy方法或者DisposableBean，这些方法的执行时机是在停机阶段之后，它们里面如果有耗时的清理操作，同样受timeout-per-shutdown-phase的影响。我有一次往一个@PreDestroy里加了Redis清理逻辑，结果优雅停机在等待Redis清理时超时了，整个进程退出得很勉强。

第三，优雅停机不改变负载均衡层面的流量切换。如果你前面挂的是Nginx，Nginx不会因为你进入了优雅停机就把连接断掉，它还是会把新请求转发过来，除非你主动从Nginx的上游列表里摘掉这个节点。这也是为什么后面一定要把Readiness和探针接进来，让编排平台自动摘流量。

4. 实操：Readiness和Liveness探针配置

4.1 开启探针端点

Spring Boot 2.3.0的Actuator默认并不暴露readiness和liveness端点，需要先开启。在application.yml里这样配：

management: endpoints: web: exposure: include: health,info,readiness,liveness endpoint: health: probes: enabled: true

endpoint.health.probes.enabled=true是让/actuator/health/liveness和/actuator/health/readiness两个探针子路径能用。注意这个开关很关键，如果你只把readiness和liveness放进了include，但忘记开probes.enabled，端点会返回404。这个我踩过，浪费了半小时排查。

开启后访问地址分别是：

• /actuator/health/liveness
• /actuator/health/readiness

它们的响应结构长这样：

{ "status": "UP", "components": { "livenessState": { "status": "UP" } } }

4.2 配置探针路径

打开端点之后，你的容器平台要把它当作HTTP探针来调。如果用的是Docker，可以在Dockerfile里配HEALTHCHECK，但说实话Docker的HEALTHCHECK在Kubernetes场景里用的不多，因为Kubernetes会直接配Pod级别的探针。下面给一个Dockerfile里的示例，方便本地测试用：

FROM openjdk:11-jre-slim COPY app.jar /app.jar EXPOSE 8080 HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \ CMD wget -qO- http://127.0.0.1:8080/actuator/health/readiness || exit 1

这个start-period参数很容易被忽略。它告诉Docker，在容器启动后的30秒内，即使探针失败，也不要把容器标记为不健康。因为Spring Boot应用启动可能需要一段时间，不加这个参数，探针一开始测失败，连续几次后容器就会被认为不健康然后重启，造成启动死循环。

4.3 定制Readiness状态

光有默认的探针还不够。很多时候你想让应用在“外部依赖还没就绪”的时候先不要接流量，那就需要自己定义状态贡献者。

实现思路是注册一个AvailabilityStateContributor，在ReadinessState里把关键依赖的检查结果映射进去。下面是一个简化的示例，把数据库连接池的健康状态作为就绪判断条件之一：

@Component public class DatabaseReadinessContributor implements AvailabilityStateContributor<ReadinessState, ReadinessState> { private final DataSource dataSource; public DatabaseReadinessContributor(DataSource dataSource) { this.dataSource = dataSource; } @Override public ReadinessState getState(ReadinessState currentState) { try (Connection connection = dataSource.getConnection()) { return ReadinessState.ACCEPTING_TRAFFIC; } catch (Exception ex) { return ReadinessState.REFUSING_TRAFFIC; } } @Override public ReadinessState getAggregateState(ReadinessState currentState, ReadinessState newState) { return newState; } }

注意这里有个关键点：虽然示例代码简洁，但真实场景下不要在每个探针请求里都去拿数据库连接，那会把自己的连接池打满。我实际项目中是把一个短连接测试的结果缓存几十秒，或者用连接池里已有的getConnection校验逻辑加超时，不能让探针本身成为故障源。

还有一点要提醒：如果你自定义了多个AvailabilityStateContributor，聚合逻辑要清楚。默认情况下，只要有一个贡献者返回REFUSING_TRAFFIC，总共的Readiness状态就会变成REFUSING_TRAFFIC。这个聚合逻辑在AvailabilityState里是取最差状态，跟Hystrix的舱壁模式有点像。

4.4 Liveness的定制要克制

Liveness状态定制在多数业务系统里其实不应该做太多。官方文档里也是建议保持默认，最多在里面加“本地缓存是否还正常”、“线程池是否还能接受任务”这类能反映进程自身健康状况的检查。不要依赖Redis、数据库、远程调用。

我自己见过一个案例：团队为了确保“依赖挂了能快速重启”，把Liveness绑了数据库连接池，结果数据库主从切换的20秒时间里，所有Pod都被Kubernetes杀掉重启。数据库切完，Pod还在重启，服务彻底断了。这就是没搞懂Liveness的定位：它是判断进程是否需要被重启，而不是判断外部依赖是否可用。依赖的问题应该靠Readiness处理，让流量不要进来，而不是让进程被反复杀掉。

5. 与Kubernetes的探针对接

5.1 Kubernetes默认探针的问题

如果你已经在用Kubernetes，那光配Spring Boot的探针端点还不够，你必须在Deployment里声明探针。很多人的Deployment就写了containerPort和resources，没有探针，这种情况下Kubernetes怎么判断Pod是否健康？只能看进程在不在。如果进程还在，它就把流量送进来；如果进程死了，它才重启。这种模式完全没法应对“进程活着，但已经无法处理请求”的场景。

常见的做法是直接在Deployment里配置readinessProbe和livenessProbe。比较合理的做法是：

readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 30 periodSeconds: 10 timeoutSeconds: 3 failureThreshold: 3 livenessProbe: httpGet: path: /actuator/health/liveness port: 8080 initialDelaySeconds: 60 periodSeconds: 15 timeoutSeconds: 3 failureThreshold: 3

initialDelaySeconds给应用留启动时间，periodSeconds控制检查频率，failureThreshold控制连续几次失败才触发动作。这里很多人会忽略一个细节：timeoutSeconds要小于periodSeconds，否则探针请求可能重叠，造成探针本身变慢。我之前把timeoutSeconds设成10秒，periodSeconds设成5秒，结果探针线程都堆在一起，应用自己的线程池也被占了一部分。

5.2 滚动发布时三者配合的实际效果

假如你有3个副本，Deployment配了上面的探针和优雅停机，那一次滚动发布是这样的：

• 新Pod被创建，状态是Pending，等调度到节点上。
• 容器启动，Spring Boot开始初始化，此时Liveness探针还没通过，readinessProbe开始探测，返回值不是200，Kubernetes不会把新Pod标记为Ready。
• 应用启动完成，Readiness端点返回200，readinessProbe通过，Pod被加入Endpoints，负载均衡开始往新Pod转发流量。
• Kubernetes开始终止一个旧Pod，旧Pod收到SIGTERM，Spring Boot触发优雅停机，Actuator的Readiness状态自动变成REFUSING_TRAFFIC。
• Kubernetes在Readiness变成失败后，把这个Pod从Endpoints中摘掉，不再转发新流量。
• 旧Pod的存量请求继续处理，直到超时时间或请求完成。

这里有个很容易被忽视的问题：如果terminationGracePeriodSeconds比spring.lifecycle.timeout-per-shutdown-phase还短，那优雅停机根本来不及跑完。Kubernetes在terminationGracePeriodSeconds到期后会给Pod发送SIGKILL强制击杀。所以Deployment里的terminationGracePeriodSeconds一定要大于等于你的优雅停机预算。比如：

spec: terminationGracePeriodSeconds: 60

否则你配了timeout-per-shutdown-phase: 30s，但Kubernetes 30秒就强制杀，白白浪费前面那30秒的排空窗口。这也是文档里没有特别强调的坑。

5.3 探针与流量的边界

还有一个现实问题：Spring Boot的Readiness端点返回正常，但旧Pod在停止过程中可能还挂在Endpoints里一小段时间。Kubernetes从Readiness失败到从Endpoints摘除，中间有几十秒的更新循环延迟，这期间如果有新请求进来，旧Pod已经不再接收新连接？其实不一定。因为Kubernetes摘除Pod是异步的，短窗口内负载均衡服务可能还保留着旧Pod的IP。所以你在网关层，还要考虑是不是要额外做一层重试或者熔断来兜底。

我自己的方案是网关层启用重试机制，遇到连接失败就换下一个节点重试，这样能把发布窗口的微量抖动吞掉。光靠后端优雅停机不可能覆盖每一个极端时序，微服务发布永远要依靠前端配合做容错。

6. 常见问题与排查技巧实录

把我在实践中碰到的问题整理了一张表，可以当速查手册用。

6.1 启动时Readiness一直不通过怎么办

最常见的情况是应用启动时间太长，超过了readinessProbe的initialDelaySeconds与failureThreshold的组合。比如你设了initialDelaySeconds: 15，但应用实际启动需要40秒，那15秒后探针开始探测，连续3次失败，Pod被标记为不健康。看起来是探针的问题，实际上是你没给应用足够启动时间。

处理办法有两个方向：一是调大initialDelaySeconds；二是Spring Boot这边自己把Readiness延后到应用准备好的时刻。Spring Boot 2.3.0里，ApplicationAvailability接口能够让你在某个组件初始化完成后再把Readiness置为ACCEPTING_TRAFFIC。比如依赖某些外部配置加载完，你可以拿到ApplicationAvailability，主动切换状态。这样探针的initialDelaySeconds可以设小，不用担心应用没准备好。

启动阶段还有一个小坑：应用在初始化的过程中Tomcat可能已经可以接受TCP连接了，但Spring MVC的DispatcherServlet还在初始化，没路由到控制器。这时探针打到/actuator/health/readiness可能还是能返回的，但业务请求会404。所以如果你遇到“探针明明通过了，但业务请求连不上”的情况，优先检查是不是所有Bean都初始化完成，别单看Actuator端点可用。

6.2 优雅停机日志怎么看

一旦进入优雅停机，Spring Boot会打出关键的日志。比较典型的是：

2025-01-12 10:00:00.001 INFO [http-nio-8080-exec-1] o.a.coyote.http11.Http11NioProtocol : Pausing ProtocolHandler ["http-nio-8080"] 2025-01-12 10:00:00.005 INFO [http-nio-8080-exec-1] o.a.coyote.http11.Http11NioProtocol : Stopping ProtocolHandler ["http-nio-8080"]

Pausing ProtocolHandler表示Tomcat开始停止接收新请求，此时新连接会被拒绝，但已建立的连接仍然可以继续处理。之后才是Stopping，表示连接全部排空，正式关闭。如果这两条日志之间的时间差很小，说明当前没有存量请求或者请求都很快处理完了。如果时间差很长，说明有请求在慢慢处理，你的优雅停机窗口正在被消耗。

如果在超时之后看到：

2025-01-12 10:00:30.010 ERROR [SpringApplicationShutdownHook] o.s.b.w.s.tomcat.TomcatWebServer : Tomcat failed to stop within 30 seconds

说明有请求处理时间超过了timeout-per-shutdown-phase，Tomcat被强制停止。这时候去排查是不是有长任务接口没有做超时控制，或者连接池里有没有没归还的连接。这个日志是排查优雅停机问题最有用的入口。

6.3 排空状态下的流量测试方法

本地验证时，你可以做一个简单的模拟：写一个Thread.sleep(10000)接口，用curl发起请求，同时用另一个终端执行kill -TERM。观察那个慢请求是否正常返回。这个实验比任何文档都直观。

生产环境验证的时候要更小心，先在灰度环境试，且要配合监控观察请求失败率、请求耗时和活跃连接数。我有一个比较稳的发布检查清单：发布前记录当前活跃连接数基线，发布过程中盯着Readiness状态变化和Tomcat的活跃线程数，等活跃线程数归零再确认进程退出。这样基本能做到发布期间请求零失败。

6.4 探针线程池配置

Spring Boot Actuator的探针请求用的是http-nio-auto-*线程池还是Tomcat的业务线程池？实际上探针请求走的是Web请求通道，占用的是Tomcat的工作线程。也就是说，如果业务请求把Tomcat线程池占满了，探针请求也会等不到线程，Kubernetes会判定Pod不健康，进而重启。

这个场景在很多高并发应用里真实发生过：业务线程池被打满，Liveness探针超时，Pod被重启，重启后流量再进来，又被占满，死循环。解决思路有几个方向：一是给Actuator单独开一个独立的管理端口，比如management.server.port=8081，探针打到独立端口上，与业务线程池隔离开；二是对业务线程池设置最大并发限制，别让线程被无限占满。我个人推荐第一个方案，独立管理端口一劳永逸，配置也不复杂。

management: server: port: 8081 endpoints: web: exposure: include: health,info,readiness,liveness

配上独立端口后，Kubernetes探针的port改成8081即可。稍微注意一下防火墙和网络安全组的放行规则，别把管理端口暴露到公网。

7. 一些经验总结

2.3.0这版功能我用了很久，从2.2迁移过来的成本其实不高，配置项也不多，但带来的收益非常明显。最直观的感受是发布流程从“心惊胆战摘流量”变成“只管滚动发布，平台自动处理流量切换”。前提是把Readiness/Liveness和优雅停机配合起来，而不是只配一个优雅停机就万事大吉。

我个人的落地建议是：如果业务应用正在走容器化，优先把独立管理端口和探针端点配置上，再配优雅停机；如果是老项目一时半会儿不上容器，优雅停机可以先改起来，至少进程退出时给请求一个排空时间。对于高并发、长耗时接口比较多的服务，timeout-per-shutdown-phase按接口P99耗时而不是平均值来定，宁可稍微长一点，求个稳。每次发布之后记得翻一下停机日志，看看有没有“failed to stop”之类的超时记录，这能提前预警一些长任务和连接泄漏问题。

这套东西折腾下来，最值钱的经验不是配置怎么写，而是理解每个探针应该管什么、不该管什么。很多时候线上事故都不是配置不会写，而是探针把不该管的东西管了，导致编排系统做出错误决策。守住这个原则，你的服务即使遇到依赖抖动，也不会被轻易“误杀”。