此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Boot 3.3.1Spring中文文档

此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Boot 3.3.1Spring中文文档

执行器端点允许您监控应用程序并与之交互。 Spring Boot 包含许多内置端点,并允许您添加自己的端点。 例如,终结点提供基本的应用程序运行状况信息。healthSpring中文文档

您可以启用或禁用每个单独的端点,并通过 HTTP 或 JMX 公开它们(使其可远程访问)。 当终结点同时启用和公开时,它被认为是可用的。 仅当内置终结点可用时,才会自动配置它们。 大多数应用程序选择公开而不是 HTTP,其中终结点的 ID 和前缀映射到 URL。 例如,默认情况下,终结点映射到 。/actuatorhealth/actuator/healthSpring中文文档

要了解有关执行器的端点及其请求和响应格式的更多信息,请参阅 API 文档

以下与技术无关的终结点可用:Spring中文文档

编号 描述

auditeventsSpring中文文档

公开当前应用程序的审核事件信息。 需要豆子。AuditEventRepositorySpring中文文档

beansSpring中文文档

显示应用程序中所有 Spring Bean 的完整列表。Spring中文文档

cachesSpring中文文档

公开可用的缓存。Spring中文文档

conditionsSpring中文文档

显示在配置类和自动配置类上评估的条件,以及它们匹配或不匹配的原因。Spring中文文档

configpropsSpring中文文档

显示所有 . 需要消毒@ConfigurationPropertiesSpring中文文档

envSpring中文文档

公开 Spring 的 . 需要消毒ConfigurableEnvironmentSpring中文文档

flywaySpring中文文档

显示已应用的任何 Flyway 数据库迁移。 需要一个或多个 bean。FlywaySpring中文文档

healthSpring中文文档

显示应用程序运行状况信息。Spring中文文档

httpexchangesSpring中文文档

显示 HTTP 交换信息(默认情况下,最近 100 次 HTTP 请求-响应交换)。 需要豆子。HttpExchangeRepositorySpring中文文档

infoSpring中文文档

显示任意应用程序信息。Spring中文文档

integrationgraphSpring中文文档

显示 Spring Integration 图。 需要依赖 。spring-integration-coreSpring中文文档

loggersSpring中文文档

显示和修改应用程序中记录器的配置。Spring中文文档

liquibaseSpring中文文档

显示已应用的任何 Liquibase 数据库迁移。 需要一个或多个 bean。LiquibaseSpring中文文档

metricsSpring中文文档

显示当前应用程序的“指标”信息。Spring中文文档

mappingsSpring中文文档

显示所有路径的整理列表。@RequestMappingSpring中文文档

quartzSpring中文文档

显示有关 Quartz Scheduler 作业的信息。 需要消毒Spring中文文档

scheduledtasksSpring中文文档

在应用程序中显示计划任务。Spring中文文档

sessionsSpring中文文档

允许从 Spring Session 支持的会话存储中检索和删除用户会话。 需要使用 Spring Session 的基于 servlet 的 Web 应用程序。Spring中文文档

shutdownSpring中文文档

让应用程序正常关闭。 仅在使用罐装时有效。 默认情况下处于禁用状态。Spring中文文档

startupSpring中文文档

显示 收集的启动步骤数据。 要求使用 .ApplicationStartupSpringApplicationBufferingApplicationStartupSpring中文文档

threaddumpSpring中文文档

执行线程转储。Spring中文文档

如果应用程序是 Web 应用程序(Spring MVC、Spring WebFlux 或 Jersey),则可以使用以下附加终结点:Spring中文文档

编号 描述

heapdumpSpring中文文档

返回堆转储文件。 在 HotSpot JVM 上,返回一个 -format 文件。 在 OpenJ9 JVM 上,返回一个 -format 文件。HPROFPHDSpring中文文档

logfileSpring中文文档

返回日志文件的内容(如果已设置 or 属性)。 支持使用 HTTP 标头检索日志文件的部分内容。logging.file.namelogging.file.pathRangeSpring中文文档

prometheusSpring中文文档

以 Prometheus 服务器可抓取的格式公开指标。 需要依赖 。micrometer-registry-prometheusSpring中文文档

要了解有关执行器的端点及其请求和响应格式的更多信息,请参阅 API 文档
编号 描述

auditeventsSpring中文文档

公开当前应用程序的审核事件信息。 需要豆子。AuditEventRepositorySpring中文文档

beansSpring中文文档

显示应用程序中所有 Spring Bean 的完整列表。Spring中文文档

cachesSpring中文文档

公开可用的缓存。Spring中文文档

conditionsSpring中文文档

显示在配置类和自动配置类上评估的条件,以及它们匹配或不匹配的原因。Spring中文文档

configpropsSpring中文文档

显示所有 . 需要消毒@ConfigurationPropertiesSpring中文文档

envSpring中文文档

公开 Spring 的 . 需要消毒ConfigurableEnvironmentSpring中文文档

flywaySpring中文文档

显示已应用的任何 Flyway 数据库迁移。 需要一个或多个 bean。FlywaySpring中文文档

healthSpring中文文档

显示应用程序运行状况信息。Spring中文文档

httpexchangesSpring中文文档

显示 HTTP 交换信息(默认情况下,最近 100 次 HTTP 请求-响应交换)。 需要豆子。HttpExchangeRepositorySpring中文文档

infoSpring中文文档

显示任意应用程序信息。Spring中文文档

integrationgraphSpring中文文档

显示 Spring Integration 图。 需要依赖 。spring-integration-coreSpring中文文档

loggersSpring中文文档

显示和修改应用程序中记录器的配置。Spring中文文档

liquibaseSpring中文文档

显示已应用的任何 Liquibase 数据库迁移。 需要一个或多个 bean。LiquibaseSpring中文文档

metricsSpring中文文档

显示当前应用程序的“指标”信息。Spring中文文档

mappingsSpring中文文档

显示所有路径的整理列表。@RequestMappingSpring中文文档

quartzSpring中文文档

显示有关 Quartz Scheduler 作业的信息。 需要消毒Spring中文文档

scheduledtasksSpring中文文档

在应用程序中显示计划任务。Spring中文文档

sessionsSpring中文文档

允许从 Spring Session 支持的会话存储中检索和删除用户会话。 需要使用 Spring Session 的基于 servlet 的 Web 应用程序。Spring中文文档

shutdownSpring中文文档

让应用程序正常关闭。 仅在使用罐装时有效。 默认情况下处于禁用状态。Spring中文文档

startupSpring中文文档

显示 收集的启动步骤数据。 要求使用 .ApplicationStartupSpringApplicationBufferingApplicationStartupSpring中文文档

threaddumpSpring中文文档

执行线程转储。Spring中文文档

编号 描述

heapdumpSpring中文文档

返回堆转储文件。 在 HotSpot JVM 上,返回一个 -format 文件。 在 OpenJ9 JVM 上,返回一个 -format 文件。HPROFPHDSpring中文文档

logfileSpring中文文档

返回日志文件的内容(如果已设置 or 属性)。 支持使用 HTTP 标头检索日志文件的部分内容。logging.file.namelogging.file.pathRangeSpring中文文档

prometheusSpring中文文档

以 Prometheus 服务器可抓取的格式公开指标。 需要依赖 。micrometer-registry-prometheusSpring中文文档

启用端点

默认情况下,除 之外的所有终结点都处于启用状态。 若要配置终结点的启用,请使用其属性。 以下示例启用终结点:shutdownmanagement.endpoint.<id>.enabledshutdownSpring中文文档

management.endpoint.shutdown.enabled=true
management:
  endpoint:
    shutdown:
      enabled: true

如果您希望终端节点启用是选择加入而不是选择退出,请将属性设置为并使用单个终端节点属性重新选择加入。 以下示例启用终结点并禁用所有其他终结点:management.endpoints.enabled-by-defaultfalseenabledinfoSpring中文文档

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
management:
  endpoints:
    enabled-by-default: false
  endpoint:
    info:
      enabled: true
