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 或证书:

nginx
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 是为了示例可复现,不宣称它是最新版本:

bash
# 只向当前实验目录的虚拟环境安装依赖。
python3 -m venv .venv
.venv/bin/python -m pip install 'websockets==15.0.1'

预期结果:依赖安装成功;安装日志受环境影响。把下列完整程序保存为 ws_server.py,执行 .venv/bin/python ws_server.py:

python
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:

python
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())

预期输出:

text
echo:ping

如握手失败,先直连 ws://127.0.0.1:9000/chat/ 确认后端可用,再检查路径、上游版本和两个升级头。连接成功后空闲断开,则检查上游读取间隔与心跳;本例后端每 20 秒发送协议 Ping,低于 75 秒读取空闲阈值。客户端还应处理网络中断与重连,75 秒不是整条连接的最长寿命。

公网 HTTPS 页面通常需要可信证书下的 wss:// 入口,并检查 Origin 和权限;本机明文实验只验证代理升级与消息通路,不表示已完成外网安全部署。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

WebSocket 为什么需要额外配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通