从Keycloak 19.0.1升级至19.0.2/3时出现校验失败问题

尝试将Keycloak Docker镜像从19.0.1升级到19.0.2或19.0.3时，触发Liquibase校验和验证失败，导致服务无法启动。错误日志如下：

auth                | 2022-10-31 03:31:50,864 INFO  [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 7220ms
auth                | 2022-10-31 03:31:52,161 INFO  [org.keycloak.quarkus.runtime.hostname.DefaultHostnameProvider] (main) Hostname settings: Base URL: <unset>, Hostname: <request>, Strict HTTPS: false, Path: <request>, Strict BackChannel: false, Admin URL: <unset>, Admin: <request>, Port: -1, Proxied: false
auth                | 2022-10-31 03:31:53,183 INFO  [org.keycloak.common.crypto.CryptoIntegration] (main) Detected crypto provider: org.keycloak.crypto.def.DefaultCryptoProvider
auth                | 2022-10-31 03:31:54,409 WARN  [org.infinispan.PERSISTENCE] (keycloak-cache-init) ISPN000554: jboss-marshalling is deprecated and planned for removal
auth                | 2022-10-31 03:31:54,443 WARN  [org.infinispan.CONFIG] (keycloak-cache-init) ISPN000569: Unable to persist Infinispan internal caches as no global state enabled
auth                | 2022-10-31 03:31:54,463 INFO  [org.infinispan.CONTAINER] (keycloak-cache-init) ISPN000556: Starting user marshaller 'org.infinispan.jboss.marshalling.core.JBossUserMarshaller'
auth                | 2022-10-31 03:31:54,692 INFO  [org.infinispan.CONTAINER] (keycloak-cache-init) ISPN000128: Infinispan version: Infinispan 'Triskaidekaphobia' 13.0.9.Final
auth                | 2022-10-31 03:31:55,042 INFO  [org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory] (main) Node name: node_432958, Site name: null
auth                | 2022-10-31 03:31:56,160 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Failed to start server in (development) mode
auth                | 2022-10-31 03:31:56,160 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: liquibase.exception.ValidationFailedException: Validation Failed:
auth                |      1 change sets check sum
auth                |           META-INF/jpa-changelog-14.0.0.xml::14.0.0-KEYCLOAK-18286-supported-dbs::keycloak was: 8:c0f6eaac1f3be773ffe54cb5b8482b70 but is now: 8:f43dfba07ba249d5d932dc489fd2b886
auth                | 
auth                | 2022-10-31 03:31:56,161 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Validation Failed:
auth                |      1 change sets check sum
auth                |           META-INF/jpa-changelog-14.0.0.xml::14.0.0-KEYCLOAK-18286-supported-dbs::keycloak was: 8:c0f6eaac1f3be773ffe54cb5b8482b70 but is now: 8:f43dfba07ba249d5d932dc489fd2b886
auth                | 
auth                | 2022-10-31 03:31:56,161 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) For more details run the same command passing the '--verbose' option. Also you can use '--help' to see the details about the usage of the particular command.
auth exited with code 1

补充信息：

• 查阅官方升级文档未找到有效解决方案
• 日志提示添加--verbose选项，但加入镜像CMD时提示“Option not found”
• 数据库结构简单：仅3个realm，每个realm含1-2个用户和1个客户端

错误是否常见？ #

这种Liquibase校验和不匹配的问题在Keycloak小版本升级中偶有出现，属于版本迭代时数据库变更脚本校验值更新导致的兼容性问题，不算罕见。

解决建议 #

1. 修正数据库校验和（推荐，无数据风险） #

直接在数据库的DATABASECHANGELOG表中，找到对应变更集的记录（ID为14.0.0-KEYCLOAK-18286-supported-dbs，文件路径META-INF/jpa-changelog-14.0.0.xml），将MD5SUM字段的值更新为日志中新的校验和8:f43dfba07ba249d5d932dc489fd2b886。

执行示例（以PostgreSQL为例，根据你的数据库类型调整语句）：

UPDATE DATABASECHANGELOG 
SET MD5SUM = '8:f43dfba07ba249d5d932dc489fd2b886' 
WHERE ID = '14.0.0-KEYCLOAK-18286-supported-dbs' AND FILENAME = 'META-INF/jpa-changelog-14.0.0.xml';

2. 跳过Liquibase校验（临时应急，谨慎使用） #

启动Keycloak时添加--spi-liquibase-change-log-validate-on-migrate=false参数，跳过校验和验证。注意：此操作会跳过所有变更集的校验，仅建议在紧急情况下使用，后续版本升级时最好恢复校验。

如果用Docker Compose，修改command部分：

services:
  auth:
    image: quay.io/keycloak/keycloak:19.0.3
    command: start-dev --spi-liquibase-change-log-validate-on-migrate=false
    # 其他配置...

3. 备份后重建数据库（适合数据量小的场景） #

因为你的数据量很小，也可以选择：

• 通过Keycloak admin后台导出现有realm、用户、客户端的配置
• 清空数据库，启动新版本Keycloak初始化全新数据库
• 导入之前备份的配置文件

关于--verbose选项的说明 #

Keycloak Quarkus版本的启动命令中，--verbose需要放在具体子命令之后，比如start-dev --verbose，而不是直接加在CMD开头。但针对这个校验错误，--verbose通常不会提供更多有效信息，优先尝试上述解决方法即可。

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