在 nginx 中转发 websocket 连接，核心做法是在 `location` 块中配置 `proxy_pass` 并显式设置 `upgrade` 和 `connection` 请求头。具体操作是添加 `proxy_http_version 1.1;`，将 `proxy_set_header upgrade $http_upgrade;` 和 `proxy_set_header connection 'upgrade';` 写入配置，这样 nginx 就能正确识别客户端的升级请求并将 tcp 通道透传给后端服务。
Nginx 如何修改 HTTP 请求头以支持协议升级
Nginx 默认使用 HTTP/1.0 代理后端，这会导致 `Upgrade` 请求被忽略或断开。要解决这个问题，必须将代理版本提升至 1.1，并手动传递客户端发来的 `Upgrade` 值。通过设置 `proxy_set_header`，Nginx 会将原始请求中的 `Upgrade` 字段原样转发给后端，同时将 `Connection` 头强制设为 `upgrade`，从而触发后端的握手流程。
server {
listen 80;
server_name example.com;
location /ws {
proxy_pass http://backend_server;
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;
}
}
上述配置中，`$http_upgrade` 变量捕获了客户端请求头中的 `websocket` 值。如果客户端未发送该头，变量为空，但 `Connection` 被固定为 `upgrade`，这在某些严格的后端实现中可能引发问题，通常建议结合条件判断或使用更稳健的配置模式。运行此配置后，Nginx 会建立一条持久的 TCP 连接，不再进行 HTTP 层面的响应解析。
如何处理非 WebSocket 流量以避免连接错误
如果所有请求都强制设置 `Connection 'upgrade'`，普通 HTTP 请求可能会因后端不支持而报错。因此，需要区分 WebSocket 请求和普通请求。可以通过检查 `$http_upgrade` 变量的值来决定 `Connection` 头的行为。对于非 WebSocket 请求，保持默认的 `close` 或 `keep-alive` 状态，确保常规 API 调用不受影响。
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://backend_server;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
}
}
这里使用了 `map` 指令创建一个变量 `$connection_upgrade`。当 `$http_upgrade` 不为空（即值为 `websocket`）时，`Connection` 设为 `upgrade`；当为空时，设为 `close`。这种写法避免了硬编码，使得同一 `location` 块既能处理 WebSocket 长连接，也能正常处理普通 HTTP 短连接。测试时，访问 `/ws` 路径应成功建立 WebSocket 连接，而访问根路径 `/` 应返回正常的 HTML 或 JSON 数据。
WebSocket 连接建立后的数据传输机制是什么
一旦 WebSocket 握手完成，Nginx 与后端之间的通信就不再遵循 HTTP 语义，而是直接转发二进制或文本帧。此时，`Upgrade` 和 `Connection` 头的作用已完成，Nginx 仅作为透明的 TCP 代理。这意味着 Nginx 不会解析消息内容，也不会干预心跳包或关闭帧的处理，除非配置了超时参数导致连接中断。
# 保持连接活跃的配置示例
location /ws {
proxy_pass http://backend_server;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# 防止 Nginx 因超时而断开空闲的 WebSocket 连接
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
在实际部署中，如果不设置 `proxy_read_timeout` 和 `proxy_send_timeout`，Nginx 默认会在 60 秒无数据活动时关闭连接。这对于需要长期保持连接的聊天应用或实时通知服务是不可接受的。设置为较大的值（如 86400 秒，即一天）可以确保连接在空闲期间不被切断。同时，后端服务也应实现心跳机制，以检测对端是否存活，因为 Nginx 的超时设置仅控制代理层的等待时间，不反映应用层的状态。