已禁用的终结点将从应用程序上下文中完全删除。 如果只想更改公开终结点的技术,请改用 includeexclude 属性
已禁用的终结点将从应用程序上下文中完全删除。 如果只想更改公开终结点的技术,请改用 includeexclude 属性

公开终结点

缺省情况下,仅通过 HTTP 和 JMX 公开运行状况终结点。 由于终结点可能包含敏感信息,因此应仔细考虑何时公开它们。Spring中文文档

若要更改公开的终结点,请使用以下特定于技术的属性:includeexcludeSpring中文文档

财产 违约

management.endpoints.jmx.exposure.excludeSpring中文文档

management.endpoints.jmx.exposure.includeSpring中文文档

healthSpring中文文档

management.endpoints.web.exposure.excludeSpring中文文档

management.endpoints.web.exposure.includeSpring中文文档

healthSpring中文文档

该属性列出公开的终结点的 ID。 该属性列出了不应公开的终结点的 ID。 该物业优先于该物业。 您可以使用终结点 ID 列表配置 和 属性。includeexcludeexcludeincludeincludeexcludeSpring中文文档

例如,要仅通过 JMX 公开 and 端点,请使用以下属性:healthinfoSpring中文文档

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

*可用于选择所有终结点。 例如,若要通过 HTTP 公开除 和 终结点之外的所有内容,请使用以下属性:envbeansSpring中文文档

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"
*在 YAML 中具有特殊含义,因此如果要包含(或排除)所有终结点,请务必添加引号。
如果应用程序公开,强烈建议同时保护终结点
如果要在端点公开时实现自己的策略,可以注册一个 Bean。EndpointFilter
财产 违约

management.endpoints.jmx.exposure.excludeSpring中文文档

management.endpoints.jmx.exposure.includeSpring中文文档

healthSpring中文文档

management.endpoints.web.exposure.excludeSpring中文文档

management.endpoints.web.exposure.includeSpring中文文档

healthSpring中文文档

*在 YAML 中具有特殊含义,因此如果要包含(或排除)所有终结点,请务必添加引号。
如果应用程序公开,强烈建议同时保护终结点
如果要在端点公开时实现自己的策略,可以注册一个 Bean。EndpointFilter

安全

出于安全考虑,默认情况下仅通过 HTTP 公开终结点。 可以使用该属性来配置公开的终结点。/healthmanagement.endpoints.web.exposure.includeSpring中文文档

在设置之前,请确保公开的执行器不包含敏感信息,通过将它们放在防火墙后面来保护,或者通过Spring Security之类的东西进行保护。management.endpoints.web.exposure.include

如果 Spring Security 在类路径上并且不存在其他 bean,则除 Spring Boot 自动配置外的所有执行器都受到保护。 如果定义自定义 Bean,则 Spring Boot 自动配置会回退,并允许您完全控制执行器访问规则。SecurityFilterChain/healthSecurityFilterChainSpring中文文档

如果您希望为 HTTP 端点配置自定义安全性(例如,仅允许具有特定角色的用户访问它们),Spring Boot 提供了一些方便的对象,您可以将其与 Spring Security 结合使用。RequestMatcherSpring中文文档

典型的 Spring Security 配置可能类似于以下示例:Spring中文文档

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http.securityMatcher(EndpointRequest.toAnyEndpoint());
		http.authorizeHttpRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
		http.httpBasic(withDefaults());
		return http.build();
	}

}
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.Customizer.withDefaults
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {

	@Bean
	fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
		http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
			requests.anyRequest().hasRole("ENDPOINT_ADMIN")
		}
		http.httpBasic(withDefaults())
		return http.build()
	}

}

前面的示例用于将请求与任何终结点匹配,然后确保所有终结点都具有该角色。 上还提供了其他几种匹配器方法。 有关详细信息,请参阅 API 文档EndpointRequest.toAnyEndpoint()ENDPOINT_ADMINEndpointRequestSpring中文文档

如果将应用程序部署在防火墙后面,您可能希望无需身份验证即可访问所有执行器端点。 您可以通过更改属性来执行此操作,如下所示:management.endpoints.web.exposure.includeSpring中文文档

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

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

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http.securityMatcher(EndpointRequest.toAnyEndpoint());
		http.authorizeHttpRequests((requests) -> requests.anyRequest().permitAll());
		return http.build();
	}

}
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {

	@Bean
	fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
		http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
			requests.anyRequest().permitAll()
		}
		return http.build()
	}

}
在上述两个示例中,配置仅适用于执行器端点。 由于 Spring Boot 的安全配置在存在任何 bean 的情况下完全后退,因此您需要使用适用于应用程序其余部分的规则来配置额外的 bean。SecurityFilterChainSecurityFilterChain

跨站点请求伪造保护

由于 Spring Boot 依赖于 Spring Security 的默认值,因此默认情况下会打开 CSRF 保护。 这意味着,在使用默认安全配置时,需要 (shutdown and loggers endpoints)、a 或 a 的执行器端点会出现 403(禁止)错误。POSTPUTDELETESpring中文文档

建议仅在创建非浏览器客户端使用的服务时完全禁用 CSRF 保护。

您可以在 Spring Security 参考指南中找到有关 CSRF 保护的其他信息。Spring中文文档

在设置之前,请确保公开的执行器不包含敏感信息,通过将它们放在防火墙后面来保护,或者通过Spring Security之类的东西进行保护。management.endpoints.web.exposure.include
在上述两个示例中,配置仅适用于执行器端点。 由于 Spring Boot 的安全配置在存在任何 bean 的情况下完全后退,因此您需要使用适用于应用程序其余部分的规则来配置额外的 bean。SecurityFilterChainSecurityFilterChain
建议仅在创建非浏览器客户端使用的服务时完全禁用 CSRF 保护。

配置端点

端点会自动缓存对不采用任何参数的读取操作的响应。 若要配置终结点缓存响应的时间量,请使用其属性。 以下示例将终结点缓存的生存时间设置为 10 秒:cache.time-to-livebeansSpring中文文档

management.endpoint.beans.cache.time-to-live=10s
management:
  endpoint:
    beans:
      cache:
        time-to-live: "10s"
前缀唯一标识正在配置的终结点。management.endpoint.<name>
前缀唯一标识正在配置的终结点。management.endpoint.<name>

清理敏感值

和 端点返回的信息可能是敏感的,因此默认情况下,值始终被完全清理(替换为 )。/env/configprops/quartz******Spring中文文档

只有在以下情况下,才能以未经清理的形式查看值:Spring中文文档

可以将可清理终结点的属性配置为以下值之一:show-valuesSpring中文文档

  • NEVER- 值始终完全清理(替换为******)Spring中文文档

  • ALWAYS- 值显示给所有用户(只要没有 Bean 应用)SanitizingFunctionSpring中文文档

  • WHEN_AUTHORIZED- 值仅显示给授权用户(只要不应用 Bean)SanitizingFunctionSpring中文文档

对于 HTTP 终结点,如果用户已通过身份验证并具有由终结点的 roles 属性配置的角色,则视为已获得授权。 默认情况下,任何经过身份验证的用户都是经过授权的。Spring中文文档

对于 JMX 端点,所有用户始终都经过授权。Spring中文文档

以下示例允许具有该角色的所有用户以原始形式查看终结点中的值。 未经授权的用户或没有该角色的用户将仅看到已清理的值。admin/envadminSpring中文文档

management.endpoint.env.show-values=WHEN_AUTHORIZED
management.endpoint.env.roles=admin
management:
  endpoint:
    env:
      show-values: WHEN_AUTHORIZED
      roles: "admin"
此示例假定尚未定义任何 bean。SanitizingFunction
此示例假定尚未定义任何 bean。SanitizingFunction

执行器 Web 端点的超媒体

添加了一个“发现页面”,其中包含指向所有端点的链接。 默认情况下,“发现页面”可用。/actuatorSpring中文文档

