配置Keycloak 18通过Nginx以HTTP公网IP访问时页面加载不全

问题现象 #

通过Nginx反向代理，使用HTTP协议绑定公网IP部署Keycloak 18.0.0时，页面加载残缺，样式、功能缺失：

原有Keycloak部署配置：

原有Nginx配置如下：

# .NET Core
location /api/ {
    proxy_pass         http://localhost:5001;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection keep-alive;
    proxy_set_header   Host $host;
    proxy_cache_bypass $http_upgrade;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
}

location /auth
{
    proxy_pass          http://localhost:8080/;
    proxy_set_header    Host               $host;
    proxy_set_header    X-Real-IP          $remote_addr;
    proxy_set_header    X-Forwarded-For    $proxy_add_x_forwarded_for;
    proxy_set_header    X-Forwarded-Host   $host;
    proxy_set_header    X-Forwarded-Server $host;
    proxy_set_header    X-Forwarded-Port   $server_port;
    proxy_set_header    X-Forwarded-Proto  $scheme;
}

部署方式为压缩包解压直接部署。 #

问题根因 #

两个配置错误共同导致故障：

1. Nginx转发规则路径不匹配：location /auth未做后缀斜杠对齐，proxy_pass末尾多余斜杠导致路径截断，Keycloak返回的静态资源路径丢失/auth前缀，浏览器请求资源时返回404，造成页面残缺。
2. Keycloak 18基于Quarkus架构构建，默认以生产模式启动，强制要求HTTPS、默认上下文路径为根路径、未开启反向代理头信任，无法适配前置Nginx代理的访问逻辑。

修复步骤 #

1. 调整Nginx配置 #

将原有/auth对应的location块替换为以下内容，对齐路径匹配规则、补充必要的代理头：

location /auth/ {
    proxy_pass          http://localhost:8080/auth/;
    proxy_http_version  1.1;
    proxy_set_header    Upgrade               $http_upgrade;
    proxy_set_header    Connection            "upgrade";
    proxy_set_header    Host                  $host;
    proxy_set_header    X-Real-IP             $remote_addr;
    proxy_set_header    X-Forwarded-For       $proxy_add_x_forwarded_for;
    proxy_set_header    X-Forwarded-Host      $host;
    proxy_set_header    X-Forwarded-Server    $host;
    proxy_set_header    X-Forwarded-Port      $server_port;
    proxy_set_header    X-Forwarded-Proto     $scheme;
    proxy_redirect      off;
}

修改后先执行nginx -t验证配置语法无报错，再执行nginx -s reload重载配置。

2. 调整Keycloak启动参数 #

压缩包版Keycloak默认启动参数不满足代理+HTTP访问要求，启动时需要附加对应参数。进入Keycloak解压目录的bin文件夹，执行以下启动命令：

./kc.sh start-dev --http-relative-path=/auth --hostname-strict=false --http-enabled=true --proxy=edge

参数说明：

• start-dev：以开发模式启动，自动关闭HTTPS强制校验，适合HTTP测试场景使用
• --http-relative-path=/auth：指定Keycloak服务的上下文路径为/auth，和Nginx转发路径完全对齐，保证静态资源、跳转地址路径正确
• --hostname-strict=false：关闭严格主机名校验，支持直接通过公网IP访问
• --http-enabled=true：显式开启HTTP端口监听
• --proxy=edge：告知Keycloak存在前置反向代理，自动读取X-Forwarded-*系列头信息，生成正确的对外访问地址

验证 #

重启Keycloak、重载Nginx后，清空浏览器缓存，访问http://你的公网IP/auth即可正常加载完整的Keycloak控制台页面。

注意：生产环境不建议长期使用HTTP+公网IP的方式部署Keycloak，存在账号信息明文传输的安全风险，建议配置域名和有效HTTPS证书后再上线使用。

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