Keycloak 18.0.2 Docker部署后管理控制台访问显示空白页

问题背景 #

我使用如下Dockerfile构建Keycloak自定义镜像：

FROM quay.io/keycloak/keycloak:18.0.2 as builder

ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
ENV KC_DB=postgres
# 安装自定义metrics扩展
RUN curl -sL <对应metrics SPI jar包下载地址> -o /opt/keycloak/providers/keycloak-metrics-spi-2.5.3.jar
RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:18.0.2
COPY --from=builder /opt/keycloak/ /opt/keycloak/
WORKDIR /opt/keycloak
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]

配合以下docker-compose配置可正常启动Keycloak服务：

version: "3.9"
services:
  keycloak_db:
    image: postgres
    environment:
      - POSTGRES_USER=$DB_USER
      - POSTGRES_PASSWORD=$DB_PASS
      - POSTGRES_DB=$DB_NAME
      - IGNORE_INIT_HOOK_LOCKFILE=true
    volumes:
      - ./db/:/docker-entrypoint-initdb.d/
    ports:
      - ${DB_EXTERNAL_PORT:-15432}:5432

  keycloak:
    container_name: keycloak
    image: keycloak
    ports:
      - "${KEYCLOAK_EXTERNAL_PORT:-18180}:8080"
    environment:
      - KEYCLOAK_ADMIN=${KEYCLOAK_USER}
      - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_PASSWORD}
      - KC_DB=postgres
      - KC_DB_URL_HOST=$DB_HOST
      - KC_DB_URL_PORT=5432
      - KC_DB_URL_DATABASE=$DB_NAME
      - KC_DB_SCHEMA=$KEYCLOAK_SCHEMA
      - KC_DB_USERNAME=$DB_USER
      - KC_DB_PASSWORD=$DB_PASS
      - KC_HTTP_ENABLED=true
      - KC_HOSTNAME=localhost
      - KC_HOSTNAME_ADMIN=localhost
      - KC_HOSTNAME_PORT=80
      - KC_HOSTNAME_STRICT_BACKCHANNEL=true
      - KC_HOSTNAME_STRICT_HTTPS=false
      - KC_PROXY=edge
      - KC_PROXY_ADDRESS_FORWARDING=true
      - KC_KEYCLOAK_FRONTEND_URL=http://localhost:18180/
      - KC_KEYCLOAK_URL=http://localhost:18180/
    depends_on:
      - keycloak_db

服务启动后可正常访问Keycloak首页，但尝试进入管理控制台时页面显示为空白。 #

排查过程记录 #

• 排查更新1：将Keycloak版本升级至18.0.2，新增环境变量KC_FEATURES=admin2后页面可显示部分内容，但仍无法正常加载管理控制台。
• 排查更新2：在构建阶段的Dockerfile中添加ENV KC_FEATURES=token-exchange配置后，可正常显示登录页面，但完成登录后页面依旧显示为空白。

问题根因与解决方案 #

问题出在3处配置错误，直接导致管理控制台加载失败。打开浏览器开发者工具查看网络请求，会看到大量静态资源、接口请求返回404或跨域错误，本质都是地址拼接、模式校验逻辑异常导致的：

1. 主机端口配置不匹配
   配置的KC_HOSTNAME_PORT=80和实际外部访问端口18180不一致。Keycloak 18+基于Quarkus架构，对主机名、端口的校验规则非常严格，前端加载静态资源、发起接口请求时会直接读取配置的端口拼接访问地址，请求打到未开放的80端口自然加载失败。
2. 启动模式与配置不匹配
   直接用start命令启动生产模式，但没有补全生产模式要求的HTTPS等完整配置，虽然设置了KC_HOSTNAME_STRICT_HTTPS=false跳过HTTPS强制跳转，但管理控制台的静态资源路径校验、登录态回跳逻辑依旧会受生产模式规则影响。本地测试环境直接用start-dev命令启动开发模式即可，省去不必要的生产环境校验逻辑。
3. 冗余冲突的URL配置
   配置的KC_KEYCLOAK_FRONTEND_URL、KC_KEYCLOAK_URL不是Keycloak 18版本的标准参数，该版本对应的前端地址配置参数为KC_HOSTNAME_URL、KC_HOSTNAME_ADMIN_URL，错误的参数名会导致前端访问地址生成逻辑混乱。

修正配置参考 #

1. 调整docker-compose中keycloak服务的环境变量：
   • 将KC_HOSTNAME_PORT的值改为实际对外暴露的端口18180
   • 删除KC_KEYCLOAK_FRONTEND_URL、KC_KEYCLOAK_URL两个冗余错误配置
   • 如果本地部署没有前置Nginx等反向代理，直接删除KC_PROXY=edge、KC_PROXY_ADDRESS_FORWARDING=true两个代理相关配置，避免请求头校验异常
2. 调整Dockerfile的启动命令，本地测试场景替换为开发模式启动：

ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev"]

如果是生产环境部署，不要使用start-dev命令，保持start启动生产模式的同时，补全HTTPS证书相关配置，确保KC_HOSTNAME、KC_HOSTNAME_PORT的值和用户实际访问的地址、端口完全一致即可。 #

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