若要禁用“发现页”,请将以下属性添加到应用程序属性:Spring中文文档

management.endpoints.web.discovery.enabled=false
management:
  endpoints:
    web:
      discovery:
        enabled: false

配置自定义管理上下文路径后,“发现页面”会自动从管理上下文的根目录移动。 例如,如果管理上下文路径为 ,则发现页可从 访问。 当管理上下文路径设置为 时,将禁用发现页,以防止与其他映射发生冲突的可能性。/actuator/management/management/Spring中文文档

CORS 支持

跨域资源共享 (CORS) 是一项 W3C 规范,允许您以灵活的方式指定授权的跨域请求类型。 如果您使用 Spring MVC 或 Spring WebFlux,则可以配置 Actuator 的 Web 端点以支持此类方案。Spring中文文档

默认情况下,CORS 支持处于禁用状态,并且仅在设置属性后启用。 以下配置允许从域进行调用:management.endpoints.web.cors.allowed-originsGETPOSTexample.comSpring中文文档

management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
management:
  endpoints:
    web:
      cors:
        allowed-origins: "https://example.com"
        allowed-methods: "GET,POST"
有关选项的完整列表,请参阅 CorsEndpointProperties
有关选项的完整列表,请参阅 CorsEndpointProperties

实现自定义终结点

如果添加 annotated with ,则任何用 、 或 注释的方法都会自动通过 JMX 公开,并且在 Web 应用程序中也会通过 HTTP 公开。 可以使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开终结点。 如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。@Bean@Endpoint@ReadOperation@WriteOperation@DeleteOperationSpring中文文档

下面的示例公开一个返回自定义对象的读取操作:Spring中文文档

	@ReadOperation
	public CustomData getData() {
		return new CustomData("test", 5);
	}
	@ReadOperation
	fun getData(): CustomData {
		return CustomData("test", 5)
	}

您还可以使用 或 编写特定于技术的终结点。 这些终结点仅限于其各自的技术。 例如,仅通过 HTTP 公开,而不通过 JMX 公开。@JmxEndpoint@WebEndpoint@WebEndpointSpring中文文档

您可以使用 和 编写特定于技术的扩展。 通过这些批注,您可以提供特定于技术的操作来扩充现有端点。@EndpointWebExtension@EndpointJmxExtensionSpring中文文档

最后,如果您需要访问特定于 Web 框架的功能,您可以实现 servlet 或 Spring 和端点,但代价是它们无法通过 JMX 或使用不同的 Web 框架。@Controller@RestControllerSpring中文文档

接收输入

端点上的操作通过其参数接收输入。 在 Web 上公开时,这些参数的值取自 URL 的查询参数和 JSON 请求正文。 在 JMX 上公开时,参数将映射到 MBean 操作的参数。 默认情况下,参数是必需的。 可以通过用 或 来注释它们,使它们成为可选的。@javax.annotation.Nullable@org.springframework.lang.NullableSpring中文文档

您可以将 JSON 请求正文中的每个根属性映射到终端节点的参数。 请考虑以下 JSON 请求正文:Spring中文文档

{
	"name": "test",
	"counter": 42
}

您可以使用它来调用 take 和 parameters 的写入操作,如以下示例所示:String nameint counterSpring中文文档

	@WriteOperation
	public void updateData(String name, int counter) {
		// injects "test" and 42
	}
	@WriteOperation
	fun updateData(name: String?, counter: Int) {
		// injects "test" and 42
	}
由于终结点与技术无关,因此只能在方法签名中指定简单类型。 具体而言,不支持使用定义 和 属性的类型声明单个参数。CustomDatanamecounter
要让输入映射到操作方法的参数,实现端点的 Java 代码应使用 编译,实现端点的 Kotlin 代码应使用 编译。 如果您使用 Spring Boot 的 Gradle 插件,或者使用 Maven 和 .-parameters-java-parametersspring-boot-starter-parent

输入类型转换

如有必要,传递给端点操作方法的参数会自动转换为所需的类型。 在调用操作方法之前,通过 JMX 或 HTTP 接收的输入将使用 以及 any 或 bean 限定的实例转换为所需的类型。ApplicationConversionServiceConverterGenericConverter@EndpointConverterSpring中文文档

自定义 Web 终结点

对 、 或 的操作使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 自动公开。 如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。@Endpoint@WebEndpoint@EndpointWebExtensionSpring中文文档

Web 终结点请求谓词

系统会自动为公开 Web 的终结点上的每个操作生成请求谓词。Spring中文文档

路径

谓词的路径由终结点的 ID 和 Web 公开的终结点的基路径确定。 默认基本路径为 。 例如,ID 为 uses 的终结点用作其在谓词中的路径。/actuatorsessions/actuator/sessionsSpring中文文档

您可以通过使用 来注释操作方法的一个或多个参数来进一步自定义路径。 此类参数将作为路径变量添加到路径谓词中。 调用终结点操作时,变量的值将传递到操作方法中。 如果要捕获所有剩余的路径元素,可以添加到最后一个参数中,并使其成为与 .@Selector@Selector(Match=ALL_REMAINING)String[]Spring中文文档

HTTP 方法

谓词的HTTP方法由操作类型决定,如下表所示:Spring中文文档

操作 HTTP 方法

@ReadOperationSpring中文文档

GETSpring中文文档

@WriteOperationSpring中文文档

POSTSpring中文文档

@DeleteOperationSpring中文文档

DELETESpring中文文档

消耗

对于使用请求正文的 (HTTP),谓词的子句为 。 对于所有其他操作,该子句为空。@WriteOperationPOSTconsumesapplication/vnd.spring-boot.actuator.v2+json, application/jsonconsumesSpring中文文档

生产

谓词的子句可以由 、 和 注释的属性确定。 该属性是可选的。 如果未使用,则自动确定该子句。producesproduces@DeleteOperation@ReadOperation@WriteOperationproducesSpring中文文档

如果操作方法返回 或 ,则子句为空。 如果操作方法返回 ,则子句为 。 对于所有其他操作,子句为 。voidVoidproducesorg.springframework.core.io.Resourceproducesapplication/octet-streamproducesapplication/vnd.spring-boot.actuator.v2+json, application/jsonSpring中文文档

Web 终结点响应状态

终结点操作的默认响应状态取决于操作类型(读取、写入或删除)以及操作返回的内容(如果有)。Spring中文文档

如果 a 返回值,则响应状态将为 200 (OK)。 如果未返回值,则响应状态将为 404 (未找到) 。@ReadOperationSpring中文文档

如果 或 返回值,则响应状态将为 200 (OK) 。 如果未返回值,则响应状态将为 204(无内容)。@WriteOperation@DeleteOperationSpring中文文档

如果调用的操作没有必需的参数或参数无法转换为所需的类型,则不会调用操作方法,响应状态将为 400(错误请求)。Spring中文文档

Web 终结点范围请求

您可以使用 HTTP 范围请求请求 HTTP 资源的一部分。 使用 Spring MVC 或 Spring Web Flux 时,自动返回范围请求的操作支持。org.springframework.core.io.ResourceSpring中文文档

使用 Jersey 时不支持范围请求。

Web 端点安全

Web 终结点或特定于 Web 的终结点扩展上的操作可以接收当前或作为方法参数。 前者通常与 结合使用,为经过身份验证和未经身份验证的用户提供不同的行为。 后者通常用于使用其方法执行授权检查。java.security.Principalorg.springframework.boot.actuate.endpoint.SecurityContext@NullableisUserInRole(String)Spring中文文档

由于终结点与技术无关,因此只能在方法签名中指定简单类型。 具体而言,不支持使用定义 和 属性的类型声明单个参数。CustomDatanamecounter
要让输入映射到操作方法的参数,实现端点的 Java 代码应使用 编译,实现端点的 Kotlin 代码应使用 编译。 如果您使用 Spring Boot 的 Gradle 插件,或者使用 Maven 和 .-parameters-java-parametersspring-boot-starter-parent
操作 HTTP 方法

