配置 Nginx 代理 WebSocket

与反向代理的配置语法类似

  1. 确保 Nginx 支持 ws, 确保客户端与服务端代码可用.
  2. 配置反向代理.
  3. 重启 nginx.

官方文档有单独的一节介绍配置.

配置语法

http {
  # 其他配置...

  server {
    listen 80;
    server_name example.com; # 替换为你的域名

    location /ws {
      proxy_pass http://localhost:8080/ws; # 后端WebSocket服务地址
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_set_header Host $host;
      proxy_cache_bypass $http_upgrade;
    }

    # 其他location配置...
  }
}

说明:

  • proxy_pass 表示代理的服务端地址
  • proxy_set_header 转发给服务端的 请求头 (必须)
    • Upgrade $http_upgrade. WebSocket 发起连接时会带有 Upgrade websocket 请求头, 来通知服务器升级协议.
    • Connection "upgrade". 表示要求后端升级连接.
  • proxy_cache_bypass $http_upgrade 设置 Nginx 绕过缓存. $http_upgrade 变量存储 Upgrade 头的值, 即 websocket, 表示 Nginx 在检查到该头部时, 不进行数据缓存, 直接发向服务端. ws 是实时通信, 不应该有缓存.

如果是配置 vite, 需要在 proxy 中设置 ws: true

WebSocket 发起连接流程

基本步骤分为几个阶段

  1. 客户端发起连接
  2. 服务端响应
  3. 握手完成
  4. 数据传输
  5. 关闭连接

详细步骤

1. 客户端发起连接

客户端发起连接 (HTTP Upgrade Request), 例如:

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: http://example.com
Sec-WebSocket-Version: 13

客户端发起一个特殊的 GET 请求, 带上指定 请求头, 向服务器请求升级到 WebSocket 协议.

  • Upgrade: websocket, 指明需要升级协议到 WebSocket. Upgrade 头专门用于请求升级协议.

  • Connection, 指令连接是否通信完成后立即关闭.

  • Sec-WebSocket-Key, 由客户端生成的随机值, 用于创建握手过程中的安全秘钥.

  • Sec-WebSocket-Version, 客户端支持的 WebSocket 版本, 通常是 13 (标准版本).

  • Origin, 一般用于校验源 URL.

关于 Upgrade, HTTP/2 禁用该机制, 该机制只用于 HTTP/1.1 中.

2. 服务端响应

服务器在接收到升级协议的请求后, 如果一切顺利, 会返回 101 状态码, 告知客户端协议切换:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

其中 Sec-WebSocket-Accept 是基于 客户端 Sec-WebSocket-Key 生成的.

3. 握手完成

客户端收到 101 响应后, 验证 Sec-WebSocket-Accept 成功后, 表示握手完成. 可以开始进行通信.

4. 数据传输

可以进行文本, 二进制等信息的传输.

数据通信以帧为单位. 包含文本帧 (Text Frame), 二进制帧 (Binary Frame), 以及控制帧 (Control Frame)

5. 关闭连接

关闭帧, 当一方希望关闭时, 发送控制帧, 来关闭连接.

如果一切正常, 双方在接收到关闭帧后, 发送确认关闭帧, 然后关闭连接.

如果网络异常等, 关闭连接, 不会有正常关闭流程.

Last Updated:
Contributors: jk