websocket代理在nginx中需透传协议升级、保活长连接、精准路径映射：必须原样传递upgrade头、设connection为"upgrade"、关闭缓冲与合理配置超时，路径匹配依赖proxy_pass末尾斜杠规则，并补充x-forwarded-proto等安全头。
WebSocket 代理在 Nginx 中不是简单转发 HTTP 请求，而是要完整透传协议升级过程、维持长连接、并确保帧流实时抵达。它的消息路由与转发逻辑，本质是“协议透传 + 连接保活 + 路径映射”，而非传统 HTTP 的内容解析或负载分发。
协议升级必须透传，不能拦截或改写
Nginx 不处理 WebSocket 消息体，只负责把客户端的 Upgrade 请求原样送往后端，并持续维持 TCP 隧道：
- 客户端发起
GET /ws HTTP/1.1并携带Upgrade: websocket和Connection: Upgrade头 - Nginx 必须用
proxy_set_header Upgrade $http_upgrade原样传递 Upgrade 头（不能写死为 websocket，兼容 mqtt 等其他协议） -
proxy_set_header Connection "upgrade"是固定字符串，不是变量；若误用$connection_upgrade且未配合 map 指令，Nginx 可能发Connection: close主动断连 - 后端收到的是原始请求头和路径，Nginx 不做内容解析、不修改 payload，所有 TEXT/BINARY 帧均直通
连接生命周期由超时与缓冲策略共同决定
WebSocket 是长连接，Nginx 默认行为会破坏其稳定性，需针对性关闭干扰项：
-
proxy_read_timeout 86400：防止空闲期被静默关闭；默认 60 秒会导致聊天类应用“无征兆掉线” -
proxy_send_timeout应同步设大（如 86400），避免大消息分片发送中途被切断 -
proxy_buffering off：禁用响应缓冲，否则后端发的多个帧可能被 Nginx 合并后一次性吐出，造成粘包或延迟 -
tcp_nodelay on：绕过 Nagle 算法，让心跳、光标更新等小数据包立即发出，保障实时性
路径转发依赖 location 匹配与 proxy_pass 末尾斜杠规则
URI 映射直接影响后端接收到的路径，必须按规则书写，不可随意加减斜杠：
- 前端连
ws://example.com/ws→ location 写location /ws { ... }，proxy_pass http://127.0.0.1:3000;（末尾无 /），后端收到路径为/ws - 前端连
ws://example.com/api/ws，想映射到后端/ws→proxy_pass http://127.0.0.1:3000/;（末尾有 /），Nginx 自动剥离/api/ws前缀 - 若需重写路径（如统一剥离前缀），可用
rewrite ^/prod-api/(.*)$ /$1 break;配合proxy_pass，但需注意 rewrite 在 proxy_pass 之前生效
HTTPS/WSS 场景需补充安全相关头字段
当代理 wss:// 时，除基础 WebSocket 配置外，还需确保后端正确识别协议与来源：
-
proxy_set_header X-Forwarded-Proto $scheme：让后端知道原始是 wss，避免生成 http 链接 -
proxy_set_header Host $host：尤其在非标准端口（如 8080）或泛域名 server 块中不可省略，否则租户路由、多租户鉴权可能失效 - SSL 终止由 Nginx 完成，后端只需处理普通 ws:// 流量，无需证书配置
