Keycloak从18升级至19/20/21时遇“Failed to find provider jpa”错误求助

核心原因 #

Keycloak 19+版本对用户会话持久化的配置逻辑做了变更，旧版本中指定jpa类型的userSessionPersisterProvider配置不再兼容，或是依赖加载逻辑发生了调整。

具体解决步骤 #

1. 调整核心配置文件 #

• 打开keycloak.conf，移除其中的userSessionPersisterProvider=jpa配置项。Keycloak 19+默认已集成JPA会话持久化能力，无需手动指定该参数，只需确保数据库连接配置正确：

  db=mysql
  db-url=jdbc:mysql://localhost:3306/keycloak?useSSL=false&characterEncoding=UTF-8&serverTimezone=UTC
  db-username=keycloak
  db-password=your_db_password
  

2. 清理过时依赖与扩展 #

• 检查Keycloak安装目录下的providers文件夹，删除所有与userSessionPersister相关的自定义jar包或旧版本扩展文件，避免新旧依赖冲突。
• 确保使用Keycloak 21官方完整发行包，不要混合旧版本的依赖文件。

3. 重新执行数据库迁移命令 #

使用Keycloak 21官方提供的命令执行构建与迁移，确保参数匹配你的数据库类型：

./kc.sh build --db=mysql --db-url=jdbc:mysql://localhost:3306/keycloak --db-username=keycloak --db-password=your_db_password

如果使用容器环境：

docker run -it --rm quay.io/keycloak/keycloak:21.0.2 build --db=mysql --db-url=jdbc:mysql://host.docker.internal:3306/keycloak --db-username=keycloak --db-password=your_db_password

4. 移除传统模式下的废弃配置 #

若你仍在使用WildFly风格的standalone.xml或standalone-ha.xml配置文件，查找并删除以下配置段：

<spi name="userSessionPersister">
    <provider name="jpa" enabled="true"/>
</spi>

Keycloak 19+已采用新的会话存储机制，该配置会引发加载冲突。

5. 验证数据库兼容性与权限 #

• 确认数据库版本符合Keycloak 21要求：例如MySQL需8.0+，PostgreSQL需10+，避免因版本不兼容导致迁移失败。
• 确保数据库用户拥有创建、修改表结构的DDL权限，迁移过程需要执行表结构变更操作。

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