端点

Actuator 端点可让你监控和与应用程序交互。Spring Boot 包含一些内置端点，并允许你添加自己的端点。例如，health 端点提供基本的应用程序运行状况信息。

你可以启用或禁用每个单独的端点，并公开它们（使它们可以通过 HTTP 或 JMX 远程访问）。当端点同时处于启用和公开状态时，它将被视为可用。仅当内置端点可用时，才会自动配置它们。大多数应用程序选择通过 HTTP 公开，其中端点的 ID 和/actuator 的前缀映射到一个 URL。例如，默认情况下，health 端点映射到/actuator/health。

要详细了解 Actuator 的端点及其请求和响应格式，请参阅API 文档。

以下与技术无关的端点可用

ID 说明

auditevents

公开当前应用程序的审计事件信息。需要一个AuditEventRepository bean。

beans

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

缓存

公开可用的缓存。

条件

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

configprops

显示所有 @ConfigurationProperties 的整理列表。受清理约束。

env

公开 Spring 的 ConfigurableEnvironment 中的属性。受清理约束。

flyway

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

健康

显示应用程序健康信息。

httpexchanges

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

信息

显示任意的应用程序信息。

integrationgraph

显示 Spring 集成图。需要依赖 spring-integration-core。

记录器

显示并修改应用程序中记录器的配置。

liquibase

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

指标

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

映射

显示所有 @RequestMapping 路径的整理列表。

quartz

显示有关 Quartz Scheduler 作业的信息。受清理约束。

scheduledtasks

显示应用程序中的计划任务。

会话

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

shutdown

允许应用程序正常关闭。仅在使用 jar 打包时有效。默认情况下禁用。

startup

显示 ApplicationStartup 收集的启动步骤数据。需要使用 BufferingApplicationStartup 配置 SpringApplication。

threaddump

执行线程转储。

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

ID 说明

heapdump

返回堆转储文件。在 HotSpot JVM 上，将返回 HPROF 格式的文件。在 OpenJ9 JVM 上，将返回 PHD 格式的文件。

日志文件

返回日志文件的内容（如果已设置 logging.file.name 或 logging.file.path 属性）。支持使用 HTTP Range 头来检索日志文件内容的一部分。

普罗米修斯

以普罗米修斯服务器可以抓取的格式公开指标。需要依赖 micrometer-registry-prometheus。

启用端点

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

属性
YAML

management.endpoint.shutdown.enabled=true

management:
  endpoint:
    shutdown:
      enabled: true

如果你希望端点启用是选择加入而不是选择退出，请将 management.endpoints.enabled-by-default 属性设置为 false，并使用单独的端点 enabled 属性选择加入。以下示例启用了 info 端点并禁用了所有其他端点

属性
YAML

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

management:
  endpoints:
    enabled-by-default: false
  endpoint:
    info:
      enabled: true

已禁用的端点将从应用程序上下文中完全删除。如果你只想更改端点公开的技术，请改用 include 和 exclude 属性。

公开端点

默认情况下，只有健康端点通过 HTTP 和 JMX 公开。由于端点可能包含敏感信息，因此你应仔细考虑何时公开它们。

要更改公开的端点，请使用以下特定于技术的 include 和 exclude 属性

属性默认值

management.endpoints.jmx.exposure.exclude

management.endpoints.jmx.exposure.include

健康

management.endpoints.web.exposure.exclude

management.endpoints.web.exposure.include

健康

include 属性列出已公开的端点的 ID。exclude 属性列出不应公开的端点的 ID。exclude 属性优先于 include 属性。你可以使用端点 ID 列表配置 include 和 exclude 属性。

例如，要仅通过 JMX 公开health和info端点，请使用以下属性

属性
YAML

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

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

*可用于选择所有端点。例如，要通过 HTTP 公开除env和beans端点之外的所有内容，请使用以下属性

属性
YAML

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

management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"

*在 YAML 中具有特殊含义，因此如果您想要包含（或排除）所有端点，请务必添加引号。

