Spring Boot Actuator端点404及映射路径异常求助

1. 检查管理端点前缀配置 #

Spring Boot Actuator的端点前缀由management.endpoints.web.base-path控制，日志里显示端点映射到/manage，大概率是这个配置被设为了/manage：

• 打开application.properties或application.yml：
  • properties格式：确认是否有management.endpoints.web.base-path=/manage，有则改成/actuator
  • yml格式：检查是否有如下配置，存在则修改base-path值

    management:
      endpoints:
        web:
          base-path: /manage
    

2. 排查自定义配置类的覆盖 #

项目中如果存在自定义配置类修改Actuator路径，比如通过WebMvcEndpointHandlerMapping调整，也要检查：

@Configuration
public class ActuatorConfig {
    @Bean
    public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) {
        // 若这里手动设置了webEndpointProperties.setBasePath("/manage")，改成"/actuator"
        webEndpointProperties.setBasePath("/actuator");
        // ...其他代码
    }
}

3. 调整Spring Security适配新前缀 #

如果之前Security配置只放行/manage/**，需要同步改成/actuator/**，否则访问会返回404或403：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/**").permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }
}

4. 排查配置优先级问题 #

• 检查启动参数：是否添加了--management.endpoints.web.base-path=/manage这类参数，有则移除或修改
• 检查系统变量：是否存在MANAGEMENT_ENDPOINTS_WEB_BASE_PATH=/manage的环境变量，需调整
• 检查环境配置：比如application-prod.properties这类环境专属配置文件是否覆盖了默认设置

5. 验证配置生效 #

修改后重启应用，查看启动日志，确认出现类似如下的映射记录：

Mapped "{[/actuator/health],methods=[GET],produces=[application/vnd.spring-boot.actuator.v3+json || application/vnd.spring-boot.actuator.v2+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.web.servlet.AbstractWebMvcEndpointHandlerMapping$OperationHandler.handle(javax.servlet.http.HttpServletRequest,java.util.Map<java.lang.String, java.lang.String>)

出现该日志后，访问http://localhost/actuator和http://localhost/actuator/health即可正常响应。

内容的提问来源于stack exchange，提问作者user20521519