升级jboss/keycloak到13.0.1报ISPN000580持久化数据迁移错误如何解决
问题根因
该错误是跨大版本升级时Keycloak依赖的Infinispan缓存组件的持久化文件格式不兼容导致:Keycloak 6.0.1使用的Infinispan版本为9.x,Keycloak 13.0.1使用的Infinispan版本为11.x,两个大版本之间的单文件存储(SingleFileStore)序列化协议存在不兼容变更,旧版本生成的缓存持久化文件无法被新版本直接识别迁移。
排查步骤
- 确认StatefulSet挂载的持久卷中是否保留了旧版本Keycloak的Infinispan缓存数据文件,默认存储路径为
/opt/jboss/keycloak/standalone/data/infinispan - 检查你修改的
standalone-ha.xml中Infinispan相关配置,是否开启了缓存持久化(passivation、persistence相关配置项),确认是否属于必须保留缓存持久化数据的场景 - 确认升级前是否已经完成了Keycloak数据库层面的备份,缓存本身不属于需要持久保留的核心业务数据,核心数据(用户、角色、客户端配置等)均存储在关系型数据库中
解决方案
场景1:无必须保留的缓存数据(绝大多数场景)
直接删除旧版本生成的Infinispan缓存持久化文件即可,操作步骤:
- 暂停Keycloak的StatefulSet,将副本数调整为0
- 逐个挂载每个Pod对应的持久卷,删除
infinispan目录下的所有缓存文件 - 调整StatefulSet副本数恢复为原有配置,重新启动Keycloak,新版本会自动生成适配当前Infinispan版本的缓存文件
- 若不想手动删除文件,也可以直接修改
standalone-ha.xml中Infinispan的单文件存储配置,添加purge="true"属性,启动一次后再去掉该属性即可:
<file-store path="keycloak" relative-to="jboss.server.data.dir" purge="true"/>
场景2:必须保留旧缓存数据(极少场景)
需要采用增量升级的方式,不可跨多个大版本直接升级:
- 先从6.0.1升级到7.x,再依次升级到8.x、9.x、10.x、11.x、12.x,最终升级到13.0.1,每个小版本升级时Infinispan会自动完成对应版本之间的缓存数据迁移
- 每次升级完成后确认服务运行正常,再执行下一个版本的升级操作
注意事项
- 升级前务必备份Keycloak对应的关系数据库所有数据,核心业务数据的恢复优先级远高于缓存数据
- 若部署的Keycloak集群规模较大,可以先启动单个实例完成缓存初始化和可能的数据库迁移后,再启动其他实例,避免集群启动冲突
内容的提问来源于stack exchange,提问作者George7a
相关产品推荐
相关产品推荐

