Spring Boot健康检查：用Actuator告别端口探测假死-开发者社区

前言：如果还在用端口判断服务“活着”，迟早要背锅

先讲一个我亲眼见过的线上事故。某天深夜，一个核心服务集群的CPU被打满，进程还挂着，端口也正常，但所有请求都卡在连接池里超时。监控面板上一切绿油油，直到凌晨三点用户密集投诉，值班的人手动重启才恢复。事后排查发现，探针一直用TCP端口连通性做存活判断——端口通，进程在，但服务已经没有处理能力了。这就是典型的“活着但没活着”。

SpringBoot健康检查要解决的就是这个问题：对外提供一个标准化的接口，用真实、语义化、多层次的状态去表达服务是否具备处理请求的能力。它不是一个“端口通不通”的开关，而是一个体系：从进程本身，到依赖组件，再到自定义业务场景，逐层上报。配合监控告警、负载均衡摘除、容器编排探针，才能把线上事故的发现时间从“用户投诉”提前到“系统自检”。

这篇文章适合谁？正在用SpringBoot做微服务或单体应用，希望在线上环境中配置出一套靠谱的健康检查，或者在踩了“假健康检查”的坑之后想彻底搞明白原理的人。我会从设计思路讲起，补全配置细节、实操步骤和排障经验，把我这些年踩过的坑一次性讲透。

1. 整体设计与思路拆解

1.1 健康检查的本质：服务状态的分层表达

在讨论SpringBoot怎么做之前，先想清楚一个底层问题：一个服务在什么情况下算“健康”？绝大多数团队的第一反应是“进程没挂”。但进程没挂，顶多算“活着”，距离“可以正常完成业务请求”还有很大距离。

我习惯把服务状态分成三个层次：

进程层：操作系统层面进程是否存在。
端口与容器层：端口能否建立TCP连接，容器是否进入Ready状态。
依赖与业务层：数据库连接是否可用、消息队列是否能消费、外部接口是否响应、核心业务线程池是否有余量。

健康检查真正有价值的地方，在于它能把这三层信息统一收敛成一个“探针返回体”。上游调用方、网关、负载均衡器、K8s调度器只需要看这个返回体的状态码，就能决定流量继续进来还是立刻摘除。你可以把健康检查理解成服务对外递交的一份“体检报告”，而不是简单的“呼吸检测仪”。

1.2 为什么不该继续用端口探测做存活判断

如果只是TCP端口通不通，很多真正的故障根本暴露不出来。举几个最常见的场景：

线程池耗尽。Tomcat默认线程池满了之后，新建TCP连接依然能握手成功，但请求会一直排队，最终超时。
数据库连接池抽干。服务进程正常，但所有线程卡在获取连接上。端口肯定通，服务早已不可用。
磁盘写满。磁盘100%时，应用日志写不进去，某些场景下进程不会立即崩，但业务已经停滞。
JVM发生频繁Full GC，应用线程长时间停顿。端口还在监听，但实际吞吐量趋近于零。

在这些场景下，“端口通”不仅没有带来安全感，反而带来了虚假的稳定信号。而SpringBoot健康检查把这些真实状态都用Indicator包装起来，返回一个HTTP状态码：200代表UP，503代表DOWN。这个状态码可以被K8s、负载均衡器、监控系统直接消费。

1.3 SpringBoot健康检查在整个架构里的位置

我不是说一个健康检查接口能解决所有稳定性问题，它是整个稳定性体系里最基础的那个环节。架构上它一般存在于三条链路：

容器编排链路：K8s的readinessProbe和livenessProbe直接请求健康检查接口，决定Pod是否被纳入Service流量负载、是否触发重启。
网关与负载均衡链路：网关通过主动探测或服务注册中心的健康标记，决定是否将请求路由给某个实例。
监控告警链路：监控系统定时拉取健康检查结果，状态为DOWN时触发告警通知。

这三条链路共用同一个协议，却有不同的诉求。readinessProbe要求结果真实反映“能否接受流量”，livenessProbe要求结果反映“进程是否还能自救”，监控告警则希望结果包含足够的细节，比如具体挂了哪个组件。所以后面聊配置时，你可能会看到同一个健康检查端点，在K8s探针和监控告警里的使用方式是完全不同的。

2. 核心细节解析与实操要点

2.1 Actuator健康检查端点的准备工作

SpringBoot的健康检查能力由spring-boot-starter-actuator提供。引入依赖后，健康检查端点默认就是开启状态，并且HTTP路径是/actuator/health。但默认开启不意味着配置到位，生产环境里必须把下面几项搞明白。

