使用Docker Compose启动Keycloak遇用户已存在错误排查

问题背景 #

我正尝试通过Docker Compose为Java Spring Boot 3.1.4后端应用启动Keycloak，使用的Docker Compose配置如下：

services:
  postgres:
    container_name: postgres
    image: postgres:latest
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: banking_microservice_db
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: root
      PGDATA: /data/postgres
    volumes:
      - db:/data/postgres
    networks:
      - keycloak-network
    restart: unless-stopped

  keycloak:
    container_name: keycloak
    image: jboss/keycloak:latest
    ports:
      - "8080:8080"
    environment:
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: admin
      DB_VENDOR: POSTGRES
      DB_ADDR: postgres
      DB_PORT: 5432
      DB_DATABASE: keycloak
      DB_USER: keycloak
      DB_PASSWORD: keycloak
      KEYCLOAK_LOGLEVEL: INFO
      PROXY_ADDRESS_FORWARDING: "true"
    depends_on:
      - postgres
    networks:
      - keycloak-network
    restart: unless-stopped

networks:
  keycloak-network:

volumes:
  db:

执行docker compose up -d时，反复出现错误：

2023-10-12 22:41:05 User with username 'admin' already added to '/opt/jboss/keycloak/standalone/configuration/keycloak-add-user.json'

已尝试删除镜像容器重下、更换Keycloak版本、修改账号密码、注释账号环境变量、删除PostgreSQL卷等操作，但问题依旧。

核心原因 #

jboss/keycloak镜像的启动脚本会检查keycloak-add-user.json文件，一旦检测到文件中已存在指定用户的配置，就会抛出该错误。之前的操作未彻底清理容器内部的这个配置文件，或者Keycloak容器关联了未被清理的匿名卷（即便compose里没显式配置），导致旧配置一直残留。

解决步骤 #

1. 彻底清理所有关联资源 #

执行以下命令，完全移除相关容器、镜像和未使用的卷，确保没有遗留配置：

docker compose down -v
docker rmi jboss/keycloak:latest postgres:latest
docker volume prune -f

• docker compose down -v：删除compose定义的容器和卷
• docker rmi：删除指定镜像
• docker volume prune -f：强制清理所有未被使用的匿名卷

2. 修正PostgreSQL初始化配置 #

你的Postgres容器默认只创建banking_microservice_db，但Keycloak需要连接keycloak数据库，需添加初始化脚本自动创建该库和用户：

• 在compose文件所在目录新建init-db文件夹，创建create-keycloak-db.sql文件：

  CREATE DATABASE keycloak;
  CREATE USER keycloak WITH ENCRYPTED PASSWORD 'keycloak';
  GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;
  

• 修改Postgres服务的volumes配置，挂载初始化脚本：

  volumes:
    - db:/data/postgres
    - ./init-db:/docker-entrypoint-initdb.d
  

3. 调整Keycloak启动配置，绕过配置文件检查 #

去掉KEYCLOAK_USER和KEYCLOAK_PASSWORD环境变量，改用启动命令直接创建管理员用户：
修改Keycloak服务的配置，替换environment里的用户变量并添加command：

keycloak:
  container_name: keycloak
  image: jboss/keycloak:latest
  ports:
    - "8080:8080"
  environment:
    DB_VENDOR: POSTGRES
    DB_ADDR: postgres
    DB_PORT: 5432
    DB_DATABASE: keycloak
    DB_USER: keycloak
    DB_PASSWORD: keycloak
    KEYCLOAK_LOGLEVEL: INFO
    PROXY_ADDRESS_FORWARDING: "true"
  command: ["sh", "-c", "/opt/jboss/keycloak/bin/add-user-keycloak.sh -u admin -p admin && /opt/jboss/keycloak/bin/standalone.sh -b 0.0.0.0"]
  depends_on:
    - postgres
  networks:
    - keycloak-network
  restart: unless-stopped

该命令会在Keycloak启动前，通过官方脚本创建管理员用户，完全绕过keycloak-add-user.json的检查逻辑。

4. 重新启动服务 #

执行docker compose up -d，此时Keycloak应该能正常启动，不再出现用户已存在的错误。

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