关于Spring Boot Admin获取Actuator端点监控地址配置及management.health健康指标器的相关分析及注意事项

关注

原创最新推荐文章于 2026-10-14 15:49:16 发布 5.6k 阅读 AI 写同款· GEO 优化 ›

【SpringBoot新手篇】SpringBoot集成actuator监控服务 SpringBoot整合actuatorSpringBoot监控管理SpringBoot Actuator的使用Actuator 的 REST 接口命令详解health自定义 HealthIndicator 健康检查infobeansconditionsheapdumpshutdownmappingsthreaddump SpringBoot监控管理微服务的特点决定了功能模块的部署是分布式的，大部分功能模块都是运行在不同的机器上，彼此通过服务调用进行交互，前后台的业务流会经过很多个微服务的处理和传递，出现阅读详情

最近在使用Spring Boot Admin的时候发现(以下简称SBA)，使用eureka的注册中心的时候sba可以正常获取到服务的管理地址和健康检测地址，而换了Nacos作为注册中的时候，sba中的服务管理地址和健康检测地址是错误的。如图

一般来说正常的
服务访问地址是：http://IP:${server.port}/${server.servlet.context-path},
服务管理地址是：http://IP:${management.server.port}/${management.server.servlet.context-path}/${management.endpoints.web.base-path},其中这里management.endpoints.web.base-path默认为/actuator,
健康检测地址是：http://IP:${management.server.port}/${management.server.servlet.context-path}/${management.endpoints.web.base-path}/health

例如一个服务的如果设置
management.server.port = 30000
management.server.servlet.context-path = /sba
服务管理地址为：http://127.0.0.1:30000/sba/actuator,
健康检测地址为：http://127.0.0.1:30000/sba/actuator/health,

如果management.endpoints.web.base-path = /act
服务管理地址为：http://127.0.0.1:30000/sba/act,
健康检测地址为：http://127.0.0.1:30000/sba/act/health,

这是从应用程序的使用角度来说的，也就是通过上面的配置就可以在对应的配置地址访问到端点监控数据。

而通常来说我们是不配置management.server.servlet.context-path和management.endpoints.web.base-path的，所以对于管理地址来说，就是简单的http://IP:${management.server.port}/actuator

哪么问题来了，为何使用Nacos作为注册中心的时候，sba取到的地址有问题呢？这样我们就只能从sba的角度来查看了，我们首先来看一下sba的自动配置类AdminServerDiscoveryAutoConfiguration，de.codecentric.boot.admin.server.cloud.config.AdminServerDiscoveryAutoConfiguration

@Bean
	@ConditionalOnMissingBean({ ServiceInstanceConverter.class })
	@ConfigurationProperties(prefix = "spring.boot.admin.discovery.converter")
	public DefaultServiceInstanceConverter serviceInstanceConverter() {
		return new DefaultServiceInstanceConverter();
	}

	@Configuration(proxyBeanMethods = false)
	@ConditionalOnMissingBean({ ServiceInstanceConverter.class })
	@ConditionalOnBean(EurekaClient.class)
	public static class EurekaConverterConfiguration {

		@Bean
		@ConfigurationProperties(prefix = "spring.boot.admin.discovery.converter")
		public EurekaServiceInstanceConverter serviceInstanceConverter() {
			return new EurekaServiceInstanceConverter();
		}

	}

	@Configuration(proxyBeanMethods = false)
	@ConditionalOnMissingBean({ ServiceInstanceConverter.class })
	@ConditionalOnBean(KubernetesDiscoveryClient.class)
	public static class KubernetesConverterConfiguration {

		@Bean
		@ConfigurationProperties(prefix = "spring.boot.admin.discovery.converter")
		public KubernetesServiceInstanceConverter serviceInstanceConverter() {
			return new KubernetesServiceInstanceConverter();
		}

	}

可以看出来，这里包含了实例的转换器，这里有一个de.codecentric.boot.admin.server.cloud.discovery.DefaultServiceInstanceConverter 我们首先来看一下，DefaultServiceInstanceConverter为其默认Converter，EurekaServiceInstanceConverter 和 KubernetesServiceInstanceConverter都继承于DefaultServiceInstanceConverter，作为Eureka和Kubernetes实现，我们来分析一下DefaultServiceInstanceConverter里是如何获取到服务实例的地址的。

public class DefaultServiceInstanceConverter implements ServiceInstanceConverter {

	private static final Logger LOGGER = LoggerFactory.getLogger(DefaultServiceInstanceConverter.class);

	private static final String KEY_MANAGEMENT_SCHEME = "management.scheme";

	private static final String KEY_MANAGEMENT_ADDRESS = "management.address";

	private static final String KEY_MANAGEMENT_PORT = "management.port";

	private static final String KEY_MANAGEMENT_PATH = "management.context-path";

	private static final String KEY_HEALTH_PATH = "health.path";

	/**
	 * Default context-path to be appended to the url of the discovered service for the
	 * managment-url.
	 */
	private String managementContextPath = "/actuator";

