Nginx反向代理WebSocket长连接超时配置

前言

用 Nginx 反向代理 WebSocket 服务时，经常出现连接建立几十秒后自动断开、前端报 1006、长连接被中断的问题。原因是 Nginx 默认把 HTTP 连接当成短连接，缺少 WebSocket 升级头和长连接超时参数。本文给出完整的 WebSocket 反代配置，包含 Upgrade 头、Connection 映射、读写超时，并说明轮询与 wss（加密）场景。

操作步骤

1. 后端 WebSocket 服务示例（端口 8080）

先确认后端 ws 服务正常监听。

2. 在 http 块定义长连接映射（可选推荐）

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

3. WebSocket 反代 server 块

server {
    listen 80;
    server_name ws.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

4. wss（HTTPS）WebSocket

server {
    listen 443 ssl;
    server_name ws.example.com;
    ssl_certificate /www/ssl/ws.crt;
    ssl_certificate_key /www/ssl/ws.key;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

5. 校验并重载

nginx -t
nginx -s reload

6. 验证长连接

用 wscat 或前端页面连接，保持空闲超过默认 60 秒不断开即成功。

常见坑

1. 漏写 Upgrade 和 Connection 头，握手失败，连接无法升级为 WebSocket。
2. 没有 map，Connection 写死 upgrade，普通 HTTP 请求也被强制升级。
3. proxy_read_timeout 默认 60 秒，空闲连接被 Nginx 主动断开，要调大。
4. 后端服务本身有心跳超时，两端超时不一致仍会断。
5. 经过多层代理（CDN、网关），中间层也需要支持长连接和 WebSocket。
6. HTTPS 下前端必须用 wss，混用 ws 会被浏览器拦截。
7. 多 location 复用代理配置时，超时参数要在需要的块里单独设置。

总结

WebSocket 反代三要素：proxy_http_version 1.1、Upgrade/Connection 升级头、调大 proxy_read_timeout。用 map 区分升级与关闭，避免误伤普通请求。配置后用长连接压测观察是否在空闲后断开，同时检查后端心跳与中间代理链路。

遇到问题加QQ23979811 协助处理