此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.3.4！spring-doc.cn

此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.3.4！spring-doc.cn

Actuator 终端节点允许您监控应用程序并与之交互。 Spring Boot 包含许多内置端点，并允许您添加自己的端点。 例如，终端节点提供基本的应用程序运行状况信息。healthspring-doc.cn

您可以启用或禁用每个单独的终端节点，并通过 HTTP 或 JMX 公开它们（使其可远程访问）。 当终端节点同时启用和公开时，该终端节点被视为可用。 仅当内置终端节点可用时，才会自动配置这些终端节点。 大多数应用程序选择通过 HTTP 进行公开，其中终端节点的 ID 和前缀映射到 URL。 例如，默认情况下，端点映射到 ./actuatorhealth/actuator/healthspring-doc.cn

要了解有关 Actuator 的终端节点及其请求和响应格式的更多信息，请参阅 API 文档。

以下与技术无关的终端节点可用：spring-doc.cn

身份证 描述

auditeventsspring-doc.cn

公开当前应用程序的审计事件信息。 需要一个 bean。AuditEventRepositoryspring-doc.cn

beansspring-doc.cn

显示应用程序中所有 Spring bean 的完整列表。spring-doc.cn

cachesspring-doc.cn

公开可用的缓存。spring-doc.cn

conditionsspring-doc.cn

显示在 configuration 和 auto-configuration 类上评估的条件，以及它们匹配或不匹配的原因。spring-doc.cn

configpropsspring-doc.cn

显示所有 的整理列表。 需进行消毒。@ConfigurationPropertiesspring-doc.cn

envspring-doc.cn

公开 Spring 的 . 需进行消毒。ConfigurableEnvironmentspring-doc.cn

flywayspring-doc.cn

显示已应用的任何 Flyway 数据库迁移。 需要一个或多个 bean。Flywayspring-doc.cn

healthspring-doc.cn

显示应用程序运行状况信息。spring-doc.cn

httpexchangesspring-doc.cn

显示 HTTP 交换信息（默认情况下，最后 100 个 HTTP 请求-响应交换）。 需要一个 bean。HttpExchangeRepositoryspring-doc.cn

infospring-doc.cn

显示任意应用程序信息。spring-doc.cn

integrationgraphspring-doc.cn

显示 Spring 集成图。 需要依赖 。spring-integration-corespring-doc.cn

loggersspring-doc.cn

显示和修改应用程序中记录器的配置。spring-doc.cn

liquibasespring-doc.cn

显示已应用的任何 Liquibase 数据库迁移。 需要一个或多个 bean。Liquibasespring-doc.cn

metricsspring-doc.cn

显示当前应用程序的 “metrics” 信息。spring-doc.cn

mappingsspring-doc.cn

显示所有路径的整理列表。@RequestMappingspring-doc.cn

quartzspring-doc.cn

显示有关 Quartz Scheduler 作业的信息。 需进行消毒。spring-doc.cn

scheduledtasksspring-doc.cn

显示应用程序中的计划任务。spring-doc.cn

sessionsspring-doc.cn

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

shutdownspring-doc.cn

允许正常关闭应用程序。 仅在使用 jar 打包时有效。 默认处于禁用状态。spring-doc.cn

startupspring-doc.cn

显示 收集的启动步骤数据。 需要使用 进行配置。ApplicationStartupSpringApplicationBufferingApplicationStartupspring-doc.cn

threaddumpspring-doc.cn

执行线程转储。spring-doc.cn

如果您的应用程序是 Web 应用程序（Spring MVC、Spring WebFlux 或 Jersey），则可以使用以下附加端点：spring-doc.cn

身份证 描述

heapdumpspring-doc.cn

返回堆转储文件。 在 HotSpot JVM 上，将返回 -format 文件。 在 OpenJ9 JVM 上，将返回 -format 文件。HPROFPHDspring-doc.cn

logfilespring-doc.cn

返回日志文件的内容（如果已设置 or 属性）。 支持使用 HTTP 标头检索日志文件的部分内容。logging.file.namelogging.file.pathRangespring-doc.cn

prometheusspring-doc.cn

以 Prometheus 服务器可抓取的格式公开指标。 需要依赖 。micrometer-registry-prometheusspring-doc.cn
要了解有关 Actuator 的终端节点及其请求和响应格式的更多信息，请参阅 API 文档。
身份证 描述

auditeventsspring-doc.cn

公开当前应用程序的审计事件信息。 需要一个 bean。AuditEventRepositoryspring-doc.cn

beansspring-doc.cn

显示应用程序中所有 Spring bean 的完整列表。spring-doc.cn

cachesspring-doc.cn

公开可用的缓存。spring-doc.cn

conditionsspring-doc.cn

显示在 configuration 和 auto-configuration 类上评估的条件，以及它们匹配或不匹配的原因。spring-doc.cn

configpropsspring-doc.cn

显示所有 的整理列表。 需进行消毒。@ConfigurationPropertiesspring-doc.cn

envspring-doc.cn

公开 Spring 的 . 需进行消毒。ConfigurableEnvironmentspring-doc.cn

flywayspring-doc.cn

显示已应用的任何 Flyway 数据库迁移。 需要一个或多个 bean。Flywayspring-doc.cn

healthspring-doc.cn

显示应用程序运行状况信息。spring-doc.cn

httpexchangesspring-doc.cn

显示 HTTP 交换信息（默认情况下，最后 100 个 HTTP 请求-响应交换）。 需要一个 bean。HttpExchangeRepositoryspring-doc.cn

infospring-doc.cn

显示任意应用程序信息。spring-doc.cn

integrationgraphspring-doc.cn

显示 Spring 集成图。 需要依赖 。spring-integration-corespring-doc.cn

loggersspring-doc.cn

显示和修改应用程序中记录器的配置。spring-doc.cn

liquibasespring-doc.cn

显示已应用的任何 Liquibase 数据库迁移。 需要一个或多个 bean。Liquibasespring-doc.cn

metricsspring-doc.cn

显示当前应用程序的 “metrics” 信息。spring-doc.cn

mappingsspring-doc.cn

显示所有路径的整理列表。@RequestMappingspring-doc.cn

quartzspring-doc.cn

显示有关 Quartz Scheduler 作业的信息。 需进行消毒。spring-doc.cn

scheduledtasksspring-doc.cn

显示应用程序中的计划任务。spring-doc.cn

sessionsspring-doc.cn

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

shutdownspring-doc.cn

允许正常关闭应用程序。 仅在使用 jar 打包时有效。 默认处于禁用状态。spring-doc.cn

startupspring-doc.cn

