Debian12部署Keycloak因找不到PostgreSQL驱动启动失败求助

核心错误原因 #

• JDBC驱动模块名称不匹配：PostgreSQL模块定义的名称是org.postgresql，但standalone配置的驱动中引用的是org.postgresql.connector，导致JBoss无法定位驱动模块，触发jboss.jdbc-driver.postgresql缺失的依赖错误。
• Infinispan缓存依赖连锁问题：第二个错误是数据源加载失败引发的连锁反应——Keycloak的actionTokens缓存组件无法初始化，进而导致后续依赖链断裂。

分步解决方案 #

1. 修正驱动模块引用 #

修改standalone配置文件中的<drivers>段，将模块名称改为与module.xml一致的org.postgresql：

<drivers>
    <driver name="postgresql" module="org.postgresql">
        <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
</drivers>

2. 验证模块路径与文件完整性 #

• 确认PostgreSQL模块路径KEYCLOAK_HOME/modules/system/layers/keycloak/org/postgresql结构正确：
  • 路径下必须同时存在module.xml和postgresql-9.4.1212.jar
  • 验证jar文件有效性：执行jar tf postgresql-9.4.1212.jar，确认输出中包含org.postgresql.xa.PGXADataSource类
• 当前module.xml的依赖配置（javax.api、javax.transaction.api）足够支持PostgreSQL驱动，无需额外修改。

3. 修复Infinispan缓存依赖（驱动问题解决后仍存在时） #

若修正驱动后仍出现Infinispan相关错误，可尝试：

• 切换为本地缓存模式：在standalone.xml中找到<cache-container name="keycloak">，确保配置为本地缓存：

  <cache-container name="keycloak" default-cache="default">
      <local-cache name="default"/>
      <local-cache name="actionTokens"/>
  </cache-container>
  

• 版本兼容性检查：PostgreSQL 9.4版本较旧，若使用最新Keycloak版本，建议将PostgreSQL升级至10及以上版本。

4. 启动验证 #

修改配置后，启动Keycloak并查看日志：

./bin/standalone.sh -c standalone.xml

启动成功后，访问Keycloak控制台验证数据源连接状态。

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