Spring Boot Actuator配置：暴露health与metrics端点

Spring Boot 2.x 对 Actuator 端点实施了更严格的安全默认策略——/actuator/health 仅返回基础 status，/actuator/metrics 完全不暴露，导致新项目一启动就遭遇 404，这并非配置失误，而是设计使然；要真正用好健康检查与指标监控，必须显式配置端点暴露规则（如 `management.endpoints.web.exposure.include`）、启用 Micrometer 指标注册、正确集成各类 HealthIndicator（尤其数据库等外部依赖），并在引入 Spring Security 后采用细粒度鉴权而非粗暴放行，稍有疏忽便会让监控失效、安全失守或诊断失真——掌握这些关键配置细节，才能让 Actuator 从“形同虚设”变为生产环境不可或缺的运维利器。

Spring Boot 2.x 默认不暴露 /actuator/health 和 /actuator/metrics

新项目启动后直接访问 /actuator/health 返回 404，不是配置错了，是 Spring Boot 2.x 起默认只暴露 /actuator/health（且仅限 status），/actuator/metrics 完全不暴露。这是安全策略变更，不是 bug。

必须显式配置暴露哪些端点，否则 Actuator 形同虚设：

• management.endpoints.web.exposure.include 控制哪些端点在 Web 层可见（如 health,metrics,info,threaddump）
• management.endpoint.health.show-details 决定健康检查是否返回详细信息（never / when_authorized / always）
• management.endpoints.web.base-path 可选，把所有端点前缀从 /actuator 改成别的（比如 /manage）

示例（application.yml）：

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

/actuator/metrics 返回空或 404？检查 Micrometer 是否生效

/actuator/metrics 列出指标名，/actuator/metrics/{name} 查具体值。但如果你看到空数组 [] 或 404，大概率是 Micrometer 没自动装配成功。

常见原因：

• 项目没引入 spring-boot-starter-actuator（必须有）
• 同时引入了旧版 spring-boot-starter-metrics（已废弃，冲突）
• 自定义了 MetricsRegistry 或 MeterRegistry Bean 但没正确注册（覆盖默认行为）
• JVM 指标（如 jvm.memory.used）需要 micrometer-registry-jvm，但 Spring Boot 2.2+ 已内置，无需额外引

验证方式：启动后 curl /actuator/metrics，应返回类似 {"names":["jvm.memory.max","process.uptime",...]}；若为空，检查 ApplicationContext 中是否存在 MeterRegistry Bean。

Health 端点返回 UP 但实际 DB 连不上？别漏掉 HealthIndicator

默认 /actuator/health 只检查应用自身状态（如是否启动完成），不会自动探测数据库、Redis、外部 HTTP 服务等依赖项。

要让健康检查反映真实依赖状态，得手动注册 HealthIndicator：

• Spring Boot 自动配置了 DataSourceHealthIndicator（只要 classpath 有 HikariCP 或 Tomcat JDBC）
• 但若用的是 Druid，需额外加 druid-spring-boot-starter，否则 DB 健康检查不生效
• 自定义检查（如调第三方 API）：实现 HealthIndicator 接口，health() 方法里抛异常会触发 OUT_OF_SERVICE
• 注意 management.endpoint.health.show-details 必须设为 when_authorized 或 always，否则下游组件的 status 不显示

Actuator 端点被拦截 401？别只配 security.ignore

加了 Spring Security 后，/actuator/** 默认被保护，访问 /actuator/health 返回 401。有人直接写 WebSecurityConfigurerAdapter 忽略整个 /actuator/**，这很危险。

更稳妥的做法是细粒度放行：

• Spring Boot 2.6+ 推荐用 SecurityFilterChain Bean 替代继承类
• 只放行必要端点，例如：requestMatchers("/actuator/health", "/actuator/info").permitAll()
• 敏感端点如 /actuator/env、/actuator/beans 必须鉴权，建议限定 IP 或走内部网络
• 如果用了 OAuth2，可配合 hasRole('ACTUATOR') 控制权限

暴露 /actuator/metrics 给监控系统时，别忘了加 Basic Auth 或反向代理层校验，否则等于把 JVM 内部状态公开。

细节容易被忽略：Actuator 的端点行为高度依赖 Spring Boot 版本、Micrometer 版本、以及你是否重写了任何 Endpoint 相关 Bean。改一个配置，可能影响全部端点的响应结构和权限逻辑。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~