Nginx的WebSocket反向代理实践过程_websocket

一、http 协议升级机制回顾

upgrade/connection 报头

客户端发起 websocket 握手时，会在普通 http 请求中加入

upgrade: websocket
connection: upgrade
sec-websocket-key: <随机值>
sec-websocket-version: 13

服务端若接受协议切换，会以 101 switching protocols 响应，并同样返回 upgrade 和 connection 报头。

hop-by-hop 报头限制

http/1.1 中，upgrade 与 connection 都属于 hop-by-hop 报头，只能在相邻节点间生效，不会被普通反向代理转发。因此，需要在 nginx 明确地把这两者从客户端请求里取出，并再设置到转发给后端的请求头中。

二、nginx 代理 websocket 的关键配置

1. 基本示例

location /chat/ {
    # 将请求转发到后端 websocket 服务
    proxy_pass http://backend;

    # 使用 http/1.1 协议，以支持 upgrade
    proxy_http_version 1.1;

    # 将客户端请求中的 upgrade 与 connection 头转发给后端
    proxy_set_header upgrade $http_upgrade;
    proxy_set_header connection "upgrade";
}

proxy_http_version 1.1

强制使用 http/1.1，否则默认的 http/1.0 无法支持协议升级。

proxy_set_header upgrade $http_upgrade

将客户端传来的 upgrade: websocket 透传给后端。

proxy_set_header connection “upgrade”

明确指定与 upgrade 配合使用。

2. 智能化 connection 设置

在某些场景下，希望仅在真有升级需求时才发 "upgrade"，否则保持连接关闭。

可借助 nginx 的 map 模块：

# 将是否存在 upgrade 头映射成变量
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    ...

    location /chat/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header upgrade $http_upgrade;
        proxy_set_header connection $connection_upgrade;
    }
}

如果客户端请求里没有 upgrade，则向后端发送 connection: close，更符合一般 http 请求的语义。

三、超时与心跳优化

默认情况下，nginx 在代理 websocket 连接时，如果后端在 60 秒内没有任何数据回传，会主动关闭连接。

这对于长时间空闲但后续可能仍要推送消息的场景并不友好。

常用的优化方案有两种：

1.延长 nginx 的 proxy_read_timeout

在 location 或 http、server 级别添加：

proxy_read_timeout 3600s;   # 将超时时间提升到 1 小时

2.后端发送 websocket ping

让后端应用周期性地向客户端（经过 nginx）发送 ping 帧，触发 nginx 读取数据，从而重置超时计时器，同时还能检测连接健康状态。

四、完整示例

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

    upstream backend {
        server 127.0.0.1:8080;    # 后端 websocket 服务地址
        # 可根据实际情况添加多台服务器，实现负载均衡
    }

    server {
        listen 80;
        server_name example.com;

        # 静态资源处理（可选）
        location /static/ {
            root /var/www/html;
        }

        # websocket 代理入口
        location /chat/ {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header   upgrade $http_upgrade;
            proxy_set_header   connection $connection_upgrade;

            # 转发客户端真实 ip（可选）
            proxy_set_header   x-real-ip        $remote_addr;
            proxy_set_header   x-forwarded-for  $proxy_add_x_forwarded_for;

            # 超时配置
            proxy_read_timeout  3600s;
            proxy_send_timeout  3600s;
        }
    }
}