Spring Boot Actuator 怎样按端点暴露健康信息

我在给 Spring Boot 服务接入监控时，最容易先做错的一件事，是把“能访问健康检查”和“把所有 Actuator 端点都开放”当成同一个配置问题。更稳妥的做法是先引入 Actuator，再用端点 ID 选择真正需要的 HTTP 入口，最后单独决定健康信息要不要带组件详情。

官方地址：https://spring.io/projects/spring-boot

本文按当前 Spring Boot 官方 Actuator 文档的端点模型说明，示例只围绕 HTTP 暴露。默认情况下，`health` 通过 `/actuator/health` 提供，而其他端点不应因为“方便调试”就一并公开。

先把 Actuator 能力加入应用

Spring Boot 官方推荐通过 `spring-boot-starter-actuator` 启用生产就绪能力。Maven 项目可以加入下面的依赖；XML 注释说明这段依赖的用途，版本继续交给项目的 Spring Boot 依赖管理。

org.springframework.bootspring-boot-starter-actuator

加入依赖后，默认的 HTTP 管理基路径是 `/actuator`，健康端点的默认路径是 `/actuator/health`。这里的“可用”要同时理解为端点存在并且通过某种技术暴露；单纯加入依赖，并不等于所有端点都能从网络访问。

如果项目使用 Gradle，等价写法如下：

dependencies {
    // 引入 Spring Boot Actuator 的生产运行监控能力
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

用 include 选择需要的端点

按端点暴露时，我通常先写一个最小清单，而不是从 `*` 开始。下面的 YAML 只让健康状态和应用自定义信息可以通过 HTTP 访问：

management:
  endpoints:
    web:
      # 只把两个明确需要的端点映射到 HTTP
      exposure:
        include: "health,info"
      # 留空表示暂不额外排除 include 中的端点
      # exclude: ""

端点 ID 是 `health`、`info`、`metrics` 这类名称，不要把完整的 `/actuator/health` 路径填进 `include`。如果要加入指标，可以写成 `include: "health,info,metrics"`；真正的 HTTP 路径仍由管理基路径和端点 ID 拼成。

当配置文件由多个环境叠加时，显式写出列表比依赖默认值更容易审查。尤其是 `include: "*"` 会暴露全部端点，YAML 中的星号还具有特殊含义，必须加引号。

management:
  endpoints:
    web:
      # 星号表示选择全部端点，YAML 中必须加引号
      exposure:
        include: "*"
        # 即使全选，也把敏感端点从结果中排除
        exclude: "env,beans,heapdump"

官方规则是 `exclude` 优先于 `include`。所以全选并排除并不是两个互相矛盾的配置，而是“先允许候选集合，再明确剔除例外”。不过生产环境仍建议从最小清单起步，只有经过安全评估的端点才逐个加入。

把健康状态和健康详情分开控制

健康端点的关键不只是“暴露还是不暴露”，还包括返回什么深度。Spring Boot 会从已注册的健康贡献者构成健康树，常见贡献者可能对应数据库、磁盘空间或自定义检查。`show-details` 和 `show-components` 控制这些细节是否出现在响应中，默认不会把详情展示给未授权访问者。

management:
  endpoint:
    health:
      # 未授权请求只看到总体状态，不看到数据库等组件细节
      show-details: when-authorized
      show-components: when-authorized
      # 只有具备该角色的认证用户才可查看健康详情
      roles: OPERATIONS

这三个值可以这样理解：

我更倾向于把 `when-authorized` 作为生产起点：负载均衡器只读总体状态，运维人员通过认证入口读取组件详情。不要把 `always` 当成“更容易接入监控”的默认答案，因为数据库名称、磁盘状态或外部依赖信息可能让暴露面扩大。

有 Spring Security 时只保护 Actuator 路径

如果 Spring Security 在类路径中并且项目没有自定义 `SecurityFilterChain`，Spring Boot 会自动保护除 `/health` 外的 Actuator 端点。但一旦自己声明了安全过滤链，自动配置就会退让，Actuator 规则也需要由应用明确写出。

下面的 Java 配置只把请求匹配范围限定在 Actuator 端点，并要求运维角色。代码中的第二条安全链用于业务接口的示意提醒；实际项目仍应根据登录方式、会话策略和 CSRF 需求补全业务规则。

import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import static org.springframework.security.config.Customizer.withDefaults;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurityConfiguration {
    @Bean
    SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        // 只匹配 /actuator/**，避免把业务接口一起套上运维角色
        http.securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(requests -> requests
                .anyRequest().hasRole("OPERATIONS"));
        // 采用 HTTP Basic 只是示例，生产环境应配合 TLS 与真实身份系统
        http.httpBasic(withDefaults());
        return http.build();
    }
}

上面的片段使用了 `withDefaults()`，完整文件还需要导入 `org.springframework.security.config.Customizer.withDefaults`。重点不在认证方式本身，而在 `EndpointRequest.toAnyEndpoint()`：它把规则范围收窄到 Actuator 路径。若你只想限制某一个端点，也可以使用对应的端点匹配器。

最后检查三个容易被忽略的边界

1. 把管理端口和业务端口分开考虑。端点是否暴露、是否经过网关和是否可被公网访问是三层问题；只写 `include` 不能替代网络隔离或认证。
2. 留意敏感端点。env、configprops、beans、heapdump 等端点可能携带配置、对象或运行时信息，除非有明确用途，否则不要加入公开清单。
3. 不要误判 YAML 的星号。include: "*" 是全选，exclude 优先；如果只想开放健康检查，就用 include: "health"，不要用全选后再猜测排除列表是否完整。

如果健康详情已经设置为 `when-authorized`，还要让实际安全规则允许授权用户访问 `/actuator/health`，否则角色配置不会凭空创建认证链。相反，如果健康检查由未认证的负载均衡器调用，就应该让它只拿到可接受的总体状态，而不是直接开放所有详情。

按最小暴露原则落地

这次配置的核心可以压缩成一句话：用 `management.endpoints.web.exposure.include` 决定“哪些端点走 HTTP”，用 `exclude` 做强制剔除，再用 `health.show-details`、`health.show-components` 和角色控制“健康信息展示到多深”。这样排查问题时，端点入口、健康内容和身份权限各自有清楚的责任边界。

只想让负载均衡器判断存活，应该怎么配？

保留默认的 `health` 暴露，并让探针访问 `/actuator/health`。不要为了让探针工作而把 `info`、`env` 或 `metrics` 一起开放。

为什么配置了 include 仍然访问不到端点？

检查端点 ID、配置文件是否被当前环境加载、是否存在更高优先级配置，以及 Spring Security、网关或防火墙是否拒绝了请求。`include` 只负责暴露选择，不会绕过认证和网络策略。

可以直接设置 show-details=always 吗？

可以，但应限于已隔离、已认证或不含敏感组件信息的场景。生产服务通常从 `when-authorized` 起步，并给健康详情配置专门角色。

技术事实参考：Spring Boot 启用生产就绪功能、Spring Boot Actuator Endpoints。文中配置与代码为围绕端点暴露任务独立整理的示例。