Spring Boot Actuator 入门详解

Spring Boot Actuator 入门详解

Spring Boot Actuator 是 Spring Boot 提供的一套生产级监控和管理功能的模块，它可以帮助开发者在应用运行时查看应用的内部状态、健康状况、指标信息等，极大地方便了应用的运维和调试。

---

一、Actuator 是什么？

Spring Boot Actuator 提供了多个端点（Endpoints），用于暴露应用的运行时信息，如：

• 应用健康状态（Health）
• 应用配置信息（Environment）
• 应用度量指标（Metrics）
• HTTP 请求追踪（HttpTrace）
• 线程信息（Threads）
• 日志配置管理
• 自定义监控信息等

这些信息可以通过 HTTP 或 JMX 的方式访问。

---

二、快速入门

1. 添加依赖

在 pom.xml 中添加 Actuator 依赖：

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

如果是 Gradle 项目：

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

---

2. 启动项目并访问端点

启动应用后，默认会暴露一些端点。默认情况下，只有 /health 和 /info 是开启的。

访问示例：

http://localhost:8080/actuator/health

注意：Spring Boot 2.x 之后，所有端点默认路径前缀为 /actuator。

---

三、常用端点说明

端点（Endpoint）	描述
/actuator/health	应用健康检查（可显示数据库、磁盘、Redis等状态）
/actuator/info	显示应用信息（如版本、构建信息）
/actuator/metrics	显示应用指标（如JVM内存、HTTP请求数等）
/actuator/env	显示当前环境变量和配置属性
/actuator/beans	显示所有Spring容器中的Bean
/actuator/mappings	显示所有@RequestMapping的映射路径
/actuator/httptrace	显示最近的HTTP请求追踪（需启用）
/actuator/threaddump	线程快照
/actuator/heapdump	生成堆转储文件（可用于分析内存泄漏）
/actuator/shutdown	关闭应用（默认关闭，需手动开启）

---

四、配置 Actuator 端点

在 application.yml 或 application.properties 中进行配置。

1. 暴露端点（重要）

默认只暴露 health 和 info，其他需要手动开启。

management:
  endpoints:
    web:
      exposure:
        include: "*"  # 暴露所有端点
        # include: health,info,metrics,env  # 或者指定部分
        # exclude: shutdown  # 可排除某些端点

⚠️ 生产环境慎用 include: "*"，建议只暴露必要的端点。

---

2. 自定义端点路径前缀

management:
  endpoint:
    base-path: /manage   # 默认是 /actuator

现在访问：http://localhost:8080/manage/health

---

3. 配置健康检查详细信息

management:
  endpoint:
    health:
      show-details: always  # always, never, when-authorized

• always：总是显示详细信息
• never：不显示
• when-authorized：授权用户才显示

---

4. 启用关闭端点（shutdown）

management:
  endpoint:
    shutdown:
      enabled: true

然后发送 POST 请求关闭应用：

curl -X POST http://localhost:8080/actuator/shutdown

---

五、自定义 Info 信息

在 application.yml 中添加：

info:
  app:
    name: My Application
    version: 1.0.0
    description: A sample Spring Boot app
  build:
    artifact: @project.artifactId@
    name: @project.name@
    version: @project.version@

注意：@project.xxx@ 需要 Maven 或 Gradle 支持资源过滤。

Maven 配置资源过滤：

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
        </resource>
    </resources>
</build>

访问 /actuator/info 即可看到自定义信息。

---

六、自定义 Actuator 端点

你可以创建自己的监控端点。

示例：自定义 /actuator/custom

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {

    @ReadOperation
    public Map<String, Object> getInfo() {
        return Map.of(
            "status", "OK",
            "message", "Custom endpoint is working!",
            "timestamp", System.currentTimeMillis()
        );
    }
}

访问：http://localhost:8080/actuator/custom

---

七、安全配置（推荐生产环境使用）

Actuator 端点包含敏感信息，建议配置安全访问。

使用 Spring Security 保护端点

添加依赖：

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

配置 application.yml：

spring:
  security:
    user:
      name: admin
      password: admin123

或者通过配置类：

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                .anyRequest().permitAll()
            )
            .httpBasic(); // 启用 Basic 认证
        return http.build();
    }
}

---

八、集成 Micrometer 与 Prometheus（监控指标）

Actuator 集成 Micrometer，支持将指标导出到 Prometheus。

1. 添加依赖

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

2. 暴露 metrics 和 prometheus 端点

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus

3. 访问 Prometheus 格式指标

http://localhost:8080/actuator/prometheus

可用于 Prometheus 抓取。

---

九、常见问题与最佳实践

1. 端点无法访问？

• 检查是否暴露了端点（management.endpoints.web.exposure.include）
• 检查路径是否正确（默认 /actuator/xxx）
• 是否有安全拦截？

2. 生产环境建议

• 不暴露所有端点（避免 include: "*"）
• 敏感端点（如 env、beans）限制访问
• 使用 HTTPS + 认证保护
• 将 /actuator 路径映射到内网或运维专用网关

3. 性能影响

• 大多数端点是轻量级的，但 heapdump、threaddump 会短暂影响性能
• 避免频繁调用

---

十、总结

功能	说明
健康检查	/health
应用信息	/info
指标监控	/metrics, /prometheus
配置查看	/env, /configprops
路由映射	/mappings
自定义端点	@Endpoint 注解
安全控制	结合 Spring Security
生产建议	限制暴露、权限控制、HTTPS

---

参考资料

• Spring Boot Actuator 官方文档
• Micrometer 官网
• Prometheus

---

✅ 小贴士：在微服务架构中，结合 Spring Boot Admin 可以图形化展示多个服务的 Actuator 信息，是运维监控的利器。