spring-boot-actuator

Spring Boot Actuator 技能

概述

• 使用 Actuator 端点、探针和 Micrometer 集成，为 Spring Boot 服务提供可用于生产环境的可观测性。
• 统一健康状态、指标和诊断配置，并将深入的参考资料放在 references/ 中。
• 满足安全运维、SLO 报告和事件诊断的平台要求。

适用场景

• 触发词：“启用 Actuator 端点”——为新的或现有的 Spring Boot 服务启用 Actuator。
• 触发词：“保护管理端口”——应用 Spring Security 策略，保护管理流量。
• 触发词：“配置健康探针”——为编排器定义就绪和存活组。
• 触发词：“将指标导出到 prometheus”——连接 Micrometer 注册表并调整指标暴露配置。
• 触发词：“调试 Actuator 启动”——当端点缺失或响应缓慢时，检查条件评估和启动指标。

快速开始

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

// Gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-actuator"
}

添加依赖后，验证端点是否有响应：

curl http://localhost:8080/actuator/health
curl http://localhost:8080/actuator/info

说明

1. 添加 Actuator 依赖

在构建配置中加入 spring-boot-starter-actuator。

验证：重启服务，并确认 /actuator/health 和 /actuator/info 返回 200 OK。

2. 暴露所需端点

• 将 management.endpoints.web.exposure.include 设置为精确的列表；对于内部部署，也可设为 "*"。
• 当默认路径 /actuator 与路由冲突时，调整 management.endpoints.web.base-path（例如 /management）。
• 查看 references/endpoint-reference.md 中的详细端点语义。

验证：curl http://localhost:8080/actuator 返回已暴露端点的列表。

3. 保护管理流量

• 使用基于角色的规则，通过 EndpointRequest.toAnyEndpoint() 配置独立的 SecurityFilterChain。
• 将 management.server.port 与防火墙控制或服务网格策略结合使用，仅允许运维人员访问。
• 仅在有需要时开放 /actuator/health/**；否则应强制进行身份验证。

验证：未经身份验证的请求访问受保护端点时返回 401 Unauthorized。

4. 配置健康探针

• 设置 management.endpoint.health.probes.enabled=true，启用 /health/liveness 和 /health/readiness。
• 通过 management.endpoint.health.group.* 对指示器进行分组，以符合平台要求。
• 通过扩展 HealthIndicator 或 ReactiveHealthContributor 实现自定义指示器；示例实现见 references/examples.md#custom-health-indicator。

验证：在将服务推广到生产环境前，确认 /actuator/health/readiness 返回 UP，且所有必需组件均已就绪。

5. 发布指标和跟踪数据

• 通过 management.metrics.export.* 启用 Micrometer 导出器（Prometheus、OTLP、Wavefront、StatsD）。
• 使用 MeterRegistryCustomizer Bean 添加 application、environment 和业务标签，以便关联可观测性数据。
• 使用 Spring Boot 3.2+ 时，通过 server.observation.* 配置暴露 HTTP 请求指标。

验证：抓取 /actuator/prometheus，并确认存在必需的计量项（http.server.requests、jvm.memory.used）。

6. 启用诊断工具

• 在事件响应期间启用 /actuator/startup（Spring Boot 3.5+）和 /actuator/conditions，以检查自动配置决策。
• 启用 /actuator/httpexchanges 进行请求审计前，先注册 HttpExchangeRepository（例如 InMemoryHttpExchangeRepository）。
• 查阅 references/endpoint-reference.md，了解端点行为和限制。

验证：/actuator/startup 和 /actuator/conditions 返回有效的 JSON 数据。

示例

基础——安全地暴露健康状态和信息

management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  endpoint:
    health:
      show-details: never

中级——带自定义指示器的就绪组

@Component
public class PaymentsGatewayHealth implements HealthIndicator {

    private final PaymentsClient client;

    public PaymentsGatewayHealth(PaymentsClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        boolean reachable = client.ping();
        return reachable ? Health.up().withDetail("latencyMs", client.latency()).build()
                         : Health.down().withDetail("error", "Gateway timeout").build();
    }
}

management:
  endpoint:
    health:
      probes:
        enabled: true
      group:
        readiness:
          include: "readinessState,db,paymentsGateway"
          show-details: always

高级——专用管理端口与 Prometheus 导出

management:
  server:
    port: 9091
    ssl:
      enabled: true
  endpoints:
    web:
      exposure:
        include: "health,info,metrics,prometheus"
      base-path: "/management"
  metrics:
    export:
      prometheus:
        descriptions: true
        step: 30s
  endpoint:
    health:
      show-details: when-authorized
      roles: "ENDPOINT_ADMIN"

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(c -> c
                .requestMatchers(EndpointRequest.to("health")).permitAll()
                .anyRequest().hasRole("ENDPOINT_ADMIN"))
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

更多端到端示例见 references/examples.md。

最佳实践

• 保持 SKILL.md 简洁，并将冗长文档放在 references/ 中，以节省上下文。
• 遵循最小权限原则：仅公开必需的端点，并限制敏感端点的访问。
• 使用按配置文件区分的 YAML 实现不可变配置，使各环境保持一致。
• 单独监控 actuator 流量，以检测抓取滥用或暴力破解尝试。
• 在 CI/CD 流水线中编写 curl 探测脚本，自动执行回归检查。

约束与警告

• 避免在公共网络上公开 /actuator/env、/actuator/configprops、/actuator/logfile 和 /actuator/heapdump。
• 除非绝对必要，否则不要发布会阻塞事件循环线程或耗时超过 250 ms 的自定义健康指标。
• 确保 Actuator 指标导出器使用受支持的 Micrometer 注册表；不受支持的导出器需要自定义注册表 Bean。
• 保持与 Spring Boot 3.5.x 规范的兼容性；较旧版本可能缺少探针和观测功能。
• 在生产环境中，切勿在未经身份验证的情况下公开 actuator 端点。
• 健康指标不应执行可能影响应用性能的高开销操作。
• 谨慎使用 /actuator/beans 和 /actuator/mappings，因为它们会暴露应用内部结构。

参考资料

• 端点快速参考
• 实现示例
• 官方文档摘录
• 使用 Actuator 进行审计
• Cloud Foundry 集成
• 启用 Actuator 功能
• HTTP 交换记录
• JMX 暴露
• 监控与指标
• 日志配置
• 指标导出器
• 使用 Micrometer 进行可观测性
• 进程与监控
• 跟踪
• Scripts 目录（scripts/）为未来自动化预留；目前没有运行时依赖。

验证清单

• 确认 mvn spring-boot:run 或 ./gradlew bootRun 会在 /actuator（或自定义基础路径）下公开预期的端点。
• 在部署到生产环境前，验证 /actuator/health/readiness 在所有必需组件就绪后返回 UP。
• 抓取 /actuator/metrics 或 /actuator/prometheus，确保所需的指标（http.server.requests、jvm.memory.used）存在。
• 运行安全扫描，验证只有预期的端口和端点可从受信任网络之外访问。