如果您的应用程序是公开的，我们强烈建议您还保护您的端点。

如果您想为端点公开的时间实现自己的策略，则可以注册一个EndpointFilter bean。

安全性

出于安全考虑，默认情况下仅通过 HTTP 公开/health端点。您可以使用management.endpoints.web.exposure.include属性来配置公开的端点。

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

如果类路径上存在 Spring Security 并且没有其他SecurityFilterChain bean，则除了/health之外的所有执行器都由 Spring Boot 自动配置保护。如果您定义了一个自定义SecurityFilterChain bean，Spring Boot 自动配置将退出并允许您完全控制执行器访问规则。

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

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

Java
Kotlin

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

}

前面的示例使用EndpointRequest.toAnyEndpoint()匹配对任何端点的请求，然后确保所有端点都具有ENDPOINT_ADMIN角色。EndpointRequest上还有其他几个匹配器方法可用。有关详细信息，请参阅API 文档。

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

属性
YAML

management.endpoints.web.exposure.include=*

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

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

Java
Kotlin

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 的安全配置在存在任何SecurityFilterChain bean 时完全退出，因此您需要配置一个附加的SecurityFilterChain bean，其中规则适用于应用程序的其余部分。

跨站点请求伪造保护

由于 Spring Boot 依赖 Spring Security 的默认设置，因此 CSRF 保护默认处于启用状态。这意味着当使用默认安全配置时，需要 POST（关闭和记录器端点）、PUT 或 DELETE 的执行器端点会收到 403（禁止）错误。

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

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

配置端点

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

属性
YAML

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

management:
  endpoint:
    beans:
      cache:
        time-to-live: "10s"

management.endpoint.<name> 前缀唯一标识正在配置的端点。

清除敏感值

/env、/configprops 和 /quartz 端点返回的信息可能很敏感，因此默认情况下，值总是完全清除（替换为 ******）。

仅在以下情况下才能以未清除的形式查看值

show-values 属性已设置为除 NEVER 之外的其他值
没有自定义 SanitizingFunction bean 适用

show-values 属性可以针对可清除端点配置为以下值之一

NEVER - 值总是完全清除（替换为 ******）
ALWAYS - 值显示给所有用户（只要没有 SanitizingFunction bean 适用）
WHEN_AUTHORIZED - 值仅显示给授权用户（只要没有 SanitizingFunction bean 适用）

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

对于 JMX 端点，所有用户始终获得授权。

以下示例允许具有 admin 角色的所有用户以原始形式查看 /env 端点中的值。未经授权的用户或没有 admin 角色的用户将只看到已清除的值。

属性
YAML

management.endpoint.env.show-values=WHEN_AUTHORIZED
management.endpoint.env.roles=admin

management:
  endpoint:
    env:
      show-values: WHEN_AUTHORIZED
      roles: "admin"

此示例假定没有定义 SanitizingFunction bean。

执行器 Web 端点的超媒体

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

要禁用“发现页面”，请将以下属性添加到应用程序属性

属性
YAML

management.endpoints.web.discovery.enabled=false

management:
  endpoints:
    web:
      discovery:
        enabled: false

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

CORS 支持

跨源资源共享 (CORS) 是一项 W3C 规范，允许您灵活地指定允许哪些类型的跨域请求。如果您使用 Spring MVC 或 Spring WebFlux，则可以配置 Actuator 的 Web 端点来支持此类场景。

CORS 支持默认情况下处于禁用状态，只有在设置了 management.endpoints.web.cors.allowed-origins 属性后才会启用。以下配置允许来自 example.com 域的 GET 和 POST 调用

属性
YAML

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。

实现自定义端点

如果您添加了一个用 @Endpoint 注释的 @Bean，则用 @ReadOperation、@WriteOperation 或 @DeleteOperation 注释的任何方法都会自动通过 JMX 公开，并且在 Web 应用程序中也会通过 HTTP 公开。可以使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开端点。如果 Jersey 和 Spring MVC 都可用，则使用 Spring MVC。

