在后端系统开发与运维中,监控管理是保障系统高可用与稳定运行的关键。无论是单体应用还是复杂的分布式架构,我们都需要一套标准化的方法来实时掌握系统的脉搏——健康状态、资源使用情况、业务指标等,以便快速定位问题、优化性能。
Spring Boot Actuator 作为 Spring Boot 生态提供的核心生产就绪组件,正好解决了这个问题。它提供了一套开箱即用的监控能力,无需大量重复造轮子,就能快速集成系统健康检查、指标收集、端点暴露等功能,是企业级 Spring Boot 应用构建可观测性的标准方案。
本文将从核心认知出发,结合配置详解与代码示例,全面解析 Actuator 在健康检查、指标收集及自定义端点等方面的使用方法,并分享生产级最佳实践,帮助你构建一套从单体到分布式都能灵活适配的监控体系。
一、核心认知:Spring Boot Actuator 是什么?
Spring Boot Actuator 是 Spring Boot 提供的一套生产级监控与管理组件。它基于 Spring 生态构建,核心目标是通过一系列标准化的端点(Endpoint),将系统的内部状态与运行指标暴露出来,方便开发者和运维人员实时洞察系统情况,甚至执行一些运维操作。
1. 核心价值与应用场景
Actuator 的核心价值在于 “开箱即用、标准化、可扩展”。你无需从零开始编写监控功能,就能快速实现以下关键场景:
- 系统健康检查:实时查看应用是否正常运行,为运维告警、容器编排(如 Kubernetes)提供健康探针依据。
- 运行指标收集:自动收集 JVM 内存、CPU 占用、HTTP 请求量、响应时间等核心指标,支撑性能分析与容量规划。
- 运维操作支持:提供动态调整日志级别、查看环境配置、优雅关闭应用等运维接口,降低日常运维成本。
- 自定义指标扩展:轻松集成 Prometheus、Grafana 等流行监控工具,同时允许你自定义业务指标(如订单量、支付成功率),实现业务与系统监控的一体化。
2. 核心组成部分
Actuator 的功能主要由端点(Endpoint)、指标收集器(Metric)、健康检查器(Health)三部分组成,它们协同工作,构成完整的监控体系:
- 端点(Endpoint):系统状态与操作的暴露入口,分为原生端点(如
/health, /info)和自定义端点,可通过 HTTP 或 JMX 方式访问。
- 指标收集器(Metric):负责收集系统运行指标(JVM、内存、HTTP请求)和自定义业务指标,支持计数器、Gauge、计时器等多种指标类型。
- 健康检查器(Health):检查应用所依赖的组件(如数据库、Redis、消息队列)的连接状态,并汇总为整体健康状态,支撑故障的快速定位。
3. 与第三方监控工具的适配
Actuator 本身并非一个完整的监控平台,而是一个强大的标准化数据出口。它可以无缝集成主流监控工具,构建端到端的监控链路,例如与 Prometheus 和 Grafana 的组合:
- 数据采集:Prometheus 通过 Actuator 暴露的端点(如
/actuator/prometheus)定期拉取指标数据。
- 可视化展示:Grafana 对接 Prometheus 数据源,将指标以丰富的图表形式展示在大屏上。
- 告警通知:结合 AlertManager 配置告警规则,在指标异常时通过邮件、钉钉等渠道发送通知。
- 日志分析:集成 ELK 栈,通过 Actuator 的
/loggers 端点动态管理日志级别,实现日志的集中分析与追踪。
二、基础集成与端点配置:Actuator 核心配置
集成 Spring Boot Actuator 非常简单,主要通过引入依赖和配置端点暴露规则来完成。以下是兼顾功能与安全的生产级基础配置方案。
1. 基础依赖引入
Spring Boot 2.x 与 3.x 版本的 Actuator 依赖配置基本一致,主要区别在于端点安全控制方面。版本号通常继承 Spring Boot Parent,无需单独指定。
Spring Boot 2.x 依赖
<!-- Spring Boot Actuator 核心依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- 若需通过 HTTP 访问端点,引入 Web 依赖(已引入则无需重复) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
Spring Boot 3.x 依赖
Spring Boot 3.x 对端点安全模型做了优化,依赖不变,但更建议显式引入安全依赖进行控制。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 3.x 版本若需进行安全控制,建议引入 Security 依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
2. 核心端点配置(application.yml)
Actuator 原生提供了数十个端点,但基于安全考虑,默认只暴露 /health 和 /info。生产环境必须遵循最小权限原则,按需暴露端点。
基础端点暴露配置
management:
endpoints:
# 端点暴露方式:web(HTTP 访问)、jmx(JMX 访问),生产环境主要用 web
web:
exposure:
# 暴露指定端点(推荐,最小权限原则)
include: health,info,metrics,prometheus,loggers
# 排除端点(若 include 为 * 时使用)
exclude: shutdown
# 开启所有原生端点(不推荐,存在安全风险)
# enabled-by-default: true
# 端点通用配置
endpoint:
# 健康检查端点配置
health:
# 显示详细健康信息(生产环境建议开启,便于故障排查)
show-details: always
# 开启健康检查分组(适配多依赖组件场景)
group:
# 自定义分组:db(数据库相关)
db:
include: db,redis
# 自定义分组:mq(消息队列相关)
mq:
include: rabbitmq,kafka
# 关闭指定端点(如 shutdown 端点,避免误操作)
shutdown:
enabled: false
# 指标相关配置
metrics:
# 启用 JVM 指标收集
enable.jvm: true
# 启用 HTTP 请求指标收集
enable.http.server.requests: true
# 指标命名规则(适配 Prometheus)
tags:
application: ${spring.application.name}
配置说明(生产级规范)
- 最小权限原则:
include 明确列出需要暴露的端点,避免使用 * 暴露所有,减少攻击面。
- 健康信息详情:
show-details: always 开启后,能直观看到数据库、缓存等每个依赖组件的具体状态。
- 禁用危险端点:
shutdown 端点可通过 HTTP 请求直接关闭应用,生产环境务必禁用。
- 指标标签:添加
application 标签,便于在 Prometheus 等监控系统中按应用维度聚合和查询指标。
3. 端点访问规则与安全控制
端点访问路径
Actuator 端点默认通过 HTTP 访问,路径前缀为 /actuator,完整格式为:http://{ip}:{port}/actuator/{endpoint-name}。
- 健康检查:
http://localhost:8080/actuator/health
- 指标收集:
http://localhost:8080/actuator/metrics
- 日志配置:
http://localhost:8080/actuator/loggers
安全控制(生产级必做)
Actuator 端点可能暴露 JVM 内存、线程堆栈、环境变量等敏感信息,生产环境必须添加访问控制。可通过 Spring Security 实现基础的权限校验。
简单安全配置示例(Spring Boot 3.x):
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
public class ActuatorSecurityConfig {
@Bean
public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
http
// 针对 Actuator 端点配置权限
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/**").hasRole("ADMIN") // 仅 ADMIN 角色可访问
.anyRequest().permitAll()
)
// 关闭 CSRF(若通过 POST 请求操作端点,如动态调整日志级别)
.csrf(csrf -> csrf.disable());
return http.build();
}
}
对于更严格的要求,可以结合企业统一认证中心(如 OAuth2)或配置 IP 白名单,仅允许运维网络内的特定主机访问。
4. 常用原生端点分类与功能
Actuator 原生端点按功能可分为健康检查、指标收集、运维操作三大类。
健康检查类端点
/actuator/health:核心健康检查端点,返回应用整体状态(UP/DOWN/OUT_OF_SERVICE)。开启详情后可查看各组件状态。
- 依赖组件支持:自动适配数据库(MySQL, PostgreSQL)、缓存(Redis)、消息队列(RabbitMQ, Kafka)等,检查其连接状态。
指标收集类端点
/actuator/metrics:查看所有可收集的指标列表(如 jvm.memory.used),可通过 ?name={metric-name} 查看具体指标详情。
/actuator/prometheus:以 Prometheus 预期的格式暴露指标,是集成可视化监控的核心端点。
运维操作类端点
/actuator/loggers:查看和动态调整日志级别(无需重启应用),支持按包名或类名设置。
/actuator/env:查看所有环境配置(配置文件、系统变量),敏感信息(如密码)会自动脱敏。
/actuator/info:查看应用自定义信息(如版本号、构建时间),需手动配置内容。
三、健康检查:Actuator 核心监控能力
健康检查是 Actuator 最核心的功能之一,它为容器平台(如 K8s)的存活探针、就绪探针以及运维监控提供了直接依据。
1. 原生健康检查(自动适配)
对于常见的技术组件,Actuator 提供了开箱即用的健康检查支持,引入对应依赖后即可自动生效:
- 数据库:MySQL、PostgreSQL、Oracle等(通过 Spring Data JPA/MyBatis 自动适配)。
- 缓存:Redis、EhCache、Caffeine等。
- 消息队列:RabbitMQ、Kafka、RocketMQ等。
- 外部服务:通过 RestTemplate/WebClient 调用的第三方接口(需手动配置检查逻辑)。
健康状态说明
Actuator 健康状态分为四级:
- UP:组件正常运行。
- DOWN:组件异常,影响应用功能。
- OUT_OF_SERVICE:组件不可用,但可能不影响核心功能。
- UNKNOWN:无法判断组件状态。
示例:数据库+Redis 健康检查响应
开启 show-details: always 后,访问 /actuator/health 会返回类似以下的详细JSON:
{
"status": "UP",
"components": {
"db": {
"status": "UP",
"details": {
"database": "MySQL",
"validationQuery": "SELECT 1"
}
},
"redis": {
"status": "UP",
"details": {
"version": "6.2.6"
}
},
"diskSpace": {
"status": "UP",
"details": {
"total": 107374182400,
"free": 53687091200,
"threshold": 10485760
}
}
}
}
2. 健康检查分组配置
当应用依赖众多组件时,可以通过分组功能,按业务维度(如数据层、消息层)查看健康状态,便于故障定位。
分组配置已在前面YAML中展示(management.endpoint.health.group)。访问分组健康状态的路径为:/actuator/health/{group-name}。
- 访问数据库分组:
http://localhost:8080/actuator/health/db
- 访问消息队列分组:
http://localhost:8080/actuator/health/mq
3. 自定义健康检查(业务组件适配)
对于 Actuator 未覆盖的自定义组件(如第三方支付接口、自研中间件),可以通过实现 HealthIndicator 接口(Spring Boot 2.x)或 HealthContributor 接口(Spring Boot 3.x)来扩展。
Spring Boot 3.x 自定义健康检查示例(检查第三方支付接口)
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthContributor;
import org.springframework.boot.actuate.health.NamedContributor;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import java.util.Iterator;
@Component
public class PaymentApiHealthContributor implements HealthContributor {
private final RestTemplate restTemplate;
// 第三方支付接口健康检查地址
private static final String PAYMENT_HEALTH_URL = "https://api.payment.com/health";
public PaymentApiHealthContributor(RestTemplate restTemplate) {
this.restTemplate = restTemplate;
}
@Override
public Health health() {
try {
// 调用第三方接口检查健康状态
String response = restTemplate.getForObject(PAYMENT_HEALTH_URL, String.class);
if ("OK".equals(response)) {
return Health.up()
.withDetail("payment-api", "第三方支付接口正常")
.withDetail("url", PAYMENT_HEALTH_URL)
.build();
} else {
return Health.down()
.withDetail("payment-api", "第三方支付接口异常")
.withDetail("response", response)
.build();
}
} catch (Exception e) {
return Health.down()
.withDetail("payment-api", "第三方支付接口调用失败")
.withDetail("error", e.getMessage())
.build();
}
}
@Override
public Iterator<NamedContributor<HealthContributor>> iterator() {
return java.util.Collections.emptyIterator();
}
}
配置完成后,访问 /actuator/health 的返回信息中就会自动包含 paymentApi 这个自定义组件的状态。
4. 健康检查生产级优化
超时控制
在自定义健康检查中调用外部接口时,务必设置合理的超时时间,避免因外部服务响应慢导致健康检查端点本身被阻塞。
// 为 RestTemplate 设置超时时间
@Bean
public RestTemplate restTemplate() {
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
factory.setConnectTimeout(1000); // 连接超时 1s
factory.setReadTimeout(1000); // 读取超时 1s
return new RestTemplate(factory);
}
故障隔离
如果某个非核心组件(如上面的支付接口)的健康检查失败,你或许不希望它导致整个应用的健康状态变为 DOWN。可以通过配置将其影响降级。
management:
endpoint:
health:
probes:
enabled: true
component:
# 忽略第三方支付接口健康状态对整体状态的影响,将其标记为 OUT_OF_SERVICE
paymentApi:
failure-status: OUT_OF_SERVICE
四、指标收集:系统与业务指标监控
Actuator 的指标收集能力不仅限于系统层面,更能轻松扩展至业务维度,是构建可观测性的数据基石。
1. 原生指标收集(开箱即用)
Actuator 自动收集以下核心系统指标,无需编码:
- JVM 指标:堆/非堆内存使用、线程数、GC 次数与耗时、类加载数量等。
- HTTP 指标:请求总数、成功率、各端点响应时间(平均、最大)、异常计数等。
- 系统指标:CPU 使用率、磁盘空间、系统负载等。
- 缓存指标:命中率、缓存大小、逐出次数等。
查看具体指标示例
访问 /actuator/metrics/jvm.memory.used,可查看 JVM 内存使用的详细数据:
{
"name": "jvm.memory.used",
"description": "The amount of used memory",
"baseUnit": "bytes",
"measurements": [
{
"statistic": "VALUE",
"value": 536870912
}
],
"availableTags": [
{
"tag": "region",
"values": ["heap", "non_heap"]
},
{
"tag": "application",
"values": ["order-service"]
}
]
}
2. 自定义业务指标(核心实战)
对于订单量、用户活跃数、接口调用次数等业务指标,可以通过 MeterRegistry 接口轻松定义。
常用指标类型说明
- 计数器(Counter):用于只增不减的指标,如订单创建次数、API调用总数。
- Gauge:用于反映瞬时值的指标,如当前在线用户数、队列中待处理的任务数。
- 计时器(Timer):用于记录耗时操作的指标,如接口响应时间、方法执行时长,自动计算分位数。
自定义业务指标示例(订单服务)
import io.micrometer.core.annotation.Timed;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import javax.annotation.PostConstruct;
import java.util.concurrent.atomic.AtomicInteger;
@Service
@RequiredArgsConstructor
public class OrderMetricService {
private final MeterRegistry meterRegistry;
private Counter orderCreateCounter; // 订单创建计数器
private AtomicInteger currentStock; // 库存数量(Gauge 指标)
// 初始化指标
@PostConstruct
public void initMetric() {
// 1. 初始化订单创建计数器(按订单类型标签区分)
orderCreateCounter = Counter.builder("order.create.count")
.description("订单创建总次数")
.tag("application", "order-service")
.tag("orderType", "online") // 在线订单
.register(meterRegistry);
// 2. 初始化库存 Gauge 指标(模拟商品库存)
currentStock = new AtomicInteger(1000);
Gauge.builder("product.stock.count", currentStock, AtomicInteger::get)
.description("商品当前库存数量")
.tag("productId", "1001")
.register(meterRegistry);
}
// 订单创建成功后,计数器递增
public void incrementOrderCreateCount() {
orderCreateCounter.increment();
}
// 更新库存(Gauge 指标动态变化)
public void updateStock(int count) {
currentStock.addAndGet(-count); // 库存减少
}
// 3. 计时器指标(统计订单处理耗时,通过注解方式)
@Timed(value = "order.process.time", description = "订单处理耗时", percentiles = {0.5, 0.95, 0.99})
public void processOrder(String orderNo) {
// 订单处理业务逻辑(模拟耗时)
try {
Thread.sleep(100);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
}
指标使用说明
- 计数器递增:在订单创建成功的方法里调用
incrementOrderCreateCount(),指标值自动累加。
- Gauge 动态更新:业务逻辑中调用
updateStock(),product.stock.count 指标会实时反映最新库存。
- 计时器注解:
@Timed 注解自动统计 processOrder 方法的执行耗时,并计算中位数、P95、P99等分位数值,对性能分析极有帮助。
3. 指标对接 Prometheus 与 Grafana
将 Actuator 的指标接入可视化监控体系是标准做法,步骤如下:
- 开启 Prometheus 端点:在配置
management.endpoints.web.exposure.include 中添加 prometheus。
- 配置 Prometheus 抓取:在
prometheus.yml 中添加一个 scrape_configs 任务,目标指向应用的 /actuator/prometheus 端点。
- Grafana 可视化:添加 Prometheus 数据源,然后可以导入丰富的社区仪表盘模板或自定义创建图表,实时展示 JVM、HTTP、业务等各类指标。
五、自定义监控端点:业务场景适配扩展
当原生端点无法满足特定需求时,你可以创建自定义端点,暴露任意的业务信息或运维操作。
1. 自定义端点核心注解
自定义端点主要通过一组注解来定义,Spring Boot 2.x 和 3.x 通用:
@Endpoint(id = "custom"):定义端点,id 即端点名称(访问路径为 /actuator/custom)。
@ReadOperation:定义 GET 请求的处理方法,用于查询数据。
@WriteOperation:定义 POST 请求的处理方法,用于修改数据或触发操作。
@DeleteOperation:定义 DELETE 请求的处理方法。
2. 自定义端点示例
示例 1:查询订单统计信息(GET 端点)
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;
import java.time.LocalDate;
import java.util.HashMap;
import java.util.Map;
@Component
@Endpoint(id = "orderStats") // 自定义端点名称:orderStats
public class OrderStatsEndpoint {
// 模拟订单统计服务
private final OrderMetricService orderMetricService;
public OrderStatsEndpoint(OrderMetricService orderMetricService) {
this.orderMetricService = orderMetricService;
}
// GET 方式访问:/actuator/orderStats
@ReadOperation
public Map<String, Object> getOrderStats() {
Map<String, Object> stats = new HashMap<>();
stats.put("date", LocalDate.now());
stats.put("totalOrderCount", 1234); // 模拟当日总订单数
stats.put("totalSalesAmount", 234567.89); // 模拟当日总销售额
stats.put("paymentSuccessRate", 98.5); // 模拟支付成功率
return stats;
}
// 带参数的 GET 访问:/actuator/orderStats?orderType=online
@ReadOperation
public Map<String, Object> getOrderStatsByType(String orderType) {
Map<String, Object> stats = new HashMap<>();
stats.put("orderType", orderType);
stats.put("count", orderType.equals("online") ? 1000 : 234);
return stats;
}
}
访问 http://localhost:8080/actuator/orderStats 即可获取业务统计数据,方便运营或产品人员查看。
示例 2:手动触发订单重试任务(POST 端点)
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.stereotype.Component;
import java.util.HashMap;
import java.util.Map;
@Component
@Endpoint(id = "orderRetry")
public class OrderRetryEndpoint {
private final OrderService orderService;
public OrderRetryEndpoint(OrderService orderService) {
this.orderService = orderService;
}
// POST 方式访问:/actuator/orderRetry,执行订单重试任务
@WriteOperation
public Map<String, String> retryOrder(String orderNo) {
Map<String, String> result = new HashMap<>();
try {
orderService.retryFailedOrder(orderNo);
result.put("status", "success");
result.put("message", "订单重试任务触发成功,订单号:" + orderNo);
} catch (Exception e) {
result.put("status", "fail");
result.put("message", "订单重试任务触发失败:" + e.getMessage());
}
return result;
}
}
通过 POST 请求调用此端点,可手动触发特定失败订单的重试,无需登录服务器或重启应用,极大提升了运维效率。
3. 自定义端点生产级规范
- 权限控制:必须通过 Spring Security 等机制限制访问,防止未授权操作。
- 参数校验:对输入参数进行有效性校验,避免非法参数导致业务异常。
- 日志记录:记录端点的访问和操作日志,便于审计和问题追溯。
- 容错处理:方法内部做好异常捕获,返回结构化的错误信息,避免端点直接抛出异常导致500错误。
- 性能考量:避免在端点方法内执行耗时过长的同步操作,必要时可采用异步处理并返回任务ID。
六、生产级最佳实践与注意事项
将 Actuator 用于生产环境,以下几方面需要特别关注。
1. 安全防护(重中之重)
- 端点最小暴露:严格按需暴露端点,敏感端点如
env, beans, shutdown 必须禁用或严控。
- 多层安全控制:组合使用 Spring Security 角色校验、网络层 IP 白名单、以及启用 HTTPS 加密通信。
- 敏感信息脱敏:Actuator 已自动对
env, configprops 端点中的 password, secret, key 等字段进行脱敏(显示为 ******),无需额外配置。
2. 性能优化
- 端点缓存:对于查询逻辑复杂的自定义端点,考虑添加缓存(如Caffeine),避免每次请求都进行密集计算或数据库查询。
- 指标采样:在高并发场景下,评估是否所有指标都需要最高粒度。适当调整 Micrometer 的指标采样率可以降低内存和CPU开销。
- 异步执行:健康检查或自定义端点中的外部调用(如检查第三方服务),应使用异步方式或配置超时,防止阻塞HTTP线程。
3. 监控链路完善
- 对接可视化工具:强烈推荐将 Actuator 与 Prometheus + Grafana 组合,这是构建现代可观测性栈的标准做法。
- 日志与监控联动:当监控指标告警时,应能快速关联到对应时间点的应用日志(通过ELK等工具),形成排查闭环。
- 配置告警:针对核心健康状态、JVM 内存使用率 (>80%)、关键接口 P99 响应时间等配置告警规则,实现主动发现问题。
4. 版本兼容与升级
- Spring Boot 2.x 与 3.x 差异:主要差异在安全配置模型和少量端点路径上,升级时需测试并调整相关配置。
- 依赖版本统一:确保
spring-boot-starter-actuator 的版本与 Spring Boot 主版本一致,避免潜在的兼容性问题。
七、核心总结:Actuator 监控体系的核心价值
Spring Boot Actuator 以 “开箱即用、标准化、可扩展” 为核心优势,为 Spring Boot 应用提供了低成本的监控入门方案,并奠定了统一监控标准的基础。它的价值在于显著降低了从零构建监控功能的开发成本,并天然支持与主流生态工具集成,从而支撑运维自动化。
无论是基础的健康检查、丰富的指标收集,还是灵活的自定义监控端点,Actuator 都提供了清晰的扩展路径。通过与 Prometheus、Grafana、ELK 等工具链的结合,可以轻松构建从数据采集、可视化展示到智能告警的完整可观测性体系。
在生产中运用 Actuator,请始终秉持 “安全第一、按需配置、扩展灵活” 的原则:严格管理端点访问权限,根据实际监控需求精准配置,并充分利用其扩展能力适配各类业务场景。掌握好 Actuator,无疑是提升 Spring Boot 应用可观测性与可运维性的关键一步。如果你想了解更多关于 Java 后端开发与系统监控的实践,欢迎访问云栈社区与其他开发者交流探讨。