WebSocket 握手失败：缺少 Upgrade 头字段

Question

在使用 WebSocket 建立连接时，客户端发起的 HTTP 请求需包含 `Upgrade: websocket` 和 `Connection: Upgrade` 头字段，以告知服务器希望升级协议至 WebSocket。常见问题是反向代理（如 Nginx）或负载均衡器未正确配置，导致这些关键头字段被过滤或丢失，从而使服务端无法识别升级请求，返回“400 Bad Request”或直接断开连接。典型表现为浏览器报错“WebSocket 握手失败：缺少 Upgrade 头字段”。该问题多见于 Nginx 配置中未显式转发 Upgrade 头，需在 location 块中添加 proxy_set_header 指令以透传相关头部。

Answer 1

1. WebSocket 握手机制与关键头部字段解析

WebSocket 协议通过 HTTP/1.1 的“协议升级”机制完成从普通 HTTP 到 WebSocket 的切换。客户端在发起连接时，必须发送包含特定头字段的 HTTP 请求，以表明其意图：

• Upgrade: websocket —— 指示服务器希望将当前连接升级为 WebSocket 协议。
• Connection: Upgrade —— 表明这是一个连接升级请求，而非标准的持久化或短连接行为。
• 其他必要字段如 Sec-WebSocket-Key 和 Sec-WebSocket-Version 也需存在。

若这些字段缺失或被中间代理修改，服务端无法识别为合法的 WebSocket 握手请求，将返回 400 错误或直接关闭连接。

浏览器开发者工具中常见错误提示：“WebSocket connection to 'ws://example.com/ws' failed: Error during WebSocket handshake: 'Upgrade' header is missing”，即为此类问题的典型表现。

2. 反向代理中的头部透传问题分析

在现代 Web 架构中，Nginx 常作为反向代理位于客户端与后端应用服务器之间。默认情况下，Nginx 并不会自动转发所有原始请求头，尤其是与连接升级相关的特殊字段。

Nginx 对 Upgrade 和 Connection 头字段有特殊的处理逻辑：它们不属于标准 HTTP/1.x 的常规语义范畴，因此需要显式配置才能透传。

配置项	作用说明
proxy_set_header Upgrade $http_upgrade;	将客户端传入的 Upgrade 头原样传递给后端服务
proxy_set_header Connection "upgrade";	设置 Connection 头为 upgrade，触发协议升级流程
proxy_http_version 1.1;	确保使用 HTTP/1.1，因 WebSocket 依赖该版本的长连接能力

3. Nginx 配置示例与最佳实践

以下是一个典型的 Nginx location 配置块，用于支持 WebSocket 连接穿透：

location /ws/ {
    proxy_pass http://backend_ws;
    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;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
}

其中，$http_upgrade 是 NGINX 内建变量，表示客户端请求中的 Upgrade 头值；而硬编码 "upgrade" 是为了确保 Connection 头正确设置。

此配置适用于基于 Node.js、Spring Boot、Tornado 等实现的 WebSocket 服务部署场景。

4. 负载均衡器与云网关的影响扩展

除了 Nginx，企业级环境中常见的负载均衡器（如 AWS ALB、Azure Application Gateway、Kong、Traefik）也可能影响 WebSocket 握手过程。

• AWS ALB 默认支持 WebSocket，但需确认监听器协议为 HTTP/HTTPS 并启用 Connection: upgrade 透传。
• Kong API 网关可通过插件（如 websocket 插件）显式开启 WebSocket 支持。
• Traefik 中需设置 [http.routers.router0.middlewares] 包含正确的升级规则。

配置不当会导致看似“随机”的连接失败，尤其在灰度发布或蓝绿部署中更易暴露此类问题。

5. 故障排查流程图（Mermaid 格式）

graph TD
    A[客户端发起 WebSocket 连接] --> B{是否收到 400/Bad Request?}
    B -- 是 --> C[检查浏览器 DevTools 中请求头]
    C --> D[确认是否存在 Upgrade: websocket 和 Connection: Upgrade]
    D -- 缺失 --> E[检查反向代理配置]
    E --> F[Nginx 是否设置了 proxy_set_header Upgrade 和 Connection?]
    F -- 否 --> G[添加相应 proxy_set_header 指令]
    F -- 是 --> H[检查 upstream 服务是否监听并处理 WS]
    G --> I[重启 Nginx 并重试]
    H --> I
    B -- 否 --> J[进一步检查 TLS、CORS 或后端认证逻辑]

6. 实际生产环境中的监控建议

为避免线上突发 WebSocket 握手失败，建议建立以下监控机制：

1. 对 WebSocket 握手接口进行定期健康探测，验证响应状态码是否为 101 Switching Protocols。
2. 采集 Nginx access log 中包含 $upstream_status 字段的日志，识别 400 类错误。
3. 使用 Prometheus + Grafana 对 nginx_http_requests_total{status="400"} 设置告警规则。
4. 在前端 JS 层捕获 onerror 和 onclose 事件，上报握手失败上下文。
5. 结合分布式追踪系统（如 Jaeger），跟踪从入口到后端服务的完整链路。
6. 对移动端和低网络质量用户做降级方案测试，例如轮询备用通道。
7. 定期审计所有边缘代理配置，确保无隐式头部过滤策略。
8. 实施 CI/CD 流程中的配置 lint 检查，防止人为遗漏关键指令。
9. 使用自动化测试工具（如 Puppeteer 或 Cypress）模拟真实浏览器行为。
10. 记录每次变更后的连接成功率指标，形成趋势分析。