Docker部署Keycloak v26经Nginx反向代理后控制台异常求助

问题现象 #

Docker部署的Keycloak v26通过Nginx反向代理对外提供服务，数据库由v19.0.2备份恢复并完成自动升级。登录管理控制台密码验证正常，但所有Realm均显示错误提示Unable to determine error message.；浏览器追踪发现仅/auth/admin/master/console/whoami请求返回502 Bad Gateway，对应Nginx和Keycloak日志均出现连接重置报错。

错误日志 #

Nginx错误日志 #

2024/10/31 15:14:36 [error] 18794#18794: *79409565 recv() failed (104: Connection reset by peer) while reading response header from upstream, client: 192.168.13.91, server: sso.mydomain.com, request: "GET /auth/admin/master/console/whoami?currentRealm=master HTTP/1.1", upstream: "http://10.10.0.89:8080/auth/admin/master/console/whoami?currentRealm=master", host: "sso.mydomain.com:8443"

Keycloak日志 #

2024-10-31 14:26:46,495 WARN  [io.netty.channel.DefaultChannelPipeline] (vert.x-eventloop-thread-2) An exceptionCaught() event was fired, and it reached at the tail of the pipeline. It usually means the last handler in the pipeline did not handle the exception.: java.net.SocketException: Connection reset
    at java.base/sun.nio.ch.SocketChannelImpl.throwConnectionReset(SocketChannelImpl.java:401)
    at java.base/sun.nio.ch.SocketChannelImpl.read(SocketChannelImpl.java:434)
    at io.netty.buffer.PooledByteBuf.setBytes(PooledByteBuf.java:255)
    at io.netty.buffer.AbstractByteBuf.writeBytes(AbstractByteBuf.java:1132)
    at io.netty.channel.socket.nio.NioSocketChannel.doReadBytes(NioSocketChannel.java:356)
    at io.netty.channel.nio.AbstractNioByteChannel$NioByteUnsafe.read(AbstractNioByteChannel.java:151)
    at io.netty.channel.nio.NioEventLoop.processSelectedKey(NioEventLoop.java:788)
    at io.netty.channel.nio.NioEventLoop.processSelectedKeysOptimized(NioEventLoop.java:724)
    at io.netty.channel.nio.NioEventLoop.processSelectedKeys(NioEventLoop.java:650)
    at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:562)
    at io.netty.util.concurrent.SingleThreadEventExecutor$4.run(SingleThreadEventExecutor.java:994)
    at io.netty.util.internal.ThreadExecutorMap$2.run(ThreadExecutorMap.java:74)
    at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
    at java.base/java.lang.Thread.run(Thread.java:1583)

当前配置 #

Nginx虚拟主机配置 #

upstream sso-mydomain-com {
        server 10.10.0.89:8080;
}

server {
        listen       443 ssl;
        server_name  sso.mydomain.com;

        location / {
            proxy_pass http://sso-mydomain-com/;
            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-Host $host;
            proxy_set_header X-Forwarded-Port $server_port;
        }
        ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}

server {
        listen       8443 ssl;
        server_name  sso.mydomain.com;
        error_log    /usr/local/nginx/logs/sso_err.log debug;

        location / {
            proxy_pass http://sso-mydomain-com/;
            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-Host $host;
            proxy_set_header X-Forwarded-Port $server_port;
        }
        ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}

Keycloak Docker Compose配置 #

services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.0
    env_file:
      - .env
    ports:
      - 8080:8080
    volumes:
      - /opt/keycloak/themes:/opt/keycloak/themes
      - /etc/localtime:/etc/localtime
    privileged: true
    command: start

Keycloak环境变量 #

KC_HOSTNAME=sso.mydomain.com
KC_DB=mysql
KC_DB_PASSWORD=********
KC_DB_URL=jdbc:mysql://10.10.0.89:3306/keycloak
KC_DB_USERNAME=keycloak
KC_HTTP_RELATIVE_PATH=/auth
KC_HTTP_ENABLED=true

KC_PROXY_HEADERS=xforwarded
KC_LOG_LEVEL=DEBUG

测试验证结果 #

• 将证书映射到Keycloak容器，域名直接指向容器IP时服务正常；
• 将证书映射到Keycloak容器，使用Nginx Stream代理时服务也正常，相关配置如下：

stream {
    upstream sso-keycloak {
        server 10.10.0.89:8443;
    }
    server {
        listen 8443;
        proxy_pass sso-keycloak;
    }
}

解决建议 #

• 调整Nginx代理超时设置：在Nginx的location /块中添加连接超时配置，避免连接提前断开：

  proxy_connect_timeout 60s;
  proxy_send_timeout 60s;
  proxy_read_timeout 60s;
  

• 指定Keycloak端口配置：在Keycloak环境变量中添加KC_HOSTNAME_PORT=8443，确保生成的回调地址使用正确的对外端口，避免请求路径不匹配。
• 优化Nginx HTTP版本与连接头：在location /块中添加HTTP/1.1支持，适配Keycloak的Vert.x底层：

  proxy_http_version 1.1;
  proxy_set_header Connection "";
  

• 明确Keycloak代理模式：修改Keycloak启动命令为start --proxy edge，或添加环境变量KC_PROXY=edge，增强反向代理场景下的兼容性。
• 排查网络层问题：确认Nginx服务器与Keycloak容器所在主机之间的防火墙、安全组规则，确保8080端口无拦截或连接中断限制。

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