显示 收集的启动步骤数据。 需要使用 进行配置。ApplicationStartupSpringApplicationBufferingApplicationStartupspring-doc.cn

threaddumpspring-doc.cn

执行线程转储。spring-doc.cn
身份证 描述

heapdumpspring-doc.cn

返回堆转储文件。 在 HotSpot JVM 上，将返回 -format 文件。 在 OpenJ9 JVM 上，将返回 -format 文件。HPROFPHDspring-doc.cn

logfilespring-doc.cn

返回日志文件的内容（如果已设置 or 属性）。 支持使用 HTTP 标头检索日志文件的部分内容。logging.file.namelogging.file.pathRangespring-doc.cn

prometheusspring-doc.cn

以 Prometheus 服务器可抓取的格式公开指标。 需要依赖 。micrometer-registry-prometheusspring-doc.cn

启用终端节点

默认情况下，除 之外的所有端点都处于启用状态。 要配置端点的启用，请使用其属性。 以下示例启用终端节点：shutdownmanagement.endpoint.<id>.enabledshutdownspring-doc.cn

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

如果您希望终端节点启用选择加入而不是选择退出，请将该属性设置为并使用单个终端节点属性来选择重新加入。 以下示例启用终端节点并禁用所有其他终端节点：management.endpoints.enabled-by-defaultfalseenabledinfospring-doc.cn

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

公开端点

默认情况下，仅通过 HTTP 和 JMX 公开运行状况终端节点。 由于 Endpoints 可能包含敏感信息，因此您应该仔细考虑何时公开它们。spring-doc.cn

要更改公开的终端节点，请使用以下特定于技术的 and 属性：includeexcludespring-doc.cn

财产 违约

management.endpoints.jmx.exposure.excludespring-doc.cn

management.endpoints.jmx.exposure.includespring-doc.cn

healthspring-doc.cn

management.endpoints.web.exposure.excludespring-doc.cn

management.endpoints.web.exposure.includespring-doc.cn

healthspring-doc.cn

该属性列出了公开的终端节点的 ID。 该属性列出了不应公开的端点的 ID。 该属性优先于该属性。 您可以使用终端节点 ID 列表配置 和 属性。includeexcludeexcludeincludeincludeexcludespring-doc.cn

例如，要仅通过 JMX 公开 and 端点，请使用以下属性：healthinfospring-doc.cn

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

*可用于选择所有端点。 例如，要通过 HTTP 公开除 和 endpoints 之外的所有内容，请使用以下属性：envbeansspring-doc.cn

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-doc.cn

management.endpoints.jmx.exposure.includespring-doc.cn

healthspring-doc.cn

management.endpoints.web.exposure.excludespring-doc.cn

management.endpoints.web.exposure.includespring-doc.cn

healthspring-doc.cn
*在 YAML 中具有特殊含义，因此如果要包含（或排除）所有终端节点，请务必添加引号。
如果您的应用程序公开，我们强烈建议您同时保护终端节点。
如果要在公开端点时实现自己的策略，则可以注册一个 Bean。EndpointFilter

安全

出于安全考虑，默认情况下，仅通过 HTTP 公开终端节点。 您可以使用该属性来配置公开的终端节点。/healthmanagement.endpoints.web.exposure.includespring-doc.cn

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

如果 Spring Security 在 Classpath 上并且不存在其他 bean，则除 Spring Boot 自动配置外的所有执行器都受到保护。 如果你定义了一个自定义 bean，Spring Boot 自动配置就会退缩，并允许你完全控制 actuator 访问规则。SecurityFilterChain/healthSecurityFilterChainspring-doc.cn

如果你希望为 HTTP 端点配置自定义安全性（例如，仅允许具有特定角色的用户访问它们），Spring Boot 提供了一些方便的对象，你可以将这些对象与 Spring Security 结合使用。RequestMatcherspring-doc.cn

典型的 Spring Security 配置可能类似于以下示例：spring-doc.cn

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-doc.cn

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

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

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

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()
	}

}
在上述两个示例中，配置仅适用于 actuator 终端节点。 由于 Spring Boot 的安全配置在存在任何 bean 的情况下完全退缩，因此您需要配置一个额外的 bean，其中包含适用于应用程序其余部分的规则。SecurityFilterChainSecurityFilterChain

跨站点请求伪造保护

由于 Spring Boot 依赖于 Spring Security 的默认值，因此 CSRF 保护默认处于打开状态。 这意味着在使用默认安全配置时，需要 （shutdown 和 loggers endpoints s）、a 或 a 的 actuator endpoints 会出现 403 （forbidden） 错误。POSTPUTDELETEspring-doc.cn

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

您可以在 Spring Security 参考指南中找到有关 CSRF 保护的其他信息。spring-doc.cn

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

配置端点

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

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

清理敏感值

和 endpoints 返回的信息可能是敏感的，因此默认情况下，值始终被完全清理（替换为）。/env/configprops/quartz******spring-doc.cn

只有在以下情况下，才能以未经清理的形式查看值：spring-doc.cn

可以将可清理终端节点的属性配置为以下值之一：show-valuesspring-doc.cn

  • NEVER- 值始终被完全清理（替换为******)spring-doc.cn

  • ALWAYS- 向所有用户显示值（只要没有 bean 适用）SanitizingFunctionspring-doc.cn

  • WHEN_AUTHORIZED- 值仅向授权用户显示（只要没有 Bean 适用）SanitizingFunctionspring-doc.cn

对于 HTTP 端点，如果用户已经过身份验证并且角色由端点的 roles 属性配置，则认为该用户已获得授权。 默认情况下，任何经过身份验证的用户都已获得授权。spring-doc.cn

对于 JMX 终端节点，所有用户始终获得授权。spring-doc.cn

以下示例允许具有该角色的所有用户以原始格式查看终端节点中的值。 未经授权的用户或没有该角色的用户将只能看到经过清理的值。admin/envadminspring-doc.cn

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

用于 Actuator Web 端点的超媒体

将添加一个“发现页面”，其中包含指向所有终端节点的链接。 默认情况下，“发现页面”处于打开状态。/actuatorspring-doc.cn

要禁用“发现页面”，请将以下属性添加到您的应用程序属性中：spring-doc.cn

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

配置自定义管理上下文路径后，“发现页面” 会自动从管理上下文移动到根目录。 例如，如果管理上下文路径为 ，则可从 获取发现页面。 当 Management context path 设置为 时，将禁用发现页面，以防止与其他映射发生冲突。/actuator/management/management/spring-doc.cn

CORS 支持

