首页 › Nginx › 反向代理（在新窗口打开） › WebSocket 代理

Nginx 从 1.3 版本开始支持 WebSocket 代理，需要在 proxy_pass 基础上做特殊配置。

核心配置

location /ws/ {
    proxy_pass http://websocket-backend:8080;

    # 关键：升级协议到 WebSocket
    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;

    # WebSocket 长连接超时（默认 60s）
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;

    # 关闭缓冲（WebSocket 需要实时通信）
    proxy_buffering off;
}

配置说明

指令	作用
proxy_http_version 1.1	WebSocket 需要 HTTP/1.1（默认 proxy 用 1.0）
proxy_set_header Upgrade $http_upgrade	传递客户端的 Upgrade 头
proxy_set_header Connection "upgrade"	将连接升级为 WebSocket
proxy_read_timeout 3600s	长连接超时，设为足够长

混合 HTTP + WebSocket

同一 location 同时处理普通 HTTP 和 WebSocket：

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://app-backend:3000;
        proxy_http_version 1.1;

        # 仅 WebSocket 升级连接，普通请求不受影响
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $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_read_timeout 3600s;
        proxy_buffering off;
    }
}

通过 map 处理 Connection 头：

http {
    # map 根据 Upgrade 头动态设置 Connection 值
    map $http_upgrade $connection_upgrade {
        default  "upgrade";
        ""       "";
    }

    server {
        location / {
            proxy_pass http://app-backend:3000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
        }
    }
}

完整示例：WebSocket 聊天服务

http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        "" close;
    }

    upstream ws_backend {
        server 127.0.0.1:8080;
        server 127.0.0.1:8081;
    }

    server {
        listen 80;
        server_name chat.example.com;

        location / {
            proxy_pass http://ws_backend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;

            proxy_read_timeout 3600s;
            proxy_send_timeout 3600s;
            proxy_buffering off;
        }
    }
}

小结

• WebSocket 代理需要 proxy_http_version 1.1 + Upgrade/Connection 头。
• proxy_read_timeout 设长（3600s）避免连接意外断开。
• proxy_buffering off 确保实时双向通信。
• 通过 map 指令可优雅处理普通 HTTP 和 WebSocket 在同一 location 的共存。
• WebSocket 连接支持 upstream 负载均衡，但需额外的会话保持方案。

上一节：代理缓存 下一节：SSL 证书与 HTTPS 配置

贡献者: 布欧-Lewyon