@ReadOperationSpring中文文档

GETSpring中文文档

@WriteOperationSpring中文文档

POSTSpring中文文档

@DeleteOperationSpring中文文档

DELETESpring中文文档

使用 Jersey 时不支持范围请求。

健康信息

您可以使用运行状况信息来检查正在运行的应用程序的状态。 它通常被监控软件用来在生产系统出现故障时提醒某人。 终结点公开的信息取决于 和 属性,可以使用以下值之一进行配置:healthmanagement.endpoint.health.show-detailsmanagement.endpoint.health.show-componentsSpring中文文档

名字 描述

neverSpring中文文档

从不显示详细信息。Spring中文文档

when-authorizedSpring中文文档

详细信息仅向授权用户显示。 可以使用 来配置授权角色。management.endpoint.health.rolesSpring中文文档

alwaysSpring中文文档

详细信息将显示给所有用户。Spring中文文档

默认值为 。 当用户处于终结点的一个或多个角色中时,将被视为已获得授权。 如果终端节点没有配置的角色(默认值),则所有经过身份验证的用户都被视为已获得授权。 可以使用该属性配置角色。nevermanagement.endpoint.health.rolesSpring中文文档

如果已保护应用程序并希望使用 ,则安全配置必须允许经过身份验证和未经身份验证的用户访问运行状况终结点。always

运行状况信息是从 HealthContributorRegistry 的内容中收集的(默认情况下,所有 HealthContributor 实例都定义在 中)。 Spring Boot 包含了许多自动配置的,你也可以自己编写。ApplicationContextHealthContributorsSpring中文文档

A 可以是 a 或 。 A 提供实际的运行状况信息,包括 . A 提供其他 . 总而言之,贡献者形成了一个树状结构来表示整个系统的运行状况。HealthContributorHealthIndicatorCompositeHealthContributorHealthIndicatorStatusCompositeHealthContributorHealthContributorsSpring中文文档

默认情况下,最终的系统运行状况由 派生,该 根据有序列表对每个状态进行排序。 排序列表中的第一个状态用作整体运行状况。 如果 no 返回 已知的状态,则使用状态。StatusAggregatorHealthIndicatorHealthIndicatorStatusAggregatorUNKNOWNSpring中文文档

可以使用 在运行时注册和注销运行状况指示器。HealthContributorRegistry

自动配置的 HealthIndicators

在适当的情况下,Spring Boot 会自动配置下表中列出的内容。 您还可以通过配置来启用或禁用选定的指标, 如下表所示:HealthIndicatorsmanagement.health.key.enabledkeySpring中文文档

钥匙 名字 描述

cassandraSpring中文文档

CassandraDriverHealthIndicatorSpring中文文档

检查 Cassandra 数据库是否已启动。Spring中文文档

couchbaseSpring中文文档

CouchbaseHealthIndicatorSpring中文文档

检查 Couchbase 群集是否已启动。Spring中文文档

dbSpring中文文档

DataSourceHealthIndicatorSpring中文文档

检查是否可以获取与的连接。DataSourceSpring中文文档

diskspaceSpring中文文档

DiskSpaceHealthIndicatorSpring中文文档

检查磁盘空间是否不足。Spring中文文档

elasticsearchSpring中文文档

ElasticsearchRestClientHealthIndicatorSpring中文文档

检查 Elasticsearch 集群是否已启动。Spring中文文档

hazelcastSpring中文文档

HazelcastHealthIndicatorSpring中文文档

检查 Hazelcast 服务器是否已启动。Spring中文文档

influxdbSpring中文文档

InfluxDbHealthIndicatorSpring中文文档

检查 InfluxDB 服务器是否已启动。Spring中文文档

jmsSpring中文文档

JmsHealthIndicatorSpring中文文档

检查 JMS 代理是否已启动。Spring中文文档

ldapSpring中文文档

LdapHealthIndicatorSpring中文文档

检查 LDAP 服务器是否已启动。Spring中文文档

mailSpring中文文档

MailHealthIndicatorSpring中文文档

检查邮件服务器是否已启动。Spring中文文档

mongoSpring中文文档

MongoHealthIndicatorSpring中文文档

检查 Mongo 数据库是否已启动。Spring中文文档

neo4jSpring中文文档

Neo4jHealthIndicatorSpring中文文档

检查 Neo4j 数据库是否已启动。Spring中文文档

pingSpring中文文档

PingHealthIndicatorSpring中文文档

始终响应 .UPSpring中文文档

rabbitSpring中文文档

RabbitHealthIndicatorSpring中文文档

检查 Rabbit 服务器是否已启动。Spring中文文档

redisSpring中文文档

RedisHealthIndicatorSpring中文文档

检查 Redis 服务器是否已启动。Spring中文文档

您可以通过设置属性来禁用它们。management.health.defaults.enabled

其他可用,但默认情况下未启用:HealthIndicatorsSpring中文文档

钥匙 名字 描述

livenessstateSpring中文文档

LivenessStateHealthIndicatorSpring中文文档

公开“活动性”应用程序可用性状态。Spring中文文档

readinessstateSpring中文文档

ReadinessStateHealthIndicatorSpring中文文档

公开“就绪”应用程序可用性状态。Spring中文文档

编写自定义 HealthIndicators

要提供自定义运行状况信息,您可以注册实现 HealthIndicator 接口的 Spring Bean。 您需要提供该方法的实现并返回响应。 响应应包括状态,并且可以选择包含要显示的其他详细信息。 以下代码显示了一个示例实现:health()HealthHealthHealthIndicatorSpring中文文档

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyHealthIndicator implements HealthIndicator {

	@Override
	public Health health() {
		int errorCode = check();
		if (errorCode != 0) {
			return Health.down().withDetail("Error Code", errorCode).build();
		}
		return Health.up().build();
	}

	private int check() {
		// perform some specific health check
		return ...
	}

}
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.HealthIndicator
import org.springframework.stereotype.Component

@Component
class MyHealthIndicator : HealthIndicator {

	override fun health(): Health {
		val errorCode = check()
		if (errorCode != 0) {
			return Health.down().withDetail("Error Code", errorCode).build()
		}
		return Health.up().build()
	}

	private fun check(): Int {
		// perform some specific health check
		return  ...
	}

}
给定的标识符是不带后缀的 Bean 的名称(如果存在)。 在前面的示例中,运行状况信息在名为 的条目中可用。HealthIndicatorHealthIndicatormy
运行状况指示器通常通过 HTTP 调用,并且需要在任何连接超时之前做出响应。 Spring Boot 将记录任何响应时间超过 10 秒的运行状况指示器的警告消息。 如果要配置此阈值,可以使用该属性。management.endpoint.health.logging.slow-indicator-threshold

除了 Spring Boot 的预定义状态类型外,还可以返回表示新系统状态的自定义。 在这种情况下,还需要提供 StatusAggregator 接口的自定义实现,或者必须使用 configuration 属性配置默认实现。HealthStatusmanagement.endpoint.health.status.orderSpring中文文档

例如,假设您的某个实现中使用了代码为 of 的 new。 若要配置严重性顺序,请将以下属性添加到应用程序属性中:StatusFATALHealthIndicatorSpring中文文档

management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
management:
  endpoint:
    health:
      status:
        order: "fatal,down,out-of-service,unknown,up"

响应中的 HTTP 状态代码反映了整体运行状况。 默认情况下,映射到 503。 任何未映射的运行状况状态,包括 ,映射到 200。 如果通过 HTTP 访问运行状况终结点,您可能还需要注册自定义状态映射。 配置自定义映射将禁用 和 的默认映射。 如果要保留默认映射,则必须显式配置它们以及任何自定义映射。 例如,以下属性映射到 503(服务不可用),并保留 和 的默认映射:OUT_OF_SERVICEDOWNUPDOWNOUT_OF_SERVICEFATALDOWNOUT_OF_SERVICESpring中文文档