跨域资源共享 （CORS） 是一种 W3C 规范，可让您以灵活的方式指定授权的跨域请求类型。 如果您使用 Spring MVC 或 Spring WebFlux，则可以配置 Actuator 的 Web 端点以支持此类场景。spring-doc.cn

CORS 支持默认处于禁用状态，并且仅在您设置了属性后才会启用。 以下配置允许和调用来自域：management.endpoints.web.cors.allowed-originsGETPOSTexample.comspring-doc.cn

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

实现自定义端点

如果添加带有 注释 、 则任何带有 、 注释的方法，或者通过 JMX 和 Web 应用程序中的 HTTP 自动公开。 可以使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开端点。 如果 Jersey 和 Spring MVC 都可用，则使用 Spring MVC。@Bean@Endpoint@ReadOperation@WriteOperation@DeleteOperationspring-doc.cn

以下示例公开返回自定义对象的读取操作：spring-doc.cn

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

您还可以使用 或 编写特定于技术的终端节点。 这些终端节点仅限于各自的技术。 例如，仅通过 HTTP 公开，而不通过 JMX 公开。@JmxEndpoint@WebEndpoint@WebEndpointspring-doc.cn

您可以使用 和 编写特定于技术的扩展。 这些注释允许您提供特定于技术的操作来增强现有终端节点。@EndpointWebExtension@EndpointJmxExtensionspring-doc.cn

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

接收输入

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

您可以将 JSON 请求正文中的每个根属性映射到终端节点的参数。 请考虑以下 JSON 请求正文：spring-doc.cn

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

您可以使用它来调用采用 and parameters 的写入操作，如下例所示：String nameint counterspring-doc.cn

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

输入类型转换

如有必要，传递给终端节点操作方法的参数会自动转换为所需的类型。 在调用操作方法之前，通过使用 的实例以及 的任何 或 bean 将通过 JMX 或 HTTP 接收的输入转换为所需的类型。ApplicationConversionServiceConverterGenericConverter@EndpointConverterspring-doc.cn

自定义 Web 终端节点

对 、 或 的操作使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 自动公开。 如果 Jersey 和 Spring MVC 都可用，则使用 Spring MVC。@Endpoint@WebEndpoint@EndpointWebExtensionspring-doc.cn

Web 终端节点请求谓词

将为 Web 公开的终端节点上的每个操作自动生成一个请求谓词。spring-doc.cn

路径

谓词的路径由终端节点的 ID 和 Web 公开的终端节点的基本路径确定。 默认基本路径为 . 例如，ID 为 uses 作为其在谓词中的路径的终端节点。/actuatorsessions/actuator/sessionsspring-doc.cn

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

HTTP 方法

谓词的 HTTP 方法由操作类型决定，如下表所示：spring-doc.cn

操作 HTTP 方法

@ReadOperationspring-doc.cn

GETspring-doc.cn

@WriteOperationspring-doc.cn

POSTspring-doc.cn

@DeleteOperationspring-doc.cn

DELETEspring-doc.cn

消耗

对于使用请求正文的 （HTTP） ，谓词的子句为 。 对于所有其他操作，子句为空。@WriteOperationPOSTconsumesapplication/vnd.spring-boot.actuator.v2+json, application/jsonconsumesspring-doc.cn

生产

谓词的子句可以由 ， 和 annotations 的属性确定。 该属性是可选的。 如果未使用，则自动确定子句。producesproduces@DeleteOperation@ReadOperation@WriteOperationproducesspring-doc.cn

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

Web 终端节点响应状态

终端节点操作的默认响应状态取决于操作类型（读取、写入或删除）以及操作返回的内容（如果有）。spring-doc.cn

如果 a 返回值，则响应状态将为 200 （OK）。 如果未返回值，则响应状态将为 404 （Not Found）。@ReadOperationspring-doc.cn

如果 a 或 返回值，则响应状态将为 200 （OK）。 如果未返回值，则响应状态将为 204 （No Content）。@WriteOperation@DeleteOperationspring-doc.cn

如果调用操作时没有必需的参数，或者使用无法转换为必需类型的参数，则不会调用操作方法，并且响应状态将为 400 （Bad Request）。spring-doc.cn

Web 终端节点范围请求

您可以使用 HTTP 范围请求来请求 HTTP 资源的一部分。 当使用 Spring MVC 或 Spring Web Flux 时，返回 a 的操作会自动支持范围请求。org.springframework.core.io.Resourcespring-doc.cn

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

Web 端点安全

Web 终端节点或特定于 Web 的终端节点扩展上的操作可以接收 current 或 as a method 参数。 前者通常结合使用，以便为经过身份验证和未经身份验证的用户提供不同的行为。 后者通常用于使用其方法执行授权检查。java.security.Principalorg.springframework.boot.actuate.endpoint.SecurityContext@NullableisUserInRole(String)spring-doc.cn

由于端点与技术无关，因此只能在方法签名中指定简单类型。 具体而言，不支持使用定义 和 properties 的类型声明单个参数。CustomDatanamecounter
要使输入映射到操作方法的参数，应使用 . 对于 Kotlin 代码，请查看 Spring 框架参考的建议。 如果您使用 Spring Boot 的 Gradle 插件，或者如果您使用 Maven 和 .-parametersspring-boot-starter-parent
操作 HTTP 方法

@ReadOperationspring-doc.cn

GETspring-doc.cn

@WriteOperationspring-doc.cn

POSTspring-doc.cn

@DeleteOperationspring-doc.cn

DELETEspring-doc.cn
使用 Jersey 时，不支持范围请求。

健康信息

您可以使用运行状况信息来检查正在运行的应用程序的状态。 监控软件经常使用它来在生产系统出现故障时提醒某人。 端点公开的信息取决于 和 属性，这些属性可以使用以下值之一进行配置：healthmanagement.endpoint.health.show-detailsmanagement.endpoint.health.show-componentsspring-doc.cn

名字 描述

neverspring-doc.cn

详细信息永远不会显示。spring-doc.cn

when-authorizedspring-doc.cn

详细信息仅向授权用户显示。 可以使用 配置授权角色。management.endpoint.health.rolesspring-doc.cn

alwaysspring-doc.cn

详细信息将向所有用户显示。spring-doc.cn

默认值为 . 当用户处于终端节点的一个或多个角色中时，即被视为已获得授权。 如果终端节点没有配置角色（默认），则所有经过身份验证的用户都被视为已获得授权。 您可以使用 property 配置角色。nevermanagement.endpoint.health.rolesspring-doc.cn

如果您已保护应用程序并希望使用 ，则您的安全配置必须允许经过身份验证和未经身份验证的用户访问 health 端点。always

