KeyCloak 13.0升级至22.0.4时H2数据库认证失败求助

问题背景 #

• 旧版本：Keycloak 13.0，使用H2 1.4.197，路径/root/keycloak/keycloak-13.0
• 升级操作流程：
  1. 生成H2备份SQL：

     java -cp h2-1.4.197.jar org.h2.tools.Script -url jdbc:h2:./standalone/data/keycloak -user sa -password sa
     

  2. 用H2 2.2.220恢复到新版本数据库：

     java -cp com.h2database.h2-2.2.220.jar org.h2.tools.RunScript -url jdbc:h2:./keycloak -script backup.sql -user sa -password sa -options FROM_1X
     

  3. 配置新版本conf/keycloak.conf的数据库参数：

     # The username of the database user.
     db-username=sa
     
     # The password of the database user.
     db-password=sa
     
     # The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.
     db-url=jdbc:h2:/root/keycloak/keycloak-22.0.4/data/keycloak
     

• 异常现象：启动Keycloak时报错Could not obtain connection to query metadata: org.h2.jdbc.JdbcSQLInvalidAuthorizationSpecException: Wrong user name or password [28000-220]，但手动用H2客户端连接该数据库文件时，sa账号可正常登录。

排查与解决步骤 #

1. 检查数据库文件权限 #

确保Keycloak运行进程对数据库文件及目录有读写权限：

# 若Keycloak以root运行，可跳过权限修改；否则替换为实际运行用户
chown -R root:root /root/keycloak/keycloak-22.0.4/data/
chmod 644 /root/keycloak/keycloak-22.0.4/data/keycloak.mv.db

2. 修改H2 JDBC URL参数 #

H2 2.x默认使用新的密码哈希算法，与H2 1.x不兼容，需在URL中强制使用旧算法。更新conf/keycloak.conf的db-url：

db-url=jdbc:h2:/root/keycloak/keycloak-22.0.4/data/keycloak;DB_CLOSE_ON_EXIT=FALSE;PASSWORD_HASH=OLD

• PASSWORD_HASH=OLD：强制H2使用1.x版本的密码哈希规则，确保旧的sa密码能被识别
• DB_CLOSE_ON_EXIT=FALSE：避免JVM退出时自动关闭数据库，符合Keycloak运行需求

3. 检查环境变量覆盖配置 #

Keycloak优先读取环境变量，若存在KC_DB_USERNAME、KC_DB_PASSWORD、KC_DB_URL会覆盖配置文件内容：

# 检查相关环境变量
echo $KC_DB_USERNAME $KC_DB_PASSWORD $KC_DB_URL

# 若有不符合的变量，执行清除
unset KC_DB_USERNAME KC_DB_PASSWORD KC_DB_URL

4. 验证数据库连接可用性 #

使用Keycloak内置的H2驱动测试连接，确认数据库本身无问题：

cd /root/keycloak/keycloak-22.0.4
java -cp ./lib/h2-*.jar org.h2.tools.Shell -url jdbc:h2:/root/keycloak/keycloak-22.0.4/data/keycloak -user sa -password sa

若能正常进入H2命令行，说明数据库连接参数正确。

5. 清理缓存后重新启动 #

Keycloak可能缓存了旧配置，清理缓存后启动：

rm -rf /root/keycloak/keycloak-22.0.4/cache/
./kc.sh start --optimized

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