别再只加依赖了！Spring Boot Actuator 端点 404？检查这3个配置项（以/prometheus为例）

Spring Boot Actuator端点404问题深度排查指南从依赖到访问的全链路分析当你兴奋地在Spring Boot项目中添加了Micrometer和Prometheus的依赖准备大展身手时却发现访问/actuator/prometheus端点时只得到一个冷冰冰的404错误页面。这种挫败感我深有体会——毕竟我也曾在凌晨三点对着浏览器反复刷新同一个URL试图找出哪里出了问题。本文将带你系统性地排查可能导致Actuator端点无法访问的各种原因而不仅仅是依赖版本问题。1. 依赖配置不仅仅是添加那么简单很多开发者认为只要在pom.xml中添加了相关依赖一切就会自动工作。但现实往往更加复杂。让我们先检查最基本的依赖配置!-- 基础Web支持 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Actuator核心功能 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency !-- Prometheus监控支持 -- dependency groupIdio.micrometer/groupId artifactIdmicrometer-registry-prometheus/artifactId scoperuntime/scope /dependency注意micrometer-registry-prometheus通常应该使用runtime作用域因为它只在运行时需要编译时不需要。版本兼容性确实是常见问题之一。Spring Boot和Micrometer的版本必须匹配。以下是一个简单的版本对应表Spring Boot版本推荐的Micrometer版本2.2.x1.3.x2.3.x1.5.x2.4.x1.6.x2.5.x1.7.x检查版本兼容性后还需要确认依赖是否正确传递。有时因为依赖冲突实际使用的版本可能与预期不同。可以通过以下命令查看实际依赖树mvn dependency:tree -Dincludesio.micrometer2. 端点暴露配置那些容易忽略的细节即使依赖配置正确如果端点没有正确暴露你仍然会得到404错误。Spring Boot Actuator的端点暴露配置看似简单实则暗藏玄机。最基本的配置看起来是这样的management: endpoints: web: exposure: include: *但这只是冰山一角。以下是几种常见的配置陷阱过度依赖通配符虽然include: *很方便但在生产环境中可能会暴露过多敏感信息混合使用include和exclude当两者同时存在时排除规则优先于包含规则YAML缩进问题不正确的缩进会导致配置不生效属性名拼写错误比如把endpoints写成endpoint更安全的做法是明确列出需要暴露的端点management: endpoints: web: exposure: include: health,info,prometheus,metrics提示可以通过/actuator端点查看当前已暴露的所有端点列表这是一个很好的调试工具。3. 安全配置看不见的拦截者即使依赖和端点配置都正确安全框架仍然可能阻止你访问Actuator端点。Spring Security是最常见的罪魁祸首。默认情况下Spring Security会保护所有端点。如果你看到了登录页面而不是404那么很可能是安全配置的问题。以下是几种解决方案方案一完全禁用安全性仅限开发环境SpringBootApplication public class MyApp { public static void main(String[] args) { new SpringApplicationBuilder(MyApp.class) .web(WebApplicationType.SERVLET) .properties(spring.autoconfigure.excludeorg.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration) .run(args); } }方案二配置特定的安全规则Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Override protected void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers(/actuator/**).permitAll() .anyRequest().authenticated() .and() .httpBasic(); } }方案三使用自定义管理端口management: server: port: 8081 endpoints: web: exposure: include: *这样可以将管理端点与业务API完全隔离便于实施不同的安全策略。4. 其他可能原因当常规检查都无效时如果以上三个方面都检查过了但问题仍然存在那么可能需要考虑一些不太常见的原因上下文路径(server.servlet.context-path)配置如果设置了上下文路径Actuator端点也会随之改变管理端点基础路径(management.endpoints.web.base-path)配置默认是/actuator但可以修改过滤器/拦截器干扰自定义的过滤器可能意外拦截了Actuator请求端口冲突另一个应用可能已经占用了端口缓存问题构建工具或IDE有时会缓存旧的依赖版本一个实用的调试方法是启用调试日志logging: level: org.springframework.boot.actuate: DEBUG org.springframework.security: DEBUG这可以帮助你看到请求是否真的到达了Actuator端点以及在哪里被拦截。在解决了一个特别棘手的Actuator问题后我养成了一个习惯每当添加新的监控或管理功能时都会从依赖、配置、安全三个维度进行交叉验证。这种系统性的检查方法不仅能解决当前问题还能预防未来可能出现的问题。