spring boot actuator 入门（1）

原创已于 2025-07-10 09:01:13 修改 · 963 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring boot #云原生 #微服务

于 2025-07-09 09:55:44 首次发布

什么是 Actuator
提供了什么功能
常用端点详解
配置与安全最佳实践
与监控/可观测性（Prometheus、Micrometer）的集成最佳实践
云原生/SRE 视角的生产级建议

1️⃣ 什么是 Spring Boot Actuator

Spring Boot Actuator 是 Spring Boot 提供的一个生产级的监控和管理功能模块，它通过暴露一组「端点」来提供关于应用状态、健康、指标、日志级别、环境配置等信息的接口。

🌟 用一句话说：Actuator 是「把你的 Spring Boot 应用变成可观测、可管理的服务」的标准工具。

2️⃣ Actuator 提供的主要功能

健康检查
应用指标
日志级别管理
应用信息暴露
环境变量、Bean、配置属性查看
路径映射信息
线程转储
HTTP 请求追踪
自定义端点扩展

3️⃣ 常用端点详解

下表是最常用的端点及其典型作用（基于 Spring Boot 2.7 / 3.x 版本为例）：

端点	作用
`/actuator/health`	应用健康状态，用于 liveness / readiness 探针
`/actuator/info`	应用信息（版本、构建、Git 等）
`/actuator/metrics`	Micrometer 指标体系入口
`/actuator/prometheus`	Prometheus scrape 格式输出
`/actuator/env`	查看环境变量、配置属性
`/actuator/beans`	所有 Spring Bean 列表
`/actuator/mappings`	所有 Spring MVC 控制器映射路径
`/actuator/loggers`	查看/动态修改日志级别
`/actuator/threaddump`	Java 线程转储
`/actuator/heapdump`	Java 堆转储
`/actuator/conditions`	条件装配报告（自动配置分析）

4️⃣ 主要配置与安全最佳实践

开启和暴露端点
Spring Boot 默认只开启 /health 和 /info。其他端点需要通过配置开启和暴露：

management:
  server:
    port: 9001
  endpoints:
    web:
      base-path: /actuator
      exposure:
        include: health,info,metrics,prometheus,loggers

生产安全实践

限制端点暴露范围
配置安全认证（Spring Security）
内网隔离或网关限制
禁用敏感端点（如 /env、/heapdump）或只给管理员角色

示例：Spring Security 中限制访问

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
      .requestMatcher(EndpointRequest.toAnyEndpoint())
      .authorizeRequests()
      .anyRequest().hasRole("ADMIN")
      .and()
      .httpBasic();
}

5️⃣ 与 Micrometer / Prometheus 集成

Spring Boot Actuator 的指标基于 Micrometer 统一度量库。

✅ Actuator 自动生成 JVM、Tomcat、数据库池、HTTP 请求等指标。
✅ Micrometer 提供后端适配器，包括 Prometheus、Graphite、Influx、New Relic、Datadog 等。

Prometheus 示例集成

<dependency> 
   <groupId>io.micrometer</groupId> 
   <artifactId>micrometer-registry-prometheus</artifactId> 
</dependency>

management:
  endpoints:
    web:
      exposure:
        include: prometheus
  metrics:
    export:
      prometheus:
        enabled: true

然后 Prometheus 通过 /actuator/prometheus 抓取。

6️⃣ 生产环境建议

✅ 最小暴露面
只暴露必要端点，敏感端点走认证/内网。

✅ 分端口
管理端口和业务端口隔离。

✅ 健康检查区分 Readiness / Liveness
Spring Boot 2.x 健康端点支持组件细分：

management:
  endpoint:
    health:
      probes:
        enabled: true

可被 Kubernetes 用来做探针：

livenessProbe:
  httpGet:
    path: /actuator/health/livenessState
readinessProbe:
  httpGet:
    path: /actuator/health/readinessState

✅ 监控集成标准化

Prometheus scrape
Grafana dashboard
AlertManager 告警

✅ 日志级别动态调整
通过 /actuator/loggers 实时调试生产问题：

# 查看当前日志级别
GET /actuator/loggers/com.example.service

# 动态修改
POST /actuator/loggers/com.example.service
{
  "configuredLevel": "DEBUG"
}

✅ 自定义健康指示器
实现 HealthIndicator 接口：

@Component
public class MyServiceHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        // 业务逻辑检查
        return Health.up().withDetail("msg", "ok").build();
    }
}