【官方文档翻译】SpringBootActuator生产特性

翻译自 spring-boot 官方文档（版本：2.2.2.RELEASE）

Spring Boot包含了许多附加功能，可以帮助您在将应用程序推送到生产环境时监视和管理它。您可以选择使用HTTP端点或与JMX一起管理和监视应用程序。审核、运行状况和度量数据收集也可以自动应用于您的应用程序。

启用生产特性

spring-boot-actuator 模块提供所有 SpringBoot 生产特性。启动这些特性的最简单的方式就是引入此依赖。

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

端点

actuator 端点允许你监控应用程序并与之互动。Spring Boot包含许多内置端点，允许你添加自己的端点。例如，health 端点提供基本的应用程序健康信息。每个端点都可以启用或禁用。这控制了端点是否被创建并且它的bean是否存在于应用程序上下文中。要远程访问端点，还必须通过JMX或HTTP暴露端点。大多数应用程序选择HTTP，其中端点的ID和前缀 /actuator 被映射到URL。例如，默认情况下，health 端点映射到 /actuator/health。以下列出了可用端点：

ID	说明
auditevents	暴露当前应用程序的审核事件信息。需要 AuditEventRepository bean
beans	显示应用程序中所有 spring bean 的完整列表。
caches	暴露可用缓存
conditions	显示在配置和自动配置类上评估的条件，以及它们匹配或不匹配的原因。
configprops	显示所有 @ConfigurationProperties 的整理列表。
env	暴露 Spring ConfigurableEnvironment 属性
flyway	显示已应用的所有 Flyway 数据库迁移。需要 Flyway beans
health	显示应用健康信息
httptrace	显示HTTP跟踪信息（默认情况下，最后100个HTTP请求-响应交换）。需要 HttpTraceRepository bean
info	显示任意应用程序信息
integrationgraph	显示了Spring集成图。需要依赖 spring-integration-core 依赖
loggers	显示并修改应用程序中 loggers 的配置
liquibase	显示已应用的任何 Liquibase 数据库迁移。需要 Liquibase bean
metrics	显示当前应用的度量信息
mappings	显示所有 @RequestMapping 路径的整理列表
scheduledtasks	显示应用的定时器任务
sessions	允许从支持Spring session的 session存储中检索和删除用户 session。需要使用Spring会话的基于Servlet的web应用程序
threaddump	执行 thread dump

如果是 web 应用（Spring MVC、Spring WebFlux、Jersey），还可以使用以下端点：

ID	说明
heapdump	返回 hprof 堆 dump 文件
jolokia	通过HTTP暴露 jmx bean（当 Jolokia 位于类路径上时，WebFlux不可用）。需要依赖 jolokia-core
logfile	返回日志文件的内容（如果已设置 logging.file.name 或 logging.file.path 属性）。支持使用HTTP Range header 来检索日志文件的部分内容
prometheus	以 Prometheus 服务器可以擦除的格式暴露 metric。需要依赖 micrometer-registry-prometheus

更多信息

开启端点

默认情况下，除了 shutdown 以外的所有端点都可用。要配置端点的启用，使用其 management.endpoint. .enabled 属性。以下示例启用 shutdown 端点：

management.endpoint.shutdown.enabled=true

如果您希望端点启用是选择可用而不是选择不可用，将 management.endpoints.enabled-by-default 属性设置为 false ，并使用各个端点的 enabled 属性选择重新启用。以下示例启用 info 端点并禁用所有其他端点：

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true

注意：禁用的端点将完全从应用程序上下文中删除。如果只想更改端点暴露的技术，请改用 include 和 exclude 属性。

暴露端点

由于端点可能包含敏感信息，因此应仔细考虑何时暴露它们。下表显示了内置端点的默认开启情况：JMX端点基本都暴露，Web端点基本不暴露（除了 health 和 info）

要更改暴露的端点，使用以下 include 和 exclude 属性：

include 属性列出暴露端点的id。exclude 属性列出不应不应暴露端点的ID。 exclude 属性优先于 include 属性。include 和 exclude 属性都可以配置同一个端点id。例如，要取消通过JMX暴露所有端点，并且只暴露 health 和 info 端点，请使用以下属性：

management.endpoints.jmx.exposure.include=health,info

* 可以用来表示所有端点。例如，要通过 HTTP 暴露除 env 和 beans 端点之外的所有内容，请使用以下属性：

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

