Actuator 监控

Spring Boot Actuator 以 HTTP 端点的形式暴露应用的运行时状态：健康检查、指标、Bean 列表、环境变量、线程转储等，是生产运维和平台集成的标准入口。

快速开始

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

默认只开放 health 端点。按需开放更多端点：

management:
  endpoints:
    web:
      exposure:
        include: health, info, metrics, env, beans, loggers, threaddump, heapdump
        # 开放全部（生产环境谨慎使用）
        # include: "*"
      base-path: /actuator   # 默认路径前缀
  server:
    port: 8081               # 可单独指定管理端口，与业务端口隔离

核心端点速查

端点	方法	说明
`/actuator/health`	GET	应用健康状态（UP/DOWN/OUT_OF_SERVICE）
`/actuator/info`	GET	应用元信息（版本、构建信息等）
`/actuator/metrics`	GET	指标列表；`/metrics/{name}` 查看单项
`/actuator/prometheus`	GET	Prometheus 格式指标（需引入 `micrometer-registry-prometheus`）
`/actuator/env`	GET	所有环境变量和配置属性
`/actuator/beans`	GET	容器中所有 Bean 的依赖关系
`/actuator/mappings`	GET	所有 `@RequestMapping` 路由列表
`/actuator/loggers`	GET/POST	查看/动态调整日志级别
`/actuator/threaddump`	GET	当前线程转储（JVM thread dump）
`/actuator/heapdump`	GET	下载堆内存快照（hprof 文件）
`/actuator/conditions`	GET	自动配置条件评估报告
`/actuator/scheduledtasks`	GET	所有定时任务列表
`/actuator/caches`	GET/DELETE	查看/清除缓存
`/actuator/shutdown`	POST	优雅关闭应用（需手动开启）

Health 端点

基本配置

management:
  endpoint:
    health:
      show-details: always        # never / when-authorized / always
      show-components: always
  health:
    db:
      enabled: true               # 数据库健康检查
    redis:
      enabled: true               # Redis 健康检查
    diskspace:
      enabled: true
      threshold: 10MB             # 磁盘剩余低于 10MB 时 DOWN

响应示例：

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": { "database": "MySQL", "validationQuery": "isValid()" }
    },
    "redis": {
      "status": "UP",
      "details": { "version": "7.2.3" }
    },
    "diskSpace": {
      "status": "UP",
      "details": { "total": 499963174912, "free": 382456832000 }
    }
  }
}

内置 HealthIndicator

指示器	检查内容	触发条件
`DataSourceHealthIndicator`	数据库连通性	类路径有 `DataSource`
`RedisHealthIndicator`	Redis PING	类路径有 `RedisConnectionFactory`
`RabbitHealthIndicator`	RabbitMQ 连通性	类路径有 `RabbitTemplate`
`KafkaHealthIndicator`	Kafka Broker 连通性	类路径有 `KafkaTemplate`
`MongoHealthIndicator`	MongoDB 连通性	类路径有 `MongoClient`
`DiskSpaceHealthIndicator`	磁盘剩余空间	始终启用
`PingHealthIndicator`	始终 UP	始终启用

自定义 HealthIndicator

@Component
public class ThirdPartyApiHealthIndicator implements HealthIndicator {
 
    private final RestTemplate restTemplate;
 
    public ThirdPartyApiHealthIndicator(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
 
    @Override
    public Health health() {
        try {
            ResponseEntity<String> resp =
                restTemplate.getForEntity("https://api.example.com/ping", String.class);
 
            if (resp.getStatusCode().is2xxSuccessful()) {
                return Health.up()
                    .withDetail("url", "https://api.example.com/ping")
                    .withDetail("responseTime", "OK")
                    .build();
            }
            return Health.down()
                .withDetail("statusCode", resp.getStatusCode().value())
                .build();
        } catch (Exception e) {
            return Health.down(e)
                .withDetail("error", e.getMessage())
                .build();
        }
    }
}

健康状态聚合

多个 HealthIndicator 的状态按以下优先级聚合（高优先级覆盖低优先级）：

DOWN > OUT_OF_SERVICE > UP > UNKNOWN

自定义聚合策略：

@Bean
public StatusAggregator customStatusAggregator() {
    // 忽略外部服务故障，不影响整体 UP 状态
    return StatusAggregator.getDefault(
        Map.of("thirdPartyApi", new Status("DEGRADED"))
    );
}

Info 端点

management:
  info:
    env:
      enabled: true     # 暴露 info.* 配置属性
    git:
      enabled: true     # 暴露 Git 提交信息（需 git-commit-id-plugin）
      mode: full        # simple / full
    build:
      enabled: true     # 暴露构建信息（需 spring-boot-maven-plugin 生成 build-info）
    java:
      enabled: true     # JVM 版本信息
    os:
      enabled: true     # 操作系统信息
 
info:
  app:
    name: "@project.artifactId@"
    version: "@project.version@"
    description: "订单管理服务"
  team: "platform-engineering"

Maven 生成构建信息（pom.xml）：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>   <!-- 生成 META-INF/build-info.properties -->
            </goals>
        </execution>
    </executions>
</plugin>

Loggers 端点（动态调整日志级别）

无需重启，通过 HTTP 实时调整日志级别：

# 查看某个包的日志级别
curl http://localhost:8080/actuator/loggers/com.example.service
 
# 动态调整（POST）
curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}'
 
