Nginx代理WebSocket带Upgrade头完整配置

前言

WebSocket 长连接走 HTTP Upgrade 握手，普通反向代理默认不传 Upgrade/Connection 头，导致连接建立失败或几秒断开。需要在代理块显式设置握手头和超时。本文讲解完整代理配置、连接升级变量、超时和心跳保活。

操作步骤

1. 定义升级映射（http 块）

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

2. WebSocket 代理 location

location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

3. 后端地址示例

upstream backend {
    server 127.0.0.1:8080;
}

4. 校验并重载

nginx -t && nginx -s reload

5. 测试握手

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" https://域名/ws/

6. 心跳保活

proxy_read_timeout 设长，避免空闲连接被 Nginx 关闭。

常见坑

1. 缺 map，Connection 头写死 upgrade，普通请求被误升级。
2. proxy_http_version 不是 1.1，Upgrade 头不生效。
3. 没加长 read/send 超时，空闲连接几十秒后断开。
4. 后端用 ws://，代理层仍要带 Upgrade 头。
5. 多台后端会话不粘，长连接落到不同节点报错。
6. WSS（wss）要在 443 SSL 块内代理。
7. CDN 不支持 WebSocket 时直接连源站。

总结

WebSocket 代理三件套：map 生成 connection_upgrade、proxy_http_version 1.1、传 Upgrade/Connection 头，并拉长 read/send 超时。用 curl 带 Upgrade 头测试握手。多节点需会话粘滞，WSS 在 SSL 块内配置。

遇到问题加QQ23979811 协助处理