	/**
	 * Default path of the health-endpoint to be used for the health-url of the discovered
	 * service.
	 */
	private String healthEndpointPath = "health";

    // 注册服务实例的名称，健康检测地址，管理地址，服务地址，metadata数据
	@Override
	public Registration convert(ServiceInstance instance) {
		LOGGER.debug("Converting service '{}' running at '{}' with metadata {}", instance.getServiceId(),
				instance.getUri(), instance.getMetadata());

		return Registration.create(instance.getServiceId(), getHealthUrl(instance).toString())
				.managementUrl(getManagementUrl(instance).toString()).serviceUrl(getServiceUrl(instance).toString())
				.metadata(getMetadata(instance)).build();
	}

    // 这里就是拼接管理地址和健康检测路径，http://192.168.14.240:2429/actuator/health
	protected URI getHealthUrl(ServiceInstance instance) {
		return UriComponentsBuilder.fromUri(getManagementUrl(instance)).path("/").path(getHealthPath(instance)).build()
				.toUri();
	}

    // 这里取的是健康检测地址，首先从服务实例的MetaData中的health.path取，取不到默认值是health
	protected String getHealthPath(ServiceInstance instance) {
		String healthPath = instance.getMetadata().get(KEY_HEALTH_PATH);
		if (!isEmpty(healthPath)) {
			return healthPath;
		}
		return this.healthEndpointPath;
	}

	protected URI getManagementUrl(ServiceInstance instance) {
		URI serviceUrl = this.getServiceUrl(instance);
		String managementScheme = this.getManagementScheme(instance);
		String managementHost = this.getManagementHost(instance);
		int managementPort = this.getManagementPort(instance);

		UriComponentsBuilder builder;
		if (serviceUrl.getHost().equals(managementHost) && serviceUrl.getScheme().equals(managementScheme)
				&& serviceUrl.getPort() == managementPort) {
			builder = UriComponentsBuilder.fromUri(serviceUrl);
		}
		else {
			builder = UriComponentsBuilder.newInstance().scheme(managementScheme).host(managementHost);
			if (managementPort != -1) {
				builder.port(managementPort);
			}
		}

		return builder.path("/").path(getManagementPath(instance)).build().toUri();
	}

    // 这里取的是Scheme的内容，首先从服务实例的MetaData中的management.scheme取，取不到就是instance.getUri().getScheme()默认的http
	private String getManagementScheme(ServiceInstance instance) {
		String managementServerScheme = instance.getMetadata().get(KEY_MANAGEMENT_SCHEME);
		if (!isEmpty(managementServerScheme)) {
			return managementServerScheme;
		}
		return getServiceUrl(instance).getScheme();
	}

    // 这里取的是管理主机地址，也是从MeatData中management.address取，取不到用的就是instance.getUri().getHost()
	protected String getManagementHost(ServiceInstance instance) {
		String managementServerHost = instance.getMetadata().get(KEY_MANAGEMENT_ADDRESS);
		if (!isEmpty(managementServerHost)) {
			return managementServerHost;
		}
		return getServiceUrl(instance).getHost();
	}

    // 这里取的是管理端口号，也是从MeatData中management.port取，取不到用的就是instance.getUri().getPort()，实例端口
	protected int getManagementPort(ServiceInstance instance) {
		String managementPort = instance.getMetadata().get(KEY_MANAGEMENT_PORT);
		if (!isEmpty(managementPort)) {
			return Integer.parseInt(managementPort);
		}
		return getServiceUrl(instance).getPort();
	}

    // 这里取的是管理路径，也是从MeatData中management.context-path取，取不到用的就是使用默认值/actuator
	protected String getManagementPath(ServiceInstance instance) {
		String managementPath = instance.getMetadata().get(DefaultServiceInstanceConverter.KEY_MANAGEMENT_PATH);
		if (!isEmpty(managementPath)) {
			return managementPath;
		}
		return this.managementContextPath;
	}

    // 这里取到的是 IP:端口号 htpp://instance.host:instance.port
	protected URI getServiceUrl(ServiceInstance instance) {
		return instance.getUri(); 
	}

	protected Map<String, String> getMetadata(ServiceInstance instance) {
		return (instance.getMetadata() != null) ? instance.getMetadata() : emptyMap();
	}

	public void setManagementContextPath(String managementContextPath) {
		this.managementContextPath = managementContextPath;
	}

	public String getManagementContextPath() {
		return this.managementContextPath;
	}

	public void setHealthEndpointPath(String healthEndpointPath) {
		this.healthEndpointPath = healthEndpointPath;
	}

	public String getHealthEndpointPath() {
		return this.healthEndpointPath;
	}

}

所以sba 会获取 instance的name、managementUrl、healthUrl、serviceUrl、metadata数据，这些地址都是首先从metadata数据中获取并进行组装，主要的涉及到配置的重点参数包含如下三个，

KEY_MANAGEMENT_PORT = "management.port"; 这个参数不需要特殊配置，因为注册中心使用的时候会自动配置进入metadata，重点在于下面的两个参数上

KEY_MANAGEMENT_PATH = "management.context-path";

KEY_HEALTH_PATH = "health.path";