先看一下基础依赖配置：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>

如果是Gradle工程，对应的是：

implementation 'org.springframework.boot:spring-boot-starter-actuator'

引入之后，SpringBoot会自动把所有已注册的HealthIndicator聚合到一起，最终返回一个树形结构的JSON，根节点是整体状态，子节点是各组件状态。

这里有个关键认知：健康检查的整体状态不是由某一个组件单独决定的，而是所有Indicator状态的汇总归纳。比如数据库挂了，但Redis正常，最终整体状态大概率是DOWN，因为这已经说明服务无法正确处理请求。不过，是否真的会被判定为DOWN，取决于状态聚合规则和排除规则。

2.2 状态码与字段语义解读

健康检查返回的状态分为四级：

UP：组件正常，服务健康。
DOWN：组件故障或不可用。
OUT_OF_SERVICE：组件被主动下线，一般维护场景使用。
UNKNOWN：状态无法确认，例如刚刚启动还在初始化。

真实返回的JSON长这样：

{ "status": "DOWN", "components": { "db": { "status": "DOWN", "details": { "error": "Cannot get connection: Connection refused" } }, "diskSpace": { "status": "UP", "details": { "total": 268435456000, "free": 8847360000, "threshold": 10485760 } }, "redis": { "status": "UP" } } }

注意两个关键点：

默认情况下，details细节不会对外开放，避免泄露内部连接信息。默认show-details策略是never。
HTTP状态码和status字段的映射关系可以通过配置调整。默认情况下，整体状态为UP时返回200，DOWN或OUT_OF_SERVICE时返回503，UNKNOWN返回200。

这个映射关系在业务网关里很重要。很多网关是根据HTTP状态码来做摘除和熔断判断的，如果状态码没有正确返回，健康检查做得再精细也白搭。

2.3 show-details、show-components与安全隔离

线上环境里，必须显式配置健康检查细节的暴露策略。我的建议分场景设置：

给K8s探针用：保持默认的never，只要状态码正确就行，越简单越好。
给监控告警平台用：可以配置为when-authorized，让内部监控系统通过认证后看到完整细节。
给人工排查用：临时debug时改成always，用完立刻改回来。

2.4 常用内置HealthIndicator说明

SpringBoot按依赖自动装配了很多Indicator，我挑几个最常用的讲，它们分别覆盖了不同的依赖类型。

DataSourceHealthIndicator

如果数据源存在就会自动注册。默认会执行一条SELECT 1（不同数据库方言有差异，Oracle之类会调用duel查询），能成功返回就判定UP。有一个隐藏参数validation-query，绝大多数情况下不需要自己设置，因为SpringBoot会根据数据库连接自动推断。需要注意的场景是：数据库连接池满了，这个Indicator拿不到连接，会直接抛异常，状态变为DOWN。

DiskSpaceHealthIndicator

磁盘空间检查，默认只会检查一个路径，而且默认阈值是10MB。换句话说，如果磁盘剩余空间低于10MB，就会被判定为DOWN。这个阈值往往不够生产环境用，我一般会显式把它调高到1GB以上，因为磁盘剩余空间低于1GB时，很多应用其实已经处于崩溃边缘了。同时只查一个路径远远不够，如果应用日志和业务存储在不同分区，还得额外配置多个路径检查。

RedisHealthIndicator

有Spring Data Redis依赖就会自动注册。它会向Redis发一个PING命令，正常返回PONG就是UP。这里有个容易忽略的问题：Redis实例如果在网络抖动期间短暂不可达，健康检查立刻变DOWN，然后K8s开始重启Pod。明明只是一个瞬断，结果被扩大成了一次线上事故。解决办法是给健康检查加上缓冲期，后面我会细讲。

RabbitHealthIndicator、KafkaHealthIndicator等

消息中间件的检查逻辑类似，会探活单个连接。问题也一样：瞬时抖动会被直接放大。这类组件在架构里的重要性通常很高，我建议为它们单独做更精细的探活，而不是只依赖SpringBoot自带的这层简单检测。

2.5 健康检查的TimeToLive与缓冲期

SpringBoot健康检查端点有个默认缓存策略：health.time-to-live。这个值很关键。如果不设置，每次调用都会实时执行所有Indicator，在高频探针轮询下会给数据库、Redis、磁盘带来额外压力。如果设置太长，故障发生后，探针拿到的还是缓存里的UP状态，告警又变成“迟到”了。

我的经验是：

