Keycloak 20.x Docker镜像无法启动（Docker Compose部署）

问题描述 #

我正在使用Docker Swarm部署全新的Keycloak 20版本，遇到了一些问题。此前我使用的是旧版Keycloak，发现启动配置等内容已发生变更，尤其是Docker相关配置。当前我的docker-compose.yml配置如下：

keycloak:
  image: quay.io/keycloak/keycloak:20.0
  environment:
    TZ: '...'
    KC_HOSTNAME: localhost
    KC_HOSTNAME_PORT: 80
    KC_HOSTNAME_STRICT_BACKCHANNEL: "true"
    KC_DB: mysql
    KC_DB_URL: jdbc:mysql://mysql:3306/keycloak
    KC_DB_USERNAME: ${KEYCLOAK_DB_USER}
    KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD}
    KEYCLOAK_ADMIN: admin
    KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_PASSWORD}
    KC_HEALTH_ENABLED: "true"
    KC_LOG_LEVEL: info
  volumes:
    - ./keycloak_realms:/realm-config # <- Unclear???
  depends_on:
    - mysql-db
  networks:
    - mysql-net
    - web
  healthcheck:
    test: [ "CMD", "curl", "-f", "http://localhost:8080/health/ready" ]
    interval: 15s
    timeout: 2s
    retries: 15
  deploy:
    resources:
      limits:
        cpus: '0.50'
        memory: 512m

启动容器后，仅能看到kc.sh脚本的文档，且找不到新版卷挂载位置等相关文档，缺乏调试相关信息。

问题根源与修正步骤 #

1. 核心问题：缺失启动命令 #

Keycloak 17+改用kc.sh CLI作为启动入口，容器默认启动时未指定命令的话，会直接输出脚本帮助文档，这就是你看到的现象。必须明确指定启动命令：

keycloak:
  # ... 现有配置 ...
  command: start --optimized

• start: 生产环境专用命令，会预编译主题和提供商，启动速度更快
• start-dev: 开发环境使用，支持热加载，适合调试

2. 领域配置卷挂载修正 #

你挂载的/realm-config是兼容旧版的领域导入路径，但需要配合--import-realm参数才能触发自动导入。修改命令为：

command: start --optimized --import-realm

确保本地./keycloak_realms目录下存放JSON格式的领域配置文件（如realm-export.json），启动时Keycloak会自动导入这些配置。

另外，Keycloak 20官方推荐的导入路径是/opt/keycloak/data/import，也可以改成：

volumes:
  - ./keycloak_realms:/opt/keycloak/data/import

两种路径都能配合--import-realm生效。

3. 健康检查与端口优化 #

• Keycloak内部默认监听8080端口，若要对外映射80端口，需添加ports字段：

  ports:
    - "80:8080"
  

• 替换健康检查为Keycloak自带的命令，比curl更可靠：

  healthcheck:
    test: ["CMD", "/opt/keycloak/bin/kc.sh", "health", "--ready"]
    interval: 15s
    timeout: 2s
    retries: 15
  

4. 修正后的完整配置片段 #

keycloak:
  image: quay.io/keycloak/keycloak:20.0
  environment:
    TZ: '...'
    KC_HOSTNAME: localhost
    KC_HOSTNAME_PORT: 80
    KC_HOSTNAME_STRICT_BACKCHANNEL: "true"
    KC_DB: mysql
    KC_DB_URL: jdbc:mysql://mysql:3306/keycloak
    KC_DB_USERNAME: ${KEYCLOAK_DB_USER}
    KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD}
    KEYCLOAK_ADMIN: admin
    KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_PASSWORD}
    KC_HEALTH_ENABLED: "true"
    KC_LOG_LEVEL: info
  command: start --optimized --import-realm
  volumes:
    - ./keycloak_realms:/opt/keycloak/data/import
  ports:
    - "80:8080"
  depends_on:
    - mysql-db
  networks:
    - mysql-net
    - web
  healthcheck:
    test: ["CMD", "/opt/keycloak/bin/kc.sh", "health", "--ready"]
    interval: 15s
    timeout: 2s
    retries: 15
  deploy:
    resources:
      limits:
        cpus: '0.50'
        memory: 512m

调试技巧 #

• 查看容器日志：docker logs <keycloak-container-id>，能获取启动时的具体错误（如数据库连接失败、配置文件格式错误）
• 进入容器调试：docker exec -it <keycloak-container-id> /bin/bash，直接执行kc.sh start --optimized --import-realm查看实时输出

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