那么只要保持这些参数使用了正确的配置，那么让sba获取到完美的管理地址、健康检测地址就变得轻松容易了。

如果你使用的是eureka作为注册中心，erueka中如何配置呢

eureka:
  instance:
    metadata-map:
      management.context-path: ${management.endpoints.web.base-path:/actuator}
      health.path: /health

如果你使用的是Nacos作为注册中心，Nacos中如何配置呢

spring:
  cloud:
    nacos:
      discovery:
        metadata:
          management.context-path: ${management.endpoints.web.base-path:/actuator}
          health.path: /health

因为开始已经说了服务管理地址是：http://IP:${management.server.port}/${management.server.servlet.context-path}/${management.endpoints.web.base-path},其中这里management.endpoints.web.base-path默认为/actuator, 所以management.context-path 就要跟随 management.endpoints.web.base-path走

这里有一个特别特别重要的点，就是在sba时候，内部默认是没有对 management.server.servlet.context-path 进行特殊的处理，所以使用sba的时候，切记，不要设置management.server.servlet.context-path，而且用处也不是很大只要不配置就可以了，也不要配置成management.server.servlet.context-path=/ 这种形式。如果你说你特别想用，哪只能去改写自己实现一个继承DefaultServiceInstanceConverter 并完成自动配置，以便完成sba对 management.server.servlet.context-path 的处理逻辑也是可以实现的，不过这里就不做过多讲解了，因为没必要浪费这样的精力去搞这件事。

到此我们只需要考虑如何为sba实现正确的配置了。

下面我们反过来再说，为何配置文件中metadata中不配置management.context-path的时候，Nacos为何无法支持呢，因为从上面的源码可以看到取 getManagementPath 的时候，优先级是先从metadata中取得，如果没有配置，那么取的就是默认的 /actuator，但是Nacos中初始化的时候却偏偏设置了management.context-path，nacos注册中心可以说是对metadata填充的还是比较全面的了，我们从com.alibaba.cloud.nacos.registry.NacosRegistration这个类中可以看到，com.alibaba.cloud.nacos.registry.NacosRegistration.init() ，在init初始化方法中，

if (null != managementPort) {
    metadata.put(MANAGEMENT_PORT, managementPort.toString());
	String contextPath = env.getProperty("management.server.servlet.context-path");
	String address = env.getProperty("management.server.address");
	if (!StringUtils.isEmpty(contextPath)) {
		metadata.put(MANAGEMENT_CONTEXT_PATH, contextPath);
	}
	if (!StringUtils.isEmpty(address)) {
		metadata.put(MANAGEMENT_ADDRESS, address);
	}
}

management.context-path 被 management.server.servlet.context-path 给覆盖掉了，这样取到的地址就少了一层目录

例如假设如下设置：

management.server.port = 30000
management.server.servlet.context-path = /sba
management.endpoints.web.base-path = /act

按设置来说 metadata中的management.context-path = ${management.endpoints.web.base-path:/actuator} 也就是 metadata中的 management.context-path = /act，sba生成的管理地址是 http://127.0.0.1:30000/sba/act

如果此时不设置management.endpoints.web.base-path，sba管理地址是 http://127.0.0.1:30000/sba/actuator

如果此时不设置management.server.servlet.context-path，sba管理地址是http://127.0.0.1:30000/actuator

但是如果此时设置了management.server.servlet.context-pathNacos会把metadata中的management.context-path覆盖

所以对于Nacos来说

例如假设只设置了management.server.servlet.context-path = /sba

那么从服务角度来说管理地址正确的应该是 http://127.0.0.1:30000/sba/actuator，
而从sba角度来说地址是http://127.0.0.1:30000/sba，所以sba生成地址就不正常了因此取不到管理地址及健康检测地址

归纳起来总结为：
sba管理地址为：http://127.0.0.1:30000/${management.context-path}
由于nacos中metadata中的management.context-path = management.server.servlet.context-path 地址就变为了 http://127.0.0.1:30000/${management.server.servlet.context-path}
而服务的实际地址是 http://127.0.0.1:30000/${management.server.servlet.context-path}/${management.endpoints.web.base-path:/actuator}，这就是nacos的问题所在。

上面只是解释了应用Nacos会出现sba取错地址问题的原因，说了很多，可能你已经迷糊了，但只要记住几点，设置如下几个参数的时候要注意。

1、management.server.servlet.context-path 尽量不要设置，设置了就会影响sba的使用除非你自己处理sba。这样nacos就不会把metadata中的management.context-path覆盖，为第三步正常使用management.context-path奠定了条件

2、management.endpoints.web.base-path 尽量不要设置，默认即可 /actuator 也挺好的，但是设置了也不影响，只是第三步要跟随设置

3、配置的时候一定要且仅仅设置metadata中的management.context-path 和 health.path两项即可

metadata:
management.context-path: ${management.endpoints.web.base-path:/actuator}
health.path: /health

这样就可以保证在Spring Boot Admin中即便使用不同注册中心都可以取到和服务匹配的管理地址和健康检测地址啦！