如何从Docker网络外部访问Keycloak容器并解决Issuer不匹配问题

问题背景 #

基于Spring开发的微服务后端采用Docker Compose部署，需将Keycloak暴露至外部网络。Docker内部可通过http://keycloak:8080/...访问Keycloak，但当前配置存在核心矛盾：

• 设置KC_HOSTNAME=keycloak后，外部访问管理控制台会重定向到http://keycloak/，无法正常使用
• 启用KC_HOSTNAME_ADMIN或KC_FRONTEND_URL会导致管理控制台出现somethingWentWrong错误
• 将KC_HOSTNAME改为localhost或不设置，会引发Spring服务中Token的Issuer URI不匹配，请求失败
• 临时修改/etc/hosts映射keycloak到本地IP的方案无法用于生产环境

解决方案 #

通过区分Keycloak的外部访问地址和内部服务访问地址，配合针对性参数配置解决冲突，具体操作如下：

1. 调整Docker Compose中Keycloak的环境变量 #

修改docker-compose.yml里Keycloak的environment配置：

keycloak:
  container_name: keycloak
  image: quay.io/keycloak/keycloak:latest
  command:
    - start-dev
  environment:
    - KEYCLOAK_ADMIN=admin
    - KEYCLOAK_ADMIN_PASSWORD=admin
    - KC_DB=postgres
    - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
    - KC_DB_USERNAME=postgres
    - KC_DB_PASSWORD=postgres
    # 外部访问使用的主机名/域名（开发环境用localhost，生产用实际域名如auth.example.com）
    - KC_HOSTNAME=localhost
    # Docker内部网络中其他服务访问Keycloak的主机名
    - KC_HOSTNAME_INTERNAL=keycloak
    - KC_PROXY=edge
    - KC_HOSTNAME_STRICT=false
    - KC_HOSTNAME_STRICT_HTTPS=false
    # 开发环境启用HTTP，生产环境建议禁用并配置HTTPS
    - KC_HTTP_ENABLED=true
  depends_on:
    - postgres
  ports:
    - "8080:8080"

2. 关键参数说明 #

• KC_HOSTNAME：指定外部用户访问Keycloak时的主机名，确保管理控制台重定向到正确的外部地址
• KC_HOSTNAME_INTERNAL：定义Docker内部网络中Spring服务等组件访问Keycloak的地址，保证Token的Issuer URI与Spring配置一致
• KC_PROXY=edge：让Keycloak正确识别外部请求的头信息，适配直接端口映射或反向代理场景
• KC_HOSTNAME_STRICT=false：允许Keycloak接受来自不同主机名的请求（内部keycloak和外部localhost）
• KC_HOSTNAME_STRICT_HTTPS=false：开发环境下禁用严格HTTPS检查，生产环境需启用并配置证书
• KC_HTTP_ENABLED=true：开发环境启用HTTP协议，生产环境建议关闭并配置HTTPS相关参数

3. Spring服务配置调整 #

在Spring微服务的application.yml中，将Keycloak的Issuer URI配置为Docker内部地址：

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://keycloak:8080/realms/你的领域名称

验证效果 #

• 外部访问：通过http://localhost:8080/admin可正常打开Keycloak管理控制台，无重定向异常
• 内部服务：Spring微服务验证Token时，Issuer URI与Keycloak颁发的Token一致，请求可正常通过

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