监控系统轮询间隔如果是10秒，那么time-to-live缓存时间设为5秒左右，取一个折中。
K8s探针默认会设置periodSeconds、timeoutSeconds，所以缓存时间建议小于periodSeconds。
READY探针和LIVENESS探针建议不要共用一个缓存前缀，否则频率一高一低会互相拖累。

配置示例：

management: endpoint: health: time-to-live: 5s

这个5秒的意思是说：虽然每次调用接口都会即时返回，但内部指标数据会缓存5秒。如果在这5秒内Redis挂了，接口最快也要到缓存过期后才能感知。这个时间窗口，对于大部分监控场景完全够用。

2.6 分组与聚合：同一探针，多个视角

有时候同一个健康检查端点需要承担多个角色。比如：

网关链路只关心“Service是否Ready”，不需要知道数据库的细节。
运维告警链路需要看“具体哪个组件掉线了”。
K8s的readinessProbe希望只关心“能否接受流量”，如果只是磁盘空间低但它还够用，不希望直接摘流量。

SpringBoot的health group就是为这种需求准备的。我们可以定义一个group，只聚合某几个Indicator，甚至给group单独配置show-details和状态映射。

配置示例：

management: endpoint: health: group: readiness: include: db,redis,diskSpace liveness: include: ping

这样就有了两个独立探针路径：/actuator/health/readiness和/actuator/health/liveness。前者用于K8s的readinessProbe，后者用于livenessProbe。readiness关注依赖是否就绪，liveness只关心Spring容器本身是否还活着。

这里有一个很重要的设计原则：readiness探针和liveness探针绝不能使用同一个状态集合。原因很直接：如果数据库闪断，readiness应该立刻摘流量，但liveness不能跟着去重启Pod，否则数据库恢复时需要重建所有实例，属于典型的“故障扩大化”。

3. 实操过程与核心环节实现

3.1 一个完整的项目改造示例

下面我会用一个虚构的“订单查询服务”举例，演示一套可落地的配置和代码。这个服务依赖MySQL、Redis和一个外部风控接口，部署在K8s集群中，前面有网关做流量分发。

第一步，依赖准备。除了starter-actuator之外，还要按需引入spring-boot-starter-data-redis、spring-boot-starter-jdbc等。

第二步，配置application.yml。我给出一个偏保守但可靠的配置方案：

management: endpoints: web: exposure: include: health,info,metrics endpoint: health: show-details: when-authorized show-components: always time-to-live: 5s group: readiness: include: db,redis,diskSpace,externalRiskApi liveness: include: ping server: port: 9090

这里management独立端口设置成9090，避免业务端口和监控端口混淆。生产环境建议给监控端口单独开管理通道。

第三步，自定义外部依赖的健康检查。默认的Indicator里没有“外部HTTP接口是否可用”这种概念，需要自己实现。代码如下：

@Component public class ExternalRiskApiHealthIndicator extends AbstractHealthIndicator { private final RestTemplate restTemplate; public ExternalRiskApiHealthIndicator(RestTemplate restTemplate) { super(10000); this.restTemplate = restTemplate; } @Override protected void doHealthCheck(Health.Builder builder) throws Exception { HttpHeaders headers = new HttpHeaders(); headers.setBasicAuth("healthcheck", "secret"); HttpEntity<Void> entity = new HttpEntity<>(headers); try { ResponseEntity<String> response = restTemplate.exchange( "https://external-risk-api.example.com/health", HttpMethod.GET, entity, String.class ); if (response.getStatusCode().is2xxSuccessful()) { builder.up() .withDetail("httpStatus", response.getStatusCode().value()) .withDetail("message", "external risk api is reachable"); } else { builder.down() .withDetail("httpStatus", response.getStatusCode().value()) .withDetail("message", "external risk api returned non-2xx"); } } catch (Exception ex) { builder.down() .withDetail("error", ex.getClass().getSimpleName()) .withDetail("message", ex.getMessage()); } } }

注意构造方法里传入的10000，这是AbstractHealthIndicator的超时时间，单位是毫秒。它保证整个健康检查执行过程在10秒内必须返回，避免某个外部接口长时间无响应拖垮整个健康检查调用链路。外部接口健康检查一般包括连接超时和读取超时，对于RestTemplate我会单独设置连接超时2秒、读取超时5秒，总的健康检查时间控制在10秒以内。

3.2 配置K8s探针时的典型示例

K8s探针直接消费健康检查端点，需要定义readiness和liveness两套探测参数。下面是一份比较合理的配置：