运行状况信息是从 的内容中收集的（默认情况下，在 您的 中定义的所有实例）。 Spring Boot 包含许多 auto-configured ，您也可以编写自己的。HealthContributorRegistryHealthContributorApplicationContextHealthContributorsspring-doc.cn

A 可以是 a 或 a 。 A 提供实际的运行状况信息，包括 . A 提供其他 的复合。 总而言之，贡献者形成一个树结构来表示整个系统的运行状况。HealthContributorHealthIndicatorCompositeHealthContributorHealthIndicatorStatusCompositeHealthContributorHealthContributorsspring-doc.cn

默认情况下，最终的系统运行状况由 派生，它根据状态的有序列表对每个状态进行排序。 排序列表中的第一个状态用作整体运行状况。 如果 no 返回 已知的状态，则使用 状态。StatusAggregatorHealthIndicatorHealthIndicatorStatusAggregatorUNKNOWNspring-doc.cn

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

自动配置的 HealthIndicators

在适当的时候， Spring Boot 会自动配置下表中列出的内容。 您还可以通过配置 、 来启用或禁用选定的指示器 下表列出了 ：HealthIndicatorsmanagement.health.key.enabledkeyspring-doc.cn

钥匙 名字 描述

cassandraspring-doc.cn

CassandraDriverHealthIndicatorspring-doc.cn

检查 Cassandra 数据库是否已启动。spring-doc.cn

couchbasespring-doc.cn

CouchbaseHealthIndicatorspring-doc.cn

检查 Couchbase 集群是否已启动。spring-doc.cn

dbspring-doc.cn

DataSourceHealthIndicatorspring-doc.cn

检查是否可以获取 的连接。DataSourcespring-doc.cn

diskspacespring-doc.cn

DiskSpaceHealthIndicatorspring-doc.cn

检查磁盘空间是否不足。spring-doc.cn

elasticsearchspring-doc.cn

ElasticsearchRestClientHealthIndicatorspring-doc.cn

检查 Elasticsearch 集群是否已启动。spring-doc.cn

hazelcastspring-doc.cn

HazelcastHealthIndicatorspring-doc.cn

检查 Hazelcast 服务器是否已启动。spring-doc.cn

jmsspring-doc.cn

JmsHealthIndicatorspring-doc.cn

检查 JMS 代理是否已启动。spring-doc.cn

ldapspring-doc.cn

LdapHealthIndicatorspring-doc.cn

检查 LDAP 服务器是否已启动。spring-doc.cn

mailspring-doc.cn

MailHealthIndicatorspring-doc.cn

检查邮件服务器是否已启动。spring-doc.cn

mongospring-doc.cn

MongoHealthIndicatorspring-doc.cn

检查 Mongo 数据库是否已启动。spring-doc.cn

neo4jspring-doc.cn

Neo4jHealthIndicatorspring-doc.cn

检查 Neo4j 数据库是否已启动。spring-doc.cn

pingspring-doc.cn

PingHealthIndicatorspring-doc.cn

始终以 .UPspring-doc.cn

rabbitspring-doc.cn

RabbitHealthIndicatorspring-doc.cn

检查 Rabbit 服务器是否已启动。spring-doc.cn

redisspring-doc.cn

RedisHealthIndicatorspring-doc.cn

检查 Redis 服务器是否已启动。spring-doc.cn

sslspring-doc.cn

SslHealthIndicatorspring-doc.cn

检查 SSL 证书是否正常。spring-doc.cn
您可以通过设置属性来禁用它们。management.health.defaults.enabled
具有名为 的“警告阈值”属性。 如果 SSL 证书在此阈值定义的时间范围内无效，则会发出警告，但仍会返回 HTTP 200 以免中断应用程序。 您可以使用此阈值为自己提供足够的提前期来轮换即将过期的证书。sslHealthIndicatormanagement.health.ssl.certificate-validity-warning-thresholdHealthIndicator

其他功能可用，但默认情况下未启用：HealthIndicatorsspring-doc.cn

钥匙 名字 描述

livenessstatespring-doc.cn

LivenessStateHealthIndicatorspring-doc.cn

公开 “Liveness” 应用程序可用性状态。spring-doc.cn

readinessstatespring-doc.cn

ReadinessStateHealthIndicatorspring-doc.cn

公开 “Readiness” 应用程序可用性状态。spring-doc.cn

编写自定义 HealthIndicators

要提供自定义运行状况信息，您可以注册实现该接口的 Spring bean。 您需要提供该方法的实现并返回响应。 响应应包含状态，并且可以选择包含要显示的其他详细信息。 以下代码显示了一个示例实现：HealthIndicatorhealth()HealthHealthHealthIndicatorspring-doc.cn

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 秒的任何运行状况指示器。 如果要配置此阈值，可以使用 property .management.endpoint.health.logging.slow-indicator-threshold

除了 Spring Boot 的预定义类型之外，还可以返回表示新系统状态的自定义。 在这种情况下，您还需要提供接口的自定义实现，或者必须使用 configuration 属性配置默认实现。StatusHealthStatusStatusAggregatormanagement.endpoint.health.status.orderspring-doc.cn

例如，假设您的某个实现中使用了代码为 的 new。 要配置严重性顺序，请将以下属性添加到您的应用程序属性中：StatusFATALHealthIndicatorspring-doc.cn

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-doc.cn

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-doc.cn

地位 映射

DOWNspring-doc.cn

SERVICE_UNAVAILABLE (503)spring-doc.cn

OUT_OF_SERVICEspring-doc.cn

SERVICE_UNAVAILABLE (503)spring-doc.cn

UPspring-doc.cn

默认情况下没有映射，因此 HTTP 状态为200spring-doc.cn

UNKNOWNspring-doc.cn

默认情况下没有映射，因此 HTTP 状态为200spring-doc.cn

反应性健康指标

对于响应式应用程序，例如使用 Spring WebFlux 的应用程序，提供用于获取应用程序运行状况的非阻塞 Contract。 与传统的 类似，运行状况信息是从 的内容中收集的（默认情况下，在您的 中定义的 all 和 instances 中）。 不检查反应式 API 的常规操作将在弹性调度器上执行。ReactiveHealthContributorHealthContributorReactiveHealthContributorRegistryHealthContributorReactiveHealthContributorApplicationContextHealthContributorsspring-doc.cn

在响应式应用程序中，您应该在运行时使用 register 和 unregister health indicators 。 如果需要注册常规 ，则应将其包装为 .ReactiveHealthContributorRegistryHealthContributorReactiveHealthContributor#adapt

要从反应式 API 提供自定义运行状况信息，您可以注册实现该接口的 Spring bean。 以下代码显示了一个示例实现：ReactiveHealthIndicatorReactiveHealthIndicatorspring-doc.cn

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-doc.cn

