一、HTTP 协议升级机制回顾
-
Upgrade/Connection 报头
- 客户端发起 WebSocket 握手时，会在普通 HTTP 请求中加入
Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: <随机值> Sec-WebSocket-Version: 13 - 服务端若接受协议切换，会以
101 Switching Protocols响应，并同样返回Upgrade和Connection报头。
- 客户端发起 WebSocket 握手时，会在普通 HTTP 请求中加入
-
Hop-by-Hop 报头限制
HTTP/1.1 中，Upgrade与Connection都属于 Hop-by-Hop 报头，只能在相邻节点间生效，不会被普通反向代理转发。因此，需要在 Nginx 明确地把这两者从客户端请求里取出，并再设置到转发给后端的请求头中。
二、Nginx 代理 WebSocket 的关键配置
1. 基本示例
location /chat/ {# 将请求转发到后端 WebSocket 服务proxy_pass http://backend;# 使用 HTTP/1.1 协议，以支持 Upgradeproxy_http_version 1.1;# 将客户端请求中的 Upgrade 与 Connection 头转发给后端proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "upgrade";
}
- proxy_http_version 1.1
强制使用 HTTP/1.1，否则默认的 HTTP/1.0 无法支持协议升级。 - proxy_set_header Upgrade $http_upgrade
将客户端传来的Upgrade: websocket透传给后端。 - proxy_set_header Connection “upgrade”
明确指定与Upgrade配合使用。
2. 智能化 Connection 设置
在某些场景下，希望仅在真有升级需求时才发 "upgrade"，否则保持连接关闭。可借助 Nginx 的 map 模块：
# 将是否存在 Upgrade 头映射成变量
map $http_upgrade $connection_upgrade {default upgrade;'' close;
}server {...location /chat/ {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection $connection_upgrade;}
}
- 如果客户端请求里没有
Upgrade，则向后端发送Connection: close，更符合一般 HTTP 请求的语义。
三、超时与心跳优化
默认情况下，Nginx 在代理 WebSocket 连接时，如果后端在 60 秒内没有任何数据回传，会主动关闭连接。这对于长时间空闲但后续可能仍要推送消息的场景并不友好。常用的优化方案有两种：
-
延长 Nginx 的
proxy_read_timeout
在location或http、server级别添加：proxy_read_timeout 3600s; # 将超时时间提升到 1 小时 -
后端发送 WebSocket Ping
让后端应用周期性地向客户端（经过 Nginx）发送 Ping 帧，触发 Nginx 读取数据，从而重置超时计时器，同时还能检测连接健康状态。
四、完整示例
http {map $http_upgrade $connection_upgrade {default upgrade;'' close;}upstream backend {server 127.0.0.1:8080; # 后端 WebSocket 服务地址# 可根据实际情况添加多台服务器，实现负载均衡}server {listen 80;server_name example.com;# 静态资源处理（可选）location /static/ {root /var/www/html;}# WebSocket 代理入口location /chat/ {proxy_pass http://backend;proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection $connection_upgrade;# 转发客户端真实 IP（可选）proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;# 超时配置proxy_read_timeout 3600s;proxy_send_timeout 3600s;}}
}
五、实践要点与注意事项
- HTTPS + WSS
若在前端使用wss://（即 TLS 加密的 WebSocket），必须在 Nginx 上配置对应的 SSL 证书，并在server块中使用ssl_certificate、ssl_certificate_key等指令。 - 负载均衡与 Sticky Session
对于需要在多实例间保持会话一致性的业务，可考虑基于 Cookie 或 IP 哈希的 Sticky Session 配置，或者将业务设计成无状态。 - 安全加固
可以在 Nginx 中加入limit_conn、limit_req等限流指令，防止恶意连接耗尽资源；也可结合lua-nginx-module实现更复杂的鉴权或动态路由。
六、总结
通过上述方式，Nginx 能够高效、稳定地将客户端的 HTTP 升级请求（Upgrade）转发到后端 WebSocket 服务，实现反向代理与负载均衡。在此基础上，再配合合理的超时调整、心跳检测与安全限流，即可构建面向生产环境的高可用、可扩展的实时通信平台。希望本文能帮助你快速上手 Nginx WebSocket 代理，并打造符合业务需求的实时架构。
