使用Spring Boot Actuator构建用户应用

Spring Boot Actuator基础配置

快速启用监控功能

通过添加spring-boot-starter-actuator依赖即可快速启用生产级监控功能。该依赖会自动配置所有Actuator默认设置，包括健康检查、环境变量、指标数据等核心功能。在Gradle构建文件中添加以下依赖：

gradle 复制代码

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

默认健康端点

默认情况下，Spring Boot Actuator仅暴露/actuator/health端点，该端点返回应用健康状态：

json 复制代码

{
  "status": "UP"
}

健康状态可能为：

UP：应用运行正常
DOWN：应用存在严重问题
OUT_OF_SERVICE：应用暂时不可用
UNKNOWN：状态未知

自定义端点路径

可以通过management.endpoints.web.base-path属性修改Actuator端点前缀路径。在application.properties中添加：

properties 复制代码

# 修改Actuator基础路径
management.endpoints.web.base-path=/users-system-management

# 应用名称配置
spring.application.name=Users App

修改后，健康检查端点将变为：http://localhost:8080/users-system-management/health

使用Spring Profiles隔离配置

建议为Actuator创建独立的profile配置：

创建application-actuator.properties配置文件
添加特定环境的Actuator配置：

properties 复制代码

# 暴露特定端点
management.endpoints.web.exposure.include=health,info

# 信息端点配置
management.info.env.enabled=true
info.application.name=${spring.application.name}
info.developer.name=Felipe
[email protected]
info.api.version=1.0

运行应用时激活profile：

bash 复制代码

./gradlew bootRun --args='--spring.profiles.active=actuator'

端点暴露控制

可以通过以下属性精确控制哪些端点对外暴露：

properties 复制代码

# 暴露所有端点
management.endpoints.web.exposure.include=*

# 选择性暴露特定端点
management.endpoints.web.exposure.include=health,info,env,metrics

# 排除敏感端点
management.endpoints.web.exposure.exclude=shutdown

端点安全配置

默认情况下，Actuator端点不包含敏感信息，但建议添加安全控制：

添加Spring Security依赖：

gradle 复制代码

implementation 'org.springframework.boot:spring-boot-starter-security'

配置端点访问权限：

java 复制代码