钥匙 名字 描述

cassandraspring-doc.cn

CassandraDriverReactiveHealthIndicatorspring-doc.cn

检查 Cassandra 数据库是否已启动。spring-doc.cn

couchbasespring-doc.cn

CouchbaseReactiveHealthIndicatorspring-doc.cn

检查 Couchbase 集群是否已启动。spring-doc.cn

elasticsearchspring-doc.cn

ElasticsearchReactiveHealthIndicatorspring-doc.cn

检查 Elasticsearch 集群是否已启动。spring-doc.cn

mongospring-doc.cn

MongoReactiveHealthIndicatorspring-doc.cn

检查 Mongo 数据库是否已启动。spring-doc.cn

neo4jspring-doc.cn

Neo4jReactiveHealthIndicatorspring-doc.cn

检查 Neo4j 数据库是否已启动。spring-doc.cn

redisspring-doc.cn

RedisReactiveHealthIndicatorspring-doc.cn

检查 Redis 服务器是否已启动。spring-doc.cn
如有必要，反应式指标将替换常规指标。 此外，任何未明确处理的内容都会自动包装。HealthIndicator

健康组

有时，将运行状况指示器组织到可用于不同目的的组中非常有用。spring-doc.cn

要创建运行状况指示器组，可以使用 该属性并将运行状况指示器 ID 列表指定到 或 。 例如，要创建仅包含数据库指示器的组，您可以定义以下内容：management.endpoint.health.group.<name>includeexcludespring-doc.cn

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

然后，您可以通过点击 来检查结果。localhost:8080/actuator/health/customspring-doc.cn

同样，要创建一个从组中排除数据库指标并包括所有其他指标的组，您可以定义以下内容：spring-doc.cn

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

默认情况下，如果运行状况组包含或排除不存在的运行状况指示器，则启动将失败。 要禁用此行为，请将 .management.endpoint.health.validate-group-membershipfalsespring-doc.cn

默认情况下，组继承与系统运行状况相同的 and 设置。 但是，您也可以按组定义这些 ID。 如果需要，您还可以覆盖 and 属性：StatusAggregatorHttpCodeStatusMappershow-detailsrolesspring-doc.cn

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
如果需要注册 custom 或 bean 以用于组，则可以使用。@Qualifier("groupname")StatusAggregatorHttpCodeStatusMapper

运行状况组还可以包括/排除 . 您还可以仅包含/排除 . 这可以使用组件的完全限定名称来完成，如下所示：CompositeHealthContributorCompositeHealthContributorspring-doc.cn

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

在上面的示例中，该组将包含名称为 复合组件 的 。 此处，它本身是一个复合，并且 具有名称的 将从组中排除。customHealthContributorprimarytestprimaryHealthContributorbcustomspring-doc.cn

运行状况组可以在主端口或管理端口上的其他路径上可用。 这在 Kubernetes 等云环境中很有用，出于安全目的，为 actuator 端点使用单独的 management 端口是很常见的。 拥有单独的端口可能会导致运行状况检查不可靠，因为即使运行状况检查成功，主应用程序也可能无法正常工作。 运行状况组可以配置其他路径，如下所示：spring-doc.cn

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

这将使运行状况组在主服务器端口上可用。 前缀是必需的，并且必须是 （表示主服务器端口） 或 （表示管理端口，如果已配置）。 路径必须是单个路径段。live/healthzserver:management:spring-doc.cn

DataSource 运行状况

运行状况指示器显示标准数据源和路由数据源 Bean 的运行状况。 路由数据源的运行状况包括其每个目标数据源的运行状况。 在运行状况终端节点的响应中，路由数据源的每个目标都使用其路由键命名。 如果您不想在指示器的输出中包含路由数据源，请设置为 。DataSourcemanagement.health.db.ignore-routing-data-sourcestruespring-doc.cn

名字 描述

neverspring-doc.cn

详细信息永远不会显示。spring-doc.cn

when-authorizedspring-doc.cn

详细信息仅向授权用户显示。 可以使用 配置授权角色。management.endpoint.health.rolesspring-doc.cn

alwaysspring-doc.cn

详细信息将向所有用户显示。spring-doc.cn
如果您已保护应用程序并希望使用 ，则您的安全配置必须允许经过身份验证和未经身份验证的用户访问 health 端点。always
您可以使用 在运行时注册和注销运行状况指示器。HealthContributorRegistry
钥匙 名字 描述

cassandraspring-doc.cn

CassandraDriverHealthIndicatorspring-doc.cn

检查 Cassandra 数据库是否已启动。spring-doc.cn

couchbasespring-doc.cn

CouchbaseHealthIndicatorspring-doc.cn

检查 Couchbase 集群是否已启动。spring-doc.cn

dbspring-doc.cn

DataSourceHealthIndicatorspring-doc.cn

检查是否可以获取 的连接。DataSourcespring-doc.cn

diskspacespring-doc.cn

DiskSpaceHealthIndicatorspring-doc.cn

检查磁盘空间是否不足。spring-doc.cn

elasticsearchspring-doc.cn

ElasticsearchRestClientHealthIndicatorspring-doc.cn

检查 Elasticsearch 集群是否已启动。spring-doc.cn

hazelcastspring-doc.cn

HazelcastHealthIndicatorspring-doc.cn

检查 Hazelcast 服务器是否已启动。spring-doc.cn

jmsspring-doc.cn

JmsHealthIndicatorspring-doc.cn

检查 JMS 代理是否已启动。spring-doc.cn

ldapspring-doc.cn

LdapHealthIndicatorspring-doc.cn

检查 LDAP 服务器是否已启动。spring-doc.cn

mailspring-doc.cn

MailHealthIndicatorspring-doc.cn

检查邮件服务器是否已启动。spring-doc.cn

mongospring-doc.cn

MongoHealthIndicatorspring-doc.cn

检查 Mongo 数据库是否已启动。spring-doc.cn

neo4jspring-doc.cn

Neo4jHealthIndicatorspring-doc.cn

检查 Neo4j 数据库是否已启动。spring-doc.cn

pingspring-doc.cn

PingHealthIndicatorspring-doc.cn

始终以 .UPspring-doc.cn

rabbitspring-doc.cn

RabbitHealthIndicatorspring-doc.cn

检查 Rabbit 服务器是否已启动。spring-doc.cn

redisspring-doc.cn

RedisHealthIndicatorspring-doc.cn

检查 Redis 服务器是否已启动。spring-doc.cn

sslspring-doc.cn

SslHealthIndicatorspring-doc.cn

