基于 Nginx 的 WebSocket 反向代理实践

一、HTTP 协议升级机制回顾

Upgrade/Connection 报头
- 客户端发起 WebSocket 握手时，会在普通 HTTP 请求中加入
  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. 基本示例

nginx 复制代码

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 模块：

nginx 复制代码

# 将是否存在 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 秒内没有任何数据回传，会主动关闭连接。这对于长时间空闲但后续可能仍要推送消息的场景并不友好。常用的优化方案有两种：

延长 Nginx 的 proxy_read_timeout

在 location 或 http、server 级别添加：
nginx 复制代码
```
proxy_read_timeout 3600s;   # 将超时时间提升到 1 小时
```
后端发送 WebSocket Ping

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

四、完整示例

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;
        }
    }
}

五、实践要点与注意事项

HTTPS + WSS
若在前端使用 wss://（即 TLS 加密的 WebSocket），必须在 Nginx 上配置对应的 SSL 证书，并在 server 块中使用 ssl_certificate、ssl_certificate_key 等指令。
负载均衡与 Sticky Session
对于需要在多实例间保持会话一致性的业务，可考虑基于 Cookie 或 IP 哈希的 Sticky Session 配置，或者将业务设计成无状态。
安全加固
可以在 Nginx 中加入 limit_conn、limit_req 等限流指令，防止恶意连接耗尽资源；也可结合 lua-nginx-module 实现更复杂的鉴权或动态路由。

六、总结

通过上述方式，Nginx 能够高效、稳定地将客户端的 HTTP 升级请求（Upgrade）转发到后端 WebSocket 服务，实现反向代理与负载均衡。在此基础上，再配合合理的超时调整、心跳检测与安全限流，即可构建面向生产环境的高可用、可扩展的实时通信平台。希望本文能帮助你快速上手 Nginx WebSocket 代理，并打造符合业务需求的实时架构。