management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503
management:
  endpoint:
    health:
      status:
        http-mapping:
          down: 503
          fatal: 503
          out-of-service: 503
如果您需要更多控制,可以定义自己的 Bean。HttpCodeStatusMapper

下表显示了内置状态的默认状态映射:Spring中文文档

地位 映射

DOWNSpring中文文档

SERVICE_UNAVAILABLE (503)Spring中文文档

OUT_OF_SERVICESpring中文文档

SERVICE_UNAVAILABLE (503)Spring中文文档

UPSpring中文文档

默认情况下没有映射,因此 HTTP 状态为200Spring中文文档

UNKNOWNSpring中文文档

默认情况下没有映射,因此 HTTP 状态为200Spring中文文档

反应性健康指标

对于反应式应用程序(例如使用 Spring WebFlux 的应用程序),提供用于获取应用程序运行状况的非阻塞协定。 与传统 类似,运行状况信息是从 ReactiveHealthContributorRegistry 的内容中收集的(默认情况下,所有 HealthContributorReactiveHealthContributor 实例都定义在 中定义)。 不检查反应式 API 的常规程序在弹性调度程序上执行。ReactiveHealthContributorHealthContributorApplicationContextHealthContributorsSpring中文文档

在反应式应用程序中,应使用 to 在运行时注册和注销运行状况指示器。 如果你需要注册一个常规,你应该用 来包装它。ReactiveHealthContributorRegistryHealthContributorReactiveHealthContributor#adapt

要从响应式 API 提供自定义运行状况信息,您可以注册实现 ReactiveHealthIndicator 接口的 Spring bean。 以下代码显示了一个示例实现:ReactiveHealthIndicatorSpring中文文档

import reactor.core.publisher.Mono;

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

	@Override
	public Mono<Health> health() {
		return doHealthCheck().onErrorResume((exception) ->
			Mono.just(new Health.Builder().down(exception).build()));
	}

	private Mono<Health> doHealthCheck() {
		// perform some specific health check
		return ...
	}

}
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.ReactiveHealthIndicator
import org.springframework.stereotype.Component
import reactor.core.publisher.Mono

@Component
class MyReactiveHealthIndicator : ReactiveHealthIndicator {

	override fun health(): Mono<Health> {
		return doHealthCheck()!!.onErrorResume { exception: Throwable? ->
			Mono.just(Health.Builder().down(exception).build())
		}
	}

	private fun doHealthCheck(): Mono<Health>? {
		// perform some specific health check
		return  ...
	}

}
若要自动处理错误,请考虑从 扩展。AbstractReactiveHealthIndicator

自动配置的 ReactiveHealthIndicators

在适当的时候,Spring Boot会自动配置以下内容:ReactiveHealthIndicatorsSpring中文文档

钥匙 名字 描述

cassandraSpring中文文档

CassandraDriverReactiveHealthIndicatorSpring中文文档

检查 Cassandra 数据库是否已启动。Spring中文文档

couchbaseSpring中文文档

CouchbaseReactiveHealthIndicatorSpring中文文档

检查 Couchbase 群集是否已启动。Spring中文文档

elasticsearchSpring中文文档

ElasticsearchReactiveHealthIndicatorSpring中文文档

检查 Elasticsearch 集群是否已启动。Spring中文文档

mongoSpring中文文档

MongoReactiveHealthIndicatorSpring中文文档

检查 Mongo 数据库是否已启动。Spring中文文档

neo4jSpring中文文档

Neo4jReactiveHealthIndicatorSpring中文文档

检查 Neo4j 数据库是否已启动。Spring中文文档

redisSpring中文文档

RedisReactiveHealthIndicatorSpring中文文档

检查 Redis 服务器是否已启动。Spring中文文档

如有必要,反应性指标将取代常规指标。 此外,任何未显式处理的内容都会自动包装。HealthIndicator

健康团体

有时,将运行状况指示器组织成可用于不同目的的组很有用。Spring中文文档

若要创建运行状况指示器组,可以使用该属性并指定运行状况指示器 ID 的列表,以或 。 例如,若要创建仅包含数据库指示器的组,可以定义以下内容:management.endpoint.health.group.<name>includeexcludeSpring中文文档

management.endpoint.health.group.custom.include=db
management:
  endpoint:
    health:
      group:
        custom:
          include: "db"

然后,您可以通过点击来检查结果。localhost:8080/actuator/health/customSpring中文文档

同样,要创建一个从组中排除数据库指标并包含所有其他指标的组,您可以定义以下内容:Spring中文文档

management.endpoint.health.group.custom.exclude=db
management:
  endpoint:
    health:
      group:
        custom:
          exclude: "db"

默认情况下,如果运行状况组包含或排除不存在的运行状况指示器,则启动将失败。 若要禁用此行为,请设置为 。management.endpoint.health.validate-group-membershipfalseSpring中文文档

默认情况下,组继承与系统运行状况相同的设置。 但是,您也可以按组定义这些。 如果需要,还可以重写 and 属性:StatusAggregatorHttpCodeStatusMappershow-detailsrolesSpring中文文档

management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
management.endpoint.health.group.custom.status.order=fatal,up
management.endpoint.health.group.custom.status.http-mapping.fatal=500
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500
management:
  endpoint:
    health:
      group:
        custom:
          show-details: "when-authorized"
          roles: "admin"
          status:
            order: "fatal,up"
            http-mapping:
              fatal: 500
              out-of-service: 500
如果您需要注册自定义或 Bean 以用于组,则可以使用。@Qualifier("groupname")StatusAggregatorHttpCodeStatusMapper

运行状况组还可以包含/排除 . 您也可以仅包含/排除 . 这可以使用组件的完全限定名称来完成,如下所示:CompositeHealthContributorCompositeHealthContributorSpring中文文档

management.endpoint.health.group.custom.include="test/primary"
management.endpoint.health.group.custom.exclude="test/primary/b"

在上面的示例中,该组将包含名称为 的 ,该名称是复合体的一个组件。 在这里,它本身就是一个复合体,带有名称的将被排除在组之外。customHealthContributorprimarytestprimaryHealthContributorbcustomSpring中文文档

运行状况组可以在主端口或管理端口上的其他路径上可用。 这在 Kubernetes 等云环境中很有用,出于安全目的,通常为执行器端点使用单独的管理端口。 使用单独的端口可能会导致运行状况检查不可靠,因为即使运行状况检查成功,主应用程序也可能无法正常工作。 可以使用其他路径配置运行状况组,如下所示:Spring中文文档

management.endpoint.health.group.live.additional-path="server:/healthz"

这将使运行状况组在主服务器端口上可用。 前缀是必需的,必须是(表示主服务器端口)或(表示管理端口,如果已配置)。 路径必须是单个路径段。live/healthzserver:management:Spring中文文档

数据源运行状况

运行状况指示器显示标准数据源和路由数据源 Bean 的运行状况。 路由数据源的运行状况包括其每个目标数据源的运行状况。 在运行状况终结点的响应中,路由数据源的每个目标都使用其路由密钥进行命名。 如果您不希望在指标的输出中包含路由数据源,请设置为 。DataSourcemanagement.health.db.ignore-routing-data-sourcestrueSpring中文文档

名字 描述

neverSpring中文文档

从不显示详细信息。Spring中文文档

when-authorizedSpring中文文档

详细信息仅向授权用户显示。 可以使用 来配置授权角色。management.endpoint.health.rolesSpring中文文档

alwaysSpring中文文档

详细信息将显示给所有用户。Spring中文文档

如果已保护应用程序并希望使用 ,则安全配置必须允许经过身份验证和未经身份验证的用户访问运行状况终结点。always
可以使用 在运行时注册和注销运行状况指示器。HealthContributorRegistry
钥匙 名字 描述

cassandraSpring中文文档

CassandraDriverHealthIndicatorSpring中文文档

检查 Cassandra 数据库是否已启动。Spring中文文档

couchbaseSpring中文文档

CouchbaseHealthIndicatorSpring中文文档