检查 SSL 证书是否正常。spring-doc.cn
您可以通过设置属性来禁用它们。management.health.defaults.enabled
具有名为 的“警告阈值”属性。 如果 SSL 证书在此阈值定义的时间范围内无效，则会发出警告，但仍会返回 HTTP 200 以免中断应用程序。 您可以使用此阈值为自己提供足够的提前期来轮换即将过期的证书。sslHealthIndicatormanagement.health.ssl.certificate-validity-warning-thresholdHealthIndicator
钥匙 名字 描述

livenessstatespring-doc.cn

LivenessStateHealthIndicatorspring-doc.cn

公开 “Liveness” 应用程序可用性状态。spring-doc.cn

readinessstatespring-doc.cn

ReadinessStateHealthIndicatorspring-doc.cn

公开 “Readiness” 应用程序可用性状态。spring-doc.cn
给定的标识符是不带后缀的 bean 的名称（如果存在）。 在前面的示例中，运行状况信息在名为 .HealthIndicatorHealthIndicatormy
运行状况指示器通常通过 HTTP 调用，并且需要在任何连接超时之前做出响应。 Spring Boot 将记录一条警告消息，用于响应时间超过 10 秒的任何运行状况指示器。 如果要配置此阈值，可以使用 property .management.endpoint.health.logging.slow-indicator-threshold
如果需要更多控制，可以定义自己的 Bean。HttpCodeStatusMapper
地位 映射

DOWNspring-doc.cn

SERVICE_UNAVAILABLE (503)spring-doc.cn

OUT_OF_SERVICEspring-doc.cn

SERVICE_UNAVAILABLE (503)spring-doc.cn

UPspring-doc.cn

默认情况下没有映射，因此 HTTP 状态为200spring-doc.cn

UNKNOWNspring-doc.cn

默认情况下没有映射，因此 HTTP 状态为200spring-doc.cn
在响应式应用程序中，您应该在运行时使用 register 和 unregister health indicators 。 如果需要注册常规 ，则应将其包装为 .ReactiveHealthContributorRegistryHealthContributorReactiveHealthContributor#adapt
若要自动处理错误，请考虑从 扩展。AbstractReactiveHealthIndicator
钥匙 名字 描述

cassandraspring-doc.cn

CassandraDriverReactiveHealthIndicatorspring-doc.cn

检查 Cassandra 数据库是否已启动。spring-doc.cn

couchbasespring-doc.cn

CouchbaseReactiveHealthIndicatorspring-doc.cn

检查 Couchbase 集群是否已启动。spring-doc.cn

elasticsearchspring-doc.cn

ElasticsearchReactiveHealthIndicatorspring-doc.cn

检查 Elasticsearch 集群是否已启动。spring-doc.cn

mongospring-doc.cn

MongoReactiveHealthIndicatorspring-doc.cn

检查 Mongo 数据库是否已启动。spring-doc.cn

neo4jspring-doc.cn

Neo4jReactiveHealthIndicatorspring-doc.cn

检查 Neo4j 数据库是否已启动。spring-doc.cn

redisspring-doc.cn

RedisReactiveHealthIndicatorspring-doc.cn

检查 Redis 服务器是否已启动。spring-doc.cn
如有必要，反应式指标将替换常规指标。 此外，任何未明确处理的内容都会自动包装。HealthIndicator
如果需要注册 custom 或 bean 以用于组，则可以使用。@Qualifier("groupname")StatusAggregatorHttpCodeStatusMapper

Kubernetes 探针

部署在 Kubernetes 上的应用程序可以通过 Container Probe 提供有关其内部状态的信息。 根据您的 Kubernetes 配置，kubelet 会调用这些探测并对结果做出反应。spring-doc.cn

默认情况下， Spring Boot 管理您的应用程序可用性状态。 如果部署在 Kubernetes 环境中，actuator 会从界面收集 “Liveness” 和 “Readiness” 信息，并在专用的运行状况指示器中使用该信息：和 。 这些指示器显示在全局运行状况终端节点 （） 上。 它们还通过使用运行状况组作为单独的 HTTP 探测公开：和 .ApplicationAvailabilityLivenessStateHealthIndicatorReadinessStateHealthIndicator"/actuator/health""/actuator/health/liveness""/actuator/health/readiness"spring-doc.cn

然后，您可以使用以下终端节点信息配置 Kubernetes 基础设施：spring-doc.cn

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

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

仅当应用程序在 Kubernetes 环境中运行时，才会自动启用这些运行状况组。 您可以使用 configuration 属性在任何环境中启用它们。management.endpoint.health.probes.enabledspring-doc.cn

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

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

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

这将使组在 和 组在主服务器端口上可用。 可以使用每个组上的属性自定义路径，有关详细信息，请参阅运行状况组。liveness/livezreadiness/readyzadditional-pathspring-doc.cn

使用 Kubernetes 探针检查外部状态

Actuator 将 “liveness” 和 “readiness” 探针配置为 Health Group。 这意味着所有运行状况组功能都可供他们使用。 例如，您可以配置其他运行状况指示器：spring-doc.cn

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

默认情况下， Spring Boot 不会向这些组添加其他运行状况指示器。spring-doc.cn

“活动性” 探测不应依赖于外部系统的运行状况检查。 如果应用程序的活跃状态被破坏，Kubernetes 会尝试通过重启应用程序实例来解决这个问题。 这意味着，如果外部系统（例如数据库、Web API 或外部缓存）发生故障，Kubernetes 可能会重新启动所有应用程序实例并产生级联故障。spring-doc.cn

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

如果应用程序的所有实例都未就绪，则具有或不接受任何传入连接的 Kubernetes Service。 没有 HTTP 错误响应（503 等），因为没有连接。 服务可能接受也可能不接受连接，具体取决于提供商。 具有显式 Ingress 的服务也以取决于实现的方式进行响应 — Ingress 服务本身必须决定如何处理来自下游的 “connection refused”。 HTTP 503 在负载均衡器和入口的情况下都很可能出现。type=ClusterIPNodePorttype=LoadBalancer

此外，如果应用程序使用 Kubernetes 自动扩展，则它可能会对从负载均衡器中取出的应用程序做出不同的反应，具体取决于其自动扩展器配置。spring-doc.cn

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

Kubernetes 探针支持的一个重要方面是它与应用程序生命周期的一致性。 （这是应用程序中的内存中内部状态）之间存在显著差异 和实际的探针（公开该状态）。 根据应用程序生命周期的阶段，探测可能不可用。AvailabilityStatespring-doc.cn

Spring Boot 在启动和关闭期间发布应用程序事件， 探针可以监听此类事件并公开信息。AvailabilityStatespring-doc.cn

