当前位置：首页 > news >正文

完整教程：Spring Boot Actuator全解析

news 2026/3/27 5:40:47

什么是 Spring Boot Actuator？

Actuator（执行器） 是一个工程术语，指的是能通过小动作控制大系统的机械装置。
在 Spring Boot 中，“Actuator” 比喻为：让你通过简单的接口（如 HTTP 请求）来观察或操作你的应用系统。

✅ 简单理解：

就像汽车上的仪表盘（显示速度、油量等）+ 控制按钮（重启、关机等）
Spring Boot Actuator 就是你应用的“监控面板”，可以查看健康状况、内存使用、请求日志、数据库迁移情况等等。
它还支持远程操作，比如优雅关闭服务。

如何启用 Actuator？

只需要添加一个依赖即可开启所有功能。

Maven：

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

Gradle：

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

添加后，Spring Boot 会自动配置一系列“端点”（endpoints），你可以通过它们获取信息或执行命令。

️ 什么是 Endpoints（端点）？

Endpoint = 一种可访问的 API 接口，用来获取应用内部信息或执行操作

例如：

/actuator/health → 查看应用是否正常
/actuator/metrics → 查看 CPU、内存、HTTP 请求统计
/actuator/env → 查看当前环境变量和配置

内置常见端点说明（摘录重点）：

端点 ID	功能
`health`	应用健康检查（数据库连通性、磁盘空间等）✅ 默认暴露
`info`	显示自定义项目信息（版本号、作者等）✅ 默认暴露
`metrics`	展示性能指标（JVM、GC、线程数等）
`env`	查看所有环境变量和配置属性（敏感！）
`beans`	列出 Spring 容器中所有的 Bean
`mappings`	查看所有 URL 路由映射（@RequestMapping）
`loggers`	动态调整日志级别（比如把某类的日志从 INFO 改成 DEBUG）
`threaddump`	获取线程快照（排查死锁问题）
`heapdump`	下载堆内存快照（用于分析内存泄漏）
`shutdown`	关闭应用 ❌ 默认禁用（太危险）

⚠️ 注意：不是所有端点都默认对外公开！出于安全考虑，很多只允许 JMX 访问或完全关闭。

如何启用/禁用某个端点？

默认情况下，除了 shutdown 外，其他端点都是 启用状态（enabled），但不一定对外暴露。

示例：启用 shutdown 端点

management.endpoint.shutdown.enabled=true

更安全的做法：默认全关，按需开

# 先关闭所有端点
management.endpoints.enabled-by-default=false
# 只打开 info
management.endpoint.info.enabled=true

类比：家里门窗默认锁着，只留一扇窗户透气。

如何暴露端点？（让外部能访问）

即使启用了端点，也不代表可以通过 HTTP 访问。需要显式“暴露”。

默认暴露规则（Web）：

只有两个端点默认可通过 HTTP 访问：

health
info

端点	是否默认暴露给 Web？
health	✅ 是
info	✅ 是
其他大多数	❌ 否

修改暴露策略（关键配置）

配置项：

management.endpoints.web.exposure.include=xxx     # 要暴露哪些
management.endpoints.web.exposure.exclude=xxx     # 不暴露哪些（优先级更高）

示例 1：暴露所有端点（危险！仅限内网测试）

management.endpoints.web.exposure.include=*

⚠️ 注意：YAML 文件中星号要加引号：

management:
endpoints:
web:
exposure:
include: "*"

示例 2：暴露除 env 和 beans 外的所有端点

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

✅ 推荐做法：开放有用的（如 metrics、health），隐藏敏感的（env、beans）

如何保护 HTTP 端点？（防止未授权访问）

如果你的应用部署在公网，绝对不能直接暴露所有端点！

如果集成了 Spring Security：

Actuator 会自动受到保护。默认策略是：必须登录且有权限才能访问。

自定义安全规则（推荐）：

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
// 匹配所有 actuator 端点请求
http.requestMatcher(EndpointRequest.toAnyEndpoint())
.authorizeRequests((requests) ->
requests.anyRequest().hasRole("ENDPOINT_ADMIN") // 需要特定角色
)
.httpBasic(); // 使用 Basic Auth 登录
}
}

✅ 效果：只有拥有 ENDPOINT_ADMIN 角色的用户才能访问任何 /actuator/* 接口。

特殊情况：内网部署，无需认证

@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint())
.authorizeRequests()
.anyRequest().permitAll(); // 所有人可访问
}

⚠️ 仅适用于防火墙后的可信网络！

⏱️ 如何配置端点缓存？

有些端点数据变化不频繁（如 beans 列表），没必要每次请求都重新计算。

可以设置缓存时间，提升性能。

示例：缓存 `beans` 端点结果 10 秒

management.endpoint.beans.cache.time-to-live=10s

✅ 好处：减少重复查询开销
❗注意：如果动态修改了 Bean，可能看到的是旧数据（直到缓存过期）

总结：如何正确使用 Actuator？

步骤	建议
1. 引入依赖	添加 `spring-boot-starter-actuator`
2. 开放必要端点	如 `health`, `info`, `metrics`
3. 关闭不必要端点	如 `env`, `beans`, `shutdown`
4. 设置暴露范围	生产环境不要 `include=*`
5. 加强安全防护	结合 Spring Security，限制访问权限
6. 配置 info 信息	在 `application.properties` 中添加：

info.app.name=MyApp
info.app.version=1.0.0
info.java.version=@java.version@

实际应用场景举例

场景	使用哪个端点
监控服务是否存活	`GET /actuator/health`
查看 JVM 内存使用	`GET /actuator/metrics/jvm.memory.used`
动态调高日志级别排查问题	`POST /actuator/loggers/com.example.service` 设置 level=DEBUG
Prometheus 监控集成	`GET /actuator/prometheus`（需引入 micrometer）
排查线程阻塞	`GET /actuator/threaddump`
分析内存溢出	下载 `GET /actuator/heapdump` 并用 MAT 工具分析