检查 Couchbase 群集是否已启动。Spring中文文档

dbSpring中文文档

DataSourceHealthIndicatorSpring中文文档

检查是否可以获取与的连接。DataSourceSpring中文文档

diskspaceSpring中文文档

DiskSpaceHealthIndicatorSpring中文文档

检查磁盘空间是否不足。Spring中文文档

elasticsearchSpring中文文档

ElasticsearchRestClientHealthIndicatorSpring中文文档

检查 Elasticsearch 集群是否已启动。Spring中文文档

hazelcastSpring中文文档

HazelcastHealthIndicatorSpring中文文档

检查 Hazelcast 服务器是否已启动。Spring中文文档

influxdbSpring中文文档

InfluxDbHealthIndicatorSpring中文文档

检查 InfluxDB 服务器是否已启动。Spring中文文档

jmsSpring中文文档

JmsHealthIndicatorSpring中文文档

检查 JMS 代理是否已启动。Spring中文文档

ldapSpring中文文档

LdapHealthIndicatorSpring中文文档

检查 LDAP 服务器是否已启动。Spring中文文档

mailSpring中文文档

MailHealthIndicatorSpring中文文档

检查邮件服务器是否已启动。Spring中文文档

mongoSpring中文文档

MongoHealthIndicatorSpring中文文档

检查 Mongo 数据库是否已启动。Spring中文文档

neo4jSpring中文文档

Neo4jHealthIndicatorSpring中文文档

检查 Neo4j 数据库是否已启动。Spring中文文档

pingSpring中文文档

PingHealthIndicatorSpring中文文档

始终响应 .UPSpring中文文档

rabbitSpring中文文档

RabbitHealthIndicatorSpring中文文档

检查 Rabbit 服务器是否已启动。Spring中文文档

redisSpring中文文档

RedisHealthIndicatorSpring中文文档

检查 Redis 服务器是否已启动。Spring中文文档

您可以通过设置属性来禁用它们。management.health.defaults.enabled
钥匙 名字 描述

livenessstateSpring中文文档

LivenessStateHealthIndicatorSpring中文文档

公开“活动性”应用程序可用性状态。Spring中文文档

readinessstateSpring中文文档

ReadinessStateHealthIndicatorSpring中文文档

公开“就绪”应用程序可用性状态。Spring中文文档

给定的标识符是不带后缀的 Bean 的名称(如果存在)。 在前面的示例中,运行状况信息在名为 的条目中可用。HealthIndicatorHealthIndicatormy
运行状况指示器通常通过 HTTP 调用,并且需要在任何连接超时之前做出响应。 Spring Boot 将记录任何响应时间超过 10 秒的运行状况指示器的警告消息。 如果要配置此阈值,可以使用该属性。management.endpoint.health.logging.slow-indicator-threshold
如果您需要更多控制,可以定义自己的 Bean。HttpCodeStatusMapper
地位 映射

DOWNSpring中文文档

SERVICE_UNAVAILABLE (503)Spring中文文档

OUT_OF_SERVICESpring中文文档

SERVICE_UNAVAILABLE (503)Spring中文文档

UPSpring中文文档

默认情况下没有映射,因此 HTTP 状态为200Spring中文文档

UNKNOWNSpring中文文档

默认情况下没有映射,因此 HTTP 状态为200Spring中文文档

在反应式应用程序中,应使用 to 在运行时注册和注销运行状况指示器。 如果你需要注册一个常规,你应该用 来包装它。ReactiveHealthContributorRegistryHealthContributorReactiveHealthContributor#adapt
若要自动处理错误,请考虑从 扩展。AbstractReactiveHealthIndicator
钥匙 名字 描述

cassandraSpring中文文档

CassandraDriverReactiveHealthIndicatorSpring中文文档

检查 Cassandra 数据库是否已启动。Spring中文文档

couchbaseSpring中文文档

CouchbaseReactiveHealthIndicatorSpring中文文档

检查 Couchbase 群集是否已启动。Spring中文文档

elasticsearchSpring中文文档

ElasticsearchReactiveHealthIndicatorSpring中文文档

检查 Elasticsearch 集群是否已启动。Spring中文文档

mongoSpring中文文档

MongoReactiveHealthIndicatorSpring中文文档

检查 Mongo 数据库是否已启动。Spring中文文档

neo4jSpring中文文档

Neo4jReactiveHealthIndicatorSpring中文文档

检查 Neo4j 数据库是否已启动。Spring中文文档

redisSpring中文文档

RedisReactiveHealthIndicatorSpring中文文档

检查 Redis 服务器是否已启动。Spring中文文档

如有必要,反应性指标将取代常规指标。 此外,任何未显式处理的内容都会自动包装。HealthIndicator
如果您需要注册自定义或 Bean 以用于组,则可以使用。@Qualifier("groupname")StatusAggregatorHttpCodeStatusMapper

Kubernetes 探测器

部署在 Kubernetes 上的应用程序可以通过容器探测提供有关其内部状态的信息。 根据您的 Kubernetes 配置,kubelet 会调用这些探测器并对结果做出反应。Spring中文文档

默认情况下,Spring Boot 管理您的应用程序可用性状态。 如果部署在 Kubernetes 环境中,执行器会从界面收集“活动”和“就绪”信息,并将该信息用于专用的运行状况指示器:和 。 这些指标显示在全局运行状况终点 () 上。 通过使用运行状况组,它们还作为单独的 HTTP 探测器公开: 和 .ApplicationAvailabilityLivenessStateHealthIndicatorReadinessStateHealthIndicator"/actuator/health""/actuator/health/liveness""/actuator/health/readiness"Spring中文文档

然后,您可以使用以下端点信息配置 Kubernetes 基础架构:Spring中文文档

livenessProbe:
  httpGet:
    path: "/actuator/health/liveness"
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

readinessProbe:
  httpGet:
    path: "/actuator/health/readiness"
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...
<actuator-port>应设置为执行器端点可用的端口。 如果已设置该属性,它可以是主 Web 服务器端口或单独的管理端口。"management.server.port"

仅当应用程序在 Kubernetes 环境中运行时,才会自动启用这些运行状况组。 可以使用配置属性在任何环境中启用它们。management.endpoint.health.probes.enabledSpring中文文档

如果应用程序启动时间超过配置的存活期,Kubernetes 会提到这是一个可能的解决方案。 一般来说,这里不一定需要 ,因为在完成所有启动任务之前会失败。 这意味着您的应用程序在准备就绪之前不会收到流量。 但是,如果您的应用程序需要很长时间才能启动,请考虑使用 a 来确保 Kubernetes 不会在启动过程中终止您的应用程序。 请参阅介绍探测器在应用程序生命周期中的行为方式的部分。"startupProbe""startupProbe""readinessProbe""startupProbe"

如果您的 Actuator 端点部署在单独的管理上下文中,则这些端点不会使用与主应用程序相同的 Web 基础架构(端口、连接池、框架组件)。 在这种情况下,即使主应用程序无法正常工作(例如,它无法接受新连接),探测检查也可能成功。 因此,最好在主服务器端口上提供 和 运行状况组。 这可以通过设置以下属性来完成:livenessreadinessSpring中文文档

management.endpoint.health.probes.add-additional-paths=true

这将使组在主服务器端口上可用,而组在主服务器端口上可用。 可以使用每个组的属性自定义路径,有关详细信息,请参阅运行状况组liveness/livezreadiness/readyzadditional-pathSpring中文文档

使用 Kubernetes 探测器检查外部状态

Actuator 将“活动”和“就绪”探测器配置为运行状况组。 这意味着所有运行状况组功能都可供他们使用。 例如,您可以配置其他运行状况指示器:Spring中文文档

management.endpoint.health.group.readiness.include=readinessState,customCheck
management:
  endpoint:
    health:
      group:
        readiness:
          include: "readinessState,customCheck"

默认情况下,Spring Boot 不会向这些组添加其他运行状况指示器。Spring中文文档

