Keycloak 18+导入已有Realm配置如何避免丢失存量用户

你当前配置的-Dkeycloak.migration.strategy=OVERWRITE_EXISTING导入策略的原生逻辑，就是检测到同名Realm时先级联删除该Realm下所有关联数据（含用户、角色、客户端、会话、权限映射等全部资源），再将导出文件中的内容全量写入数据库。日志中打印的Realm 'tyk' already exists. Removing it before import就是该逻辑的直接输出，这是策略的设计行为，和Keycloak 18+采用Quarkus架构无关，也是存量用户被全部删除的核心原因。

以下方案均适配Keycloak >=18.0.0的Quarkus发行版，按生产可用性优先级排序：

方案1：用部分导入替代全量导入，仅同步配置不触碰用户数据 #

启动阶段的kc.sh import是全量导入模式，设计目标就是整库替换，不适合已有生产数据的Realm配置更新场景，直接改用Keycloak原生的部分导入能力即可：

• 预处理你的Realm导出JSON文件，删除文件中users字段下的所有内容，仅保留你需要更新的配置项：Realm基础参数、客户端、角色、客户端作用域、认证流程、身份提供者、事件配置等，不要带任何用户数据。
• 调用Admin API执行部分导入，参考命令如下：

# 先获取管理员Token
TOKEN=$(curl -X POST "http://<keycloak实例地址>/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=<管理员用户名>" \
  -d "password=<管理员密码>" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" | jq -r .access_token)

# 执行部分导入，资源已存在时可按需选SKIP(跳过)或OVERWRITE(更新配置)
curl -X POST "http://<keycloak实例地址>/admin/realms/tyk/partialImport" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @/opt/keycloak/data/import/tyk-realm-without-users.json

• 部分导入不会删除Realm内任何已有数据，仅处理导入文件中包含的资源
• 只要导入文件中不含users字段，就完全不会读写用户表，数十万级用户规模下无额外性能开销
• 该操作不需要重启Keycloak，在K8s环境中可以独立用Job执行，不需要放在init容器中阻塞主服务启动

方案2：全量导入前后做用户数据迁移 #

如果必须保留init容器全量导入的部署模式，可通过数据备份回绕的方式规避用户丢失：

• 执行全量导入前，先备份数据库中目标Realm关联的所有用户表、用户-角色关联表、用户-组关联表、用户属性表数据
• 全量导入完成后，将备份的用户数据重新写入数据库，注意同步更新新生成的Realm ID关联字段，避免数据关联断裂

注意：该方案需要直接操作Keycloak底层数据库，表结构会随Keycloak版本迭代发生变化，维护成本高，十万级用户数据回写耗时较长，非特殊场景不推荐使用。

方案3：配置变更走声明式更新，废弃全量导入流程 #

长期生产运维建议将Realm配置变更纳入IaC流程：

• 全量导入仅在全新环境首次部署时执行，已有生产环境永远不触发全量覆盖导入
• 所有Realm配置的新增、修改操作，均通过Admin API或声明式配置工具直接在运行中的Keycloak实例上执行
• 该模式全程不会触发Realm删除重建逻辑，对存量用户零影响，也没有额外的数据备份恢复成本

Keycloak内置的全量导入仅支持两种策略：OVERWRITE_EXISTING（覆盖即删旧建新）、IGNORE_EXISTING（存在同名Realm则直接跳过，不更新任何配置），不存在“更新配置保留用户”的内置全量导入策略，不要浪费时间尝试修改全量导入参数达到目标。
所有导入操作上线前，必须先在和生产数据结构一致的测试环境验证，确认用户数据无丢失、配置符合预期再推生产。

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