配置 WebSocket 代理

WebSocket 是一种通过单个 TCP 连接提供全双工通信通道的协议。API7 企业版可以代理 WebSocket 流量，让你管理客户端与上游服务之间的实时双向通信。

前置条件

• API7 企业版实例正在运行。
• 已创建网关组且网关实例正在运行。
• 一个 Dashboard Token。

启动 WebSocket 示例服务器

启动一个支持 WebSocket 的示例上游服务器：

docker run -d \
  --name websocket-server \
  -p 8080:8080 \
  jmalloc/echo-server

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

以下示例假设网关可以通过 host.docker.internal 访问 Docker 主机。如果环境使用其他主机地址，请替换 host.docker.internal。

在路由上启用 WebSocket

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

为 WebSocket 配置路由

创建或更新路由，并将 enable_websocket 字段设置为 true。

Admin API

# 1. 为 WebSocket 上游创建服务
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": "host.docker.internal",
          "port": 8080,
          "weight": 1
        }
      ]
    }
  }'

# 2. 为该服务创建路由
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
  }'

ADC

adc.yaml

services:
  - name: websocket-service
    upstream:
      nodes:
        - host: host.docker.internal
          port: 8080
          weight: 1
    routes:
      - name: websocket-route
        uris:
          - /.ws
        enable_websocket: true

adc sync -f adc.yaml

验证配置

可以使用 wscat 或 curl 等工具测试 WebSocket 连接。

使用 wscat

通过 npm 安装 wscat：

npm install -g wscat

然后连接 WebSocket 路由：

wscat -c ws://localhost:9080/.ws

如果连接成功，可以发送 hello 并收到回显响应。

在本地验证环境中，Admin API 示例通过 http://127.0.0.1:9080/.ws 返回了 101 Switching Protocols。

使用 curl

也可以使用 curl 并提供所需的升级请求头，测试初始握手：

curl -i -N -H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Host: localhost" \
-H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
-H "Sec-WebSocket-Version: 13" \
http://localhost:9080/.ws

握手成功会返回 HTTP/1.1 101 Switching Protocols 响应。

后续步骤

• 配置 gRPC 代理——了解如何处理 gRPC 流量和转码。
• 配置 GraphQL 代理——探索感知 GraphQL 的流量管理。