以下示例公开了返回自定义对象的读取操作

Java
Kotlin

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

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

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

您可以使用 @EndpointWebExtension 和 @EndpointJmxExtension 编写特定于技术的扩展。这些注释允许您提供特定于技术的运算，以增强现有端点。

最后，如果您需要访问特定于 Web 框架的功能，则可以实现 servlet 或 Spring @Controller 和 @RestController 端点，但代价是它们在 JMX 上或使用不同的 Web 框架时不可用。

接收输入

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

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

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

您可以使用此来调用一个写入操作，该操作采用 String name 和 int counter 参数，如下例所示

Java
Kotlin

	@WriteOperation
	public void updateData(String name, int counter) {
		// injects "test" and 42
	}

	@WriteOperation
	fun updateData(name: String?, counter: Int) {
		// injects "test" and 42
	}

由于端点与技术无关，因此只能在方法签名中指定简单类型。特别是，不支持声明具有定义 name 和 counter 属性的 CustomData 类型的单个参数。

为了让输入映射到操作方法的参数，实现端点的 Java 代码应使用 -parameters 编译，实现端点的 Kotlin 代码应使用 -java-parameters 编译。如果您使用 Spring Boot 的 Gradle 插件或使用 Maven 和 spring-boot-starter-parent，这将自动发生。

输入类型转换

传递给端点操作方法的参数在必要时会自动转换为所需类型。在调用操作方法之前，通过使用 ApplicationConversionService 实例以及任何使用 @EndpointConverter 限定的 Converter 或 GenericConverter bean，将通过 JMX 或 HTTP 接收的输入转换为所需类型。

自定义 Web 端点

在 @Endpoint、@WebEndpoint 或 @EndpointWebExtension 上的操作会自动通过 Jersey、Spring MVC 或 Spring WebFlux 暴露在 HTTP 上。如果 Jersey 和 Spring MVC 都可用，则使用 Spring MVC。

Web 端点请求谓词

为 Web 暴露端点上的每个操作自动生成请求谓词。

路径

谓词的路径由端点的 ID 和 Web 暴露端点的基本路径确定。默认基本路径是 /actuator。例如，ID 为 sessions 的端点在谓词中使用 /actuator/sessions 作为其路径。

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

HTTP 方法

谓词的 HTTP 方法由操作类型确定，如下表所示

操作 HTTP 方法

@ReadOperation

GET

@WriteOperation

POST

@DeleteOperation

DELETE

消耗

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

产生

谓词的produces子句可由@DeleteOperation、@ReadOperation和@WriteOperation注释的produces属性确定。该属性是可选的。如果未使用，则produces子句将自动确定。

如果操作方法返回void或Void，则produces子句为空。如果操作方法返回org.springframework.core.io.Resource，则produces子句为application/octet-stream。对于所有其他操作，produces子句为application/vnd.spring-boot.actuator.v2+json, application/json。

Web 端点响应状态

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

如果@ReadOperation返回一个值，则响应状态将为 200（确定）。如果它不返回值，则响应状态将为 404（未找到）。

如果@WriteOperation或@DeleteOperation返回一个值，则响应状态将为 200（确定）。如果它不返回值，则响应状态将为 204（无内容）。

如果在没有必需参数或使用无法转换为必需类型参数的情况下调用操作，则不会调用操作方法，并且响应状态将为 400（错误请求）。

Web 端点范围请求

你可以使用 HTTP 范围请求来请求 HTTP 资源的一部分。在使用 Spring MVC 或 Spring Web Flux 时，返回org.springframework.core.io.Resource的操作会自动支持范围请求。

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

Web 端点安全性

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

健康信息

你可以使用健康信息来检查正在运行的应用程序的状态。它通常由监控软件使用，以便在生产系统宕机时向某人发出警报。health 端点公开的信息取决于 management.endpoint.health.show-details 和 management.endpoint.health.show-components 属性，它们可以使用以下值之一进行配置