# 恢复默认级别
curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": null}'

日志配置详见日志。

Kubernetes 健康探针

Spring Boot 2.3+ 内置 Liveness / Readiness 探针，与 K8s 原生集成：

management:
  endpoint:
    health:
      probes:
        enabled: true          # 开启 /actuator/health/liveness 和 /actuator/health/readiness
  health:
    livenessstate:
      enabled: true
    readinessstate:
      enabled: true

# kubernetes deployment.yaml
livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3
 
readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 3

探针	含义	DOWN 时 K8s 行为
Liveness	进程是否健康（死锁、OOM 等）	重启 Pod
Readiness	是否可以接收流量	从 Service 摘除，不发送流量

编程式修改 Readiness 状态（如优雅停机时）：

@Component
@RequiredArgsConstructor
public class ShutdownHandler implements ApplicationListener<ContextClosedEvent> {
 
    private final ApplicationEventPublisher publisher;
 
    @Override
    public void onApplicationEvent(ContextClosedEvent event) {
        // 先告知 K8s 停止路由新流量
        AvailabilityChangeEvent.publish(publisher, this, ReadinessState.REFUSING_TRAFFIC);
    }
}

优雅停机详见优雅停机。

自定义端点

@Component
@Endpoint(id = "feature-flags")         // 访问路径：/actuator/feature-flags
public class FeatureFlagsEndpoint {
 
    private final FeatureFlagService flagService;
 
    // GET /actuator/feature-flags
    @ReadOperation
    public Map<String, Boolean> getAllFlags() {
        return flagService.getAllFlags();
    }
 
    // GET /actuator/feature-flags/{flagName}
    @ReadOperation
    public Map<String, Object> getFlag(@Selector String flagName) {
        return Map.of(
            "name", flagName,
            "enabled", flagService.isEnabled(flagName)
        );
    }
 
    // POST /actuator/feature-flags/{flagName}
    @WriteOperation
    public void setFlag(@Selector String flagName, boolean enabled) {
        flagService.setFlag(flagName, enabled);
    }
 
    // DELETE /actuator/feature-flags/{flagName}
    @DeleteOperation
    public void deleteFlag(@Selector String flagName) {
        flagService.removeFlag(flagName);
    }
}

仅在 Web 环境暴露的端点：

@Component
@WebEndpoint(id = "session-info")      // 仅通过 HTTP 暴露（不通过 JMX）
public class SessionInfoEndpoint {
 
    @ReadOperation
    @Produces(MediaType.APPLICATION_JSON_VALUE)
    public WebEndpointResponse<Map<String, Object>> sessionInfo(
            HttpServletRequest request) {
        HttpSession session = request.getSession(false);
        if (session == null) {
            return new WebEndpointResponse<>(Map.of("active", false), 200);
        }
        return new WebEndpointResponse<>(Map.of(
            "active", true,
            "id", session.getId(),
            "creationTime", session.getCreationTime()
        ), 200);
    }
}

安全保护

Actuator 端点暴露了敏感信息，生产环境必须保护：

@Configuration
@EnableWebSecurity
public class ActuatorSecurityConfig {
 
    @Bean
    public SecurityFilterChain actuatorSecurityChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/actuator/**")
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health/**").permitAll()  // 探针公开
                .requestMatchers("/actuator/info").permitAll()        // 版本信息公开
                .requestMatchers("/actuator/**").hasRole("ACTUATOR")  // 其余需认证
            )
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

spring:
  security:
    user:
      name: actuator
      password: ${ACTUATOR_PASSWORD}
      roles: ACTUATOR

也可通过管理端口隔离（只在内网可达）：

management:
  server:
    port: 8081   # 业务端口 8080，管理端口 8081 仅内网开放

安全详见安全。

指标集成

引入 Prometheus 依赖后，/actuator/prometheus 自动暴露指标：

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

指标采集完整配置详见指标采集。

知识仓库

探索

Actuator 监控

Actuator 监控

快速开始

核心端点速查

Health 端点

基本配置

内置 HealthIndicator

自定义 HealthIndicator

健康状态聚合

Info 端点

Loggers 端点（动态调整日志级别）

Kubernetes 健康探针

自定义端点

安全保护

指标集成

相关链接

关系图谱

目录

反向链接