apiVersion: apps/v1 kind: Deployment metadata: name: order-query-service spec: template: spec: containers: - name: order-query-service image: registry.example.com/order-query-service:1.2.0 ports: - containerPort: 8080 readinessProbe: httpGet: path: /actuator/health/readiness port: 9090 initialDelaySeconds: 30 periodSeconds: 10 timeoutSeconds: 3 failureThreshold: 3 livenessProbe: httpGet: path: /actuator/health/liveness port: 9090 initialDelaySeconds: 60 periodSeconds: 15 timeoutSeconds: 3 failureThreshold: 3

几个参数我是按照经验定的：

initialDelaySeconds设为30，给SpringBoot启动、数据源初始化留出时间。
periodSeconds设为10，与缓存时间5秒配套，避免频繁触发真实探测。
timeoutSeconds设为3，一是避免探针调用过久，二是让一次失败的检测不会拖垮整个周期。
failureThreshold设为3，连续三次失败才会真正把Pod标记为异常。这样能过滤掉瞬时抖动。

这里最核心的一个坑是：不要顺手把readinessProbe和livenessProbe指向同一个path。如果你用一个包含db和redis的复杂健康检查做liveness，数据库短暂超时一秒，Pod就会被杀掉，这是很多团队踩过的“探针误杀”大坑。

3.3 在网关层配置摘除逻辑

网关层消费健康检查时，我建议设计一个简单的轮询任务。以Spring Cloud Gateway为例，可以自己拉取健康检查结果，然后把DOWN状态的实例从路由列表中剔除。

伪代码如下：

public boolean isHealthy(InstanceInfo instance) { String url = "http://" + instance.getHost() + ":9090/actuator/health/readiness"; try { HttpResponse response = httpClient.execute(url, 2, TimeUnit.SECONDS); return response.getStatusLine().getStatusCode() == 200; } catch (Exception e) { return false; } }

注意这里我只用了HTTP状态码，没有解析JSON。原因在于：网关关心的是“这个实例能不能流流量”，而不是“磁盘还剩下多少”。把JSON解析放在网关层只会增加耦合度，状态码已经足够表达“是否可用”。

3.4 验证探针效果的具体操作

配置完成后，可以在本地模拟一次故障来验证整体体验。比如把数据库停掉：

docker stop mysql curl http://localhost:9090/actuator/health/readiness

正常情况会返回类似下面的JSON：

{ "status": "DOWN", "components": { "db": { "status": "DOWN", "details": { "error": "Connection refused" } } } }

再恢复数据库，等缓存过期后再请求一次，状态会重新回到UP。整个过程验证了三个关键点：Indicator能正确感知依赖状态、缓存时间不会掩盖故障、HTTP状态码能正确返回503。

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

4.1 Spring Security把健康检查拦在门外

现象：K8s探针请求/actuator/health/readiness返回401。

排查过程：先确认management.endpoint.health的路径是否真的存在，再用curl手动带上认证信息请求，如果带认证就通、不带就不通，那就是被Spring Security拦截了。

解决方式分两种：

如果只是想让探针访问，不暴露细节，那对/actuator/health**路径放行是安全的，前提是show-details设为never。
如果希望监控系统拿到组件细节，就把management.server.port独立出来，然后在Security里只对管理端口放行。

http .authorizeHttpRequests(auth -> auth .requestMatchers("/actuator/health").permitAll() .requestMatchers("/actuator/health/**").permitAll() .anyRequest().authenticated() );

但要注意，这段代码放行的是所有环境下的健康检查端点，生产环境一定要配合网段限制，不能裸奔。

4.2 服务假死但健康检查依然全绿

这是刚开始提到的那个事故的高发版本。进程在、端口通、数据库和Redis都正常，但请求处理已经卡死。这种问题最复杂，也是最容易漏掉的场景。

根本原因在于：默认Indicator只检查外部依赖状态，不检查应用自身的处理能力。怎么解决？自定义一个Indicator，专门探测核心业务的线程池或请求队列。

举个例子，如果你的核心处理器使用的是固定大小的线程池，可以这样检测：

@Component public class CoreThreadPoolHealthIndicator extends AbstractHealthIndicator { private final ThreadPoolTaskExecutor coreExecutor; public CoreThreadPoolHealthIndicator(ThreadPoolTaskExecutor coreExecutor) { this.coreExecutor = coreExecutor; } @Override protected void doHealthCheck(Health.Builder builder) { int activeCount = coreExecutor.getActiveCount(); int poolSize = coreExecutor.getPoolSize(); int queueSize = coreExecutor.getThreadPoolExecutor().getQueue().size(); int utilization = (int) Math.floor(activeCount * 100.0 / poolSize); if (queueSize > 5000 || utilization > 95) { builder.down() .withDetail("activeCount", activeCount) .withDetail("queueSize", queueSize) .withDetail("utilization", utilization + "%"); return; } builder.up() .withDetail("activeCount", activeCount) .withDetail("queueSize", queueSize) .withDetail("utilization", utilization + "%"); } }

