服务上线只是第一步，真正的挑战在于运行期间如何知道它是否健康、内存是否吃紧、接口响应是否变慢。Spring Boot Actuator 正是官方给出的答案，它以一系列HTTP端点的形式，把应用内部的运行时信息暴露出来，配合监控平台就能搭出一套完整的生产级监控体系。本文将从零开始，带你完成Actuator的引入、配置、自定义扩展以及与Prometheus、Grafana的整合。
一、Actuator 是什么，能监控哪些东西
Actuator 是 Spring Boot 的一个子模块，专门用于暴露应用自身的运行信息。所谓Actuator，中文可以理解为执行器，它会在应用启动时自动注册一批端点（Endpoint），每个端点对应一类监控数据。比如 /actuator/health 返回健康状态，/actuator/metrics 返回各项性能指标，/actuator/env 返回环境变量与配置属性。
在实际使用中，Actuator提供的端点大致可以分为四类。第一类是配置类，包括环境信息、Bean列表、配置属性映射；第二类是指标类，包括HTTP请求统计、JVM内存与GC、线程池、数据源连接池；第三类是控制类，比如优雅停机端点；第四类是审计与日志类，可以在线查看和调整日志级别。这些端点默认只开放健康检查这一个，其余都需要手动开启，这是出于安全考虑的默认设计。
需要注意的是，端点是否暴露分为两层控制：一层是是否启用（enabled），另一层是是否通过HTTP暴露（exposure）。一个端点只有同时满足这两个条件，才能通过HTTP访问到。理解这个两层机制，是后续排查端点访问不到问题的基础。
二、快速整合：依赖引入与基础配置
整合Actuator非常简单，只需在pom.xml中添加依赖。以Maven项目为例，引入spring-boot-starter-actuator即可，这个starter会自动装配所有必要的组件，包括Micrometer指标门面库：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>如果项目使用Gradle，则添加对应的implementation配置。引入依赖后启动应用，访问 http://127.0.0.1:8080/actuator/health，如果返回类似 {"status":"UP"} 的JSON，说明整合已经成功。
默认情况下只有health端点暴露，需要通过配置文件开放更多端点。在application.yml中可以这样写：
management:
endpoints:
web:
exposure:
include: health,info,metrics,env,threaddump
exclude: shutdown
endpoint:
health:
show-details: always
shutdown:
enabled: false其中 include 支持通配符 *，但强烈不建议在面向公网的服务上全量暴露，特别是env、heapdump这类可能泄露敏感信息的端点。如果确有需要，可以让Actuator监听独立的管理端口，与管理流量隔离：
management:
server:
port: 9090
endpoints:
web:
base-path: /manage这样业务请求走8080端口，监控请求走9090端口，配合防火墙规则只允许内网访问9090，安全性会大大提升。
三、健康检查深度解析与自定义扩展
health端点是使用频率最高的端点，它背后由一组HealthIndicator接口的实现类共同决定最终状态。Spring Boot自动配置了磁盘空间、数据源、Redis、RabbitMQ等常见组件的健康检查器，只要项目引入了对应的starter，它们就会自动生效。访问 /actuator/health 时可以看到各个组件的分项状态。
除了自带的检查器，业务系统往往需要自定义健康检查逻辑，比如检测关键远程服务是否可达、核心缓存是否正常。实现方式很简单，注册一个实现了HealthIndicator接口的Bean即可：
@Component
public class ThirdPartyHealthIndicator implements HealthIndicator {
@Override
public Health health() {
// 模拟检测第三方服务连通性
boolean available = checkRemoteService();
if (available) {
return Health.up()
.withDetail("service", "payment-api")
.withDetail("latency", "35ms")
.build();
}
return Health.down()
.withDetail("error", "connection timeout")
.build();
}
private boolean checkRemoteService() {
// 实际项目中这里发送探测请求
return true;
}
}这个自定义检查器会被自动纳入整体健康状态的计算，任何一个组件DOWN都会让整体状态变为DOWN，负载均衡器或Kubernetes的存活探针就能据此摘除异常实例。此外还可以自定义HealthAggregator的分组规则，把非核心组件的状态波动排除在整体判断之外，避免无关紧要的告警噪音。
四、指标采集与 Prometheus、Grafana 可视化
metrics端点底层依赖Micrometer，它相当于监控领域的SLF4J，为各种监控系统提供了统一的门面。要对接Prometheus，只需添加对应实现依赖：
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>同时在配置中暴露prometheus端点，应用就会在 /actuator/prometheus 输出Prometheus格式的文本指标数据，包括JVM内存使用、GC次数、Tomcat线程池、HTTP请求的计数与耗时分位数等。Prometheus服务端配置抓取任务后，即可周期性拉取这些数据。
业务侧也可以埋入自定义指标，例如统计订单创建的速率：
@Service
public class OrderService {
private final Counter orderCounter;
public OrderService(MeterRegistry registry) {
this.orderCounter = Counter.builder("business.order.created")
.description("订单创建总数")
.tag("app", "order-service")
.register(registry);
}
public void createOrder() {
// 创建订单的业务逻辑
orderCounter.increment();
}
}数据进入Prometheus之后，用Grafana配置数据源并导入官方的JVM、Spring Boot仪表盘模板，就能得到直观的曲线图。再配合Grafana的告警规则，比如当堆内存使用率连续五分钟超过百分之八十五、或接口P95耗时超过一秒时触发通知，一套从数据采集到告警闭环的监控体系就搭建完成了。
五、安全防护与常见踩坑
Actuator端点包含大量敏感信息，必须做好访问控制。常见做法有三种：一是独立管理端口配合网络隔离；二是引入spring-boot-starter-security，为 /actuator/** 路径配置角色认证；三是在网关层拦截外部对管理端点的请求。三种方式可以叠加使用，安全始终是监控体系的前提而不是可选项。
踩坑方面，最常见的问题是配置了include却仍然404，原因通常是端点被disable或Spring Security拦截了管理路径，排查时先确认端点是否出现在 /actuator 的列表返回中。另一个高频问题是health返回DOWN导致容器反复重启，往往是因为数据库或Redis网络波动被纳入了整体状态，解决办法是利用health group将非核心检查单独分组，让存活探针只关注核心组件。另外，在生产环境开启heapdump端点时要格外谨慎，生成堆转储文件会带来明显的停顿和磁盘占用。
总结一下，Actuator的价值在于把监控能力标准化了，从健康检查到指标采集再到外部系统对接，几乎不需要写多少代码。建议每个上线的Spring Boot应用都引入它，并结合独立管理端口、安全认证和可视化平台，让应用运行状态真正透明可控。
Spring Boot Actuator应用监控健康检查修改时间：2026-09-12 15:18:44