Nginx WebSocket 代理握手失败怎么办：Upgrade、Connection 与超时配置
Nginx WebSocket 握手失败时，按客户端请求头、Nginx upgrade 映射、上游地址和超时顺序排查，并记录状态码与断开时间。
WebSocket 握手失败先检查客户端请求头、Nginx upgrade 映射和上游地址，不要先更换代理 IP。返回 101 只表示握手升级成功，不代表长连接稳定。
如何检查客户端请求头和 Nginx 转发配置
确认客户端发送 Upgrade: websocket 和 Connection: Upgrade。核对 location 路径、proxy_pass 上游地址以及 HTTP/1.1 与 upgrade 映射；具体配置应结合现有站点配置和当前 Nginx 文档核实。
通用代理参数可先参考代理参数说明，再结合现有 Nginx 配置核对。
修改后先运行 nginx -t，通过后再 reload。用同一客户端记录握手状态、请求路径和请求 ID；返回 101 后继续观察首个数据帧与关闭时间。
握手成功但连接空闲断开时，区分应用未发送数据和中间层超时；不要把 101 当成长连接状态的唯一标准。
下面按状态码和断开时间定位客户端、Nginx 或上游问题。
| 状态/现象 | 优先检查 | 日志位置 | 处理动作 |
|---|---|---|---|
| 400 | Upgrade/Connection 请求头 | access log | 修正客户端握手 |
| 404 | URL、location 路径 | access log | 修正路由映射 |
| 502 | upstream 地址和状态 | error log、上游日志 | 修复上游连通性 |
| 101 后断开 | 上游协议、心跳 | Nginx 与上游日志 | 查关闭原因 |
| 空闲断开 | read timeout、心跳 | 两端日志 | 调整对应超时 |
使用请求 ID 对齐两端日志，确认故障后再修改对应配置。
修改 Nginx 配置后如何验证 WebSocket 连接
确认客户端发送 Upgrade: websocket 和 Connection: Upgrade，再核对 location、proxy_pass、HTTP/1.1 和 upgrade 映射。修改后先运行 nginx -t，通过后 reload；用同一请求记录状态码、请求 ID、首个数据帧和关闭时间。
400、404、502 和 101 后断开怎么排查
400 查客户端头，404 查 URL 与 location，502 查 upstream 和端口，101 后断开查上游关闭原因、协议和心跳，固定时间断开查 read timeout。101 只证明握手升级，不证明长连接稳定。
跨层故障可参考代理 IP 故障排查中心分辨客户端、代理和上游问题。
修改配置后先验证 Nginx 语法
配置关系应同时满足 HTTP/1.1、Upgrade 映射和正确 upstream；改动后先运行 nginx -t，再 reload，最后用客户端确认返回 101 Switching Protocols。日志至少记录请求 ID、状态码、upstream 地址、握手耗时和断开时间；101 只证明升级完成，后续断开仍需查空闲超时和上游日志。具体 location 片段按项目配置和当前 Nginx 文档复核。
如果握手之外还出现延迟或不稳定，可补充参考代理 IP 可用率、延迟和稳定性怎么测试。
FAQ
修改配置后如何确认已加载？
先执行 nginx -t，通过后 reload，再用握手请求和日志确认新配置生效。
客户端没有发送 Upgrade 请求头时需要改 Nginx 吗？
先检查客户端是否按 WebSocket 方式发起握手。Nginx 配置不能代替客户端发起 Upgrade 请求。
400、404 和 502 分别先查什么？
400 检查请求头和协议；404 检查 URL 与 location；502 检查 upstream、端口和上游服务状态。
返回 101 后连接仍然断开怎么办？
对照上游关闭日志、心跳和 proxy_read_timeout，判断是上游主动关闭还是空闲超时。101 只表示握手升级成功。