注意：* 号在YAML中有特殊含义，因此如果要包括（或排除）所有端点，请确保添加引号，如下例所示：

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

注意：如果应用是暴露在公共环境中，强烈建议保护你的应用端点。

如果想自定义端点暴露策略，可以注册一个 EndpointFilter bean。

保护 HTTP 端点

应该像保护其他敏感URL一样保护HTTP端点。如果存在Spring Security，那么在默认情况下，使用 SpringSecurity 的内容协商策略来保护端点。如果希望为 HTTP 端点配置自定义安全性，例如，只允许具有特定角色的用户访问它们，那么 Spring Boot 提供了一些方便的 RequestMatcher 对象，可以与 Spring Security 结合使用。

典型的 Spring Security 配置可能类似于以下示例：

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests((requests) ->
                requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic();
    }
}

上面的示例使用 EndpointRequest.toAnyEndpoint() 将请求与所有端点匹配，然后确保所有端点都具有 ENDPOINT_ADMIN 角色。EndpointRequest 上还提供了其他几种匹配方法。有关详细信息，请参阅API文档（HTML或PDF）。

如果在防火墙后部署应用程序，您可能希望可以访问所有 actuator 端点，而不需要身份验证。可以通过更改 management.endpoints.web.exposure.include 属性来执行此操作，如下所示：

management.endpoints.web.exposure.include=*

此外，如果存在Spring Security，则需要添加自定义安全配置，以允许未经身份验证的对端点的访问，如以下示例所示：

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests((requests) ->
            requests.anyRequest().permitAll());
    }
}

配置端点

端点对不带任何参数的读取操作的响应自动缓存。要配置端点缓存响应的时间量，使用其 cache.time-to-live 属性。以下示例将bean端点缓存的生存时间设置为10秒：

# application.properties
management.endpoint.beans.cache.time-to-live=10s

注意：management.endpoint. 前缀用来唯一标识正在配置的端点。
当发出经过身份验证的HTTP请求时， Principal 被视为端点的输入，因此，响应将不会被缓存。

Actuator web 端点超媒体

添加了一个“发现页”，其中包含指向所有端点的链接。默认情况下，“发现页”在 /actuator 可用。配置自定义管理上下文路径时，“发现页”会自动从 /actuator 移动到管理上下文的根目录。例如，如果管理上下文路径是 /management ，那么可以从 /management 获得发现页。当管理上下文路径设置为 / 时，将禁用发现页，以防止与其他映射发生冲突。

CORS 跨域支持

跨域资源共享（CORS）是一个 W3C 规范，它允许您灵活地指定什么样的跨域请求被授权。如果使用Spring MVC 或 Spring WebFlux，则可以配置 actuator 的 web 端点来支持此类场景。默认情况下禁用CORS支持，并且仅在设置了 management.endpoints.web.cors.allowed-origins 属性后才启用。以下配置允许从 example.com 域进行 GET 和 POST 调用：

management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST

有关配置的完整项可以查看 CorsEndpointProperties.java

实现自定义端点

如果添加了一个使用 @Endpoint 的 @Bean，则用 @ReadOperation、@WriteOperation 或 @DeleteOperation 注解的任何方法都将自动通过JMX暴露，在web应用程序中，也可以通过HTTP暴露。端点可以使用Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 暴露。如果 Jersey 和 Spring MVC 都可用，那么将使用Spring MVC。还可以使用 @JmxEndpoint 或 @WebEndpoint 编写特定于技术的端点。这些端点仅限于其各自的技术。例如，@WebEndpoint 仅通过 HTTP 而不是 JMX 暴露。

可以使用 @EndpointWebExtension 和 @EndpointJmxExtension 编写特定于技术的扩展。这些注解允许你供特定于技术的操作以扩充现有端点。

最后，如果需要访问特定于 web 框架的功能，可以实现 Servlet 或 Spring @Controller 和 @RestController 端点，但代价是它们不能通过JMX使用，或者使用不同的web框架。

接收输入

端点上的操作通过其参数接收输入。当通过 web 暴露时，这些参数的值取自URL的查询参数和JSON request body。当通过 JMX 暴露时，参数被映射到 MBean 操作的参数。默认情况下，参数是必需的。通过使用 @org.springframework.lang.Nullable 对它们进行注解，可以使它们成为可选的。

JSON请求体中的每个根属性都可以映射到端点的一个参数。考虑以下JSON请求体：