Docker容器中导入Keycloak领域配置遇错误，求解决方案

错误原因分析 #

• KC-SERVICES0010: Failed to add user 'admin' to realm 'master': user with username exists：你的realm.json中包含了master领域的admin用户，但启动容器时已通过KEYCLOAK_ADMIN环境变量创建该用户，重复导入导致冲突。
• io.quarkus.runtime.QuarkusBindException：执行kc.sh import时，Keycloak会尝试启动新服务器实例，而原容器的Keycloak已占用8080端口，引发端口绑定失败。

解决方案 #

方法一：启动容器时直接导入配置（推荐） #

停止并清理当前运行的容器，通过启动参数一次性完成服务启动与配置导入：

# 停止并删除现有容器
docker stop <CONTAINER_ID>
docker rm <CONTAINER_ID>

# 挂载本地realm.json，启动时自动导入
docker run -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -p 8080:8080 \
  -v /本地路径/realm.json:/tmp/realm.json \
  quay.io/keycloak/keycloak:17.0.1 start-dev --import-file /tmp/realm.json

该方式会自动跳过已存在的用户，且不会启动重复实例，避免端口冲突。

方法二：修改配置后在运行中导入 #

1. 编辑realm.json，删除master领域下的admin用户配置（仅保留自定义领域内容）。
2. 在容器内停止当前Keycloak服务：

   /opt/keycloak/bin/kc.sh stop
   

3. 执行离线导入（禁用HTTP服务，避免端口冲突）：

   /opt/keycloak/bin/kc.sh import --file /tmp/realm.json --http-enabled=false
   

4. 重新启动Keycloak：

   /opt/keycloak/bin/kc.sh start-dev
   

方法三：离线模式导入后启动服务 #

1. 停止现有容器：

   docker stop <CONTAINER_ID>
   

2. 启动临时容器执行离线导入（不启动HTTP服务）：

   docker run -it --rm \
     -v /本地路径/realm.json:/tmp/realm.json \
     -v keycloak-data:/opt/keycloak/data \
     quay.io/keycloak/keycloak:17.0.1 import --file /tmp/realm.json --http-enabled=false
   

3. 启动正常运行的Keycloak容器：

   docker run -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
     -p 8080:8080 \
     -v keycloak-data:/opt/keycloak/data \
     quay.io/keycloak/keycloak:17.0.1 start-dev
   

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