nginx 稳定维持分布式 websocket 游戏长连接需四点：一要透传 upgrade/connection 头并正确配置 proxy_http_version 1.1 和 map 指令；二要分层设置超时（proxy_read_timeout 至少 300s）并与后端严格对齐；三要通过 sticky cookie 或 hash 头实现会话强绑定，避免轮询漂移；四要关闭 buffering 和 gzip，适配小包、低延迟、顺序敏感的游戏数据流。
要在分布式 WebSocket 游戏中用 Nginx 稳定维持长连接，关键不是堆砌参数，而是让 Nginx 的每个基础机制都贴合游戏场景的真实链路特征：低延迟、高并发、会话强绑定、心跳稀疏但不可丢、客户端网络极不稳定（尤其是移动端锁屏/切后台）。下面从四个最直接影响线上表现的维度展开说明。
必须透传 Upgrade 与 Connection 头，且避免 header 冲突
游戏客户端发起 WebSocket 握手时，请求头中一定包含 Upgrade: websocket 和 Connection: Upgrade。Nginx 默认会过滤这两个头，导致后端收不到升级信号，返回 200 而非 101，前端直接报错 “Unexpected response code: 200”。
- 在对应 location 块中固定写死：proxy_http_version 1.1（HTTP/2 不支持 Upgrade，不能替代）
- proxy_set_header Upgrade $http_upgrade —— 动态转发原始值，不是硬编码 "websocket"
-
proxy_set_header Connection $connection_upgrade —— 配合 map 指令预处理更健壮：
map $http_upgrade $connection_upgrade { default upgrade; '' close; } - 禁用 proxy_cache_bypass $http_upgrade 或 proxy_cache off，防止缓存层干扰握手
超时设置要分层对齐，不能只调大 proxy_read_timeout
游戏连接空闲期可能长达数分钟（如观战、匹配等待），但心跳间隔通常为 15–30 秒。Nginx 默认 proxy_read_timeout=60，只要 60 秒没收到后端数据，就会主动断连——这是线上高频 1006 错误的主因。
- proxy_read_timeout 300（5 分钟）是常规起点；若支持离线重连或弱网观战，建议设为 1800（30 分钟）
- proxy_send_timeout 300 —— 防止向后端推送广播消息时因队列积压被中断
- keepalive_timeout 20 —— 仅控制握手阶段的初始连接空闲时间，设为略大于后端服务的 connection-timeout（如 Spring Boot 的 server.tomcat.connection-timeout=15s），避免 Nginx 先断
- 所有超时值必须与后端框架（如 Netty、Swoole）的读写超时、心跳检测周期严格对齐，否则会出现“一端已关、另一端还在等”
强制连接保持（stickiness），杜绝轮询漂移
游戏会话状态（角色位置、技能冷却、房间成员）基本都存在后端内存中。默认轮询会让一次 ping 帧路由到 A 节点，下一次 pong 路由到 B 节点，B 无上下文直接断连——这不是超时问题，是路由逻辑错误。
- ip_hash：适合内网直连或可信公网环境，配置最简，但不适用于 CDN、运营商 NAT 或移动端（大量用户 IP 相同）
- sticky cookie ws_route expires=1h path=/ws/：推荐生产使用。后端在握手成功响应中 Set-Cookie，Nginx 自动识别并绑定；兼容所有网络环境
- hash $upstream_http_x_game_node：高阶方案。后端在 Upgrade 响应头中注入 X-Game-Node: node-03，Nginx 提取并哈希到 upstream，适合需灰度/分服管理的大型游戏
- 同时启用 upstream keepalive 32，复用到后端的空闲连接，降低后端 TCP 创建压力
关闭缓冲与压缩，适配游戏数据流特性
WebSocket 在游戏中用于实时同步（位置帧、技能事件、语音信令），数据具有突发性、小包多、顺序敏感的特点。Nginx 默认开启的缓冲和压缩会引入不可控延迟甚至乱序。
- proxy_buffering off —— 必须放在具体 location 块内（如 /game/ws），不可全局关闭
- proxy_buffer_size 4k 和 proxy_busy_buffers_size 8k —— 防止单帧过大（如截图推送）阻塞连接
- gzip off 或至少 gzip_disable "msie6" —— 游戏客户端极少需要压缩，且压缩耗 CPU、增延迟
- 若使用 HTTPS，确保 ssl_protocols TLSv1.2 TLSv1.3，禁用 TLSv1.1 及以下；TLS 握手失败也会表现为连接闪断
