Nginx 稳定代理 WebSocket 需透传 Upgrade 头、设超时为 86400 秒、关闭缓冲，路径精确匹配且 HTTPS 下启用 TLSv1.2+。

要让 Nginx 稳定代理 WebSocket 并实现超长连接保持，核心不是“开启开关”，而是精准匹配 WebSocket 的通信特性：协议升级必须透传、空闲连接不能被误杀、数据流不能被缓冲截断。

必须透传协议升级头

WebSocket 握手本质是 HTTP 升级请求，Nginx 默认会过滤 Upgrade 和 Connection 头，导致后端收不到升级信号，返回 200 而非 101，前端直接报错“Unexpected response code: 200”。

• proxy_http_version 1.1：强制使用 HTTP/1.1，这是 Upgrade 机制的前提
• proxy_set_header Upgrade $http_upgrade：把客户端原始的 Upgrade 头（如 websocket）原样转发
• proxy_set_header Connection "upgrade"：注意必须带英文双引号，且值为字面量 upgrade，不能写成 $http_connection 或漏引号

超时时间要远大于心跳间隔

WebSocket 空闲时不发数据，只靠心跳维持活跃。Nginx 默认 proxy_read_timeout=60 秒，只要 60 秒没收到后端数据，就会主动断连——这就是连接频繁中断的根源。

• proxy_read_timeout 86400：设为 24 小时，确保覆盖任意心跳周期（例如后端心跳 30 秒，此处至少设 60 秒以上）
• proxy_send_timeout 86400：防止向后端发送大消息或慢响应时被中断
• keepalive_timeout 86400：保持客户端到 Nginx 的连接存活，与上游超时对齐更稳妥

禁用缓冲并限定作用范围

WebSocket 是低延迟、流式双向通信，Nginx 默认开启的响应缓冲（proxy_buffering on）会导致消息堆积、延迟甚至乱序，尤其在推送密集场景下明显。

• proxy_buffering off：必须在具体 WebSocket location 块中关闭（如 /ws/），不可放在 http 全局块
• 可选加 proxy_buffer_size 16k 和 proxy_busy_buffers_size 32k，防止单次接收过大包阻塞连接
• 同时建议加 proxy_cache off，避免缓存干扰实时性

路径匹配与负载均衡注意事项

配置生效的前提是请求真正进入对应 location，且后端健康可用。

• WebSocket 路径（如 /ws/ 或 /api/ws）需用精确或前缀匹配，避免 rewrite 改写请求头或路径
• 若用 upstream，建议启用 keepalive 32（保持到后端的空闲连接数），并配 max_fails/fail_timeout 做基础健康检查
• HTTPS 下必须完整配置 SSL（证书、密钥、ssl_protocols TLSv1.2+），且仍需 proxy_http_version 1.1；HTTP/2 不支持 Upgrade，不能替代