名称说明

never

详细信息永远不会显示。

when-authorized

详细信息仅显示给经过授权的用户。可以通过使用 management.endpoint.health.roles 配置授权角色。

always

详细信息显示给所有用户。

默认值为 never。当用户处于端点的某个或多个角色中时，该用户被视为已授权。如果端点没有配置角色（默认值），则所有经过身份验证的用户都被视为已授权。你可以使用 management.endpoint.health.roles 属性配置角色。

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

健康信息是从 HealthContributorRegistry 的内容中收集的（默认情况下，所有在你的 ApplicationContext 中定义的 HealthContributor 实例）。Spring Boot 包含许多自动配置的 HealthContributors，你也可以编写你自己的。

HealthContributor 可以是 HealthIndicator 或 CompositeHealthContributor。HealthIndicator 提供实际的健康信息，包括 Status。CompositeHealthContributor 提供其他 HealthContributors 的复合。综合起来，贡献者形成树结构来表示整体系统健康状况。

默认情况下，最终系统健康状况由 StatusAggregator 推导，它根据有序的状态列表对来自每个 HealthIndicator 的状态进行排序。排序列表中的第一个状态用作整体健康状态。如果没有 HealthIndicator 返回 StatusAggregator 已知的状态，则使用 UNKNOWN 状态。

你可以使用 HealthContributorRegistry 在运行时注册和取消注册健康指示器。

自动配置的 HealthIndicators

在适当的时候，Spring Boot 会自动配置下表中列出的 HealthIndicators。你还可以通过配置 management.health.key.enabled 来启用或禁用选定的指示器，其中 key 在下表中列出

键名称说明

cassandra

CassandraDriverHealthIndicator

检查 Cassandra 数据库是否启动。

couchbase

CouchbaseHealthIndicator

检查 Couchbase 集群是否启动。

db

DataSourceHealthIndicator

检查是否可以获取与 DataSource 的连接。

diskspace

DiskSpaceHealthIndicator

检查磁盘空间是否不足。

elasticsearch

ElasticsearchRestClientHealthIndicator

检查 Elasticsearch 集群是否启动。

hazelcast

HazelcastHealthIndicator

检查 Hazelcast 服务器是否启动。

influxdb

InfluxDbHealthIndicator

检查 InfluxDB 服务器是否启动。

jms

JmsHealthIndicator

检查 JMS 代理是否启动。

ldap

LdapHealthIndicator

检查 LDAP 服务器是否启动。

mail

MailHealthIndicator

检查邮件服务器是否启动。

mongo

MongoHealthIndicator

检查 Mongo 数据库是否启动。

neo4j

Neo4jHealthIndicator

检查 Neo4j 数据库是否启动。

ping

PingHealthIndicator

始终以 UP 响应。

rabbit

RabbitHealthIndicator

检查 Rabbit 服务器是否启动。

redis

RedisHealthIndicator

检查 Redis 服务器是否启动。

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

其他 HealthIndicators 可用，但默认情况下未启用

键名称说明

livenessstate

LivenessStateHealthIndicator

公开“Liveness”应用程序可用性状态。

readinessstate

ReadinessStateHealthIndicator

公开“Readiness”应用程序可用性状态。

编写自定义 HealthIndicators

要提供自定义健康信息，你可以注册实现 HealthIndicator 接口的 Spring bean。你需要提供 health() 方法的实现并返回 Health 响应。Health 响应应该包含一个状态，并且可以选择包含要显示的其他详细信息。以下代码显示了一个示例 HealthIndicator 实现

Java
Kotlin

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  ...
	}

}

给定 HealthIndicator 的标识符是 bean 的名称，如果存在，则不带 HealthIndicator 后缀。在前面的示例中，健康信息在名为 my 的条目中可用。

健康指示符通常通过 HTTP 调用，并且需要在任何连接超时之前做出响应。Spring Boot 将记录一条警告消息，针对任何响应时间超过 10 秒的健康指示符。如果你想配置此阈值，可以使用 management.endpoint.health.logging.slow-indicator-threshold 属性。

