Keycloak部署于群晖反向代理后公网子域名无法访问求助

我在群晖RackStation上运行Keycloak Docker容器，设备可通过公网域名访问且前置Cloudflare防护。内网能正常访问Keycloak实例，但通过群晖DSM反向代理配置的子域名https://sso.example.com无法访问。访问该子域名时，页面会跳转到Keycloak管理控制台，不久后出现错误提示：somethingWentWrongDescription。

网络链路 #

Internet → https://sso.example.com → Cloudflare → 群晖DSM反向代理（https://sso.example.com） → http://localhost:20600

反向代理请求头配置 #

Docker Compose配置 #

version: '3.7'

services:
  db:
    image: postgres
    container_name: keycloak-db
    volumes:
      - /volume1/docker/keycloak/db:/var/lib/postgresql/data:rw
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

  keycloak:
    image: quay.io/keycloak/keycloak
    container_name: keycloak
    restart: on-failure:5
    command: start
    healthcheck:
      test: curl -f http://localhost:8080/ || exit 1
    environment:
      KC_PROXY_HEADERS: xforwarded
      KC_HTTP_ENABLED: true
      KC_HOSTNAME_STRICT: false
      KC_HTTP_RELATIVE_PATH: /auth
      KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN}
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://db/${POSTGRES_DB}
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 20600:8080
    depends_on:
        - db

补充信息 #

• 旧版本Keycloak可正常通过该子域名访问，升级到最新版本后出现问题
• 已参考Stack Overflow上《Keycloak behind reverse proxy》相关问题，未解决

从配置和问题现象来看，核心问题出在Keycloak新版本的主机名与反向代理适配配置缺失，结合Cloudflare+群晖反向代理的网络环境，需调整以下关键配置：

1. 明确配置外部访问主机名 #

新版本Keycloak对主机名校验逻辑更严格，即使KC_HOSTNAME_STRICT设为false，也需指定外部可访问的主机名，避免生成错误回调URL。在Keycloak环境变量中添加：

KC_HOSTNAME: sso.example.com

2. 修正反向代理请求头 #

当前配置缺少X-Forwarded-Host头，这是Keycloak识别外部访问域名的关键，需在群晖反向代理中新增：

同时，将X-Forwarded-Proto的值固定为https（Cloudflare到群晖的链路为HTTPS，避免变量传递异常）。

3. 调整Keycloak代理模式 #

针对Cloudflare这类边缘代理场景，将代理模式改为edge更适配，更新环境变量：

KC_PROXY: edge
KC_PROXY_HEADERS: xforwarded

4. 最终调整后的Keycloak环境变量示例 #

environment:
  KC_PROXY: edge
  KC_PROXY_HEADERS: xforwarded
  KC_HTTP_ENABLED: true
  KC_HOSTNAME: sso.example.com
  KC_HOSTNAME_STRICT: false
  KC_HTTP_RELATIVE_PATH: /auth
  KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN}
  KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
  KC_DB: postgres
  KC_DB_URL: jdbc:postgresql://db/${POSTGRES_DB}
  KC_DB_USERNAME: ${POSTGRES_USER}
  KC_DB_PASSWORD: ${POSTGRES_PASSWORD}

排查建议 #

1. 修改配置后重启Keycloak容器和群晖反向代理
2. 通过浏览器开发者工具检查请求响应头，确认X-Forwarded-*系列头是否正确传递
3. 查看Keycloak容器日志（docker logs keycloak），定位具体错误堆栈信息

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