Nginx代理WebSocket需显式配置协议升级与长连接：必须设proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、Connection "upgrade"；调整proxy_read_timeout等超时值、禁用缓冲；wss场景需传X-Forwarded-Proto并确保HTTPS基础配置。
要让 Nginx 正确代理 WebSocket 连接，关键不是“加个 proxy_pass 就行”，而是必须显式满足协议升级机制和长连接维持条件。漏掉任一配置，客户端常卡在 400 或直接断连，日志里却看不到明显错误。
必须设置的协议升级头
WebSocket 握手依赖 HTTP/1.1 的 Upgrade 流程，Nginx 默认不透传相关头部：
- proxy_http_version 1.1：硬性要求，不能省略或设为 1.0
- proxy_set_header Upgrade $http_upgrade：用变量而非写死 "websocket"，兼容 MQTT、STOMP 等其他升级协议
- proxy_set_header Connection "upgrade"：注意是固定字符串 "upgrade"，不是 $connection_upgrade（后者在非升级请求时为空，会导致 Connection: close）
超时与缓冲必须调整
默认值专为短连接设计，会主动切断 WebSocket 长连接：
- proxy_read_timeout 至少设为 86400（24 小时），若后端每 30 秒发一次 ping，可设为 45，但绝不能 ≤30
- proxy_send_timeout 建议同步设为相同值，避免大消息分片中途被中断
- proxy_buffering off：禁用响应缓冲，防止多个 TEXT 帧被合并发送，造成延迟或粘包
- tcp_nodelay on：绕过 Nagle 算法，小数据（如光标移动、心跳）立即发出
HTTPS（wss）场景额外注意
当代理 wss:// 请求时，后端需要知道原始协议类型：
- 添加 proxy_set_header X-Forwarded-Proto $scheme，否则后端可能误生成 http 链接
- SSL 证书、listen 443 ssl 等基础 HTTPS 配置需已就绪
- wss 流量经 Nginx 解密后转为 ws 转发给后端，无需后端再处理 TLS
基于端口的 server 块别漏 Host 头
监听非标准端口（如 8080）时，server_name _ 虽能兜底，但后端若靠 Host 判断租户或路由就会失败：
- 务必保留 proxy_set_header Host $host
- location 中 proxy_pass 目标地址末尾斜杠要一致（如 /ws/ 对应 proxy_pass http://backend/ws/）