除了 Spring Boot 预定义的 Status 类型之外，Health 可以返回一个自定义 Status，表示新的系统状态。在这种情况下，你还需要提供 StatusAggregator 接口的自定义实现，或者必须使用 management.endpoint.health.status.order 配置属性配置默认实现。

例如，假设你的一个 HealthIndicator 实现中使用了一个代码为 FATAL 的新 Status。要配置严重性顺序，请将以下属性添加到你的应用程序属性中

属性
YAML

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 状态代码反映了整体健康状态。默认情况下，OUT_OF_SERVICE 和 DOWN 映射到 503。任何未映射的健康状态，包括 UP，都映射到 200。如果你通过 HTTP 访问健康端点，你可能还希望注册自定义状态映射。配置自定义映射会禁用 DOWN 和 OUT_OF_SERVICE 的默认映射。如果你想保留默认映射，则必须显式配置它们，以及任何自定义映射。例如，以下属性将 FATAL 映射到 503（服务不可用），并保留 DOWN 和 OUT_OF_SERVICE 的默认映射

属性
YAML

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

如果你需要更多控制，可以定义你自己的 HttpCodeStatusMapper bean。

下表显示了内置状态的默认状态映射

状态映射

DOWN

SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

SERVICE_UNAVAILABLE (503)

UP

默认情况下没有映射，因此 HTTP 状态为 200

UNKNOWN

默认情况下没有映射，因此 HTTP 状态为 200

响应式健康指示符

对于反应式应用程序（例如那些使用 Spring WebFlux 的应用程序），ReactiveHealthContributor 提供了一个非阻塞契约来获取应用程序运行状况。类似于传统的 HealthContributor，运行状况信息是从 ReactiveHealthContributorRegistry 的内容中收集的（默认情况下，所有 HealthContributor 和 ReactiveHealthContributor 实例都在 ApplicationContext 中定义）。不针对反应式 API 进行检查的常规 HealthContributors 在弹性调度程序上执行。

在反应式应用程序中，您应该使用 ReactiveHealthContributorRegistry 在运行时注册和注销运行状况指示器。如果您需要注册常规 HealthContributor，则应该使用 ReactiveHealthContributor#adapt 对其进行包装。

要从反应式 API 提供自定义运行状况信息，您可以注册实现 ReactiveHealthIndicator 接口的 Spring Bean。以下代码显示了一个示例 ReactiveHealthIndicator 实现

Java
Kotlin

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 会自动配置以下 ReactiveHealthIndicators

键名称说明

cassandra

CassandraDriverReactiveHealthIndicator

检查 Cassandra 数据库是否启动。

couchbase

CouchbaseReactiveHealthIndicator

检查 Couchbase 集群是否启动。

elasticsearch

ElasticsearchReactiveHealthIndicator

检查 Elasticsearch 集群是否启动。

mongo

MongoReactiveHealthIndicator

检查 Mongo 数据库是否启动。

neo4j

Neo4jReactiveHealthIndicator

检查 Neo4j 数据库是否启动。

redis

RedisReactiveHealthIndicator

检查 Redis 服务器是否启动。

如有必要，反应式指示器会替换常规指示器。此外，任何未显式处理的 HealthIndicator 都会自动包装。

运行状况组

有时将运行状况指示器组织到可用于不同目的的组中很有用。

要创建运行状况指示器组，您可以使用 management.endpoint.health.group.<name> 属性，并指定要 include 或 exclude 的运行状况指示器 ID 列表。例如，要创建一个仅包含数据库指示器的组，您可以定义以下内容

属性
YAML

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

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

然后，您可以通过访问 localhost:8080/actuator/health/custom 来检查结果。

同样，若要创建一个将数据库指标从组中排除且包含所有其他指标的组，您可以定义以下内容

属性
YAML

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

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

默认情况下，如果健康组包含或排除了不存在的健康指标，启动将失败。若要禁用此行为，请将 management.endpoint.health.validate-group-membership 设置为 false。

