如何在 Spring Boot Actuator 中启用所有接口

1. 简介

在本教程中，我们将学习如何在 Spring Boot Actuator 中启用所有接口。我们会从 Maven 依赖开始讲起，接着介绍如何通过配置文件控制接口的暴露与启用，最后会简要说明如何对这些接口进行安全保护。

需要注意的是，Spring Boot 1.x 和 2.x 在 Actuator 接口的配置方式上有较大变化，本文将基于 Spring Boot 2.x 及以上版本进行讲解。

2. 环境准备

要使用 Actuator，首先需要在 pom.xml 中引入 spring-boot-starter-actuator 依赖：

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

⚠️ 从 Spring Boot 2.0 开始，**如果想通过 HTTP 访问这些接口，还必须引入 web starter**：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.1.2</version>
</dependency>

3. 启用和暴露接口

从 Spring Boot 2 开始，接口默认是启用但不暴露的。除了 /shutdown 外的所有接口都是启用状态，但只有 /health 和 /info 是对外暴露的。所有接口的访问路径都在 /actuator 下。

✅ 因此，在添加了上述依赖后，你可以通过以下地址访问这两个接口：

http://localhost:8080/actuator/health
http://localhost:8080/actuator/info

访问 http://localhost:8080/actuator 可以看到当前暴露的接口列表（因为 Actuator 接口支持 HATEOS）：

{"_links":{"self":{"href":"http://localhost:8080/actuator","templated":false},
"health":{"href":"http://localhost:8080/actuator/health","templated":false},
"info":{"href":"http://localhost:8080/actuator/info","templated":false}}}

3.1. 暴露所有接口

要暴露所有接口（除了 /shutdown），只需在 application.properties 中添加如下配置：

management.endpoints.web.exposure.include=*

重启服务后再次访问 /actuator，你会看到更多的接口被暴露出来：

{"_links":{"self":{"href":"http://localhost:8080/actuator","templated":false},
"beans":{"href":"http://localhost:8080/actuator/beans","templated":false},
"caches":{"href":"http://localhost:8080/actuator/caches","templated":false},
"health":{"href":"http://localhost:8080/actuator/health","templated":false},
"info":{"href":"http://localhost:8080/actuator/info","templated":false},
"conditions":{"href":"http://localhost:8080/actuator/conditions","templated":false},
"configprops":{"href":"http://localhost:8080/actuator/configprops","templated":false},
"env":{"href":"http://localhost:8080/actuator/env","templated":false},
"loggers":{"href":"http://localhost:8080/actuator/loggers","templated":false},
"heapdump":{"href":"http://localhost:8080/actuator/heapdump","templated":false},
"threaddump":{"href":"http://localhost:8080/actuator/threaddump","templated":false},
"metrics":{"href":"http://localhost:8080/actuator/metrics","templated":false},
"scheduledtasks":{"href":"http://localhost:8080/actuator/scheduledtasks","templated":false},
"mappings":{"href":"http://localhost:8080/actuator/mappings","templated":false}}}

3.2. 暴露特定接口

有些接口可能包含敏感信息，因此我们可以选择性地暴露某些接口。

✅ management.endpoints.web.exposure.include 支持逗号分隔的接口列表。例如，只暴露 /beans 和 /loggers：

management.endpoints.web.exposure.include=beans, loggers

我们也可以通过 exclude 属性来排除特定接口。例如，暴露所有接口但排除 /threaddump：

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=threaddump

⚠️ 注意：exclude 的优先级高于 include。

3.3. 启用特定接口

除了控制接口的暴露，我们还可以控制接口是否启用。

首先关闭默认启用所有接口的配置：

management.endpoints.enabled-by-default=false

然后只启用并暴露 /health 接口：

management.endpoint.health.enabled=true
management.endpoints.web.exposure.include=health

这样，只有 /health 接口可以访问。

3.4. 启用 shutdown 接口

由于 /shutdown 接口具有破坏性，默认是禁用的。

要启用它，只需添加以下配置：

management.endpoint.shutdown.enabled=true

此时访问 /actuator 会看到 /shutdown 接口。⚠️ 该接口只接受 POST 请求，你可以通过如下命令优雅关闭应用：

curl -X POST http://localhost:8080/actuator/shutdown

4. 接口安全保护

在生产环境中，我们通常需要对接口进行安全保护。

首先，添加 Spring Security 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>2.5.1</version>
</dependency>

✅ 添加该依赖后，默认会对所有暴露的接口启用基本认证（除了 /info 和 /health）。

我们可以通过自定义安全配置，将 /actuator/** 的访问权限限制为 ADMIN 角色。

首先排除默认的安全配置：

@SpringBootApplication(exclude = { 
    SecurityAutoConfiguration.class, 
    ManagementWebSecurityAutoConfiguration.class 
})

然后在配置类中定义用户和角色：

@Bean
public InMemoryUserDetailsManager userDetailsService() {
    UserDetails user =  User.withDefaultPasswordEncoder()
        .username("user")
        .password("password")
        .roles("USER")
        .build();
    UserDetails admin =  User.withDefaultPasswordEncoder()
        .username("admin")
        .password("password")
        .roles("USER", "ADMIN")
        .build();
    return new InMemoryUserDetailsManager(user, admin);
}

接着使用 Spring Boot 提供的便捷方法，限制 /actuator/** 的访问权限：

http.authorizeHttpRequests(authz -> {
        authz.requestMatchers(mvc.pattern("/actuator/**"))
            .hasRole("ADMIN")
            .anyRequest()
            .authenticated();
    });

5. 总结

在本教程中，我们了解了 Spring Boot Actuator 的默认配置方式，并学会了如何通过配置文件控制接口的启用与暴露。由于 /shutdown 接口的特殊性，我们还单独讲解了如何启用它。

最后，我们演示了如何通过 Spring Security 对接口进行安全保护。

示例代码已上传至 GitHub。

Persistence

REST

Security