Spring Boot Actuator 接入与运维实践指南

摘要：Actuator 为 Spring Boot 应用提供统一的健康检查、指标与运行态信息入口。本文说明 Maven 依赖、YAML 配置、端点暴露、HTTP 接口观测（http.server.requests）、健康检查、敏感信息脱敏、安全与排障要点，适用于 Spring Boot 2.4.x 及相近版本。

关键词：Spring Boot、Actuator、健康检查、Metrics、HTTP 指标、运维

1. 适用场景

负载均衡或容器编排需要 HTTP 健康探针 （如 /actuator/health）
需要 JVM 与 Web 请求指标 （如 /actuator/metrics）
需要按 URI / 方法 查看单个 HTTP 接口的调用与耗时（http.server.requests）
线上排障需要查看 配置项来源 （/actuator/env），并避免敏感值明文外泄
需要将 管理端点 与业务流量在端口或网络上拆分

2. 依赖引入

在业务模块 pom.xml 中增加：

xml 复制代码

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

说明：

引入该依赖后，Actuator 相关 Bean 由自动配置注册
是否通过 HTTP 访问、开放哪些端点，由 management.endpoints.web.exposure.include 等属性决定，与「是否引入依赖」相互独立

3. 最小可用配置

在 application.yml 或 bootstrap.yml（以实际生效的配置为准）中加入：

yaml 复制代码

management:
  endpoints:
    web:
      base-path: /actuator
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: never

配置项	作用
`management.endpoints.web.base-path`	管理端点前缀，一般为 `/actuator`
`management.endpoints.web.exposure.include`	允许通过 Web 访问的端点白名单
`management.endpoint.health.show-details`	健康详情展示策略；`never` 最保守

验证：

bash 复制代码

curl -s http://localhost:8080/actuator
curl -s http://localhost:8080/actuator/health
curl -s http://localhost:8080/actuator/metrics

将 8080 替换为 server.port 的实际值。

4. 端点暴露规则

4.1 注册与 HTTP 暴露

多数端点在引入 Actuator 后会注册
只有通过 exposure.include 声明的端点（或通配）才会映射到 HTTP

临时开放 env 用于排障时（建议仅内网）：

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env

需要查看路由注册信息时，将 mappings 加入同一列表。

通配暴露（风险高，仅建议隔离网络或本地调试）：

yaml 复制代码

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

4.2 管理端口与业务端口分离

yaml 复制代码

management:
  server:
    port: 18080

业务仍使用 server.port；管理端点使用 management.server.port，便于防火墙与网关分别策略。

5. 健康检查：`/actuator/health`

负载均衡探针：使用聚合结果 UP / DOWN 即可
启用多个 HealthIndicator 时，应了解健康状态的 聚合规则

yaml 复制代码

management:
  endpoint:
    health:
      show-details: never

show-details 常见取值：never、when_authorized、always（以后者为准请查阅所用 Boot 版本文档）。生产环境建议使用 never 或 when_authorized。

6. 指标：`/actuator/metrics`

前提：exposure.include 中包含 metrics。

Actuator 提供：

GET /actuator/metrics：列出指标名
GET /actuator/metrics/{metricName}：查询指定指标

6.1 按指标名查询

bash 复制代码

curl -s http://localhost:8080/actuator/metrics
curl -s "http://localhost:8080/actuator/metrics/jvm.memory.used"

6.2 监测单个 HTTP 接口（`http.server.requests`）

在 Spring Web 应用（如 Spring MVC）中，通常存在 http.server.requests 指标，按 URI、HTTP 方法、状态码等维度统计。

先查看该指标下已有 tag 与测量项：

bash 复制代码

curl -s "http://localhost:8080/actuator/metrics/http.server.requests"

再使用 tag 查询参数过滤到具体接口（多个 tag 为 AND；uri 须与实际路径一致，注意 URL 编码）：

bash 复制代码

curl -s "http://localhost:8080/actuator/metrics/http.server.requests?tag=uri:/api/example&tag=method:GET"

响应中的 measurements 通常包含 COUNT、TOTAL_TIME 等（随版本与配置略有差异）。

注意：

某路径 未被请求过 时，可能不会出现对应 uri 的 tag 组合
若列表中指标名不同，可在 /actuator/metrics 返回中搜索含 http 的指标名后再查
更完整的耗时分布（百分位等）依赖 management.metrics.distribution 等配置，需单独查阅官方文档

6.3 路由与 Handler：`/actuator/mappings`

在 exposure.include 中加入 mappings 后：

bash 复制代码

curl -s "http://localhost:8080/actuator/mappings"

在返回的 JSON 中按业务路径搜索，可确认 URL 对应的 Controller 方法 与 HTTP 谓词。

目的	使用方式
调用量、总耗时等运行时统计	`/actuator/metrics/http.server.requests` 及 `tag` 参数
URL 与 Java Handler 的映射关系	`/actuator/mappings` 中搜索路径

OpenAPI / Swagger / Knife4j 负责 接口文档（入参、出参、模型说明），与 Actuator 职责不同。

7. `/actuator/env` 与敏感信息脱敏

/actuator/env 用于查看配置键值及其 PropertySource，便于确认配置来源。

对 password、secret、token、key 等键名，返回值会被脱敏（如 **），属默认安全行为。

扩展脱敏键名模式示例：

yaml 复制代码

management:
  endpoint:
    env:
      keys-to-sanitize: password,secret,key,token,.*credentials.*

生产环境不宜为查看明文而缩小脱敏范围；敏感配置应走密钥系统或受控的配置中心权限。

8. 安全建议

8.1 缩小暴露范围

生产环境可优先仅开放：

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        include: health,info

确有监控需求时再增加 metrics 等。env、heapdump、threaddump 等应默认关闭或严格鉴权后再开放。

8.2 网络与网关

管理端口或 /actuator/** 应限制在内网或可审计通道
对外网关不应将 Actuator 路径暴露到公网路由

8.3 与 Spring Security 集成

对 /actuator/** 单独配置匹配规则：例如放行 health、info，其余要求认证与授权。具体 API 以当前工程使用的 Spring Security 版本文档为准。

9. 配置不生效时的排查顺序

实际加载顺序：bootstrap.yml 与 application.yml，以及是否启用远程配置
配置中心是否覆盖同名 management.*
spring.profiles.active 是否指向其他 profile 专属文件
环境变量、JVM -D 参数（如 MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE）
依赖中的 application.properties / 自动配置是否写入默认值
使用 /actuator/env 查看目标键的 propertySources 定位来源

10. Prometheus 指标导出（独立步骤）

Actuator 不依赖 Prometheus。仅当采集端需要 Prometheus 文本格式 时，增加依赖：

xml 复制代码

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

并在 exposure.include 中加入 prometheus：

yaml 复制代码

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus

验证：

bash 复制代码

curl -s http://localhost:8080/actuator/prometheus

未引入上述依赖时，通常不存在 /actuator/prometheus 端点。

11. 上线前检查清单

exposure.include 已按环境收敛
健康检查 URL 与端口已与负载均衡或编排配置对齐
管理端点已做网络隔离或网关限制
若开放 env：已确认脱敏与访问控制
已核对远程配置与环境变量无意外覆盖

12. 结语

Actuator 落地需同时约定：依赖范围、HTTP 暴露列表、网络与鉴权。不同环境（开发、测试、生产）宜使用不同暴露策略，避免在生产使用与开发相同的宽松配置。

Spring Boot Actuator 接入与运维实践指南