默认情况下，组继承与系统健康相同的 StatusAggregator 和 HttpCodeStatusMapper 设置。但是，您也可以在每个组的基础上定义这些设置。如果需要，您还可以覆盖 show-details 和 roles 属性

属性
YAML

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

如果您需要注册自定义 StatusAggregator 或 HttpCodeStatusMapper Bean 以与该组一起使用，则可以使用 @Qualifier("groupname")。

健康组还可以包含/排除 CompositeHealthContributor。您还可以仅包含/排除 CompositeHealthContributor 的特定组件。这可以使用组件的全限定名称按如下方式完成

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

在上面的示例中，custom 组将包含名称为 primary 的 HealthContributor，该名称是复合 test 的组件。此处，primary 本身是一个复合，名称为 b 的 HealthContributor 将从 custom 组中排除。

健康组可以在主端口或管理端口上的其他路径中使用。这在云环境（如 Kubernetes）中很有用，在 Kubernetes 中，出于安全目的，通常为执行器端点使用单独的管理端口。拥有单独的端口可能会导致不可靠的健康检查，因为即使健康检查成功，主应用程序也可能无法正常工作。可以按如下方式使用其他路径配置健康组

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

这将在 /healthz 上的主服务器端口上提供 live 健康组。前缀是必需的，并且必须是 server:（表示主服务器端口）或 management:（表示管理端口，如果已配置）。路径必须是单个路径段。

数据源健康

DataSource 健康指标显示标准数据源和路由数据源 Bean 的健康状况。路由数据源的健康状况包括其每个目标数据源的健康状况。在健康端点的响应中，每个路由数据源的目标都使用其路由键命名。如果您不想在指标的输出中包含路由数据源，请将 management.health.db.ignore-routing-data-sources 设置为 true。

Kubernetes 探测

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

默认情况下，Spring Boot 管理您的应用程序可用性状态。如果在 Kubernetes 环境中部署，执行器会从 ApplicationAvailability 接口收集“活动”和“就绪”信息，并在专用的运行状况指示器中使用该信息：LivenessStateHealthIndicator 和 ReadinessStateHealthIndicator。这些指示器显示在全局运行状况端点 ("/actuator/health") 上。它们还使用运行状况组作为单独的 HTTP 探测公开："/actuator/health/liveness" 和 "/actuator/health/readiness"。

然后，您可以使用以下端点信息配置您的 Kubernetes 基础设施

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

readinessProbe:
  httpGet:
    path: "/actuator/health/readiness"
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

<actuator-port> 应设置为执行器端点可用的端口。如果已设置 "management.server.port" 属性，则它可以是主 Web 服务器端口或单独的管理端口。

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

如果应用程序启动时间超过配置的活动期，Kubernetes 会将 "startupProbe" 作为可能的解决方案。一般来说，此处不一定需要 "startupProbe"，因为 "readinessProbe" 会一直失败，直到完成所有启动任务。这意味着您的应用程序在就绪之前不会接收流量。但是，如果您的应用程序启动时间很长，请考虑使用 "startupProbe" 来确保 Kubernetes 不会在应用程序启动过程中将其关闭。请参阅描述探测在应用程序生命周期中的行为的部分。

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

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

这将使 liveness 组在 /livez 处可用，并使 readiness 组在主服务器端口的 /readyz 处可用。路径可以使用每个组上的 additional-path 属性进行自定义，有关详细信息，请参阅健康组。

使用 Kubernetes 探针检查外部状态

Actuator 将“liveness”和“readiness”探针配置为健康组。这意味着所有健康组功能都对它们可用。例如，您可以配置其他健康指示器

属性
YAML

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

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

默认情况下，Spring Boot 不会向这些组添加其他健康指示器。

“liveness”探针不应依赖于外部系统的健康检查。如果应用程序的活动状态中断，Kubernetes 会尝试通过重新启动应用程序实例来解决该问题。这意味着如果外部系统（例如数据库、Web API 或外部缓存）发生故障，Kubernetes 可能会重新启动所有应用程序实例并创建级联故障。

