Keycloak从v8迁移至v18：启动方法、文档及注意事项咨询

迁移启动方式 #

直接使用v18的启动命令关联旧版数据库，Keycloak会自动执行数据库迁移脚本：

• 开发模式启动示例（自动迁移数据库）：

  ./bin/kc.sh start-dev --db-url=jdbc:mysql://localhost:3306/keycloak_v8 --db-username=root --db-password=your-pass
  

• 若需先导出旧配置再导入，v8导出命令：

  ./bin/standalone.sh -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=jpa -Dkeycloak.migration.file=v8_full_export.json
  

  v18导入命令：

  ./bin/kc.sh import --file=v8_full_export.json
  

迁移核心步骤 #

1. 全量备份旧环境
   • 备份v8的数据库（用数据库自带工具做全量备份，比如MySQL的mysqldump，PostgreSQL的pg_dump）
   • 导出v8所有领域、用户、客户端配置到JSON文件，作为迁移备选方案
2. 部署v18基础环境
   • 下载Keycloak v18安装包并解压
   • 确认数据库驱动已适配（v18默认包含MySQL、PostgreSQL等主流驱动，无需额外添加）
3. 执行迁移操作
   • 用v18启动命令连接旧数据库，系统会自动检测版本并执行迁移脚本
   • 若自动迁移报错，使用之前导出的JSON文件执行导入操作
4. 验证迁移完整性
   • 登录v18管理控制台，逐一检查领域配置、用户列表、角色权限、客户端设置
   • 测试业务系统的登录、授权流程，确保与迁移前一致

关键注意事项 #

• 版本跨度适配：v8到v18跨了多个大版本，注意核心变更：v11移除部分旧REST API，v17切换为Quarkus架构，启动命令从standalone.sh改为kc.sh，配置文件从standalone.xml改为conf/keycloak.conf
• 数据库版本要求：v18对数据库版本有最低要求，比如MySQL需5.7以上，PostgreSQL需10以上，提前确认旧数据库是否符合
• 自定义配置迁移：手动迁移v8中standalone.xml里的自定义配置（比如HTTPS证书、LDAP集成、自定义主题）到v18的conf/keycloak.conf或对应配置文件
• 客户端SDK适配：业务系统使用的Keycloak客户端SDK需升级到兼容v18的版本，避免API调用失败
• 测试优先：必须在测试环境完成全流程迁移、功能验证后，再操作生产环境，迁移前准备回滚方案
• 密码哈希兼容性：v8默认的密码哈希算法在v18中仍受支持，但不要修改默认哈希配置，避免用户无法登录

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