跳到主要内容
版本：3.10.x

配置 WebSocket 代理

WebSocket 通过单个 TCP 连接提供持久的双向通信。它常用于实时数据源、聊天、协作应用，以及其他实时交换数据的工作负载。

API7 企业版可以代理初始 HTTP 升级请求，并保持由此建立的 WebSocket 连接。本指南将配置指向 WebSocket 上游的路由，并验证通过网关的双向流量。

前置条件​

  • API7 企业版实例正在运行。
  • 已创建网关组且网关实例正在运行。
  • 按照从控制台获取 Token中的步骤准备一个 Token。
  • 已在运行示例上游的环境中安装 Docker。
  • 已在用于验证的客户端上安装 websocat。
  • 如果使用 ADC 配置，请确保 ADC 已安装并连接到目标网关组。

启动 WebSocket 示例服务器​

将 GATEWAY_CONTAINER 设置为正在运行的 API7 网关容器。创建专用网络，并将网关连接到该网络：

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network create gateway-websocket-net
docker network connect gateway-websocket-net "$GATEWAY_CONTAINER"

在共享网络中启动固定版本的 WebSocket 示例服务器：

docker run -d \
  --name websocket-server \
  --network gateway-websocket-net \
  jmalloc/echo-server:v0.3.7

服务器在 /.ws 公开 WebSocket 端点，并回显收到的所有消息。

对于非 Docker 部署的网关，请在网关可访问的位置运行示例服务器，并在上游配置中将 websocket-server 替换为该地址。

在路由上启用 WebSocket​

WebSocket 代理按路由启用。将 enable_websocket 设置为 true 后，网关会处理初始 HTTP Upgrade 握手并维持连接。

为示例上游创建服务，并创建将 enable_websocket 设置为 true 的路由：

对于 Admin API 配置，请导出控制台 Token，并将 {gateway_group_id} 替换为目标网关组 ID。快速入门创建的网关组使用 default。

export API_KEY=replace-with-dashboard-token

创建服务：

curl -k "https://localhost:7443/apisix/admin/services/websocket-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "websocket-service",
    "upstream": {
      "type": "roundrobin",
      "nodes": [
        {
          "host": "websocket-server",
          "port": 8080,
          "weight": 1
        }
      ]
    }
  }'

创建路由：

curl -k "https://localhost:7443/apisix/admin/routes/websocket-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "websocket-route",
    "paths": ["/.ws"],
    "service_id": "websocket-service",
    "enable_websocket": true
  }'

验证连接​

通过 API7 网关建立连接：

websocat "ws://127.0.0.1:9080/.ws"

发送 hello。服务器应回显该消息：

Request served by <container-id>
hello
hello

成功建立连接并收到回显消息，表明网关已完成协议升级，并在两个方向上代理流量。

后续步骤​

WebSocket 流量可以使用应用于 HTTP 升级请求的相同身份认证、流量管理和可观测性功能。