“活动”探测不应依赖于外部系统的运行状况检查。 如果应用程序的活跃状态被破坏,Kubernetes 会尝试通过重新启动应用程序实例来解决这个问题。 这意味着,如果外部系统(如数据库、Web API 或外部缓存)发生故障,Kubernetes 可能会重新启动所有应用程序实例并创建级联故障。Spring中文文档

至于“就绪”探测,应用程序开发人员必须仔细选择检查外部系统。 因此,Spring Boot 在就绪性探测中不包含任何其他运行状况检查。 如果应用程序实例的就绪状态为“未就绪”,则 Kubernetes 不会将流量路由到该实例。 某些外部系统可能不由应用程序实例共享,在这种情况下,它们可能包含在就绪性探测中。 其他外部系统可能对应用程序不是必需的(应用程序可能具有断路器和回退),在这种情况下,它们绝对不应包括在内。 遗憾的是,由所有应用程序实例共享的外部系统很常见,您必须做出判断调用:将其包含在就绪性探测中,并期望应用程序在外部服务关闭时停止服务,或者将其排除在外并处理堆栈上层的故障,也许通过在调用方中使用断路器。Spring中文文档

如果应用程序的所有实例都未就绪,则 Kubernetes 服务接受或不接受任何传入连接。 没有 HTTP 错误响应(503 等),因为没有连接。 可能接受也可能不接受连接的服务,具体取决于提供程序。 具有显式入口的服务也以依赖于实现的方式进行响应,即入口服务本身必须决定如何处理来自下游的“拒绝连接”。 HTTP 503 很可能同时适用于负载均衡器和入口。type=ClusterIPNodePorttype=LoadBalancer

此外,如果应用程序使用 Kubernetes 自动缩放,它可能会对从负载均衡器中删除的应用程序做出不同的反应,具体取决于其自动缩放器配置。Spring中文文档

应用程序生命周期和探测状态

Kubernetes Probes 支持的一个重要方面是它与应用程序生命周期的一致性。 (这是应用程序的内存中内部状态)之间存在显着差异 以及实际的探测器(公开该状态)。 根据应用程序生命周期的阶段,探测器可能不可用。AvailabilityStateSpring中文文档

Spring Boot 在启动和关闭期间发布应用程序事件, 探测器可以侦听此类事件并公开信息。AvailabilityStateSpring中文文档

下表显示了 HTTP 连接器在不同阶段的状态。AvailabilityStateSpring中文文档

当 Spring Boot 应用程序启动时:Spring中文文档

启动阶段 Liveness状态 就绪状态 HTTP 服务器 笔记

开始Spring中文文档

BROKENSpring中文文档

REFUSING_TRAFFICSpring中文文档

未开始Spring中文文档

Kubernetes 会检查“活动”探测器,如果时间过长,则重新启动应用程序。Spring中文文档

开始Spring中文文档

CORRECTSpring中文文档

REFUSING_TRAFFICSpring中文文档

拒绝请求Spring中文文档

应用程序上下文将刷新。应用程序执行启动任务,但尚未接收流量。Spring中文文档

准备Spring中文文档

CORRECTSpring中文文档

ACCEPTING_TRAFFICSpring中文文档

接受请求Spring中文文档

启动任务已完成。应用程序正在接收流量。Spring中文文档

当 Spring Boot 应用程序关闭时:Spring中文文档

关断阶段 活体状态 就绪状态 HTTP 服务器 笔记

运行Spring中文文档

CORRECTSpring中文文档

ACCEPTING_TRAFFICSpring中文文档

接受请求Spring中文文档

已请求关闭。Spring中文文档

正常关机Spring中文文档

CORRECTSpring中文文档

REFUSING_TRAFFICSpring中文文档

新请求被拒绝Spring中文文档

如果启用,则正常关机将处理正在进行的请求Spring中文文档

关机完成Spring中文文档

不适用Spring中文文档

不适用Spring中文文档

服务器已关闭Spring中文文档

应用程序上下文已关闭,应用程序将关闭。Spring中文文档

有关 Kubernetes 部署的更多信息,请参阅 Kubernetes 容器生命周期部分
<actuator-port>应设置为执行器端点可用的端口。 如果已设置该属性,它可以是主 Web 服务器端口或单独的管理端口。"management.server.port"
如果应用程序启动时间超过配置的存活期,Kubernetes 会提到这是一个可能的解决方案。 一般来说,这里不一定需要 ,因为在完成所有启动任务之前会失败。 这意味着您的应用程序在准备就绪之前不会收到流量。 但是,如果您的应用程序需要很长时间才能启动,请考虑使用 a 来确保 Kubernetes 不会在启动过程中终止您的应用程序。 请参阅介绍探测器在应用程序生命周期中的行为方式的部分。"startupProbe""startupProbe""readinessProbe""startupProbe"
如果应用程序的所有实例都未就绪,则 Kubernetes 服务接受或不接受任何传入连接。 没有 HTTP 错误响应(503 等),因为没有连接。 可能接受也可能不接受连接的服务,具体取决于提供程序。 具有显式入口的服务也以依赖于实现的方式进行响应,即入口服务本身必须决定如何处理来自下游的“拒绝连接”。 HTTP 503 很可能同时适用于负载均衡器和入口。type=ClusterIPNodePorttype=LoadBalancer
启动阶段 Liveness状态 就绪状态 HTTP 服务器 笔记

开始Spring中文文档

BROKENSpring中文文档

REFUSING_TRAFFICSpring中文文档

未开始Spring中文文档

Kubernetes 会检查“活动”探测器,如果时间过长,则重新启动应用程序。Spring中文文档

开始Spring中文文档

CORRECTSpring中文文档

REFUSING_TRAFFICSpring中文文档

拒绝请求Spring中文文档

应用程序上下文将刷新。应用程序执行启动任务,但尚未接收流量。Spring中文文档

准备Spring中文文档

CORRECTSpring中文文档

ACCEPTING_TRAFFICSpring中文文档

接受请求Spring中文文档

启动任务已完成。应用程序正在接收流量。Spring中文文档

关断阶段 活体状态 就绪状态 HTTP 服务器 笔记

运行Spring中文文档

CORRECTSpring中文文档

ACCEPTING_TRAFFICSpring中文文档

接受请求Spring中文文档

已请求关闭。Spring中文文档

正常关机Spring中文文档

CORRECTSpring中文文档

REFUSING_TRAFFICSpring中文文档

新请求被拒绝Spring中文文档

如果启用,则正常关机将处理正在进行的请求Spring中文文档

关机完成Spring中文文档

不适用Spring中文文档

不适用Spring中文文档

服务器已关闭Spring中文文档

应用程序上下文已关闭,应用程序将关闭。Spring中文文档

有关 Kubernetes 部署的更多信息,请参阅 Kubernetes 容器生命周期部分

申请资料

应用程序信息公开从 . 中定义的所有 InfoContributor bean 收集的各种信息。 Spring Boot 包含许多自动配置的 bean,您可以编写自己的 bean。ApplicationContextInfoContributorSpring中文文档

自动配置的 InfoContributors

在适当的时候,Spring 会自动配置以下 bean:InfoContributorSpring中文文档

编号 名字 描述 先决条件

buildSpring中文文档

BuildInfoContributorSpring中文文档

公开生成信息。Spring中文文档

一种资源。META-INF/build-info.propertiesSpring中文文档

envSpring中文文档

EnvironmentInfoContributorSpring中文文档

公开其名称以 开头的任何属性。Environmentinfo.Spring中文文档

没有。Spring中文文档

gitSpring中文文档

GitInfoContributorSpring中文文档

公开 git 信息。Spring中文文档

一种资源。git.propertiesSpring中文文档

javaSpring中文文档

JavaInfoContributorSpring中文文档

公开 Java 运行时信息。Spring中文文档

没有。Spring中文文档

osSpring中文文档

OsInfoContributorSpring中文文档

公开操作系统信息。Spring中文文档