至于“readiness”探针，应用程序开发人员必须仔细选择是否检查外部系统。因此，Spring Boot 在 readiness 探针中不包含任何其他健康检查。如果应用程序实例的 readiness 状态为未准备就绪，Kubernetes 不会将流量路由到该实例。某些外部系统可能不会由应用程序实例共享，在这种情况下，它们可以包含在 readiness 探针中。其他外部系统可能对应用程序来说不是必需的（应用程序可能具有断路器和后备），在这种情况下，绝对不应该包含它们。不幸的是，由所有应用程序实例共享的外部系统很常见，您必须做出判断：将其包含在 readiness 探针中并期望在外部服务关闭时应用程序退出服务，或者将其排除在外并处理堆栈中较高的故障，也许可以通过在调用方中使用断路器。

如果应用程序的所有实例都未准备就绪，则 type=ClusterIP 或 NodePort 的 Kubernetes 服务不接受任何传入连接。没有 HTTP 错误响应（503 等），因为没有连接。具有 type=LoadBalancer 的服务可能会或可能不会接受连接，具体取决于提供程序。具有显式 ingress 的服务也会以取决于实现的方式响应——ingress 服务本身必须决定如何处理下游的“连接被拒绝”。对于负载均衡器和 ingress，HTTP 503 很有可能发生。

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

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

Kubernetes 探测支持的一个重要方面是其与应用程序生命周期的协调一致性。AvailabilityState（应用程序的内存内内部状态）与实际探测（公开该状态）之间存在显著差异。探测可能不可用，具体取决于应用程序生命周期的阶段。

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

下表显示了不同阶段的 AvailabilityState 和 HTTP 连接器状态。

当 Spring Boot 应用程序启动时

启动阶段活动状态准备状态 HTTP 服务器备注

正在启动

BROKEN

REFUSING_TRAFFIC

未启动

Kubernetes 检查“活动”探测，如果花费时间过长，则重新启动应用程序。

已启动

CORRECT

REFUSING_TRAFFIC

拒绝请求

应用程序上下文已刷新。应用程序执行启动任务，但尚未接收流量。

已准备就绪

CORRECT

ACCEPTING_TRAFFIC

接受请求

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

当 Spring Boot 应用程序关闭时

关闭阶段活动状态准备状态 HTTP 服务器备注

正在运行

CORRECT

ACCEPTING_TRAFFIC

接受请求

已请求关闭。

正常关闭

CORRECT

REFUSING_TRAFFIC

拒绝新请求

如果已启用，正常关闭处理正在进行的请求。

关闭完成

N/A

服务器已关闭

应用程序上下文已关闭，应用程序已关闭。

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

应用程序信息

应用程序信息公开从所有 InfoContributor bean（在 ApplicationContext 中定义）收集的各种信息。Spring Boot 包含许多自动配置的 InfoContributor bean，您也可以编写自己的 bean。

自动配置的 InfoContributors

在适当的情况下，Spring 会自动配置以下 InfoContributor bean

ID 名称说明先决条件

build

BuildInfoContributor

公开构建信息。

META-INF/build-info.properties 资源。

env

EnvironmentInfoContributor

公开名称以 info. 开头的 Environment 中的任何属性。

无。

git

GitInfoContributor

公开 git 信息。

git.properties 资源。

java

JavaInfoContributor

公开 Java 运行时信息。

无。

os

OsInfoContributor

公开操作系统信息。

无。

process

ProcessInfoContributor

公开进程信息。

无。

是否启用单个贡献者由其 management.info.<id>.enabled 属性控制。不同的贡献者对此属性有不同的默认设置，具体取决于其先决条件和公开信息的性质。

如果没有先决条件表明应启用，则默认情况下 env、java、os 和 process 贡献者处于禁用状态。可以通过将其 management.info.<id>.enabled 属性设置为 true 来启用每个贡献者。

