文章目录一、开篇从“出问题再查”到“提前发现问题”二、Actuator端点体系全解2.1 什么是Actuator端点2.2 核心内置端点清单2.3 端点配置三、健康检查机制与探针配置3.1 健康检查的语义分层3.2 健康组配置3.3 自定义健康指示器3.4 健康检查的性能考量四、指标采集与Micrometer集成4.1 Micrometer指标采集的门面4.2 Spring Boot 4.0的模块化变更4.3 核心指标清单4.4 自定义指标4.5 2025版可观测性新特性五、自定义端点开发实战5.1 Endpoint注解开发5.2 端点安全RequestMatcher六、生产安全配置6.1 2026年Actuator安全漏洞警示6.2 独立管理端口6.3 高危端点的处理6.4 健康检查的安全配置七、踩坑指南坑一健康检查导致Pod重启风暴坑二Actuator端点参数使用了错误的空安全注解坑三Micrometer Tracing依赖缺失导致Trace ID不显示坑四Prometheus端点暴露了敏感标签坑五CVE-2026-22731 健康组路径认证绕过八、课后作业九、下节预告《最新版 SpringCloud 2025 从入门到实战》系列课程导航适配版本Spring Boot 4.0.8、Spring Cloud 2025.1.3Oakwood、Micrometer 2.x、JDK 21课程定位监控追踪阶段开篇从可观测性概念到Actuator端点全解建立微服务监控的认知框架一、开篇从“出问题再查”到“提前发现问题”第21-24课我们完成了Sentinel熔断限流容错体系的全部建设。Sentinel解决的是**“出问题时怎么办”** ——熔断、降级、限流让系统在故障时优雅降级而非直接崩溃。但还有一个更根本的问题没有回答如何知道系统即将出问题假设你的微服务集群运行着20个服务实例。某个实例的内存使用率正在缓慢上升从60%涨到75%用了3天再过半天就会触发OOM导致服务崩溃。如果没有监控你只能在服务崩溃后收到告警然后开始排查日志。如果有了监控你可以在内存使用率超过80%时提前收到告警在服务崩溃前扩容或重启实例用户对此毫无感知。这就是可观测性Observability的价值。可观测性由三大支柱构成指标Metrics告诉你“系统当前状态如何”链路追踪Tracing告诉你“一个请求经过了哪些服务、每段耗时多少”日志Logging告诉你“系统在某个时刻发生了什么”。Spring Boot Actuator是可观测性的基础设施。它提供了开箱即用的端点Endpoints暴露应用的运行状态、健康检查、指标数据、环境配置等信息。第26课的PrometheusGrafana、第27课的SkyWalking、第28课的ELK都建立在Actuator和Micrometer的基础之上。本课将从Actuator的端点体系讲起深入健康检查机制和探针配置剖析Micrometer的指标采集原理实战自定义端点开发最后给出生产安全配置和2025版适配要点。二、Actuator端点体系全解2.1 什么是Actuator端点Actuator是Spring Boot提供的生产就绪特性Production-ready Features模块通过HTTP或JMX暴露应用内部的运行时信息。每个端点Endpoint是一个命名的功能单元通过id标识HTTP暴露时默认映射到/actuator/{id}路径。Actuator的核心设计原则是“默认安全”默认只暴露/health和/info两个端点其余端点需要显式配置才会暴露。这是为了避免生产环境中意外泄露敏感信息如环境变量、配置属性、堆转储。2.2 核心内置端点清单Spring Boot 4.0的Actuator内置端点按功能分为以下几类类别端点ID默认暴露核心用途健康检查health✅ HTTP应用健康状态支持liveness/readiness探针应用信息info✅ HTTP应用元数据版本、构建时间、Git信息指标metrics❌ 需显式开启所有Micrometer指标的列表和详情Prometheusprometheus❌ 需显式开启Prometheus文本格式的指标流环境env❌环境变量和配置属性Beanbeans❌容器中所有Bean的定义和依赖关系配置属性configprops❌ConfigurationProperties的绑定值日志loggers❌动态修改日志级别映射mappings❌所有RequestMapping路径线程threaddump❌JVM线程转储堆heapdump❌JVM堆转储生产环境应禁用关闭shutdown❌优雅关闭应用生产环境应禁用网关gateway❌Gateway路由信息需Gateway依赖生产环境的暴露原则最小暴露按需开启。生产环境只暴露health、info、metrics、prometheus四个端点其余端点通过management.endpoints.web.exposure.include显式指定或通过management.endpoint.id.enabledfalse单独禁用高危端点heapdump、env、shutdown。2.3 端点配置YAML配置方式management:endpoints:web:exposure:include:health,info,metrics,prometheus# 只暴露这4个端点exclude:env,beans,heapdump,shutdown# 排除高危端点endpoint:health:show-details:when-authorized# 健康详情仅授权用户可见prometheus:enabled:truemetrics:enabled:trueenv:enabled:false# 显式禁用到env端点heapdump:enabled:falseshutdown:enabled:false三、健康检查机制与探针配置3.1 健康检查的语义分层Spring Boot 4.0的健康检查将健康状态分为三个语义层次这是理解健康检查的关键Liveness存活进程是否活着。只回答“JVM是否还在运行”这个问题。如果liveness探针失败K8s会重启Pod。注意liveness不应该检查外部依赖如数据库否则数据库短暂不可用会导致Pod被反复重启形成重启风暴。Readiness就绪应用是否能接收流量。检查关键依赖数据库、Redis、下游服务是否可用。如果readiness探针失败K8s会将Pod从Service的端点列表中移除摘除流量但不重启Pod。Dependency Health依赖健康每个外部依赖的详细健康状态。MySQL、Redis、Elasticsearch等组件的连接状态。核心实践原则liveness和readiness必须分开配置。只看PID存在与否等于把“进程卡死”和“依赖不可用”两类故障混在一起导致错误的处理策略。3.2 健康组配置Spring Boot 4.0支持通过健康组Health Groups将不同的健康指标组合到不同的探针中management:endpoint:health:probes:add-additional-paths:true# 在根路径暴露 /livez 和 /readyzgroup:liveness:include:livenessState# 只包含应用存活状态readiness:include:readinessState,db# 包含就绪状态 数据库show-details:always配置效果路径含义失败后果/actuator/health/liveness存活探针K8s重启Pod/actuator/health/readiness就绪探针K8s摘除流量/livez存活探针根路径同上add-additional-pathstrue时/readyz就绪探针根路径同上add-additional-pathstrue时add-additional-pathstrue的作用是在根路径暴露/livez和/readyz这是K8s编排器期望的常规路径。原有的/actuator/health/liveness路径仍然保留新路径是追加的不是替换的。3.3 自定义健康指示器当需要检查外部服务如第三方API、自定义缓存的健康状态时实现HealthIndicator接口ComponentpublicclassThirdPartyApiHealthIndicatorimplementsHealthIndicator{AutowiredprivateThirdPartyApiClientapiClient;OverridepublicHealthhealth(){try{booleanavailableapiClient.ping();if(available){returnHealth.up().withDetail(endpoint,apiClient.getEndpoint()).withDetail(latency,apiClient.getLastLatency()ms).build();}returnHealth.down().withDetail(reason,API returned non-OK status).build();}catch(Exceptione){returnHealth.down(e).withDetail(endpoint,apiClient.getEndpoint()).build();}}}自定义健康指示器会自动注册到/actuator/health的响应中键名为thirdPartyApi去掉HealthIndicator后缀、驼峰转小写。踩坑提示HealthIndicator的实现不应抛出异常。如果health()方法抛出异常Spring Boot会捕获并将其转换为DOWN状态但不会包含异常详情。应该像上面的代码一样捕获异常并返回带有详情的Health.down()。3.4 健康检查的性能考量健康检查端点会被K8s频繁调用liveness每10秒、readiness每5秒是常见的配置。因此健康检查的实现必须轻量且快速。反模式在HealthIndicator中执行复杂的数据库查询或HTTP调用导致健康检查端点本身成为性能瓶颈。正确做法使用连接池的isValid()方法检查数据库连接而非执行SELECT 1对于外部HTTP依赖使用缓存的健康状态每30秒刷新一次而非每次健康检查都发起真实请求为健康检查设置独立的超时时间如2秒避免因依赖服务超时导致健康检查阻塞management:health:redis:enabled:truedb:enabled:truediskspace:enabled:truethreshold:100MB四、指标采集与Micrometer集成4.1 Micrometer指标采集的门面Spring Boot Actuator的指标采集基于Micrometer。Micrometer是一个指标门面类似于SLF4J之于日志——它提供了一套统一的API底层可以对接不同的监控系统Prometheus、Datadog、CloudWatch等。引入micrometer-registry-prometheus后Actuator会自动将指标以Prometheus格式暴露在/actuator/prometheus端点。4.2 Spring Boot 4.0的模块化变更Spring Boot 4.0对可观测性模块进行了模块化重构这是升级时最容易踩坑的地方旧依赖新依赖spring-boot-starter-actuator包含所有spring-boot-starter-actuator仅核心—spring-boot-micrometer-metrics指标模块—spring-boot-micrometer-tracing追踪模块spring-boot-starter-actuatormicrometer-tracing-bridge-bravespring-boot-starter-actuatorspring-boot-micrometer-tracing-brave关键变化追踪相关的模块被拆分spring-boot-micrometer-tracing是基础模块需要配合具体的桥接实现Brave或OpenTelemetry。!-- Spring Boot 4.0 的可观测性依赖 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-actuator/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-micrometer-metrics/artifactId/dependencydependencygroupIdio.micrometer/groupIdartifactIdmicrometer-registry-prometheus/artifactId/dependency4.3 核心指标清单启用Actuator和Prometheus注册表后以下指标自动可用指标类别指标名含义JVM内存jvm.memory.used各内存池使用量JVM GCjvm.gc.pauseGC停顿时间和次数JVM线程jvm.threads.live存活线程数HTTP请求http.server.requests每个端点的请求数、耗时、状态码CPUsystem.cpu.usage系统CPU使用率进程process.cpu.usage进程CPU使用率数据库hikaricp.connections.active连接池活跃连接数负载均衡spring.cloud.loadbalancer.requests.active各服务的活跃请求数4.4 自定义指标通过MeterRegistry注册自定义业务指标ServicepublicclassOrderMetricsService{privatefinalCounterorderCreatedCounter;privatefinalTimerorderProcessTimer;publicOrderMetricsService(MeterRegistryregistry){// 计数器订单创建总数按状态标记this.orderCreatedCounterCounter.builder(order.created.total).description(Total orders created).tag(status,pending).register(registry);// 计时器订单处理耗时this.orderProcessTimerTimer.builder(order.process.duration).description(Order processing duration).publishPercentiles(0.5,0.95,0.99).register(registry);}publicvoidrecordOrderCreated(Stringstatus){orderCreatedCounter.increment();}publicTTrecordProcessTime(SupplierToperation){returnorderProcessTimer.record(operation);}}4.5 2025版可观测性新特性Spring Boot 4.0将可观测性从“可选增强”升级为运行时核心契约首次将JVM Agent集成深度内置于启动生命周期中。应用启动时Spring Boot自动检测并加载兼容的Java Agent如Micrometer Registry Agent或OpenTelemetry Java Agent通过字节码增强实现零侵入的指标采集。Agent-Ready的核心变化旧版本需要手动添加-javaagent参数Spring Boot 4.0由spring-boot-loader自动发现并初始化Agent。启用方式spring:instrumentation:opentelemetry:enabled:trueresource:attributes:service.name:order-serviceenvironment:prod同时Spring Boot 4.0新增了/actuator/agent/status端点实时暴露已激活的Agent列表、插桩覆盖率和性能开销统计。五、自定义端点开发实战5.1 Endpoint注解开发通过Endpoint、ReadOperation、WriteOperation等注解定义自定义端点ComponentEndpoint(idrelease)publicclassReleaseEndpoint{AutowiredprivateReleaseInfoProviderreleaseInfoProvider;ReadOperationpublicReleaseInforelease(){returnreleaseInfoProvider.getCurrentRelease();}ReadOperationpublicReleaseInforeleaseForVersion(SelectorStringversion){returnreleaseInfoProvider.getRelease(version);}WriteOperationpublicvoidupdateRelease(SelectorStringversion){releaseInfoProvider.setCurrentRelease(version);}DeleteOperationpublicvoidclearRelease(SelectorStringversion){releaseInfoProvider.clearRelease(version);}}注解语义注解HTTP方法用途ReadOperationGET读取数据WriteOperationPOST写入数据DeleteOperationDELETE删除数据Selector路径变量从URL路径中提取参数访问方式/actuator/release、/actuator/release/{version}。5.2 端点安全RequestMatcher自定义端点默认受Actuator的安全配置保护。如果需要为特定端点配置独立的安全策略使用EndpointRequestConfigurationpublicclassActuatorSecurityConfig{BeanpublicSecurityFilterChainactuatorSecurityFilterChain(HttpSecurityhttp)throwsException{http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests(auth-auth.requestMatchers(EndpointRequest.to(health,info)).permitAll().requestMatchers(EndpointRequest.to(release)).hasRole(ACTUATOR_ADMIN).anyRequest().authenticated());returnhttp.build();}}注意EndpointRequest.toAnyEndpoint()匹配所有Actuator端点包括/actuator根路径。EndpointRequest.to(health, info)只匹配指定的端点。六、生产安全配置6.1 2026年Actuator安全漏洞警示2026年披露了两个与Actuator相关的安全漏洞必须引起重视CVE-2026-22731Actuator健康组Health Groups的“附加路径”映射逻辑存在缺陷。当通过additional-path配置了健康组路径时可能绕过身份认证直接访问健康端点。修复版本Spring Boot 4.0.3、3.5.11、3.4.15或更高版本。CVE-2026-40976当应用是Servlet-based、依赖spring-boot-actuator-autoconfigure但不依赖spring-boot-health时默认安全过滤链可能缺少授权规则允许未授权访问所有端点。修复版本Spring Boot 4.0.6或更高版本。Spring Cloud Commons的CVE-2026-59284writable env actuator endpoint缺少allow listSpring Cloud 2025.1.3已修复此漏洞。行动建议确保Spring Boot版本不低于4.0.8Spring Cloud版本为2025.1.3在防火墙或网络ACL层面限制管理端点的访问来源显式配置安全规则不依赖默认行为。6.2 独立管理端口将Actuator端点暴露在独立端口上与业务流量隔离management:server:port:8081# Actuator 独立端口仅内网可访问endpoints:web:base-path:/manage# 修改基础路径优势业务端口如8080不暴露Actuator端点降低攻击面。防火墙只需放行8081端口的内网访问公网完全不可达。6.3 高危端点的处理以下端点在生产环境中必须禁用除非有明确的业务需求端点风险处理方式heapdump下载堆转储可获取内存中的敏感数据密码、Tokenmanagement.endpoint.heapdump.enabledfalseenv暴露所有环境变量和配置属性management.endpoint.env.enabledfalseshutdown远程关闭应用management.endpoint.shutdown.enabledfalsethreaddump线程转储可能包含敏感信息仅在排查时临时开启6.4 健康检查的安全配置健康检查端点虽然默认暴露但健康详情show-details应限制为授权用户可见management:endpoint:health:show-details:when-authorized# 仅授权用户可见详情roles:ACTUATOR_ADMIN# 需要该角色未授权用户访问时/actuator/health只返回{status:UP}不包含数据库、Redis等依赖的详细状态。七、踩坑指南坑一健康检查导致Pod重启风暴现象数据库短暂不可用后K8s反复重启Pod服务完全不可用。原因liveness探针包含了数据库健康检查。数据库不可用时liveness失败K8s重启PodPod重启后数据库仍然不可用再次重启形成循环。解决liveness只检查livenessState不包含任何外部依赖。数据库、Redis等依赖放入readiness探针。坑二Actuator端点参数使用了错误的空安全注解现象升级到Spring Boot 4.0后自定义端点的可选参数报编译错误。原因Spring Boot 4.0移除了javax.annotations.NonNull和org.springframework.lang.Nullable在Actuator端点参数上的支持。必须使用OptionalParameter或org.jspecify.annotations.Nullable。解决将端点参数注解迁移到OptionalParameter或JSpecify的Nullable。坑三Micrometer Tracing依赖缺失导致Trace ID不显示现象升级到Spring Boot 4.0后日志中不再显示Trace ID和Span ID。原因Spring Boot 4.0将追踪模块拆分需要显式添加桥接依赖dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-micrometer-tracing-brave/artifactId/dependency解决添加spring-boot-micrometer-tracing-brave或spring-boot-micrometer-tracing-opentelemetry依赖。坑四Prometheus端点暴露了敏感标签现象Prometheus指标中包含uri标签暴露了内部API路径。原因http.server.requests指标默认包含请求URI。如果URI中包含敏感参数如/api/user/{id}中的id实际值可能泄露信息。解决配置指标标签过滤management:metrics:tags:application:${spring.application.name}web:server:request:autotime:enabled:true同时确保URI使用路径模板/api/user/{id}而非实际值。坑五CVE-2026-22731 健康组路径认证绕过现象配置了add-additional-pathstrue后/livez和/readyz路径可能绕过安全认证。原因健康组的附加路径映射逻辑存在缺陷。解决升级到Spring Boot 4.0.8或至少4.0.3。同时如果不需要根路径的/livez和/readyz不要开启add-additional-paths。八、课后作业作业一在service-user中引入Actuator依赖配置只暴露health、info、metrics、prometheus四个端点。访问/actuator/health确认返回了UP状态。作业二配置liveness和readiness探针。在service-user中实现一个HealthIndicator检查一个模拟的外部服务。配置readiness组包含该检查liveness组只包含livenessState。验证模拟外部服务不可用时/actuator/health/readiness返回DOWN而/actuator/health/liveness仍返回UP。作业三实现一个自定义Endpoint暴露当前服务的版本信息和启动时间。配置该端点仅ACTUATOR_ADMIN角色可访问。作业四通过MeterRegistry注册一个自定义的Counter记录某个业务方法的调用次数。访问/actuator/metrics/{your.metric.name}验证指标存在且计数正确。作业五进阶配置Actuator独立管理端口8081验证业务端口8080无法访问Actuator端点。配置show-details: when-authorized验证未授权用户只能看到{status:UP}。九、下节预告第26课将进入PrometheusGrafana指标监控大盘搭建。我们将从Prometheus的指标采集原理讲起完成Prometheus部署、指标暴露、Grafana可视化大盘搭建配置CPU/内存/QPS/延迟监控和告警规则。本课完成了Actuator的端点体系和指标采集基础第26课将把这些指标真正“用起来”——采集、存储、可视化、告警。Actuator是数据源Prometheus是采集器Grafana是展示层三者构成指标监控的完整链路。《最新版 SpringCloud 2025 从入门到实战》系列课程导航去订阅第一部分微服务前置基础 新版环境搭建第1-5课第二部分注册中心核心Nacos 最新版第6-9课第三部分配置中心核心Nacos配置中心第10-12课第四部分服务通信核心OpenFeign LoadBalancer第13-16课第五部分网关核心SpringCloud Gateway 新版第17-20课第六部分熔断、限流、降级Sentinel 新版第21-24课第七部分微服务监控、链路追踪、日志体系第25-28课第八部分微服务高阶特性 分布式核心能力第29-31课第九部分企业级完整项目实战 架构复盘第32-35课