本地启动Keycloak start-dev模式报错：找不到oracle/sql/CharacterSet

问题根源 #

启动报错的核心原因是：Quarkus的Oracle JDBC扩展默认被包含在Keycloak的构建包中，但Oracle官方JDBC驱动受许可证限制，无法从公共Maven仓库自动拉取，导致运行时找不到oracle/sql/CharacterSet类。

解决方案 #

方案1：排除Oracle JDBC扩展（无需Oracle数据库时使用） #

如果不需要连接Oracle数据库，直接从项目中排除Oracle JDBC扩展即可：

1. 打开Keycloak项目根目录下的quarkus/server/pom.xml文件
2. 找到keycloak-quarkus-server依赖块，添加排除规则：

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-quarkus-server</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-jdbc-oracle</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 重新构建项目：

mvn clean install -DskipTests

4. 再次执行原启动命令即可。

方案2：添加Oracle JDBC驱动（需要连接Oracle数据库时使用） #

如果需要对接Oracle数据库，需手动引入官方JDBC驱动：

1. 从Oracle官方渠道下载对应Java版本的JDBC驱动（如ojdbc11对应Java 11+）
2. 将驱动Jar包安装到本地Maven仓库（替换命令中的Jar路径、版本信息）：

mvn install:install-file -Dfile=./ojdbc11.jar -DgroupId=com.oracle.database.jdbc -DartifactId=ojdbc11 -Dversion=23.3.0.23.09 -Dpackaging=jar

3. 在quarkus/server/pom.xml中添加驱动依赖：

<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc11</artifactId>
    <version>23.3.0.23.09</version>
</dependency>

4. 重新构建项目并启动服务。

额外说明 #

• Keycloak默认构建会包含多种数据库驱动扩展以适配不同场景，但Oracle驱动因许可证限制无法自动引入，这也是切换到release/26.0分支后问题仍存在的原因。

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