Spring Boot 健康检查 DOWN 怎么排查

业务接口偶尔还能访问，但 /actuator/health 已经返回 DOWN；或者服务刚启动就被探针反复重启。先不要把健康检查关掉，应该确认失败的是哪个检查项、谁在调用它，以及这个结果会触发什么动作。

本文按 Spring Boot 3.5、JDK 17 及以上和 Actuator 说明。命令中的地址只是本地排查示例；管理端口、context path、鉴权和代理前缀以项目实际配置为准，未对本站生产服务执行这些变更。

先确认拿到的是健康结果

在有权限的应用运行环境中请求实际端点：

curl -i --connect-timeout 3 --max-time 10 \
  http://127.0.0.1:8080/actuator/health

这段命令使用 Bash；PowerShell 可改成单行 curl.exe。超时值只是限制本次排查请求的等待，不是应用配置建议。

默认情况下 DOWN 和 OUT_OF_SERVICE 映射为 503；项目若定制了 HTTP 状态映射，应检查最终生效值。只看 HTTP 200 不能证明业务链路正常。Actuator 健康信息文档给出了状态与组件机制。

定位组件，而不是只记一个 DOWN

健康结果可能汇总了数据库、Redis、磁盘空间和自定义检查。处理方向应该来自具体组件及其错误，而不是凭总状态猜数据库故障。

诊断环境可以按已有鉴权方案允许授权人员查看组件信息。例如：

management.endpoints.web.exposure.include=health
management.endpoint.health.show-components=when-authorized
management.endpoint.health.show-details=when-authorized

这些属性不会替你建立安全访问规则，也不会自动把匿名调用者变成授权用户。已有 Spring Security 配置的项目，要核对认证和角色策略；没有必要为了排查对公网暴露所有管理端点。组件详情可能含连接地址与异常信息，记录时按内部日志管理。

下面仅示意阅读方向，不是一次真实故障输出：总状态 DOWN，下层 db 为 DOWN 而 diskSpace 为 UP，就先对照数据源配置、数据库网络与连接池日志。若 redis 为 DOWN，则检查应用同一网络中的 DNS、TLS、认证与连接超时。

对应排查可继续看数据库连接池耗尽和Redis 连接超时。健康检查失败和业务失败可能来自同一依赖，也可能是健康检查使用了不同配置，要用实际连接信息验证。

分清存活、就绪和总健康

存活检查用于判断实例是否需要重启；就绪检查用于判断实例是否可以接流量。把总健康地址同时用于两者，可能让一个共享数据库故障变成所有应用实例一起重启。

按 Spring Boot 的探针说明，在需要显式启用的环境中可配置：

management.endpoint.health.probes.enabled=true
management.endpoint.health.probes.add-additional-paths=true

这让 liveness、readiness 分组可用，并在主业务端口提供 /livez、/readyz。它不代表业务依赖已经全部加入检查。路径和暴露规则仍要在部署环境验证。

不要把共享数据库或第三方接口轻易加进 liveness；重启应用一般修不好外部服务。是否加入 readiness，要根据这个依赖失败时实例还能否提供有效服务决定。例如可降级的可选推荐接口，不宜简单决定整个应用能否接流量。分组内容应由实际业务能力来定义。

管理端口成功，为什么业务端口仍然失败

如果单独设置 management.server.port，管理端点和业务接口可能不共用相同的连接器。管理端口可访问，不等于业务端口还有能力接收连接。

排查时写清完整的探针目标：实例、端口、路径、Host、协议以及调用来源。分别验证主业务端口上的探针和一个有代表性的只读业务请求，确认负载均衡访问的是同一实例。

假设实际业务端口为 8080，可在应用本机对照：

curl -i --max-time 10 http://127.0.0.1:8080/livez
curl -i --max-time 10 http://127.0.0.1:8080/readyz

若本机正常、集群探针失败，就查探针来源到目标端口的网络、鉴权、服务网格和路径重写。若只有管理端口正常，继续查业务连接器、线程池和请求积压。

启动慢与依赖失败要分别处理

应用在启动任务执行完之前可能还没进入接流量状态。先对照启动日志与探针事件的时间线，看它究竟在正常初始化，还是已经卡在不可恢复的错误上。

在 Kubernetes 中，startup probe 可以为慢启动提供启动检查窗口；具体间隔和失败阈值要根据实际启动耗时设置，而不是照搬某组秒数。Kubernetes 探针文档说明了这些检查各自影响的行为。

增大阈值只改变平台多久采取动作，不会修复数据库连不上或健康检查实现阻塞的问题。自定义检查也应控制执行时间，避免每次探测都创建高成本任务，或在依赖变慢时叠加更多调用。

复测时看状态转换和实际流量

修复后从原探针来源重复访问，确认失败组件恢复，再观察实例的就绪状态和实际业务请求。测试发布、依赖短暂不可用和恢复三个过程：该摘流时摘流，该恢复时恢复，避免重启风暴。

记录修改前后的健康组件、HTTP 状态、探针事件和业务请求结果。不要仅以“页面绿了”结束；如果修改的是分组规则，还要确认它表达了预期业务能力。

参考资料

• Spring Boot 3.5 Actuator endpoints
• Spring Boot 生产环境监控 HTTP 配置
• Kubernetes liveness、readiness 与 startup probes

更新记录

• 2026-10-29：初稿；按官方资料核对健康分组与探针配置，示意场景不作为本站生产实测记录。