下表显示了 HTTP 连接器在不同阶段的状态。AvailabilityStatespring-doc.cn

当 Spring Boot 应用程序启动时：spring-doc.cn

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

开始spring-doc.cn

BROKENspring-doc.cn

REFUSING_TRAFFICspring-doc.cn

未启动spring-doc.cn

Kubernetes 会检查 “liveness” Probe，如果时间过长，则会重启应用程序。spring-doc.cn

开始spring-doc.cn

CORRECTspring-doc.cn

REFUSING_TRAFFICspring-doc.cn

拒绝请求spring-doc.cn

应用程序上下文将刷新。应用程序执行启动任务，但尚未接收流量。spring-doc.cn

准备spring-doc.cn

CORRECTspring-doc.cn

ACCEPTING_TRAFFICspring-doc.cn

接受请求spring-doc.cn

启动任务已完成。应用程序正在接收流量。spring-doc.cn

当 Spring Boot 应用程序关闭时：spring-doc.cn

关闭阶段 活动状态 就绪状态 HTTP 服务器 笔记

运行spring-doc.cn

CORRECTspring-doc.cn

ACCEPTING_TRAFFICspring-doc.cn

接受请求spring-doc.cn

已请求关闭。spring-doc.cn

正常关闭spring-doc.cn

CORRECTspring-doc.cn

REFUSING_TRAFFICspring-doc.cn

新请求被拒绝spring-doc.cn

如果启用，正常关闭将处理正在进行的请求。spring-doc.cn

关机完成spring-doc.cn

不适用spring-doc.cn

不适用spring-doc.cn

服务器已关闭spring-doc.cn

应用程序上下文已关闭，应用程序已关闭。spring-doc.cn
有关 Kubernetes 部署的更多信息，请参阅 Kubernetes 容器生命周期。
<actuator-port>应设置为 actuator endpoints 可用的端口。 它可以是主 Web 服务器端口，也可以是单独的管理端口（如果已设置该属性）。"management.server.port"
如果应用程序的启动时间超过配置的活跃期，Kubernetes 会提到 这是可能的解决方案。 一般来说，这里不一定需要 the，因为 在完成所有启动任务之前 都会失败。 这意味着您的应用程序在准备就绪之前不会接收流量。 但是，如果您的应用程序需要很长时间才能启动，请考虑使用 a 来确保 Kubernetes 不会在启动过程中终止您的应用程序。 请参阅描述 Probe 在应用程序生命周期中的行为方式的部分。"startupProbe""startupProbe""readinessProbe""startupProbe"
如果应用程序的所有实例都未就绪，则具有或不接受任何传入连接的 Kubernetes Service。 没有 HTTP 错误响应（503 等），因为没有连接。 服务可能接受也可能不接受连接，具体取决于提供商。 具有显式 Ingress 的服务也以取决于实现的方式进行响应 — Ingress 服务本身必须决定如何处理来自下游的 “connection refused”。 HTTP 503 在负载均衡器和入口的情况下都很可能出现。type=ClusterIPNodePorttype=LoadBalancer
启动阶段 LivenessState 就绪状态 HTTP 服务器 笔记

开始spring-doc.cn

BROKENspring-doc.cn

REFUSING_TRAFFICspring-doc.cn

未启动spring-doc.cn

Kubernetes 会检查 “liveness” Probe，如果时间过长，则会重启应用程序。spring-doc.cn

开始spring-doc.cn

CORRECTspring-doc.cn

REFUSING_TRAFFICspring-doc.cn

拒绝请求spring-doc.cn

应用程序上下文将刷新。应用程序执行启动任务，但尚未接收流量。spring-doc.cn

准备spring-doc.cn

CORRECTspring-doc.cn

ACCEPTING_TRAFFICspring-doc.cn

接受请求spring-doc.cn

启动任务已完成。应用程序正在接收流量。spring-doc.cn
关闭阶段 活动状态 就绪状态 HTTP 服务器 笔记

运行spring-doc.cn

CORRECTspring-doc.cn

ACCEPTING_TRAFFICspring-doc.cn

接受请求spring-doc.cn

已请求关闭。spring-doc.cn

正常关闭spring-doc.cn

CORRECTspring-doc.cn

REFUSING_TRAFFICspring-doc.cn

新请求被拒绝spring-doc.cn

如果启用，正常关闭将处理正在进行的请求。spring-doc.cn

关机完成spring-doc.cn

不适用spring-doc.cn

不适用spring-doc.cn

服务器已关闭spring-doc.cn

应用程序上下文已关闭，应用程序已关闭。spring-doc.cn
有关 Kubernetes 部署的更多信息，请参阅 Kubernetes 容器生命周期。

应用信息

应用程序信息公开了从 中定义的所有 bean 收集的各种信息。 Spring Boot 包含许多自动配置的 bean，您可以编写自己的 bean。InfoContributorApplicationContextInfoContributorspring-doc.cn

自动配置的 InfoContributors

在适当的时候， Spring 会自动配置以下 bean：InfoContributorspring-doc.cn

身份证 名字 描述 先决条件

buildspring-doc.cn

BuildInfoContributorspring-doc.cn

公开生成信息。spring-doc.cn

资源。META-INF/build-info.propertiesspring-doc.cn

envspring-doc.cn

EnvironmentInfoContributorspring-doc.cn

公开其名称以 开头的任何属性。Environmentinfo.spring-doc.cn

没有。spring-doc.cn

gitspring-doc.cn

GitInfoContributorspring-doc.cn

公开 git 信息。spring-doc.cn

资源。git.propertiesspring-doc.cn

javaspring-doc.cn

JavaInfoContributorspring-doc.cn

公开 Java 运行时信息。spring-doc.cn

没有。spring-doc.cn

osspring-doc.cn

OsInfoContributorspring-doc.cn

公开 Operating System 信息。spring-doc.cn

没有。spring-doc.cn

processspring-doc.cn

ProcessInfoContributorspring-doc.cn

公开进程信息。spring-doc.cn

没有。spring-doc.cn

sslspring-doc.cn

SslInfoContributorspring-doc.cn

公开 SSL 证书信息。spring-doc.cn

已配置的 SSL 捆绑包。spring-doc.cn

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

由于没有先决条件来指示应启用它们，因此 、 、 和 contributors 默认处于禁用状态。贡献者具有配置 SSL 捆绑包的先决条件，但默认情况下处于禁用状态。 可以通过将其属性设置为 来启用每个 。envjavaosprocesssslmanagement.info.<id>.enabledtruespring-doc.cn

