Docker部署Keycloak 21设置独立管理控制台端口无效求助

问题描述 #

本地测试Docker化的Keycloak 21，默认服务端口为8080，尝试将管理控制台端口设为8888，但访问该端口时被拒绝。已配置KC_HOSTNAME_ADMIN_URL但未生效，除Nginx反向代理外未找到其他有效方案，寻求解决办法。

当前使用的docker-compose配置：

version: '3'

volumes:
  mysql_data:
      driver: local

services:
  mysql:
      image: mysql:5.7
      volumes:
        - mysql_data:/var/lib/mysql
      environment:
        MYSQL_ROOT_PASSWORD: root
        MYSQL_DATABASE: keycloak
        MYSQL_USER: keycloak
        MYSQL_PASSWORD: password
  keycloak:
      image: quay.io/keycloak/keycloak:21.0.1
      environment:
        DB_VENDOR: MYSQL
        DB_ADDR: mysql
        DB_DATABASE: keycloak
        DB_USER: keycloak
        DB_PASSWORD: password
        KEYCLOAK_USER: user
        KEYCLOAK_PASSWORD: keycloak
        KEYCLOAK_ADMIN: admin
        KEYCLOAK_ADMIN_PASSWORD: keycloak
        KC_HOSTNAME_ADMIN_URL: http://localhost:8888
        # KC_PORT_ADMIN: 8888            
      ports:
        - 8080:8080
        - 8888:8888
      depends_on:
        - mysql
      command: start-dev
      # command: start-dev --hostname-admin-url=http://127.0.0.1:8888

问题根源 #

1. Keycloak 21基于Quarkus架构，默认仅监听单个端口（8080），KC_HOSTNAME_ADMIN_URL仅用于生成管理控制台的外部访问链接，不会触发Keycloak额外监听其他端口。
2. 配置中映射了8888:8888，但Keycloak内部并未监听8888端口，导致访问被拒绝。
3. 同时配置了旧版废弃的KEYCLOAK_USER/KEYCLOAK_PASSWORD和新版的KEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD，可能引发配置冲突。

解决方案 #

方案一：无需反向代理（快速实现） #

通过端口映射将8888指向Keycloak内部的8080端口，结合KC_HOSTNAME_ADMIN_URL实现管理控制台的独立端口访问：

修改后的docker-compose配置：

version: '3'

volumes:
  mysql_data:
      driver: local

services:
  mysql:
      image: mysql:5.7
      volumes:
        - mysql_data:/var/lib/mysql
      environment:
        MYSQL_ROOT_PASSWORD: root
        MYSQL_DATABASE: keycloak
        MYSQL_USER: keycloak
        MYSQL_PASSWORD: password
  keycloak:
      image: quay.io/keycloak/keycloak:21.0.1
      environment:
        DB_VENDOR: MYSQL
        DB_ADDR: mysql
        DB_DATABASE: keycloak
        DB_USER: keycloak
        DB_PASSWORD: password
        KEYCLOAK_ADMIN: admin
        KEYCLOAK_ADMIN_PASSWORD: keycloak
        KC_HOSTNAME_ADMIN_URL: http://localhost:8888
      ports:
        - 8080:8080  # 业务服务端口
        - 8888:8080  # 将8888映射到Keycloak内部监听的8080端口
      depends_on:
        - mysql
      command: start-dev

配置完成后：

• 访问http://localhost:8080使用业务服务
• 访问http://localhost:8888/admin直接进入管理控制台，页面内的跳转链接会自动指向http://localhost:8888

方案二：反向代理实现完全隔离（可选） #

若需要管理控制台与业务服务彻底隔离（8888端口直接访问管理控制台根路径，无需加/admin），可使用Nginx反向代理：

1. 新增Nginx服务到docker-compose：

version: '3'

volumes:
  mysql_data:
      driver: local

services:
  mysql:
      image: mysql:5.7
      volumes:
        - mysql_data:/var/lib/mysql
      environment:
        MYSQL_ROOT_PASSWORD: root
        MYSQL_DATABASE: keycloak
        MYSQL_USER: keycloak
        MYSQL_PASSWORD: password
  keycloak:
      image: quay.io/keycloak/keycloak:21.0.1
      environment:
        DB_VENDOR: MYSQL
        DB_ADDR: mysql
        DB_DATABASE: keycloak
        DB_USER: keycloak
        DB_PASSWORD: password
        KEYCLOAK_ADMIN: admin
        KEYCLOAK_ADMIN_PASSWORD: keycloak
        KC_HOSTNAME_ADMIN_URL: http://localhost:8888
      depends_on:
        - mysql
      command: start-dev
  nginx:
      image: nginx:alpine
      volumes:
        - ./nginx.conf:/etc/nginx/conf.d/default.conf
      ports:
        - 8080:8080
        - 8888:8888
      depends_on:
        - keycloak

2. 创建nginx.conf文件：

server {
    listen 8080;
    server_name localhost;
    location / {
        proxy_pass http://keycloak:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

server {
    listen 8888;
    server_name localhost;
    location / {
        proxy_pass http://keycloak:8080/admin;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

配置完成后：

• 访问http://localhost:8080使用业务服务
• 访问http://localhost:8888直接进入管理控制台根路径

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