Spring Boot响应式Netty模式下无法访问H2控制台

问题根源 #

H2数据库控制台是基于Servlet实现的，而Spring WebFlux默认使用Netty服务器（非Servlet容器），无法自动识别并注册H2控制台的Servlet，导致访问时出现404错误。

解决方案 #

方案一：切换到Servlet栈（简单直接，若项目允许）

如果项目不需要严格依赖WebFlux的响应式特性，可以将WebFlux替换为传统Servlet栈：

1. 修改Gradle依赖，替换spring-boot-starter-webflux为spring-boot-starter-web，同时调整DGS依赖为Servlet版本：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    // 替换webflux为web
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation(platform("com.netflix.graphql.dgs:graphql-dgs-platform-dependencies:5.5.5"))
    // 使用DGS的Servlet starter
    implementation 'com.netflix.graphql.dgs:graphql-dgs-spring-boot-starter:5.5.5'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
    compileOnly 'org.projectlombok:lombok'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'io.projectreactor:reactor-test'
}

2. 重启应用后，直接访问http://localhost:8080/h2-console/即可。

方案二：在WebFlux中兼容H2控制台（保留响应式栈）

若必须使用WebFlux，需将服务器切换为支持Servlet的容器（如Tomcat），并手动注册H2控制台的Servlet：

1. 修改Gradle依赖，替换Netty为Tomcat：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation('org.springframework.boot:spring-boot-starter-webflux') {
        // 排除默认的Netty
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-reactor-netty'
    }
    // 添加Tomcat starter
    implementation 'org.springframework.boot:spring-boot-starter-tomcat'
    implementation(platform("com.netflix.graphql.dgs:graphql-dgs-platform-dependencies:5.5.5"))
    implementation 'com.netflix.graphql.dgs:graphql-dgs-webflux-starter:5.5.5'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
    compileOnly 'org.projectlombok:lombok'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'io.projectreactor:reactor-test'
}

2. 创建配置类，手动注册H2控制台Servlet：

import org.h2.server.web.WebServlet;
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

// 仅在local环境生效，和配置匹配
@Profile("local")
@Configuration
public class H2ConsoleConfiguration {

    @Bean
    public ServletRegistrationBean<WebServlet> h2ConsoleServletRegistration() {
        ServletRegistrationBean<WebServlet> registrationBean = new ServletRegistrationBean<>(new WebServlet());
        registrationBean.addUrlMappings("/h2-console/*");
        return registrationBean;
    }
}

3. 确保启动时激活local配置文件（比如添加启动参数--spring.profiles.active=local），重启应用后即可访问H2控制台。

额外检查项 #

• 确认application.yml中的spring.h2.console.enabled=true和path=/h2-console配置正确，且当前激活的是local配置文件。
• 若后续添加Spring Security，需配置放行/h2-console/**路径，否则会被拦截。

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