Spring Boot Actuator 是每个 Java 后端工程师都应该掌握的生产观测利器。它用一套标准化端点（endpoint）把应用的健康检查、运行时指标、线程与内存状态直接暴露出来，让你不用登录服务器就能掌握生产应用的健康状况。本文从依赖接入讲起，带你把 Actuator 的健康端点与指标端点真正用在生产环境。
一、为什么生产环境离不开 Actuator
没有可观测性，线上出问题只能靠猜。传统做法是在服务器上敲 top、翻日志、连 JVM 做 thread dump，效率低且需登录生产机。Actuator 把这些信息变成 HTTP 端点：探针能问 /actuator/health 判断应用是否就绪，监控能定时抓取 /actuator/prometheus 拉走指标，排障能直接拿到 /actuator/threaddump。K8s 的 readiness/liveness 探针、Prometheus、Grafana 都依赖它，是云原生可观测链路的入口。
二、三步接入 Actuator
只需引入 starter 并显式暴露你需要的端点。默认只开 health 与 info，其余按需开启。
1. 引入依赖
<!-- Maven -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
# Gradle
implementation 'org.springframework.boot:spring-boot-starter-actuator'2. 暴露端点配置
management:
endpoints:
web:
exposure:
include: health,info,metrics,prometheus
endpoint:
health:
show-details: when_authorized
probes:
enabled: true
info:
env:
enabled: true三、核心端点速查
| 端点 | 默认暴露 | 作用 |
|---|---|---|
| /actuator/health | 是 | 应用与下游依赖健康状态 |
| /actuator/info | 是 | 构建版本、Git、环境信息 |
| /actuator/metrics | 否 | JVM/HTTP/Tomcat 等运行时指标 |
| /actuator/prometheus | 否 | Prometheus 拉取格式指标 |
| /actuator/threaddump | 否 | 线程快照，定位阻塞/死锁 |
| /actuator/loggers | 否 | 运行时动态调整日志级别 |
四、自定义健康检查 health 端点
默认 health 只查磁盘与数据库。当订单服务、第三方 API 等下游挂掉时，你希望探针立刻变红，这就需自定义 HealthIndicator。
@Component
public class OrderServiceHealthIndicator implements HealthIndicator {
private final OrderClient orderClient;
public OrderServiceHealthIndicator(OrderClient orderClient) {
this.orderClient = orderClient;
}
@Override
public Health health() {
try {
orderClient.ping();
return Health.up()
.withDetail("orderService", "reachable")
.build();
} catch (Exception e) {
return Health.down()
.withDetail("error", e.getMessage())
.build();
}
}
}更进一步，用分组把探针拆成 readiness（依赖就绪）与 liveness（进程存活），让 K8s 在依赖故障时重启流量而非杀容器：
management:
endpoint:
health:
group:
readiness:
include: db,redis,orderService
liveness:
include: diskSpace五、指标端点 metrics 与 Micrometer
Actuator 的指标底层是 Micrometer。系统指标（JVM 内存、GC、HTTP 请求量）开箱即用；业务指标则需用 MeterRegistry 注册。关于把指标接进监控面板，可参考站内 Prometheus + Grafana 监控面板实战。
@Autowired
private MeterRegistry registry;
private final Counter orderCounter = Counter.builder("orders.created")
.tag("channel", "web")
.register(registry);
public void createOrder(Order o) {
orderCounter.increment(); // 每笔订单 +1，Grafana 里画 QPS
// ...业务逻辑
}六、把指标喂给 Prometheus + Grafana
引入 Prometheus 注册表后，/actuator/prometheus 会输出符合抓取协议的文本，Prometheus 定时 pull 即可。
<!-- Maven -->
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
# prometheus.yml
scrape_configs:
- job_name: 'spring-boot'
metrics_path: '/actuator/prometheus'
static_configs:
- targets: ['app:8080']配合 Prometheus + Grafana 监控面板实战 即可搭建 JVM、HTTP 延迟、订单 QPS 的实时看板，告警也能直接落到指标上。
七、生产安全：别把端点裸奔
Actuator 端点一旦公网暴露，/actuator/env、/shutdown 会成重大隐患。务必放在内网、加鉴权、按需暴露。鉴权方案可复用站内 Spring Security 认证授权与 JWT 实战。
management:
endpoints:
web:
exposure:
include: health,info,metrics,prometheus
endpoint:
health:
probes:
enabled: true
server:
port: 9091 # 独立管理端口，不对外
# Spring Security 放行策略
@Bean
SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
http.authorizeHttpRequests(a -> a
.requestMatchers("/actuator/health/**").permitAll()
.requestMatchers("/actuator/**").hasRole("ACTUATOR")
.anyRequest().authenticated());
return http.build();
}八、优雅停机与探针协作
发布重启时，先让 readiness 探针变红摘流量，再停进程，可做到用户零感知。具体停机姿势见站内 Graceful Shutdown 优雅停机与无损下线；Actuator 的 readiness 分组正是 K8s 滚动发布时摘流量的信号源。
九、高频排坑清单
| 现象 | 原因 | 解法 |
|---|---|---|
| 端点访问 404 | 未加入 exposure.include | 在 include 中追加端点名 |
| health 一直 UP 但下游已挂 | 未实现自定义 Indicator | 实现 HealthIndicator 并注册 bean |
| 看不到自定义指标 | 指标没绑定 MeterRegistry | 用注入的 registry 注册 Counter/Timer |
| Prometheus 拉不到数据 | 缺 micrometer-registry-prometheus | 加依赖并暴露 prometheus 端点 |
| show-details 不显示 | 未授权访问 | show-details 设为 when_authorized 并带凭证 |
十、小结
Spring Boot Actuator 是生产可观测的基石：health 端点对接 K8s 探针、metrics 端点喂给 Prometheus、自定义 Indicator 与 Meter 让业务可见。记住三件事——按需暴露、内网鉴权、指标接入监控大盘，你就能在故障发生前看见苗头，在发布时做到无损。与它搭配的线程池调优可看 Spring Boot 异步线程池 @Async 配置与避坑，链路追踪见 OpenTelemetry 链路追踪实战。
十、/actuator/info 暴露构建与 Git 信息
运维排障时常需要确认线上跑的是哪个版本、哪次提交。/actuator/info 能聚合构建信息：接入 spring-boot-starter-actuator 后，再引入 info-maven 或 git-commit-id-plugin，启动后即可看到 artifact 版本、构建时间，以及 Git 分支与 commitId。把它接入内部发布系统，故障时一眼就能核对“生产到底部署了哪份代码”，避免多人各执一词。
management:
info:
git:
mode: full
build:
enabled: true
# 效果：/actuator/info 返回
# {"git":{"branch":"main","commit":{"id":"a1b2c3d"}},
# "build":{"version":"1.4.2","timestamp":"2026-09-20"} }十一、用 Timer 统计接口延迟分布
Counter 只能计数，要衡量性能必须看分布。Timer 记录每次调用的耗时，并自动产出分位数（p50/p95/p99），是接口 SLA 的硬指标。把它包在业务方法外层，Prometheus 抓取后就能在 Grafana 画出延迟热力。
private final Timer orderTimer = Timer.builder("orders.latency")
.tag("api", "create").register(registry);
public Order createOrder(Order o) {
return orderTimer.recordCallable(() -> orderService.save(o));
}十二、排坑之外：把观测做成习惯
Actuator 不是“接上就完事”的开关，而是可观测文化的入口。建议把 health 探针纳入 CI 冒烟（部署后自动 curl 校验 200）、把核心指标纳入值班大盘与告警，并把自定义 Indicator 当作新增外部依赖的标配。当每一次发布都能用数据说话，线上事故的平均修复时间（MTTR）会显著下降——这正是可观测性投入最值得的回报。