我会把这个线程池的指标检查加入readiness探针组，这样“业务容量耗尽”才能真正反映到健康状态里。经验值是：线程池活跃度超过90%且持续一段时间，就已经具备事故特征了，健康状态必须降级为DOWN。

4.3 健康检查状态导致负载均衡错误摘除

现象：某个实例的健康检查偶发510状态码，结果网关立刻把所有流量切走，其他实例扛不住压力，最终集群整体雪崩。

这类问题多半是健康检查里包含了一些“非核心依赖”，这些依赖短暂抖动后恢复了，但负载均衡器已经做出了摘除决策。解决办法：

把健康检查分组。核心依赖（数据库、核心消息队列）放在readiness探针组，非核心依赖（某个外部报表接口）放在单独分组。
给非核心依赖单独配置一个statusMapping，把它映射为200，或者说映射成UP。但要谨慎，这样会掩盖真实故障。
在负载均衡器端增加“连续失败N次才摘除”的策略，而不是一次失败立即摘除。

4.4 健康检查接口本身拖垮了服务

现象：健康检查被监控系统以1秒一次的频率轮询，每次都要查询数据库、Redis、外部接口。高峰期时，健康检查调用本身消耗了大量连接和线程资源，反而引发了故障。

解决方案：

设置缓存时间，至少2秒，推荐5秒。
独立管理端口，避免公共流量和探针流量互相争抢。
将健康检查逻辑中的外部调用超时控制在几百毫秒到2秒之间，不要让它慢吞吞地等满10秒。
监控系统轮询周期统一调整为10秒，而不是秒级。

4.5 数据库连接池耗尽导致健康检查假DOWN

DataSourceHealthIndicator需要拿一个连接执行校验SQL。如果连接池已经耗尽，它拿不到连接，健康检查就返回DOWN。但这未必意味着数据库有问题，可能是某个大查询占满了连接池。

这种case下，真正的修复方向是排查连接泄漏和慢SQL，而不是让应用不停重启。所以我建议把数据源健康检查的超时时间调小，并加入连接池使用率信息：

management: health: db: timeout: 3s

同时，自定义数据源Indicator，把连接池当前空闲数、活跃数、等待队列长度都放到details里，方便监控系统给出精确告警。

4.6 缓存与时间窗口导致的状态滞后

健康检查缓存时间设得越长，状态滞后越明显。极端情况下，K8s探针刚拿到UP，几秒后服务已不可用，但探针下一次检查还在缓存期内，延迟摘除流量。

所以缓存时间的设定要综合考虑监控系统的轮询周期和探针的periodSeconds。我一般会遵循一个简单公式：

缓存时间 <= 探针周期 / 2

比如探针周期10秒，缓存时间最多5秒。这样即使状态滞后，也不会超过半个探针周期。

4.7 附：一份问题排查速查表

现象	可能原因	优先排查项
健康检查返回401	Spring Security拦截	放行路径，或独立管理端口
服务假死但健康检查UP	未检查业务线程池/队列	自定义核心线程池Indicator
数据库正常但健康DOWN	连接池耗尽，查询超时	检查活跃连接数与慢SQL
频繁触发Pod重启	liveness和readiness混用	拆分探针组，liveness只含ping
网关流量异常抖动	偶发状态码导致立即摘除	增加连续失败阈值，调整group
探针接口慢、资源占用高	无缓存，外部调用超时过长	设置time-to-live，调小外部超时
磁盘未满但状态DOWN	默认阈值10MB只会看一个路径	配置多个路径并调高阈值

结尾

从我的实践经验来看，健康检查这个功能，真正难的不是引入Actuator、写几行配置，而是把“健康定义”想清楚，不同场景用不同探针，不同依赖配置不同超时。踩过几次坑之后，我现在每个新项目的健康检查配置都会先过一遍“三问”：有没有把端口监控当成服务存活判断？有没有把瞬时抖动误判成永久故障？有没有把readiness和liveness的职责混在一起？这三问过完，线上事故的发现时间基本就能从“用户投诉”提前到“系统自动摘除”。

最后再分享一个小技巧：每次上线前，我会特意人为停掉一两个下游依赖，看看健康检查的返回体是否还是干净的UP。如果看到的是乱七八糟的状态码，说明配置还是有漏洞，趁早修好再上线。这套方法，建议每个团队都在测试环境里跑一遍。