build 和 git 信息贡献者默认启用。可以通过将其 management.info.<id>.enabled 属性设置为 false 来禁用每个贡献者。或者，要禁用通常默认启用的每个贡献者，请将 management.info.defaults.enabled 属性设置为 false。

自定义应用程序信息

启用 env 贡献者时，可以通过设置 info.* Spring 属性来自定义 info 端点公开的数据。info 键下的所有 Environment 属性都会自动公开。例如，可以将以下设置添加到 application.properties 文件中

属性
YAML

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"

除了硬编码这些值，还可以在构建时扩展信息属性。

假设使用 Maven，可以将前面的示例重写如下

属性
YAML

[email protected]@
[email protected]@
[email protected]@

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

Git 提交信息

info 端点的另一个有用功能是它能够在构建项目时发布有关 git 源代码存储库状态的信息。如果 GitProperties bean 可用，则可以使用 info 端点公开这些属性。

如果在类路径的根目录下存在 `git.properties` 文件，则会自动配置一个 `GitProperties` bean。有关更多详细信息，请参阅“如何生成 git 信息”。

默认情况下，端点会公开 `git.branch`、`git.commit.id` 和 `git.commit.time` 属性（如果存在）。如果您不希望端点响应中包含任何这些属性，则需要将它们从 `git.properties` 文件中排除。如果您想显示完整的 git 信息（即 `git.properties` 的完整内容），请使用 `management.info.git.mode` 属性，如下所示

属性
YAML

management.info.git.mode=full

management:
  info:
    git:
      mode: "full"

要完全禁用 `info` 端点中的 git 提交信息，请将 `management.info.git.enabled` 属性设置为 `false`，如下所示

属性
YAML

management.info.git.enabled=false

management:
  info:
    git:
      enabled: false

构建信息

如果存在 `BuildProperties` bean，则 `info` 端点还可以发布有关您的构建的信息。如果类路径中存在 `META-INF/build-info.properties` 文件，则会发生这种情况。

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

Java 信息

info 端点发布有关您的 Java 运行时环境的信息，有关更多详细信息，请参阅 JavaInfo。

操作系统信息

info 端点发布有关您的操作系统的的信息，有关更多详细信息，请参阅 OsInfo。

进程信息

info 端点发布有关您的进程的信息，有关更多详细信息，请参阅 ProcessInfo。

编写自定义 InfoContributors

要提供自定义应用程序信息，您可以注册实现 InfoContributor 接口的 Spring bean。

以下示例提供了一个带有单个值的 `example` 条目

Java
Kotlin

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

}

如果您访问 `info` 端点，您应该会看到包含以下附加条目的响应

{
	"example": {
		"key" : "value"
	}
}

软件物料清单 (SBOM)

sbom 端点公开软件物料清单。可以自动检测 CycloneDX SBOM，但也可以手动配置其他格式。

spring-boot-starter-parent Maven 父级和 Spring Boot Gradle 插件分别配置了 CycloneDX Maven 插件和 CycloneDX Gradle 插件。

要获取 CycloneDX SBOM，你需要将其添加到 Maven 构建中

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

对于 Gradle，你需要应用 CycloneDX Gradle 插件

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

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

其他 SBOM 格式

如果你想以不同的格式发布 SBOM，可以使用一些配置属性。

配置属性 management.endpoint.sbom.application.location 设置应用程序 SBOM 的位置。例如，将其设置为 classpath:sbom.json 将使用类路径上 /sbom.json 资源的内容。

CycloneDX、SPDX 和 Syft 格式的 SBOM 的媒体类型会自动检测。要覆盖自动检测的媒体类型，请使用配置属性 management.endpoint.sbom.application.media-type。

其他 SBOM

执行器端点可以处理多个 SBOM。要添加 SBOM，请使用配置属性 management.endpoint.sbom.additional，如下例所示

属性
YAML

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.json 中。如果文件不存在，可以使用 optional: 前缀来防止启动失败。