Spring Boot management endpoints 配置指南

理解 Actuator 端点暴露范围、健康检查、安全边界和排查步骤。

撰写与维护： ErickPang · 更新于： 2026-07-10

说明 Actuator management endpoints 的暴露范围、健康检查、安全边界和 YAML/Properties 配置方式。

management endpoints 是什么

Spring Boot Actuator 提供健康检查、指标、环境信息和运行状态等端点。开发和运维经常依赖 health、info、metrics 等端点确认服务是否正常。

这些端点很有用，但也有安全风险。不要在生产环境随意暴露 env、beans、configprops 等可能包含敏感信息的端点。配置时应区分本地调试、测试环境和生产环境。

常见暴露配置

Spring Boot 默认只通过 HTTP 暴露 health。生产环境应继续遵循最小暴露原则，只增加确实需要的端点，例如受控的 info；其他端点应放在内网或加认证保护。配置前先明确谁会访问这些端点，以及路径是否经过网关或鉴权。

如果端点访问不到，先确认是否引入了 spring-boot-starter-actuator，再检查 exposure.include、management.server.port 和应用上下文路径。

management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  endpoint:
    health:
      show-details: when_authorized

排查清单

端点配置不生效时，不要只看 YAML。还要确认依赖、profile、端口和安全配置。某些项目会把 management 端口和应用端口分开，也可能通过网关隐藏真实路径。

生产环境建议把 Actuator 配置作为发布检查项，尤其是暴露范围和 health 详情级别。

确认已引入 spring-boot-starter-actuator
确认 exposure.include 包含目标端点
确认 management 端口和 context path
确认安全配置没有拦截或误开放端点

include、exclude 与通配符

exposure.include 决定允许远程访问的端点集合，exposure.exclude 用于从集合中移除端点，而且 exclude 优先。YAML 中星号有特殊含义，如果本地排查时确实要使用通配符，必须写成字符串 "*"。

不要把 include: "*" 直接复制到生产环境。env、configprops、beans、loggers 等端点可能暴露配置结构或改变运行状态。即使已经接入 Spring Security，也应逐项确认访问规则，而不是把“需要登录”等同于“可以全部暴露”。

management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans,configprops"

验证路径、状态码和安全边界

默认 health 地址是 /actuator/health。若设置 management.endpoints.web.base-path、server.servlet.context-path 或独立 management.server.port，最终地址会变化。独立端口只改变监听位置，并不会自动提供身份认证或网络隔离。

本地验证时先访问 health，再访问一个未暴露端点。前者应返回健康 JSON；后者通常应返回 404。接入 Spring Security 后还要分别验证匿名请求和授权请求，确保需要保护的端点返回 401、403 或根本不对公网路由。

curl -i http://localhost:8080/actuator/health
curl -i http://localhost:8080/actuator/env

# expected: health is available; env is not exposed

官方依据与相关文章

Spring Boot Actuator 文档区分 endpoint 的 enabled、exposed 和 access。排查时不要只确认 Bean 存在，还要同时检查暴露配置与安全规则。

本站由 ErickPang 独立维护，与 Spring、JetBrains 或 Broadcom 无官方关联。