Keycloak Docker容器用户未导入问题求助

一、单独导入用户文件未生效的原因 #

• Keycloak的import命令存在逻辑限制：只有首次创建领域时，才会自动加载同目录下关联的*-users-*.json用户文件。如果目标容器中已存在test领域（哪怕是刚创建的空领域），导入流程会跳过用户数据，仅处理领域配置。
• 你执行导入时，领域被成功创建，但此时属于“领域已存在”的场景，所以同目录的用户文件未被加载。

二、10k用户合并导入挂起的原因 #

• 内存不足：Keycloak导入大体积JSON文件时，会将整个文件加载到内存解析。10k用户的JSON文件体积较大，默认JVM堆内存无法支撑，引发频繁GC甚至内存溢出，导致进程挂起。
• 大事务阻塞：合并后的单文件导入会将所有用户操作打包成一个超大事务，数据库无法处理此类大事务，出现锁表、超时等情况，最终导致进程卡住。
• 单文件导入效率瓶颈：Keycloak对单文件批量导入的逻辑未做分片处理，一次性处理所有用户请求，导致系统资源耗尽。

三、解决方案 #

解决用户未导入问题 #

1. 先删除目标容器的test领域，再执行导入：

   # 进入目标容器Keycloak的bin目录
   ./kc.sh delete realms test
   # 重新执行导入，首次创建领域时会自动加载用户文件
   ./kc.sh import --dir export/
   

2. 若需保留现有领域，使用REST API批量导入：
   • 获取管理员Token后，遍历test-users-*.json中的用户数据，调用/admin/realms/test/users接口分批创建用户，避免一次性提交过多请求。

解决10k用户导入挂起问题 #

1. 调整JVM内存参数：启动Keycloak时增加堆内存，缓解内存压力：

   export JAVA_OPTS="-Xmx4g -Xms2g"
   ./kc.sh import --dir export/
   

   可根据服务器配置调整Xmx值，如8G内存服务器可设为-Xmx6g。
2. 拆分用户文件分批导入：
   • 将test-users-*.json拆分为每个含500-1000个用户的小文件，通过API或首次创建领域的方式分批导入，避免一次性处理过大数据量。
3. 优化数据库配置：
   • 针对使用的数据库（如PostgreSQL、MySQL）调整连接池大小、事务超时时间，增加临时表空间，避免数据库成为瓶颈。

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