Spring Boot Actuator 端点配置详解

🔧 Spring Boot Actuator 端点配置详解

在 Spring Boot 2.x 及以上版本 中，Actuator 引入了 “启用（Enabled）” 和 “暴露（Exposed）” 两个独立的概念，二者缺一不可，才能通过 HTTP 或 JMX 访问端点。

✅ 1. 启用（Enable） vs 暴露（Expose）

概念	说明
启用（Enabled）	控制端点是否在应用内部被激活。如果未启用，即使暴露也无法访问。
暴露（Exposed）	控制已启用的端点是否通过 HTTP 或 JMX 公开对外访问。

📌 类比理解：

• 启用 = 灯泡是否通电（内部功能是否可用）
• 暴露 = 开关是否打开（外部能否看到灯光）

---

📌 2. 配置方式（YAML 示例）

（1）暴露端点（通过 HTTP 或 JMX）

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env        # 暴露指定的 HTTP 端点
        # include: "*"                          # 暴露所有 HTTP 端点（慎用！）
    jmx:
      exposure:
        include: "*"                             # 暴露所有 JMX 端点

⚠️ 注意：

• web.exposure.include 控制 HTTP 访问
• jmx.exposure.include 控制 JMX 访问
• 默认只暴露 health 和 info

（2）排除某些端点

management:
  endpoints:
    web:
      exposure:
        include: "*"                    # 暴露所有
        exclude: env,beans,threaddump   # 但排除敏感端点

🔐 生产环境建议：避免暴露 env、beans、shutdown 等敏感端点。

---

🛠️ 3. 启用/禁用特定端点

即使某个端点被暴露，也必须先“启用”才能使用。

management:
  endpoint:
    health:
      enabled: true
    env:
      enabled: true
    shutdown:
      enabled: false   # 默认就是 false，防止误关闭
    metrics:
      enabled: true

📝 示例：你想使用 /actuator/shutdown 关闭应用，必须配置：

management:
  endpoint:
    shutdown:
      enabled: true
  endpoints:
    web:
      exposure:
        include: shutdown

---

🔄 4. 端点 ID 与路径映射

每个端点有一个 ID，默认路径为 /actuator/{id}。

端点 ID	默认 HTTP 路径
health	/actuator/health
info	/actuator/info
metrics	/actuator/metrics
env	/actuator/env

你可以自定义端点 ID 或路径前缀：

management:
  endpoint:
    base-path: /manage        # 修改基础路径 → /manage/health
  endpoints:
    web:
      base-path: /api          # 更细粒度控制（优先级更高）

---

🔐 5. 安全建议（生产环境必看）

风险点	建议
env 端点泄露配置	如数据库密码、密钥等
beans 泄露内部结构	可能被用于攻击分析
shutdown 可关闭服务	高危操作
所有端点未认证访问	任何人都可查看

推荐安全配置示例：

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
        # 不暴露 env, beans, shutdown, heapdump 等
  endpoint:
    shutdown:
      enabled: false

spring:
  security:
    user:
      name: ${ADMIN_USER:admin}
      password: ${ADMIN_PASSWORD:securePass123!}

配合 Spring Security 限制 /actuator/** 的访问权限。

---

🧪 6. 验证端点是否生效

启动应用后，可通过以下方式验证：

1. 访问 /actuator 查看已暴露的端点列表：

   GET http://localhost:8080/actuator
   

   返回 JSON 列出所有可用端点及其链接。

2. 检查日志：

   Exposing 3 endpoint(s) beneath base path '/actuator'
   

3. 使用命令行测试：

   curl http://localhost:8080/actuator/health
   

---

🧩 常见配置组合示例

✅ 开发环境（宽松）

management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: always

✅ 生产环境（安全）

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: when-authorized
    env:
      enabled: false
    beans:
      enabled: false
    shutdown:
      enabled: false

---

✅ 总结：端点配置三步法

1. 启用端点：management.endpoint.<id>.enabled=true
2. 暴露端点：management.endpoints.web.exposure.include=xxx
3. 保护端点：结合 Spring Security 或网络隔离（如内网访问）

🚀 黄金法则：
最小暴露原则 —— 只暴露必要的端点，尤其是生产环境！