Nginx代理Socket.IO需透传WebSocket升级头并保障长连接：必须配置proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"，路径精确匹配/socket.io/，集群部署需ip_hash+socket.io-redis。
要让 Nginx 正确代理基于 Socket.IO 的实时应用，核心是解决两个问题：一是支持 WebSocket 协议升级，二是保障长连接不被意外中断。Socket.IO 在建立连接时会先走 HTTP 轮询（polling），再升级到 WebSocket（transport=websocket），Nginx 必须透传升级头、维持连接，并兼容这种多阶段握手机制。
基础 WebSocket 代理配置
这是最常用、也最必要的配置块，适用于单实例部署：
- 确保 Nginx 版本 ≥ 1.3.13（推荐 ≥ 1.18），否则无法正确处理 Upgrade 流程
- 在 location /socket.io/ 或 location / 块中添加以下关键指令：
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_pass http://backend_socketio;
其中 backend_socketio 是 upstream 定义的后端服务，例如：
upstream backend_socketio {
server 127.0.0.1:3000;
}
注意：/socket.io/ 路径必须与客户端初始化时的 path 一致（默认就是 /socket.io/），否则升级请求无法命中该 location。
跨域与安全头补充
生产环境通常需配合 HTTPS 和跨域访问，建议补充以下头信息：
- proxy_set_header Host $host; —— 保证后端能正确识别原始域名
- proxy_set_header X-Real-IP $remote_addr; 和 X-Forwarded-For $proxy_add_x_forwarded_for; —— 传递真实客户端 IP，便于日志和风控
- 若前端部署在不同域名（如 https://app.example.com），后端无需额外设 CORS；Socket.IO 不依赖 Access-Control-Allow-Origin，但需服务端校验 Origin 字段（由业务逻辑控制）
负载均衡下的集群部署要点
当扩展为多个 Socket.IO 实例时，必须解决“连接粘性”和“消息广播”问题：
- 用 ip_hash 保证同一客户端始终路由到同一节点（避免 polling 请求跳节点导致 session 断开）：
upstream chat_nodes {
ip_hash;
server 127.0.0.1:4000;
server 127.0.0.1:5000;
} - 仅靠 Nginx 不足以实现跨节点广播，必须搭配 socket.io-redis 适配器，将房间、事件等状态存入 Redis，使各实例可协同响应
- 超时设置建议显式调大：
proxy_read_timeout 60;
proxy_send_timeout 60;（默认 60 秒已够用，但低活跃场景可设为 300）
常见失败现象与对应检查点
若出现连接失败、频繁重连或 502/504 错误，可按顺序排查：
- 浏览器控制台是否显示 “WebSocket is closed before the connection is established”？→ 检查 Upgrade 和 Connection 头是否被 Nginx 或中间设备（如 CDN、WAF）清除
- 是否只在 polling 阶段成功，但无法升级到 websocket？→ 确认 Nginx 版本、location 是否精确匹配 /socket.io/，且没有其他 rewrite 规则干扰
- 集群中部分用户收不到消息？→ 检查 socket.io-redis 是否启用，Redis 连接是否正常，各实例 adapter 配置是否一致
- Nginx 日志中出现 “upstream prematurely closed connection”？→ 后端进程崩溃或未正确处理 upgrade，检查 Node.js 服务日志
