Web 服务器与网关 / 系统课时
代理 WebSocket 连接
代理 WebSocket 连接
本课解决 Nginx 作为反向代理时 WebSocket 无法升级、连接建立后立即断开的问题。通过配置必要的 HTTP 升级请求头和合理的超时参数,可以让客户端与后端服务保持稳定的双向通信。
学习目标
- 理解 WebSocket 与普通 HTTP 请求在代理阶段的差异。
- 配置 Nginx 支持 WebSocket 协议升级。
- 使用日志和参数定位连接断开问题。
WebSocket 代理的核心机制
WebSocket 建立连接时首先发送 HTTP Upgrade 请求,客户端希望将普通 HTTP 连接转换为长连接通信。Nginx 默认代理 HTTP 请求时不会自动转发升级相关请求头,因此需要显式配置。
关键请求头包括 Upgrade 和 Connection。前者声明协议升级目标,后者告诉代理链路保持升级意图,否则后端服务可能收到普通 HTTP 请求并拒绝切换协议。
配置 Nginx 转发 WebSocket
以下是一个完整的站点代理示例,假设 WebSocket 服务监听本机 <PORT> 端口。
nginx
server {
listen 80;
server_name example.com;
location /socket/ {
proxy_pass http://127.0.0.1:<PORT>;
# 转发协议升级信息,让后端完成 WebSocket 握手
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 长连接需要更长的空闲保持时间
proxy_read_timeout 300s;
proxy_send_timeout 300s;
}
}预期结果
text
Nginx reload succeeds.
WebSocket client receives HTTP 101 Switching Protocols.
Connection remains open for bidirectional messages.配置生效后,客户端发起 WebSocket 握手时,Nginx 会转发升级请求。后端返回 101 Switching Protocols 后,连接进入双向通信状态。
验证连接是否成功
可以通过客户端工具或应用日志验证握手结果。重点观察 HTTP 状态码和后续消息是否能够双向传输。
bash
curl -i -N \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
http://example.com/socket/预期输出
text
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: upgrade实际测试中,普通 curl 不会完成完整 WebSocket 会话,但可以用于确认升级响应是否到达。
排查连接立即断开
如果握手成功但连接马上关闭,通常不是 Upgrade 配置问题,而是长连接生命周期管理异常。优先检查以下方向:
proxy_read_timeout是否小于业务心跳间隔。- 后端 WebSocket 服务是否主动关闭空闲连接。
- Nginx error.log 是否存在 upstream reset 或 timeout 信息。
如果经过代理后只有第一次消息成功,需要确认后端应用是否依赖特定路径、Host 或认证头信息,避免代理修改请求导致业务关闭连接。
按自己的节奏,确认真正理解。