如何在不同环境间迁移同步Keycloak客户端配置

你碰到的两个原生导出方案的缺陷是实际生产中非常常见的坑，控制台自带的导出能力本来就只设计用来做全量备份，根本不适合做细粒度的跨环境配置同步，通用落地方案分两类：

长期方案：声明式配置即代码管理 #

这是目前生产环境的标准做法，完全可以避免手动逐环境改配置的问题：

• 放弃控制台手动导配置的思路，把你这个前端客户端的所有配置（客户端基础参数、client roles含复合角色关联关系、自定义client scope、角色映射mapper）全部写成Keycloak支持的声明式JSON配置片段，和业务代码一起存在代码仓库做版本管理。
• 部署各环境Keycloak的时候，挂载这个配置片段到Keycloak的data/import目录，启动时加--import-realm参数就行：Keycloak启动时只会检查、更新配置文件里明确定义的资源，不会覆盖realm下其他业务的客户端、用户、权限配置，生产环境用也没有风险。
• 后续要加角色、改mapper规则的时候，直接改仓库里的配置文件，走CI/CD流水线按顺序部署到开发、预发、生产环境，自动完成所有环境的配置同步，不需要手动登录控制台操作。

临时迁移方案：调用管理API拉取全量配置 #

如果只是要把本地已经调好的配置快速迁到其他环境，不用等搭流水线，可以直接调Keycloak管理端接口拉取完整配置，避开控制台导出丢数据的问题：

1. 先拿realm管理员的访问token，依次调用以下接口拉取全量配置：
   • 拉客户端基础配置：GET /admin/realms/{你的realm名}/clients/{客户端的UUID}
   • 拉全量客户端角色（含复合角色的关联规则）：GET /admin/realms/{你的realm名}/clients/{客户端的UUID}/roles
   • 拉所有自定义协议映射器：GET /admin/realms/{你的realm名}/clients/{客户端的UUID}/protocol-mappers/models
   • 拉默认/可选客户端作用域配置：GET /admin/realms/{你的realm名}/clients/{客户端的UUID}/default-client-scopes、GET /admin/realms/{你的realm名}/clients/{客户端的UUID}/optional-client-scopes
2. 把以上接口返回的内容合并成标准的Keycloak配置片段，到目标环境调用对应的PUT/POST接口批量提交即可，不会丢失任何角色、映射器配置，也不会影响realm内其他资源。

注意事项 #

绝对不要在生产环境执行全量realm覆盖导入，哪怕是提前做过备份，也很容易冲掉其他业务线的客户端配置、已有用户的权限映射，直接造成线上故障。
控制台自带的「导出单个客户端」功能长期存在角色、mapper配置丢失的已知问题，仅适合导出无自定义配置的简单公共客户端，生产迁移不要用这个功能。

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