SpringBoot健康检查端点监控

本文目录导读：

1. 基础健康检查端点
2. 健康检查端点配置
3. 自定义健康指标
4. 常见健康检查指标
5. 健康检查API使用
6. 监控集成
7. 安全配置
8. 高级配置示例
9. 最佳实践
10. 问题排查

我来详细介绍 SpringBoot 健康检查端点和监控相关内容。

基础健康检查端点

1 启用 Actuator

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

2 配置文件

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env,beans,loggers
        # 或使用 * 暴露所有端点
        # include: "*"
  endpoint:
    health:
      show-details: always  # 显示详细信息
      show-components: always  # 显示组件状态

健康检查端点配置

1 核心配置选项

management:
  health:
    # 健康检查缓存时间
    cache:
      timeout: 10000
    # 默认健康指标
    defaults:
      enabled: true
    # 磁盘空间检查
    diskspace:
      enabled: true
      path: /tmp
      threshold: 10GB
    # 数据库健康检查
    db:
      enabled: true
    # Redis健康检查
    redis:
      enabled: true
  endpoint:
    health:
      # 自定义响应状态
      status:
        http-mapping:
          UP: 200
          DOWN: 503
          OUT_OF_SERVICE: 503

自定义健康指标

1 实现 HealthIndicator

@Component
public class CustomHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        try {
            // 执行健康检查逻辑
            boolean isHealthy = checkServiceHealth();
            if (isHealthy) {
                return Health.up()
                    .withDetail("service", "running")
                    .withDetail("timestamp", System.currentTimeMillis())
                    .build();
            } else {
                return Health.down()
                    .withDetail("service", "unavailable")
                    .withDetail("error", "Service is not responding")
                    .build();
            }
        } catch (Exception e) {
            return Health.down()
                .withDetail("error", e.getMessage())
                .build();
        }
    }
    private boolean checkServiceHealth() {
        // 实际的健康检查逻辑
        return true;
    }
}

2 使用 AbstractHealthIndicator

@Component
public class DatabaseHealthIndicator extends AbstractHealthIndicator {
    @Autowired
    private DataSource dataSource;
    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        try (Connection conn = dataSource.getConnection()) {
            if (conn.isValid(5000)) {
                builder.up()
                    .withDetail("database", "MySQL")
                    .withDetail("version", conn.getMetaData().getDatabaseProductVersion());
            } else {
                builder.down()
                    .withDetail("error", "Cannot connect to database");
            }
        }
    }
}

常见健康检查指标

1 内置健康指标

management:
  health:
    # 启用所有内置健康指标
    defaults:
      enabled: true
    # 各组件健康检查配置
    diskspace:
      enabled: true
    db:
      enabled: true
    elasticsearch:
      enabled: true
    influxdb:
      enabled: true
    jms:
      enabled: true
    ldap:
      enabled: true
    mail:
      enabled: true
    mongo:
      enabled: true
    neo4j:
      enabled: true
    ping:
      enabled: true
    rabbit:
      enabled: true
    redis:
      enabled: true
    solr:
      enabled: true

2 自定义健康检查分组

management:
  endpoint:
    health:
      group:
        custom-group:
          include: db,redis,custom
          show-details: always
          status:
            http-mapping:
              UP: 200
              DOWN: 503

健康检查API使用

1 访问健康检查端点

# 基本健康检查
GET /actuator/health
# 详细健康检查
GET /actuator/health?format=detailed
# 健康分组检查
GET /actuator/health/custom-group

2 响应示例

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963170816,
        "free": 123456789012,
        "threshold": 10485760
      }
    },
    "redis": {
      "status": "UP",
      "details": {
        "version": "6.2.6"
      }
    },
    "custom": {
      "status": "UP",
      "details": {
        "service": "running",
        "timestamp": 1634567890123
      }
    }
  }
}

监控集成

1 Prometheus 集成

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

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

2 Grafana 集成

# application.yml
management:
  endpoints:
    web:
      base-path: /actuator
  metrics:
    tags:
      application: ${spring.application.name}

安全配置

1 保护健康检查端点

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/actuator/health").permitAll()  // 允许匿名访问
                .antMatchers("/actuator/**").hasRole("ADMIN")  // 需要管理员权限
                .anyRequest().authenticated()
            .and()
            .httpBasic();
    }
}

2 自定义响应状态码

management:
  endpoint:
    health:
      status:
        http-mapping:
          UP: 200
          DOWN: 503
          OUT_OF_SERVICE: 503
          UNKNOWN: 200

高级配置示例

1 完整配置

spring:
  application:
    name: my-service
server:
  port: 8080
management:
  server:
    port: 8081  # 监控端口与业务端口分离
    address: 127.0.0.1  # 只监听本地
  endpoints:
    web:
      base-path: /internal  # 自定义路径
      exposure:
        include: health,info,metrics,prometheus
        exclude: env,beans  # 排除敏感端点
      cors:
        allowed-origins: http://example.com
        allowed-methods: GET,POST
  endpoint:
    health:
      show-details: when-authorized  # 仅授权用户查看详情
      roles: ADMIN
      cache:
        time-to-live: 10s  # 缓存10秒
# 自定义健康检查
spring:
  datasource:
    hikari:
      connection-test-query: SELECT 1
      validation-timeout: 3000

2 自定义健康检查器注册

@Component
public class HealthCheckConfig {
    @Bean
    public ReactiveHealthIndicator reactiveHealthChecker() {
        return () -> Mono.just(Health.up()
            .withDetail("service", "reactive")
            .build());
    }
    @Bean
    public HealthAggregator healthAggregator() {
        OrderedHealthAggregator aggregator = new OrderedHealthAggregator();
        aggregator.setStatusOrder(Status.DOWN, Status.OUT_OF_SERVICE, Status.UP, Status.UNKNOWN);
        return aggregator;
    }
}

最佳实践

1 健康检查设计原则

@Component
public class BestPracticeHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        // 1. 快速返回结果（设置超时）
        // 2. 不依赖外部服务状态
        // 3. 不执行耗时操作
        // 4. 避免在健康检查中执行业务逻辑
        return Health.up()
            .withDetail("quick", "health check")
            .build();
    }
}

2 超时设置

management:
  health:
    defaults:
      enabled: true
    # 整体超时
    status:
      order: DOWN, OUT_OF_SERVICE, UNKNOWN, UP
  endpoint:
    health:
      time-to-live: 10000  # 缓存时间10秒

问题排查

1 常见问题

# 检查端点是否暴露
curl http://localhost:8080/actuator
# 检查健康详情
curl http://localhost:8080/actuator/health
# 查看所有端点
curl http://localhost:8080/actuator/beans

2 日志配置

logging:
  level:
    org.springframework.boot.actuate: DEBUG
    org.springframework.boot.actuate.health: TRACE

通过以上配置，您可以构建一个完整、安全且可扩展的 SpringBoot 健康检查监控系统，记得根据实际需求调整配置,并注意在生产环境中保护敏感信息。