Nginx反向代理Keycloak出现502 Bad Gateway错误的解决方法

问题概述 #

尝试将Keycloak部署到网站的/keycloak路径下，访问https://www.mywebsite.com/keycloak/时出现502 Bad Gateway错误。Nginx日志显示无法连接到http://127.0.0.1:8080，Keycloak容器日志显示服务已正常启动并监听0.0.0.0:8080。

核心原因 #

Nginx运行在主机环境，而Keycloak运行在Docker容器中：

• Keycloak容器的8080端口未映射到主机端口，导致主机上的Nginx无法通过localhost:8080访问容器内的服务；
• Docker容器默认处于独立的私有网络，主机直接访问容器内部端口会被拒绝。

解决方案 #

方案1：映射Keycloak端口到主机（简单直接） #

修改docker-compose.yml，给Keycloak服务添加端口映射，将容器内的8080端口绑定到主机的8080端口：

version: '3.8'

services:
  keycloak:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: custom-keycloak
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
      - KC_HOSTNAME=mywebsite.com
      - KC_PROXY=edge
      - KC_HTTP_RELATIVE_PATH=/keycloak
    volumes:
      - keycloak_data:/opt/keycloak/data
    networks:
      - keycloak-network
    ports:
      - "8080:8080"  # 添加端口映射配置

networks:
  keycloak-network:
    driver: bridge

volumes:
  keycloak_data:

修改后重启Keycloak容器，Nginx现有proxy_pass http://localhost:8080;配置即可生效。

方案2：让Nginx接入Keycloak的Docker网络（更安全，避免端口暴露） #

如果不想将Keycloak端口暴露到主机，推荐让Nginx（Docker运行模式）加入Keycloak的私有网络，直接通过容器名访问：

1. 修改Nginx配置的proxy_pass，将localhost:8080替换为容器名custom-keycloak:8080：

location /keycloak/ {  
    proxy_pass http://custom-keycloak: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-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /keycloak;
}

2. 修改Nginx的docker-compose配置，加入Keycloak的私有网络：

services:
  nginx:
    # 保留原有Nginx配置
    networks:
      - keycloak-network

networks:
  keycloak-network:
    external: true  # 引用已存在的Keycloak网络

3. 若Nginx运行在主机上，可通过docker inspect custom-keycloak | grep IPAddress获取容器IP，将proxy_pass指向该IP；或改用Docker host网络模式（不推荐，安全性较低）。

额外配置检查 #

确保Keycloak与Nginx的路径配置完全匹配：

• Keycloak的KC_HTTP_RELATIVE_PATH=/keycloak与Nginx的X-Forwarded-Prefix /keycloak保持一致；
• KC_PROXY=edge配置正确，适配HTTPS反向代理场景。

内容的提问来源于stack exchange，提问作者M. Nicol