Keycloak 15.0.2 Docker环境下如何覆盖已存在的realm完成重新导入？

问题根因 #

配置失效的核心原因是JVM参数被错误拼接在了KEYCLOAK_IMPORT环境变量的值中，无法被Keycloak识别生效，OVERWRITE_EXISTING迁移策略实际没有启用。KEYCLOAK_IMPORT仅负责指定导入文件路径，额外JVM参数需要单独配置。

修复docker-compose配置 #

将原环境变量配置拆分，使用Keycloak官方镜像支持的JAVA_OPTS_APPEND参数注入JVM配置：

volumes:
  - ./keycloak-realm.json:/tmp/keycloak-realm.json
environment:
  - KEYCLOAK_USER=<你的管理员用户名>
  - KEYCLOAK_PASSWORD=<你的管理员密码>
  - KEYCLOAK_IMPORT=/tmp/keycloak-realm.json
  - JAVA_OPTS_APPEND=-Dkeycloak.profile.feature.upload_scripts=enabled -Dkeycloak.migration.strategy=OVERWRITE_EXISTING

操作前建议备份Keycloak关联的持久化数据库数据，避免配置丢失

生效步骤 #

• 修改完成后执行以下命令重建Keycloak容器：

  docker-compose up -d --force-recreate keycloak
  

• 查看容器启动日志，确认无KC-SERVICES0003报错，realm导入流程正常执行

备选方案：使用Admin CLI强制导入 #

如果环境变量配置方式仍未生效，可进入容器直接调用Keycloak官方管理工具执行覆盖导入：

1. 进入运行中的Keycloak容器

   docker exec -it <你的Keycloak容器名称> bash
   

2. 登录管理员账号

   /opt/jboss/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user <管理员用户名> --password <管理员密码>
   

3. 执行覆盖导入

   /opt/jboss/keycloak/bin/kcadm.sh create partialImport -r <目标realm名称> -s ifResourceExists=OVERWRITE -o -f /tmp/keycloak-realm.json
   

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