没有。Spring中文文档

processSpring中文文档

ProcessInfoContributorSpring中文文档

公开进程信息。Spring中文文档

没有。Spring中文文档

是否启用单个贡献者由其属性控制。 不同的参与者对此属性具有不同的默认值,具体取决于其先决条件和他们公开的信息的性质。management.info.<id>.enabledSpring中文文档

由于没有指示应启用它们的先决条件,因此默认情况下禁用 、 、 和 contributors。 可以通过将其属性设置为 来启用每个 。envjavaosprocessmanagement.info.<id>.enabledtrueSpring中文文档

默认情况下,和 info 参与者处于启用状态。 可以通过将其属性设置为 来禁用每个 。 或者,若要禁用通常默认启用的每个参与者,请将该属性设置为 。buildgitmanagement.info.<id>.enabledfalsemanagement.info.defaults.enabledfalseSpring中文文档

自定义应用程序信息

启用参与者后,可以通过设置 Spring 属性来自定义终结点公开的数据。 键下的所有属性都会自动公开。 例如,您可以将以下设置添加到文件中:envinfoinfo.*Environmentinfoapplication.propertiesSpring中文文档

info.app.encoding=UTF-8
info.app.java.source=17
info.app.java.target=17
info:
  app:
    encoding: "UTF-8"
    java:
      source: "17"
      target: "17"

除了对这些值进行硬编码外,还可以在生成时扩展信息属性Spring中文文档

假设您使用 Maven,您可以重写前面的示例,如下所示:Spring中文文档

info:
  app:
    encoding: "@project.build.sourceEncoding@"
    java:
      source: "@java.version@"
      target: "@java.version@"

Git 提交信息

端点的另一个有用功能是,它能够在构建项目时发布有关源代码存储库状态的信息。 如果 Bean 可用,则可以使用端点来公开这些属性。infogitGitPropertiesinfoSpring中文文档

如果类路径的根目录中有可用的文件,则会自动配置 Bean。 有关详细信息,请参阅“如何生成 git 信息”。GitPropertiesgit.properties

默认情况下,终结点会公开 、 和属性(如果存在)。 如果不希望在终结点响应中使用任何这些属性,则需要从文件中排除这些属性。 如果要显示完整的 git 信息(即 的完整内容),请使用该属性,如下所示:git.branchgit.commit.idgit.commit.timegit.propertiesgit.propertiesmanagement.info.git.modeSpring中文文档

management.info.git.mode=full
management:
  info:
    git:
      mode: "full"

若要完全禁用终结点的 git 提交信息,请将属性设置为 ,如下所示:infomanagement.info.git.enabledfalseSpring中文文档

management.info.git.enabled=false
management:
  info:
    git:
      enabled: false

构建信息

如果 Bean 可用,则终端节点还可以发布有关构建的信息。 如果类路径中有可用的文件,则会发生这种情况。BuildPropertiesinfoMETA-INF/build-info.propertiesSpring中文文档

Maven 和 Gradle 插件都可以生成该文件。 有关详细信息,请参阅“如何生成生成信息”。

Java 信息

端点发布有关 Java 运行时环境的信息,有关详细信息,请参阅 JavaInfoinfoSpring中文文档

操作系统信息

端点发布有关操作系统的信息,有关详细信息,请参阅 OsInfoinfoSpring中文文档

工艺信息

终结点发布有关进程的信息,有关详细信息,请参阅 ProcessInfoinfoSpring中文文档

编写自定义信息贡献者

若要提供自定义应用程序信息,可以注册实现 InfoContributor 接口的 Spring Bean。Spring中文文档

以下示例提供具有单个值的条目:exampleSpring中文文档

import java.util.Collections;

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

@Component
public class MyInfoContributor implements InfoContributor {

	@Override
	public void contribute(Info.Builder builder) {
		builder.withDetail("example", Collections.singletonMap("key", "value"));
	}

}
import org.springframework.boot.actuate.info.Info
import org.springframework.boot.actuate.info.InfoContributor
import org.springframework.stereotype.Component
import java.util.Collections

@Component
class MyInfoContributor : InfoContributor {

	override fun contribute(builder: Info.Builder) {
		builder.withDetail("example", Collections.singletonMap("key", "value"))
	}

}

如果到达终结点,应会看到包含以下附加条目的响应:infoSpring中文文档

{
	"example": {
		"key" : "value"
	}
}
编号 名字 描述 先决条件

buildSpring中文文档

BuildInfoContributorSpring中文文档

公开生成信息。Spring中文文档

一种资源。META-INF/build-info.propertiesSpring中文文档

envSpring中文文档

EnvironmentInfoContributorSpring中文文档

公开其名称以 开头的任何属性。Environmentinfo.Spring中文文档

没有。Spring中文文档

gitSpring中文文档

GitInfoContributorSpring中文文档

公开 git 信息。Spring中文文档

一种资源。git.propertiesSpring中文文档

javaSpring中文文档

JavaInfoContributorSpring中文文档

公开 Java 运行时信息。Spring中文文档

没有。Spring中文文档

osSpring中文文档

OsInfoContributorSpring中文文档

公开操作系统信息。Spring中文文档

没有。Spring中文文档

processSpring中文文档

ProcessInfoContributorSpring中文文档

公开进程信息。Spring中文文档

没有。Spring中文文档

除了对这些值进行硬编码外,还可以在生成时扩展信息属性Spring中文文档

假设您使用 Maven,您可以重写前面的示例,如下所示:Spring中文文档

info:
  app:
    encoding: "@project.build.sourceEncoding@"
    java:
      source: "@java.version@"
      target: "@java.version@"
如果类路径的根目录中有可用的文件,则会自动配置 Bean。 有关详细信息,请参阅“如何生成 git 信息”。GitPropertiesgit.properties
Maven 和 Gradle 插件都可以生成该文件。 有关详细信息,请参阅“如何生成生成信息”。

软件物料清单 (SBOM)

终结点公开软件物料清单。 CycloneDX SBOM可以自动检测,但也可以手动配置其他格式。sbomSpring中文文档

Maven 父插件和 Spring Boot Gradle 插件分别配置了 CycloneDX Maven 插件CycloneDX Gradle 插件spring-boot-starter-parentSpring中文文档

要获得 CycloneDX SBOM,您需要将其添加到您的 Maven 构建中:Spring中文文档

<build>
    <plugins>
        <plugin>
            <groupId>org.cyclonedx</groupId>
            <artifactId>cyclonedx-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

对于 Gradle,您需要应用 CycloneDX Gradle 插件:Spring中文文档

plugins {
    id 'org.cyclonedx.bom' version '1.8.2'
}

然后,执行器端点将公开一个名为“application”的 SBOM,用于描述应用程序的内容。sbomSpring中文文档

其他 SBOM 格式

如果要以不同的格式发布 SBOM,可以使用一些配置属性。Spring中文文档

configuration 属性设置应用程序 SBOM 的位置。 例如,如果将 this 设置为将使用类路径上的资源内容。management.endpoint.sbom.application.locationclasspath:sbom.json/sbom.jsonSpring中文文档

自动检测 CycloneDX、SPDX 和 Syft 格式的 SBOM 介质类型。 若要覆盖自动检测的媒体类型,请使用 configuration 属性 。management.endpoint.sbom.application.media-typeSpring中文文档

其他 SBOM

执行器端点可以处理多个 SBOM。 若要添加 SBOM,请使用 configuration 属性,如以下示例所示:management.endpoint.sbom.additionalSpring中文文档

management.endpoint.sbom.additional.system.location=optional:file:/system.spdx.json
management.endpoint.sbom.additional.system.media-type=application/spdx+json
management:
  endpoint:
    sbom:
      additional:
        system:
          location: "optional:file:/system.spdx.json"
          media-type: "application/spdx+json"

这将添加一个名为“system”的 SBOM,它存储在 . 如果文件不存在,则可以使用前缀来防止启动失败。/system.spdx.jsonoptional:Spring中文文档