默认情况下，和 info 参与者处于启用状态。 可以通过将其属性设置为 来禁用 each。 或者，要禁用通常默认启用的每个参与者，请将该属性设置为 。buildgitmanagement.info.<id>.enabledfalsemanagement.info.defaults.enabledfalsespring-doc.cn

自定义应用程序信息

启用贡献者后，您可以通过设置 Spring 属性来自定义端点公开的数据。 键下的所有属性都会自动公开。 例如，您可以向文件添加以下设置：envinfoinfo.*Environmentinfoapplication.propertiesspring-doc.cn

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"

除了对这些值进行硬编码外，您还可以在构建时扩展 info 属性。spring-doc.cn

假设您使用 Maven，则可以按如下方式重写前面的示例：spring-doc.cn

[email protected]@
[email protected]@
[email protected]@
info:
  app:
    encoding: "@project.build.sourceEncoding@"
    java:
      source: "@java.version@"
      target: "@java.version@"

Git 提交信息

终端节点的另一个有用功能是，它能够在构建项目时发布有关源代码存储库状态的信息。 如果 Bean 可用，则可以使用端点公开这些属性。infogitGitPropertiesinfospring-doc.cn

如果文件在 Classpath 的根目录中可用，则会自动配置 Bean。 有关更多详细信息，请参阅生成 Git 信息。GitPropertiesgit.properties

默认情况下，终端节点公开 、 和 属性（如果存在）。 如果您不希望终端节点响应中出现这些属性中的任何一个，则需要将它们从文件中排除。 如果要显示完整的 git 信息（即 的完整内容），请使用该属性，如下所示：git.branchgit.commit.idgit.commit.timegit.propertiesgit.propertiesmanagement.info.git.modespring-doc.cn

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

要从端点完全禁用 git 提交信息，请将该属性设置为 ，如下所示：infomanagement.info.git.enabledfalsespring-doc.cn

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

构建信息

如果 Bean 可用，则终端节点还可以发布有关您的构建的信息。 如果 Classpath 中有文件可用，则会发生这种情况。BuildPropertiesinfoMETA-INF/build-info.propertiesspring-doc.cn

Maven 和 Gradle 插件都可以生成该文件。 有关更多详细信息，请参阅生成生成信息。

Java 信息

终端节点发布有关 Java 运行时环境的信息，请参阅了解更多详细信息。infoJavaInfospring-doc.cn

OS 信息

终端节点发布有关您的操作系统的信息，请参阅了解更多详细信息。infoOsInfospring-doc.cn

过程信息

终端节点发布有关您的进程的信息，请参阅了解更多详细信息。infoProcessInfospring-doc.cn

SSL 信息

终端节点发布有关 SSL 证书（通过 SSL 捆绑包配置）的信息，请参阅了解更多详细信息。此端点重复使用 的“warning threshold”属性：如果 SSL 证书在此阈值定义的时间范围内无效，它将触发警告。查看属性。infoSslInfoSslHealthIndicatormanagement.health.ssl.certificate-validity-warning-thresholdspring-doc.cn

编写自定义 InfoContributor

要提供自定义应用程序信息，您可以注册实现该接口的 Spring Bean。InfoContributorspring-doc.cn

以下示例提供一个具有单个值的条目：examplespring-doc.cn

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-doc.cn

{
	"example": {
		"key" : "value"
	}
}
身份证 名字 描述 先决条件

buildspring-doc.cn

BuildInfoContributorspring-doc.cn

公开生成信息。spring-doc.cn

资源。META-INF/build-info.propertiesspring-doc.cn

envspring-doc.cn

EnvironmentInfoContributorspring-doc.cn

公开其名称以 开头的任何属性。Environmentinfo.spring-doc.cn

没有。spring-doc.cn

gitspring-doc.cn

GitInfoContributorspring-doc.cn

公开 git 信息。spring-doc.cn

资源。git.propertiesspring-doc.cn

javaspring-doc.cn

JavaInfoContributorspring-doc.cn

公开 Java 运行时信息。spring-doc.cn

没有。spring-doc.cn

osspring-doc.cn

OsInfoContributorspring-doc.cn

公开 Operating System 信息。spring-doc.cn

没有。spring-doc.cn

processspring-doc.cn

ProcessInfoContributorspring-doc.cn

公开进程信息。spring-doc.cn

没有。spring-doc.cn

sslspring-doc.cn

SslInfoContributorspring-doc.cn

公开 SSL 证书信息。spring-doc.cn

已配置的 SSL 捆绑包。spring-doc.cn

除了对这些值进行硬编码外，您还可以在构建时扩展 info 属性。spring-doc.cn

假设您使用 Maven，则可以按如下方式重写前面的示例：spring-doc.cn

[email protected]@
[email protected]@
[email protected]@
info:
  app:
    encoding: "@project.build.sourceEncoding@"
    java:
      source: "@java.version@"
      target: "@java.version@"
如果文件在 Classpath 的根目录中可用，则会自动配置 Bean。 有关更多详细信息，请参阅生成 Git 信息。GitPropertiesgit.properties
Maven 和 Gradle 插件都可以生成该文件。 有关更多详细信息，请参阅生成生成信息。

软件物料清单 （SBOM）

终端节点公开 Software Bill of Materials。 CycloneDX SBOM 可以自动检测，但其他格式也可以手动配置。sbomspring-doc.cn

Maven 父级和 Spring Boot Gradle 插件分别配置 CycloneDX Maven 插件和 CycloneDX Gradle 插件。spring-boot-starter-parentspring-doc.cn

要获得 CycloneDX SBOM，您需要将以下内容添加到您的 Maven 构建中：spring-doc.cn

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

对于 Gradle，您需要应用 CycloneDX Gradle 插件：spring-doc.cn

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

然后，执行器端点将公开一个名为 “application” 的 SBOM，它描述了应用程序的内容。sbomspring-doc.cn

其他 SBOM 格式

如果要以其他格式发布 SBOM，可以使用一些配置属性。spring-doc.cn

configuration 属性设置应用程序 SBOM 的位置。 例如，将此设置为 this 将使用 Classpath 上的资源内容。management.endpoint.sbom.application.locationclasspath:sbom.json/sbom.jsonspring-doc.cn

可自动检测 CycloneDX、SPDX 和 Syft 格式的 SBOM 的介质类型。 要覆盖自动检测到的媒体类型，请使用 configuration 属性 。management.endpoint.sbom.application.media-typespring-doc.cn

其他 SBOM

执行器终端节点可以处理多个 SBOM。 要添加 SBOMs，请使用 configuration property ，如以下示例所示：management.endpoint.sbom.additionalspring-doc.cn

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-doc.cn