SpringBoot Actuator监控端点详解，打造生产级应用健康检查

前言

在开发环境下，我们判断应用是否运行只要看控制台有没有报错就行。但在生产环境，应用部署在几台甚至几百台 Linux 服务器上，我们不可能每时每刻盯着日志。

更糟糕的是，有时候应用进程还在，但数据库连接池耗尽了 ，或者磁盘空间满了 ，此时应用处于"半死不活 "状态，无法处理请求，导致用户访问超时。
这就是为什么我们需要 Spring Boot Actuator 。它将生产环境的监控指标（健康状态、内存占用、线程数、HTTP 请求追踪等）标准化为 HTTP 接口，让运维和监控系统（如 Prometheus, Grafana）能实时感知应用状态。
本文将基于 Spring Boot 2.x/3.x ，结合 Mermaid 流程图，带你深入剖析 Actuator 的核心端点与实战配置。

一、 Actuator 架构全景

Spring Boot Actuator 的核心模块由三部分组成：

Endpoints ：具体的监控接口（如 /health, /metrics）。
Metrics：度量数据（如 JVM 内存使用率、HTTP QPS）。
Observability：可观测性（整合 Prometheus 等外部系统）。

1.1 请求处理链路图

当客户端请求 Actuator 端点时，内部的处理流程如下：
Spring Boot 应用
无权限
有权限
监控客户端

Prometheus/Shell/Zabbix
发送 HTTP 请求

/actuator/health
Servlet Filter
安全过滤器

判断是否有权限
返回 401/403
DispatcherServlet
Endpoint Mapping

寻找 Handler
HealthEndpoint
健康检查指标
DataSourceHealthIndicator
DiskSpaceHealthIndicator
RedisHealthIndicator
汇总健康状态

UP / DOWN
返回 JSON 响应

二、快速集成

首先，引入 spring-boot-starter-actuator 依赖。

xml 复制代码

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

配置暴露端点（默认只暴露 health 和 info）：

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        # * 代表暴露所有，生产环境建议只暴露 health, metrics, prometheus
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: always # 总是显示详细检查结果

启动应用后，访问 `http://localhost:8080/actuator`，你会看到所有可用的端点列表。

三、核心监控端点详解

Actuator 提供了十几个开箱即用的端点，以下是生产环境最常用的几个：

端点 ID	描述	敏感度
`/health`	应用健康状态（UP/DOWN）	默认不敏感
`/metrics`	应用指标（内存、线程、HTTP请求数）	敏感
`/info`	自定义应用信息（版本、作者）	不敏感
`/loggers`	查看和修改日志级别	敏感
`/env`	查看环境变量和配置属性	高敏感

3.1 健康检查

这是最重要 的端点。Kubernetes (K8s) 和负载均衡器通常通过它来判断是否转发流量。
请求示例： GET /actuator/health
默认响应：

json 复制代码

{
  "status": "UP"
}

如果开启了 show-details: always，它会显示详细的子状态：

json 复制代码

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 500107909120,
        "free": 419430430720,
        "threshold": 10485760,
        "path": "."
      }
    },
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid()"
      }
    }
  }
}

3.2 指标监控

访问 /actuator/metrics 会列出所有可用的指标名称。

例如查看 JVM 最大内存：
GET /actuator/metrics/jvm.memory.max

json 复制代码

{
  "name": "jvm.memory.max",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 2147483648
    }
  ],
  "availableTags": [ ... ]
}

四、实战：自定义健康检查

除了数据库、Redis 等中间件的自动检查，我们经常需要检查业务相关的资源 。

比如：系统是否连接了关键的第三方支付接口？或者某个本地缓存文件是否存在？

我们可以通过实现 HealthIndicator 接口来扩展。

4.1 自定义检查流程

implements
依赖
返回构建
<<interface>>
HealthIndicator
+health() : Health
PaymentHealthIndicator
-PaymentService service
+health() : Health
Health
+build() : Builder
+up() : Builder
+down() : Builder
+withDetail() : Builder
PaymentService

4.2 代码实现

假设我们需要检查支付接口是否正常：

java 复制代码

@Component
public class PaymentHealthIndicator implements HealthIndicator {
    @Autowired
    private PaymentService paymentService;
    @Override
    public Health health() {
        try {
            // 模拟检查第三方支付接口连通性
            boolean isAlive = paymentService.pingThirdParty();
            
            if (isAlive) {
                // 1. 健康状态
                return Health.up()
                        // 2. 添加详细信息
                        .withDetail("channel", "Alipay")
                        .withDetail("latency", "23ms")
                        .build();
            } else {
                return Health.down().withDetail("error", "支付网关连接超时").build();
            }
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

重启应用后，再次访问 /actuator/health，你会看到 payment 组件的状态：

json 复制代码

{
  "status": "UP",
  "components": {
    "payment": {
      "status": "UP",
      "details": {
        "channel": "Alipay",
        "latency": "23ms"
      }
    }
  }
}

五、生产级集成：Prometheus + Grafana

Actuator 自带的 metrics 格式只适合人工查看。如果做自动化监控，通常集成 Prometheus。

5.1 依赖与配置

引入 Prometheus 依赖 ：

xml 复制代码

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

配置 YAML ：

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        include: health,prometheus
  metrics:
    tags:
      application: ${spring.application.name}

访问端点 ：/actuator/prometheus
此时你会看到 Prometheus 格式的文本数据：

复制代码

# HELP jvm_memory_max_bytes The maximum amount of memory in bytes...
jvm_memory_max_bytes{application="demo-service",...} 2147483648

5.2 监控架构图

定期拉取数据
数据存储&报警
数据源
发送邮件/钉钉
Spring Boot App

/actuator/prometheus
Prometheus Server
AlertManager
Grafana 可视化
运维人员

六、总结

Spring Boot Actuator 是连接"开发"与"生产运维"的桥梁。

基础：引入 actuator 依赖，暴露 /health 端点，确保应用存活状态。
定制：实现 HealthIndicator，深度结合业务逻辑检查核心依赖。
进阶：配合 Prometheus 和 Grafana，实现全链路可视化监控和自动报警。
掌握了 Actuator，你的应用就不再是黑盒，而是一台透明、可观测的精密仪器！

SpringBoot Actuator监控端点详解，打造生产级应用健康检查