英文原文:https://docs.spring.io/spring-boot/docs/2.1.6.RELEASE/reference/html/production-ready-endpoints.html
GitHub:https://github.com/jijicai/Spring/tree/master/spring-boot
53、端点
Actuator 端点可让你监控应用程序并与之交互。Spring Boot 包括许多内置的端点,并允许你添加自己的端点。例如,health 端点提供基本的应用程序运行状况信息。
可以启用或禁用每个单独的端点。这将控制是否创建端点以及其 bean 是否存在于应用程序上下文中。要远程访问端点,还必须通过 JMX 或 HTTP 公开。大多数应用程序选择 HTTP,其中端点的 ID 以及 /actuator 的前缀映射到 URL。例如,默认情况下,health 端点映射到 /actuator/health。
以下与技术无关的端点是可用的:
ID 描述 默认启用
auditevents 公开当前应用程序的审核事件信息。 Yes
beans 显示应用程序中所有 Spring bean 的完整列表。 Yes
caches 公开可用的缓存。 Yes
conditions 显示在配置和自动配置类上评估的条件,以及它们匹配或不匹配的原因。 Yes
configprops 显示所有 @ConfigurationProperties 的整理列表。 Yes
env 从 Spring 的 ConfigurableEnvironment 中公开属性。 Yes
flyway 显示已应用的所有 Flyway 数据库迁移。 Yes
health 显示应用程序运行状况信息。 Yes
httptrace 显示 HTTP 跟踪信息(默认情况下,最后 100 个 HTTP 请求-响应交换)。 Yes
info 显示任意应用程序信息。 Yes
integrationgraph 显示 Spring 集成图。 Yes
loggers 显示和修改应用程序中记录器的配置。 Yes
liquibase 显示已应用的任何 Liquibase 数据库迁移。 Yes
metrics 显示当前应用程序的“度量”信息。 Yes
mappings 显示所有 @RequestMapping 路径的整理列表。 Yes
scheduledtasks 显示应用程序中的计划任务。 Yes
sessions 允许从支持 Spring Session 的会话存储中检索和删除用户会话。在使用 Spring Session 对反应式 web 应用程序的支持时不可用。 Yes
shutdown 允许优雅地关闭应用程序。 No
threaddump 执行线程转储。 Yes
如果你的应用程序是 web 应用程序(Spring MVC 、 Spring WebFlux 或 Jersey),则可以使用以下附加端点:
ID 描述 默认启用
heapdump 返回 hprof 堆转储文件。 Yes
jolokia 通过 HTTP 公开 JMX bean(当 Jolokia 在类路径上时,WebFlux 不可用)。 Yes
logfile 返回日志文件的内容(如果已设置 logging.file 或 logging.path 属性)。支持使用 HTTP Range 头来检索日志文件的部分内容。 Yes
prometheus 以 Prometheus 服务器可以抓取的格式公开度量。 Yes
要了解有关 Actuator 端点及其请求和响应格式的更多信息,请参阅单独的 API 文档(HTML 或 PDF)。
53.1、启用端点
默认情况下,启用除 shutdown 以外的所有端点。要配置端点的启用,请使用其 management.endpoint.<id>.enabled 属性。以下示例启用 shutdown 端点:
management.endpoint.shutdown.enabled=true
如果你希望端点启用是 opt-in(选入) 而不是 opt-out(退出,不参与),请将 management.endpoints.enabled-by-default 属性设置为 false,并使用各个端点的 enabled 属性选择重新启用。以下示例启用 info 端点并禁用所有其他端点:
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
注释:禁用的端点将完全从应用程序上下文中删除。如果只想更改端点公开的技术,请改用 include 和 exclude 属性。(https://docs.spring.io/spring-boot/docs/2.1.6.RELEASE/reference/html/production-ready-endpoints.html#production-ready-endpoints-exposing-endpoints )
53.2、公开端点
由于端点可能包含敏感信息,因此应仔细考虑何时公开它们。下表显示了内置端点的默认公开:
ID JMX Web
auditevents Yes No
beans Yes No
caches Yes No
conditions Yes No
configprops Yes No
env Yes No
flyway Yes No
health Yes Yes
heapdump N/A No
httptrace Yes No
info Yes Yes
integrationgraph Yes No
jolokia N/A No
logfile N/A No
loggers Yes No
liquibase Yes No
metrics Yes No
mappings Yes No
prometheus N/A No
scheduledtasks Yes No
sessions Yes No
shutdown Yes No
threaddump Yes No
要更改公开的端点,请使用以下特定于技术的 include 和 exclude 属性:
属性 默认
management.endpoints.jmx.exposure.exclude
management.endpoints.jmx.exposure.include *
management.endpoints.web.exposure.exclude
management.endpoints.web.exposure.include info, health
include 属性列出了公开的端点的 IDs。exclude 属性列出不应公开的端点的 IDs。exclude 属性优先于 include 属性。include 和 exclude 属性都可以配置一个端点 IDs 列表。
例如,要停止在 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: "*"
注释:如果你的应用程序公开,我们强烈建议你也保护你的端点。(https://docs.spring.io/spring-boot/docs/2.1.6.RELEASE/reference/html/production-ready-endpoints.html#production-ready-endpoints-security )
提示:如果你想在公开端点时实现自己的策略,可以注册 EndpointFilter bean。
53.3、保护 HTTP 端点
你应该像保护任何其他敏感 URL 一样小心保护 HTTP 端点。如果存在 Spring Security,则默认情况下使用 Spring Security 的内容协商策略来保护端点。如果你希望为 HTTP 端点配置自定义安全性,例如,仅允许具有特定角色的用户访问它们, Spring Boot 提供了一些方便的 RequestMatcher 对象,这些对象可以与 Spring Security 结合使用。
典型的 Spring Security 配置可能类似于以下示例:
@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
.anyRequest().hasRole("ENDPOINT_ADMIN")
.and()
.httpBasic();
}
}
上述示例使用 EndpointRequest.toAnyEndpoint() 将请求与任何端点匹配,然后确保所有端点都具有 ENDPOINT_ADMIN 角色。EndpointRequest 上还提供了其他几种匹配器方法。有关详细信息,请参阅 API 文档(HTML 或 PDF)。
如果你在防火墙后部署应用程序,你可能希望可以访问所有 actuator 端点,而不需要身份验证。可以通过更改 management.endpoints.web.exposure.include 属性来执行此操作,如下所示:
application.properties
management.endpoints.web.exposure.include=*
此外,如果存在 Spring Security,则需要添加自定义安全配置,以允许未经身份验证的对端点的访问,如下面示例所示:
@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
.anyRequest().permitAll();
}
}