Web 服务器与网关 / 系统课时
WebSocket 为什么需要额外配置
WebSocket 为什么需要额外配置
普通 HTTP 代理可用,WebSocket 却可能握手失败,因为协议升级所需的逐跳请求头不会自动按原样转发。本篇配置 HTTP/1.1 升级链路,再用真实回显客户端验证连接和消息,而不只检查一个 101 状态码。
学习目标
- 解释 Upgrade 和 Connection 请求头在反向代理中的作用。
- 配置 Nginx 1.28 可用的 WebSocket 转发与空闲超时。
- 验证握手后的消息收发,并区分握手失败和空闲断开。
握手成功后连接承担新协议
本篇讨论常见的 HTTP/1.1 WebSocket 升级。客户端请求带有 Upgrade,后端接受后返回 101;Nginx 才在两侧之间建立升级后的数据通道。Upgrade 和 Connection 属于逐跳字段,普通代理不会简单照抄,因此需要显式设置。

101 只表示协议升级被接受,不保证应用鉴权、订阅或后续消息处理都正常。若后端返回 400 或 403,应先检查它拒绝握手的原因,不要强行把状态码改成 101。
配置升级头和上游协议
下面是放入 http 上下文的片段示例,包含 map 与 server;map 不能放进 location。后端在本机 9000,入口用 8080,因此不依赖公网 DNS 或证书:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 127.0.0.1:8080;
server_name ws.test;
location /chat/ {
proxy_pass http://127.0.0.1:9000;
# 1.28 默认代理 HTTP/1.0,显式启用升级所需的 HTTP/1.1。
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 75s;
}
}这里无 URI 的 proxy_pass 保留 /chat/。map 在没有 Upgrade 时给出 close,避免把普通 HTTP 请求一律标成升级。本例显式设置 1.1,可用于 1.28;Nginx 从 1.29.7 起改变了上游默认 HTTP 版本,升级配置仍应结合实际版本检查。官方 WebSocket 文档说明了这些代理要求。
启动真实回显后端
使用 Linux Python 3.10 以上及 venv、pip,在独立实验目录执行以下命令;固定 websockets 15.0.1 是为了示例可复现,不宣称它是最新版本:
# 只向当前实验目录的虚拟环境安装依赖。
python3 -m venv .venv
.venv/bin/python -m pip install 'websockets==15.0.1'预期结果:依赖安装成功;安装日志受环境影响。把下列完整程序保存为 ws_server.py,执行 .venv/bin/python ws_server.py:
import asyncio
from websockets.asyncio.server import serve
async def echo(connection):
# 连续处理消息,而不是只读一条就结束处理函数。
async for message in connection:
await connection.send("echo:" + message)
async def main():
async with serve(echo, "127.0.0.1", 9000, ping_interval=20) as server:
await server.serve_forever()
if __name__ == "__main__":
asyncio.run(main())预期结果:服务保持运行,接受 WebSocket 连接;收到文本 ping 时发送文本 echo:ping。协议帧与握手由库负责,文本 ping 与协议 Ping 帧是两回事。本例采用该库公开的 asyncio 服务接口,生产服务还需按业务加入鉴权与消息限制。
发送消息并检查连接结果
检查并重载 Nginx 后,把以下完整客户端保存为 ws_client.py,用同一虚拟环境执行 .venv/bin/python ws_client.py。本机入口只有该实验站点时,客户端可直接使用回环 URL:
import asyncio
from websockets.asyncio.client import connect
async def main():
# 禁用环境中的正向代理,实验连接明确走本机 Nginx。
async with connect("ws://127.0.0.1:8080/chat/", proxy=None) as connection:
await connection.send("ping")
print(await asyncio.wait_for(connection.recv(), timeout=3))
if __name__ == "__main__":
asyncio.run(main())预期输出:
echo:ping如握手失败,先直连 ws://127.0.0.1:9000/chat/ 确认后端可用,再检查路径、上游版本和两个升级头。连接成功后空闲断开,则检查上游读取间隔与心跳;本例后端每 20 秒发送协议 Ping,低于 75 秒读取空闲阈值。客户端还应处理网络中断与重连,75 秒不是整条连接的最长寿命。
公网 HTTPS 页面通常需要可信证书下的 wss:// 入口,并检查 Origin 和权限;本机明文实验只验证代理升级与消息通路,不表示已完成外网安全部署。