@Configuration
public class ActuatorSecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/**").hasRole("ACTUATOR")
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

常用基础端点

端点路径	说明	默认启用
`/health`	应用健康状态	是
`/info`	应用基本信息	否
`/env`	环境变量信息	否
`/metrics`	应用指标数据	否
`/loggers`	日志配置信息	否

通过合理配置这些基础功能，可以快速构建出适合生产环境的监控体系，为后续深入使用Actuator高级功能奠定基础。

核心Actuator端点详解

/actuator/info端点：应用元数据展示

该端点用于展示应用基础信息与自定义元数据，需通过以下配置显式启用：

properties 复制代码

management.endpoints.web.exposure.include=info
management.info.env.enabled=true

典型配置示例：

properties 复制代码

# 基础信息
[email protected]@
[email protected]@

# 自定义元数据
info.developer.team=Platform-Engineering
info.deployment.region=us-east-1

端点响应示例：

json 复制代码

{
  "application": {
    "name": "Users App",
    "version": "2.1.0"
  },
  "git": {
    "branch": "main",
    "commit": {
      "id": "3d1e846",
      "time": "2023-05-15T08:42:19Z"
    }
  },
  "build": {
    "artifact": "users-service",
    "group": "com.example"
  }
}

/actuator/env端点：环境变量探查

该端点实时暴露应用运行环境的所有配置属性，包括：

系统环境变量
JVM系统属性
应用配置文件(application.properties/yml)
随机属性值

启用方式：

properties 复制代码

management.endpoints.web.exposure.include=env

典型响应结构：

json 复制代码

{
  "activeProfiles": ["production"],
  "propertySources": [
    {
      "name": "systemEnvironment",
      "properties": {
        "PATH": {
          "value": "/usr/local/bin:/usr/bin"
        }
      }
    },
    {
      "name": "applicationConfig: [classpath:/application.yml]",
      "properties": {
        "spring.datasource.url": {
          "value": "jdbc:h2:mem:testdb"
        }
      }
    }
  ]
}

/actuator/beans端点：容器Bean分析

展示Spring应用上下文中所有注册的Bean定义信息，包括：

Bean作用域(Singleton/Prototype)
依赖关系
资源位置
类型信息

启用配置：

properties 复制代码

management.endpoints.web.exposure.include=beans

示例输出片段：

json 复制代码

{
  "contexts": {
    "Users App": {
      "beans": {
        "userController": {
          "scope": "singleton",
          "type": "com.example.UserController",
          "dependencies": ["userService"]
        },
        "jpaRepositories": {
          "scope": "singleton",
          "type": "org.springframework.data.jpa.repository.support.JpaRepositoryFactoryBean"
        }
      }
    }
  }
}

/actuator/metrics端点：系统指标监控

提供JVM及系统级性能指标数据，支持按指标名称细查：

基础启用配置：

properties 复制代码

management.endpoints.web.exposure.include=metrics

获取所有可用指标：

bash 复制代码

GET /actuator/metrics

响应示例：

json 复制代码

{
  "names": [
    "jvm.memory.used",
    "system.cpu.usage",
    "http.server.requests",
    "hikaricp.connections.active"
  ]
}

查询特定指标（如JVM内存）：

bash 复制代码

GET /actuator/metrics/jvm.memory.used

详细指标响应：

json 复制代码

{
  "name": "jvm.memory.used",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 250892312
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": ["heap", "nonheap"]
    }
  ]
}

/actuator/threaddump端点：线程分析

生成当前JVM线程快照，用于诊断死锁、线程阻塞等问题：

启用方式：

properties 复制代码

management.endpoints.web.exposure.include=threaddump

典型线程信息结构：

json 复制代码

{
  "threads": [
    {
      "threadName": "http-nio-8080-exec-1",
      "threadId": 31,
      "state": "WAITING",
      "stackTrace": [
        {
          "className": "java.lang.Object",
          "methodName": "wait",
          "lineNumber": -2
        }
      ]
    }
  ]
}

端点安全增强配置

对于生产环境，建议对敏感端点进行细粒度控制：

java 复制代码

@Bean
public SecurityFilterChain actuatorSecurity(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/actuator/health").permitAll()
            .requestMatchers("/actuator/info").permitAll()
            .requestMatchers("/actuator/**").hasRole("ADMIN")
        )
        .httpBasic(Customizer.withDefaults());
    return http.build();
}

配合细化的健康端点展示策略：

properties 复制代码

# 仅对管理员显示详情
management.endpoint.health.show-details=when_authorized
management.endpoint.health.roles=ADMIN

通过合理配置这些核心端点，可以全面掌握应用运行状态，快速定位性能瓶颈和运行时问题。建议根据实际生产需求选择暴露的端点，并配合安全机制保护敏感信息。

安全与审计配置

集成Spring Security保护端点访问

为保护Actuator端点中的敏感信息，需集成Spring Security进行访问控制。在build.gradle中添加安全依赖：

gradle 复制代码

implementation 'org.springframework.boot:spring-boot-starter-security'

配置基于角色的端点访问策略，仅允许具有ACTUATOR角色的用户访问监控端点：

java 复制代码

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http, HandlerMappingIntrospector introspector) throws Exception {
    MvcRequestMatcher.Builder mvcMatcherBuilder = new MvcRequestMatcher.Builder(introspector);
    http
        .csrf(csrf -> csrf.disable())
        .authorizeHttpRequests(auth -> auth
            .requestMatchers(mvcMatcherBuilder.pattern("/actuator/**")).hasRole("ACTUATOR")
            .anyRequest().authenticated())
        .formLogin(Customizer.withDefaults())
        .httpBasic(Customizer.withDefaults());
    return http.build();
}

配置角色化用户管理

通过UserDetailsManager创建内存用户存储，并分配不同权限角色：

java 复制代码

@Bean
UserDetailsManager userDetailsManager(PasswordEncoder passwordEncoder){
    UserDetails admin = User.builder()
        .username("admin")
        .password(passwordEncoder.encode("admin"))
        .roles("ADMIN","USER","ACTUATOR")
        .build();
    
    UserDetails manager = User.builder()
        .username("manager")
        .password(passwordEncoder.encode("manager"))
        .roles("ADMIN","USER")
        .build();
        
    return new InMemoryUserDetailsManager(admin, manager);
}

@Bean
PasswordEncoder passwordEncoder(){
    return new BCryptPasswordEncoder();
}

审计事件记录实现

Actuator提供/actuator/auditevents端点记录安全事件，需配置审计存储库：

java 复制代码

@Bean
public AuditEventRepository auditEventRepository() {
    return new InMemoryAuditEventRepository();
}

该端点会记录三类关键事件：

AUTHENTICATION_SUCCESS：认证成功事件
AUTHORIZATION_FAILURE：授权失败事件
AUTHENTICATION_FAILURE：认证失败事件

示例审计日志输出：

json 复制代码

{
  "events": [
    {
      "timestamp": "2023-11-20T19:04:28.683151Z",
      "principal": "admin",
      "type": "AUTHENTICATION_SUCCESS",
      "data": {
        "remoteAddress": "0:0:0:0:0:0:0:1"
      }
    }
  ]
}

自定义审计事件处理

可通过监听AuditApplicationEvent实现自定义审计逻辑：

java 复制代码

@EventListener
public void on(AuditApplicationEvent event) {
    log.info("审计事件触发 - 类型: {}, 用户: {}", 
        event.getAuditEvent().getType(),
        event.getAuditEvent().getPrincipal());
}

生产环境建议

替换InMemoryAuditEventRepository为持久化实现
配置HTTPS加密通信
定期轮换审计日志
实现审计日志分析告警机制

完整安全配置示例：

properties 复制代码

# 安全相关配置
management.endpoint.health.roles=ACTUATOR
management.endpoint.health.show-details=when_authorized
management.endpoints.web.exposure.include=health,info,auditevents

通过以上配置，可构建完整的端点安全防护体系，同时满足审计合规性要求。实际生产部署时，建议结合企业安全规范进行扩展。

自定义端点开发

端点基础实现

通过实现@Endpoint注解可创建自定义Actuator端点，以下示例展示日志事件配置端点的完整实现：

java 复制代码

@Component
@Endpoint(id="event-config")
public class LogEventEndpoint {
    private LogEventConfig config = new LogEventConfig();
    
    @ReadOperation
    public LogEventConfig config() {
        return config;
    }
    
    @WriteOperation
    public void eventConfig(@Nullable Boolean enabled, 
                          @Nullable String prefix, 
                          @Nullable String postfix) {
        if (enabled != null) this.config.setEnabled(enabled);
        if (prefix != null) this.config.setPrefix(prefix);
        if (postfix != null) this.config.setPostfix(postfix);
    }
}

关键注解说明：

@Endpoint(id="event-config")：定义端点ID，自动映射为/actuator/event-config路径
@ReadOperation：标记HTTP GET操作，返回当前配置状态
@WriteOperation：标记HTTP POST操作，支持动态修改配置参数

配置模型设计

端点配置模型采用Lombok简化代码：

java 复制代码

@Data
@AllArgsConstructor
@NoArgsConstructor
public class LogEventConfig {
    private Boolean enabled = true;
    private String prefix = ">> ";
    private String postfix = " <<";
}

业务集成示例

在日志处理器中集成端点配置功能：

java 复制代码

@Slf4j
@Component
@AllArgsConstructor
public class UserLogs {
    private final LogEventEndpoint endpoint;

    @Async
    @EventListener
    void userEventHandler(UserEvent event) {
        if (endpoint.isEnable()) {
            log.info("{} {} {}", 
                endpoint.config().getPrefix(),
                event.getMessage(),
                endpoint.config().getPostfix());
        }
    }
}

JMX集成管理

自定义端点自动通过JMX暴露，可通过JConsole进行操作：

连接应用JMX端口
导航至org.springframework.boot > Endpoint > event-config
在Operations标签页执行读写操作

![JMX操作界面示意图]

端点安全配置

在application-actuator.properties中启用端点：

properties 复制代码

management.endpoints.web.exposure.include=health,info,event-config
management.endpoint.health.show-details=when_authorized

动态配置验证

通过cURL测试端点功能：

bash 复制代码

# 读取当前配置
curl -u admin:admin http://localhost:8080/actuator/event-config

# 修改配置参数
curl -X POST -H "Content-Type: application/json" -d '{
    "prefix": "[EVENT] ",
    "postfix": " [END]"
}' http://localhost:8080/actuator/event-config

生产环境建议

为写操作添加@Secured注解进行权限控制
实现配置持久化存储
添加参数校验逻辑
考虑配置变更的原子性

这种自定义端点模式适用于需要运行时调整的业务参数，相比传统配置文件方式，提供了更灵活的动态管理能力。

健康检查高级配置

健康指标优先级控制

通过management.endpoint.health.status.order属性可以自定义健康状态的优先级顺序。默认值为：

properties 复制代码

management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up

当存在多个健康指标时，系统会按照该顺序确定最终应用状态。例如，若RabbitMQ健康状态为DOWN但优先级配置中移除了down：

properties 复制代码

management.endpoint.health.status.order=fatal,out-of-service,unknown,up

此时即使RabbitMQ不可用，应用整体状态仍会显示为UP。

内置健康指标详解

Spring Boot Actuator内置了多种健康指标：

数据库健康指标

自动检测DataSource连接状态，支持H2、PostgreSQL等常见数据库：
json 复制代码
```
"db": {
  "status": "UP",
  "details": {
    "database": "H2",
    "validationQuery": "isValid()"
  }
}
```

磁盘空间指标

监控系统磁盘使用情况，默认阈值10MB：

json 复制代码

"diskSpace": {
  "status": "UP",
  "details": {
    "total": 1000240963584,
    "free": 97917366272,
    "threshold": 10485760
  }
}

中间件健康指标

包括RabbitMQ、Redis等组件的自动检测：

json 复制代码

"rabbit": {
  "status": "DOWN",
  "details": {
    "error": "Connection refused"
  }
}

自定义健康指标实现

通过实现HealthIndicator接口可创建业务专属健康检查：

java 复制代码

@Component
public class EventsHealthIndicator implements HealthIndicator {
    private final LogEventEndpoint endpoint;

    @Override
    public Health health() {
        return endpoint.isEnable() ? 
            Health.up().build() :
            Health.status(new Status("EVENTS-DOWN", "事件服务已禁用")).build();
    }
}

命名约定：类名需以HealthIndicator结尾，注册的组件名称为前缀部分（如EventsHealthIndicator对应events组件）

健康详情暴露策略

通过以下配置控制健康详情信息的可见性：

properties 复制代码

# 显示策略：never|when_authorized|always
management.endpoint.health.show-details=when_authorized

# 允许查看详情的角色
management.endpoint.health.roles=ACTUATOR

RabbitMQ健康检测实战

添加AMQP依赖：

gradle 复制代码

implementation 'org.springframework.boot:spring-boot-starter-amqp'

健康状态自动检测：

json 复制代码

{
  "status": "DOWN",
  "components": {
    "rabbit": {
      "status": "DOWN",
      "details": {
        "error": "Connection refused"
      }
    }
  }
}

启动RabbitMQ服务后状态变化：

json 复制代码

"rabbit": {
  "status": "UP",
  "details": {
    "version": "3.12.9"
  }
}

复合状态决策机制

当多个健康指标状态冲突时，系统按照以下逻辑决策最终状态：

按status.order定义顺序检查
遇到第一个匹配的非UP状态即终止判断
全部通过则返回UP状态

这种机制允许根据业务重要性灵活调整不同组件的健康影响权重。

生产环境建议

关键组件采用自定义健康指标
合理设置状态优先级顺序
通过show-details控制敏感信息暴露
结合Kubernetes的liveness/readiness探针使用
对核心组件实现降级处理逻辑

Spring Boot Actuator核心价值总结

Spring Boot Actuator作为Spring生态中的生产级监控组件，通过标准化端点暴露、细粒度健康检查和灵活的安全控制三大核心机制，为现代化应用提供了开箱即用的运维能力支撑。

端点暴露体系

Actuator采用分层式端点设计，通过management.endpoints.web.exposure属性实现精确控制：

properties 复制代码

# 暴露核心监控端点
management.endpoints.web.exposure.include=health,info,metrics
# 排除敏感端点
management.endpoints.web.exposure.exclude=env

这种设计既保证了基础监控需求，又能防止敏感信息泄露。端点路径支持自定义前缀，便于与企业现有监控体系集成：

properties 复制代码

management.endpoints.web.base-path=/monitor

健康检查机制

健康检查系统采用模块化设计，具有以下特点：

多级状态聚合 ：通过status.order定义状态优先级

properties 复制代码

management.endpoint.health.status.order=critical,warning,up

内置指标丰富：包含数据库、磁盘、中间件等20+健康指标
业务状态扩展：支持自定义健康指示器

java 复制代码

@Component
public class PaymentHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        return checkPaymentGateway() ? 
            Health.up().build() : 
            Health.down().withDetail("error", "支付通道不可用").build();
    }
}

安全审计体系

通过与Spring Security深度集成，提供完整的审计跟踪能力：

java 复制代码

@Bean
public SecurityFilterChain actuatorSecurity(HttpSecurity http) {
    http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/actuator/**").hasRole("MONITOR")
        .requestMatchers("/actuator/shutdown").hasRole("ADMIN"));
    return http.build();
}

审计事件自动记录认证、授权等关键操作，支持自定义事件处理：

java 复制代码

@EventListener
public void handleAuditEvent(AuditApplicationEvent event) {
    auditService.record(event.getAuditEvent());
}

生产实践建议

端点暴露：按最小权限原则控制端点可见性
健康检查：关键业务组件实现自定义HealthIndicator
安全配置：结合企业安全规范启用HTTPS和角色控制
监控集成：通过Micrometer对接Prometheus等监控系统

以下代码展示了一个完整的生产就绪配置示例：

properties 复制代码

# 端点配置
management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=when_authorized

# 安全配置
management.endpoint.health.roles=OPS
management.server.port=9091
management.server.ssl.enabled=true

# 健康检查
management.endpoint.health.status.order=critical,maintenance,up

Spring Boot Actuator通过这种模块化、可扩展的设计，在保持轻量级的同时满足了企业级应用的监控需求，是构建云原生应用不可或缺的基础组件。