Nginx稳定代理WebSocket的关键是精准适配其通信机制：必须透传Upgrade和Connection头（proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"），设proxy_read_timeout和proxy_send_timeout为86400，关闭proxy_buffering与proxy_cache，并启用tcp_nodelay。
要让 Nginx 稳定代理 WebSocket 并维持长连接，关键不是“开启支持”，而是精准适配 WebSocket 的通信机制：它依赖协议升级、拒绝缓冲、容忍空闲、透传帧流。配置错一个环节，连接就会静默中断或握手失败。
必须透传 Upgrade 和 Connection 头
WebSocket 握手本质是 HTTP 升级请求，Nginx 默认丢弃这两个逐跳头，导致后端收不到升级信号，返回 200 而非 101。
- proxy_http_version 1.1：强制使用 HTTP/1.1，这是 Upgrade 机制的前提，HTTP/1.0 或 HTTP/2 均不适用
- proxy_set_header Upgrade $http_upgrade：用变量转发原始 Upgrade 值（如 websocket、h2c），不能硬写 "websocket"
- proxy_set_header Connection "upgrade"：必须是带英文双引号的字面量 "upgrade"，不是 $http_connection（后者常为 keep-alive）
超时时间要远大于心跳周期
WebSocket 空闲时不发业务数据，仅靠心跳维持活跃。Nginx 默认 proxy_read_timeout=60 秒，会主动断开“无响应”连接——这就是频繁掉线的根源。
- proxy_read_timeout 86400：设为 24 小时（或至少 ≥ 心跳间隔 × 3），确保覆盖任意空闲时段
- proxy_send_timeout 86400：同步调大，避免后端推送大消息（如音频 chunk、状态快照）时被中断
- keepalive_timeout 86400（可选）：与上游超时对齐，提升客户端到 Nginx 的 TCP 层存活稳定性
关闭缓冲并禁用干扰行为
WebSocket 是低延迟、流式双向协议，Nginx 默认的缓冲和缓存策略会堆积帧、引入延迟、甚至导致粘包。
- proxy_buffering off：必须在具体 location 块中关闭（如 /ws/），不可放全局；防止后端帧被攒批发送
- proxy_cache off：禁用所有 proxy_cache_* 指令，WebSocket 消息不可缓存，启用即失败
- tcp_nodelay on：绕过 Nagle 算法，小帧（如光标移动、VAD 触发）立即透传，对实时性敏感场景很关键
路径匹配与 HTTPS 注意事项
配置生效的前提是请求真正进入对应 location，且链路各环节兼容 TLS。
- WebSocket 路径（如 /ws、/api/ws）建议用精确或前缀匹配，避免 rewrite 改写或被通用 location 拦截
- HTTPS 场景下，server 块必须含 listen 443 ssl，且 ssl_certificate / ssl_certificate_key 路径正确、域名匹配
- wss 连接由 Nginx 终止 TLS，后端走 http://，需补 proxy_set_header X-Forwarded-Proto $scheme 避免协议误判
