Keycloak standalone模式8升级12后首次重启无法启动咨询

二次启动时Keycloak内置的Liquibase迁移工具未识别到首次启动已完成的数据库变更，重复执行外键约束添加脚本，触发H2约束已存在错误。
跨大版本直接从Keycloak 8升级到12时，Liquibase DATABASECHANGELOG表的条目格式、校验值不兼容，同时H2嵌入式数据库的元数据存储在版本切换后无法被Keycloak 12正确读取，是问题核心诱因。

修复现有损坏环境 #

1. 确认Keycloak服务完全停止，无残留进程占用H2文件
   • 执行ps aux | grep standalone排查残留进程，如有则强制终止
   • 进入standalone/data/h2/目录，删除所有后缀为.lock.db的锁文件
2. 手动删除冲突的外键约束
   • 进入Keycloak安装目录的modules/system/layers/base/com/h2database/h2/main/目录，找到对应版本的H2 jar包
   • 执行命令连接H2数据库：
     java -cp h2-*.jar org.h2.tools.Shell -url "jdbc:h2:$(pwd)/../../../../data/h2/keycloak" -user sa -password ""
   • 执行SQL删除冲突约束：

     ALTER TABLE PUBLIC.SCOPE_MAPPING DROP CONSTRAINT "FK_OUSE064PLMLR732LXJCN1Q5F1";
     

3. 手动标记Liquibase变更为已执行，避免重复运行
   • 继续在H2命令行中插入对应变更记录，使Liquibase跳过该步骤：

     INSERT INTO DATABASECHANGELOG 
     (ID, AUTHOR, FILENAME, DATEEXECUTED, ORDEREXECUTED, MD5SUM, DESCRIPTION, COMMENTS, EXECTYPE, CONTEXTS, LABELS, LIQUIBASE, DEPLOYMENT_ID)
     VALUES 
     ('add-scope-mapping-client-fk', 'keycloak', 'META-INF/jpa-changelog-12.0.0.xml', CURRENT_TIMESTAMP, (SELECT MAX(ORDEREXECUTED)+1 FROM DATABASECHANGELOG), '8:0', 'addForeignKeyConstraint', '', 'EXECUTED', NULL, NULL, '3.8.0', '12000');
     

   如果后续启动仍抛出其他约束/索引已存在错误，重复执行删除冲突对象、插入变更记录的操作即可。

4. 重启Keycloak服务验证

规避同类问题的后续操作 #

• 升级路径修正：禁止直接跨大版本从Keycloak 8升级到12，需按官方要求逐版本跳转（8→9→10→11→12），每个版本升级后正常启停一次服务，确认数据库变更写入DATABASECHANGELOG表后再升级下一个版本
• H2数据迁移：升级完成后先执行全量数据导出，再导入到全新的Keycloak 12空实例中，避免旧版本元数据残留
• 运行权限修正：不要使用sudo启动Keycloak服务，使用固定普通用户运行，防止H2数据库文件权限不一致导致的元数据读取异常
• 生产环境替换数据库：放弃H2嵌入式数据库，改用MySQL/PostgreSQL等独立外部数据库，从根源上规避H2版本兼容、元数据读取类问题

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