Keycloak 21.0.2导出大量用户后导入遇重复用户失败求助

一、先定位重复用户来源 #

首先明确重复是导出分片逻辑导致，还是源Keycloak本身存在重复用户：

• 命令行快速排查：用jq工具（需提前安装）遍历所有导出文件，提取唯一标识字段（username或email）统计重复项：

  # 统计重复的username
  cat exp/myrealm-users-*.json | jq -r '.[]?.username' | sort | uniq -d
  # 统计重复的email
  cat exp/myrealm-users-*.json | jq -r '.[]?.email' | sort | uniq -d
  

  执行后会输出所有重复的用户名或邮箱，确认重复范围。

二、针对性解决重复问题 #

1. 导出分片导致的重复：去重后重新导入 #

如果是导出分片逻辑产生重复，可通过脚本合并去重后重新分片：

• Python去重脚本示例：

  import json
  import os
  from collections import defaultdict
  
  # 创建清理后文件的存放目录
  os.makedirs("exp-cleaned", exist_ok=True)
  # 选择去重依据字段，优先用username，也可改为email
  deduplicate_key = "username"
  user_map = {}
  
  # 遍历所有导出的用户文件
  for file_name in os.listdir("exp"):
      if not file_name.startswith("myrealm-users-") or not file_name.endswith(".json"):
          continue
      file_path = os.path.join("exp", file_name)
      with open(file_path, "r", encoding="utf-8") as f:
          users = json.load(f)
          for user in users:
              # 仅保留有唯一标识的用户，避免空值导致的问题
              if deduplicate_key in user and user[deduplicate_key]:
                  user_map[user[deduplicate_key]] = user
  
  # 将去重后的用户分片保存，每个文件50个用户（可根据Keycloak性能调整）
  unique_users = list(user_map.values())
  chunk_size = 50
  for idx in range(0, len(unique_users), chunk_size):
      chunk = unique_users[idx:idx+chunk_size]
      output_file = os.path.join("exp-cleaned", f"myrealm-users-{idx//chunk_size}.json")
      with open(output_file, "w", encoding="utf-8") as f:
          json.dump(chunk, f, indent=2)
  

  运行脚本后，用exp-cleaned目录下的文件执行导入即可。

2. 源Keycloak本身存在重复用户：先清理源端 #

如果排查后发现源Keycloak里本身就有重复用户（比如相同username/email），建议先在源端清理：

• 登录源Keycloak管理后台，通过用户搜索功能找到重复用户，保留有效账号后删除重复项；
• 清理完成后重新执行导出命令，再导入到目标环境，从根源避免重复问题。

三、调整导入策略快速绕过重复 #

如果不想修改导出文件，可直接通过Keycloak导入命令的参数跳过或覆盖重复用户：

• 跳过重复用户：使用--strategy SKIP_EXISTING参数，导入时自动跳过已存在的用户，不会因重复报错：

  ./kc.sh import --dir exp --users-only --strategy SKIP_EXISTING
  

  加上--users-only可以只导入用户数据，避免其他配置项的干扰。
• 覆盖重复用户：如果需要用导出的用户数据覆盖目标环境的现有用户，可使用--strategy OVERWRITE_EXISTING（注意：此操作会覆盖目标环境的用户数据，需谨慎操作）：

  ./kc.sh import --dir exp --users-only --strategy OVERWRITE_EXISTING
  

四、分批导入降低风险 #

因为文件数量近6000个，一次性导入可能出现性能问题或排查困难，可分批导入：

# 按文件名排序，每100个文件为一批进行导入
files=($(ls exp/myrealm-users-*.json | sort))
batch_size=100
for ((i=0; i<${#files[@]}; i+=batch_size)); do
  batch_dir="exp-batch-$((i/batch_size))"
  mkdir -p "$batch_dir"
  cp "${files[@]:i:batch_size}" "$batch_dir"/
  ./kc.sh import --dir "$batch_dir" --users-only --strategy SKIP_EXISTING
  rm -rf "$batch_dir"
done

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