NGINX代理Docker化Keycloak：静态资源缺失/auth前缀问题解决

问题本质 #

Keycloak不知道自己是通过/auth路径被反向代理的，所以生成静态资源链接时没加这个前缀，结果这些请求被Nginx转发给了Angular应用，返回的是HTML页面而非CSS/JS资源，自然就报错了。

解决步骤 #

得从Keycloak的Docker配置和Nginx代理规则两方面入手，让Keycloak自动生成带/auth前缀的资源链接。

1. 修改Docker Compose里的Keycloak配置 #

在docker-compose.yaml的Keycloak服务中添加两个环境变量，明确告诉它对外的访问路径：

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    environment:
      # 保留你原来的其他变量，比如数据库配置、管理员账号等
      KEYCLOAK_FRONTEND_URL: http://localhost/auth/
      PROXY_ADDRESS_FORWARDING: "true"
    # 你的其他配置（端口映射、网络设置等）保持不变

• KEYCLOAK_FRONTEND_URL：指定Keycloak对外暴露的完整根路径，这样它生成的所有前端资源链接都会基于这个路径生成
• PROXY_ADDRESS_FORWARDING：开启这个开关后，Keycloak会信任反向代理传递的请求头，正确识别外部访问的真实地址

2. 调整Nginx的代理配置 #

确保Nginx把所有/auth开头的请求都转给Keycloak，同时正确传递请求头：

server {
    listen 80;
    server_name localhost;

    # 处理Angular应用的请求
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
    }

    # 代理Keycloak的所有请求
    location /auth/ {
        proxy_pass http://keycloak:8080/auth/;
        # 传递必要的请求头，让Keycloak知道外部访问的信息
        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-Proto $scheme;
        # 修正Keycloak返回的跳转链接，把内部容器地址换成外部代理地址
        proxy_redirect http://keycloak:8080/auth/ http://localhost/auth/;
    }
}

• 注意proxy_pass末尾的/：这个不能丢，不然Nginx会把/auth/css转发成http://keycloak:8080/css，肯定找不到资源
• proxy_redirect：用来替换Keycloak返回的跳转URL，避免前端拿到内部的容器地址

3. 验证操作 #

1. 重启Keycloak服务：docker-compose down && docker-compose up -d
2. 重启Nginx：如果是本地Nginx执行nginx -s reload，如果是Docker部署的Nginx就重启对应容器
3. 打开Angular应用，触发登录流程，检查浏览器控制台里的静态资源请求，确认路径是否自动带上了/auth前缀

容易踩的坑 #

• 没开启PROXY_ADDRESS_FORWARDING=true：Keycloak会无视反向代理的请求头，还是用容器内部的地址生成资源链接
• proxy_pass末尾没加/：路径拼接错误，导致资源请求被转发到Angular应用那边
• KEYCLOAK_FRONTEND_URL末尾没加/：可能会出现路径拼接异常，比如生成http://localhost/authcss这种错误链接

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