Node反向代理如何正确转发WebSocket连接？

Question

常见问题： 在使用 Node.js（如 `http-proxy` 或 `express-http-proxy`）搭建反向代理时，若未显式处理 WebSocket 升级请求（`Upgrade: websocket`），代理会将 `GET` 请求当作普通 HTTP 流量转发，导致 `Connection: upgrade` 和 `Upgrade: websocket` 头被忽略或篡改，后端 WebSocket 服务无法完成握手。典型现象包括：客户端报错 `Error during WebSocket handshake: Unexpected response code: 200` 或 `400`；`ws://` 连接瞬间断开；`nginx` 转发正常但 Node 代理失败。根本原因在于：默认 HTTP 代理不透传 `upgrade` 事件、未监听 `upgrade` 事件并手动建立底层 socket 管道、未正确保留原始 `Host`/`Origin`/`Sec-WebSocket-Key` 等关键头字段，且常遗漏对 `CONNECT` 方法或非标准路径的兼容处理。解决需主动拦截 `upgrade` 事件，禁用 `proxyReqOpt` 中的自动头过滤，并确保 TCP 层双向流直通——这与普通 HTTP 代理逻辑有本质区别。

Answer 1

```html

一、现象层：典型 WebSocket 代理失败的可观测症状

• 浏览器控制台报错：Error during WebSocket handshake: Unexpected response code: 200 或 400
• ws:// 连接在 onopen 前即触发 onclose（event.code = 1006）
• 抓包可见：客户端发出含 Upgrade: websocket + Connection: upgrade + Sec-WebSocket-Key 的 GET 请求，但后端返回 HTTP/1.1 200 OK（非 101 Switching Protocols）
• Nginx 反向代理相同后端可正常握手，Node.js 代理却失败 —— 暴露架构差异本质
• 使用 curl -i -N -H "Upgrade: websocket" ... 手动测试时，代理返回 405 Method Not Allowed 或静默丢弃

二、协议层：HTTP/1.1 Upgrade 机制与 WebSocket 握手的不可替代性

WebSocket 并非独立协议，而是基于 HTTP/1.1 的 协议升级协商机制：

1. 客户端发起标准 HTTP GET 请求，携带强制头：Upgrade: websocket、Connection: upgrade、Sec-WebSocket-Key、Sec-WebSocket-Version: 13
2. 服务端验证后，必须以 HTTP/1.1 101 Switching Protocols 响应，并回传 Sec-WebSocket-Accept 头
3. 握手成功后，TCP 连接原地升格为全双工二进制帧通道，后续通信不再走 HTTP 解析栈
4. 任何中间件若将该请求当作普通 HTTP 处理（如重写 Host、过滤 Connection 头、缓冲响应体），即破坏握手原子性

三、实现层：http-proxy 默认行为与 WebSocket 的根本冲突

行为维度	普通 HTTP 代理	WebSocket 升级代理
事件监听	仅处理 request、response	必须显式监听 upgrade 事件
数据流模型	应用层（HTTP message）转发	TCP 层（socket duplex stream）直通
Header 处理	自动删除 Connection、Upgrade 等逐跳头	需保留原始 Host、Origin、Sec-WebSocket-Key

四、代码层：正确实现 WebSocket 透传的最小可行方案

const httpProxy = require('http-proxy');
const proxy = httpProxy.createProxyServer({
  changeOrigin: true,
  // 关键：禁用默认 header 清洗
  proxyReqOptDecorator: (proxyReqOpts, srcReq) => {
    proxyReqOpts.headers = { ...srcReq.headers }; // 全量透传
    return proxyReqOpts;
  }
});

// 必须拦截 upgrade 事件！
proxy.on('upgrade', (req, socket, head) => {
  const target = `http://${process.env.WS_BACKEND || 'localhost:8080'}`;
  proxy.web(req, socket, { target, changeOrigin: true }, (err) => {
    if (err) console.error('WS upgrade failed:', err);
  });
});

// 普通 HTTP 请求仍走常规代理
app.use((req, res) => {
  proxy.web(req, res, { target: 'http://backend' });
});

五、深度排查：诊断清单与调试工具链

• ✅ 使用 tcpdump -i lo port 3000 -w ws.pcap 抓包，比对客户端→代理→后端的完整 TCP 流
• ✅ 在 upgrade 事件回调中打印 req.headers，确认 Sec-WebSocket-Key 是否丢失
• ✅ 后端启用 ws.Server({ noServer: true }) 手动解析握手，定位是代理截断还是后端拒绝
• ✅ 验证 Origin 头是否被代理篡改（尤其跨域场景下影响后端校验逻辑）
• ✅ 检查 Node.js 版本 —— v18.13+ 对 net.Socket 的 setTimeout 行为变更可能引发超时中断

六、架构层：为什么 Nginx “开箱即用”而 Node.js 需深度定制？

graph LR
  A[客户端 WebSocket 请求] --> B{Nginx}
  B -->|内置 upgrade 模块| C[直接 socket splice]
  A --> D{Node.js http-proxy}
  D -->|默认无 upgrade 处理| E[降级为 HTTP 代理]
  D -->|显式 on('upgrade')| F[手动 pipe socket]
  F --> G[等效于 splice]

Nginx 在内核态实现 ngx_http_upstream_handler 直接接管 TCP 连接；而 Node.js 的 http.Server 将 upgrade 视为特殊事件需用户显式消费——这是运行时模型差异，非功能缺陷。

七、生产加固：高可用 WebSocket 代理的关键增强点

1. 添加 timeout 和 ping/pong 心跳透传支持（避免中间设备 kill idle connection）
2. 实现 ws:// → wss:// 协议转换时的 TLS 终止与重加密
3. 对 Sec-WebSocket-Protocol 头做白名单校验，防止协议混淆攻击
4. 集成 Prometheus metrics：跟踪 ws_upgrade_success_total、ws_handshake_duration_seconds
5. 设计优雅降级：当后端 WebSocket 不可用时，返回 503 + 自定义错误帧而非静默断连

```