Nginx代理WebSocket需禁用干扰项以确保二进制帧无损透传：完整透传握手头（proxy_http_version 1.1、Upgrade/Connection/Host头）、关闭缓冲与压缩（proxy_buffering off、gzip off）、调大超时（proxy_read_timeout 86400等）、验证字节级一致性。
Linux 下 Nginx 代理 WebSocket 时，默认能透传二进制帧（opcode=2），但必须关闭所有可能篡改原始字节流的行为，否则会出现截断、粘包、1009 错误或 payload 不一致等问题。核心不是“开启”什么功能，而是“禁用干扰项”并确保协议升级完整。
确保 WebSocket 握手头完整透传
这是连接建立的前提，缺一不可：
- proxy_http_version 1.1——HTTP/1.0 不支持 Upgrade，必须显式启用
- proxy_set_header Upgrade $http_upgrade——用变量转发，兼容各类客户端（如发 "mqtt" 或空值）
- proxy_set_header Connection "upgrade"——注意小写 upgrade 和英文双引号；若写成 "$http_connection" 可能混入 keep-alive，导致后端拒绝升级
- proxy_set_header Host $host——多域名部署时易漏，缺失可能导致 404 或握手失败
关闭所有缓冲与压缩行为
Nginx 若对 WebSocket 流做缓存、压缩或重写，会破坏帧边界和原始字节顺序：
- proxy_buffering off——防止攒多个帧再发，避免毫秒级延迟或粘包
- gzip off——WebSocket 帧本身不可压缩，开启后服务端解码失败，尤其影响 ArrayBuffer、图片分片等
- proxy_buffer_size 4k——仅设最小缓冲区，不启用 proxy_buffers 多级缓存
- proxy_set_header X-Accel-Buffering "no"——部分 Nginx 版本需显式禁用内部加速缓冲
调大超时并跳过无效请求体检查
二进制传输（如模型权重、音视频分片）耗时长，Nginx 默认 60 秒超时极易中断：
- proxy_read_timeout 86400——覆盖长空闲期或分片间隔（24 小时足够）
- proxy_send_timeout 86400——避免大帧未发完就被切断
- client_max_body_size 0——WebSocket 不走 HTTP body 流程，此项必须禁用限制
- client_body_timeout 0——跳过对帧数据的无效读取等待
- tcp_nodelay on——关闭 Nagle 算法，保障小帧（如鼠标坐标、控制指令）立即送达
验证二进制帧是否真正无损透传
不能只看连接成功（101 响应），要确认字节级一致性：
- 前端执行
ws.send(new Uint8Array([0x01, 0xFF, 0x80]))，检查后端收到的 ArrayBuffer 是否完全一致 - Wireshark 抓包过滤
websocket，确认 Frame Type 显示 BINARY，Payload Length 和原始字节完全匹配 - 若返回 400 或立即断连 → 优先查 Upgrade/Connection 头是否丢失；若长度错乱或截断 → 重点查 proxy_buffering 和 gzip 是否残留
