要让 Nginx 稳定代理 WebSocket，核心是贴合其全双工、长连接、依赖心跳的本质：需透传 Upgrade 头（proxy_http_version 1.1、Upgrade 和 Connection）、关闭缓冲与缓存、禁用 Nagle 算法，并将 read/send/keepalive 超时设为远大于心跳间隔（如 86400 秒），同时确保 location 精确匹配及系统资源充足。
要让 Nginx 稳定代理 WebSocket，核心不是加几行配置，而是让每个环节贴合 WebSocket 的通信本质：它不是请求-响应式短连接，而是全双工、长生命周期、依赖心跳维持的 TCP 连接。Nginx 默认按 HTTP 模式处理，稍有不匹配就会静默断连或握手失败。
透传协议升级头，确保 101 握手成功
WebSocket 握手是 HTTP 升级过程，必须原样传递两个逐跳头，否则后端收不到升级信号，返回 200 而非 101：
- proxy_http_version 1.1; —— HTTP/1.0 不支持 Upgrade，缺了这句握手直接失败
- proxy_set_header Upgrade $http_upgrade; —— 用变量转发原始值（如 websocket、mqtt），兼容多种升级场景
- proxy_set_header Connection "upgrade"; —— 必须是带英文双引号的字面量 upgrade，不能写成 $http_connection（可能含 keep-alive，会覆盖升级意图）
关闭干扰行为，避免帧流被截断
WebSocket 数据以帧（frame）形式实时双向流动，Nginx 默认缓冲和超时机制会破坏这种流式特性：
- proxy_buffering off; —— 防止多个 TEXT/BINARY 帧被缓存合并，造成粘包或延迟
- proxy_cache off; —— 显式禁用缓存，避免 Upgrade 请求被缓存命中返回 200
- tcp_nodelay on; —— 绕过 Nagle 算法，小帧（如游戏光标、聊天消息）立即送达
超时设置需远大于心跳间隔
空闲不等于断开。WebSocket 依赖后端定时发送 ping/pong 维持活跃，Nginx 若按默认 60 秒超时判断，会主动杀掉“安静”的连接：
- proxy_read_timeout 86400; —— 设为 24 小时，确保覆盖任意心跳周期（例如后端心跳 30 秒，此处至少设为 60 秒以上）
- proxy_send_timeout 86400; —— 避免向后端推送大数据分片或慢响应时被中断
- keepalive_timeout 86400; —— 保持客户端到 Nginx 的连接存活，与上游超时对齐更稳妥
路径匹配与系统资源协同调优
配置生效的前提是请求真正进入对应 location，且底层资源足够支撑大量长连接：
- location 使用精确匹配（= /ws）或前缀匹配（/ws/），避免 rewrite 改写路径或 header
- worker_connections 至少设为 65535，配合 worker_rlimit_nofile 1048576 和系统级文件描述符扩容
- HTTPS 下必须启用 TLSv1.2+，且 proxy_http_version 1.1 不可省略（HTTP/2 不支持 Upgrade）
