跳转到主要内容

​
协议概述

wss://scraping-api.55-tech.com/ws 上的 WebSocket 中继提供双向代理功能。您连接到网关，发送一条 JSON 连接消息，网关通过地理分布式代理节点在您和目标之间中继所有帧。 
Client ←→ Gateway (wss://.../ws) ←→ Agent ←→ Target WebSocket

​
交��式测试页面

/ws/docs 端点返回协议格式： 
curl https://scraping-api.55-tech.com/ws/docs

{
  "type": "connected",
  "status": 101,
  "node_id": "scraping-de1",
  "message": "This is a documentation endpoint. Connect via WebSocket at wss://scraping-api.55-tech.com/ws"
}
要进行交互式 WebSocket 测试，请使用 wscat： 
npm install -g wscat
wscat -c wss://scraping-api.55-tech.com/ws
然后粘贴： 
{"apiKey":"YOUR_API_KEY","url":"wss://echo.websocket.events"}

​
连接消息（客户端 → 网关）

必须在连接后 10 秒内以 JSON 文本形式发送。 
{
  "apiKey": "YOUR_API_KEY",
  "url": "wss://target.example.com/stream",
  "headers": {
    "Authorization": "Bearer token",
    "Origin": "https://target.example.com"
  },
  "cookies": {
    "session": "abc123"
  },
  "geo": "US,DE",
  "agent": "de1",
  "idle_timeout": 0
}

​
字段说明

FieldTypeRequiredDefaultDescription
apiKeystringYes—用于身份验证的 API 密钥。也接受 key。
urlstringYes—目标 WebSocket URL（wss://... 或 ws://...）
headersobjectNo{}随 WS 升级请求发送到目标的自定义请求头。适用于目标期望的 Authorization、Origin、Cookie 等请求头。
cookiesobjectNo{}随 WS 升级请求发送的 Cookie。会合并到 Cookie 请求头中。
geostringNo—将代理节点选择限制到特定国家。逗号分隔的 ISO 代码（例如 US,DE,AT）。
agentstringNo—通过标识固定到特定代理节点（例如 de1），或逗号分隔进行随机选择（de1,at5,us3）。
idle_timeoutfloatNo0如果 > 0，在指定秒数内未收到目标消息后断开连接。0 = 不超时。

​
响应消息（网关 → 客户端）

​
Connected

代理节点成功连接到目标 WebSocket 后发送一次。 
{
  "type": "connected",
  "status": 101,
  "node_id": "scraping-de1"
}
FieldTypeDescription
typestring始终为 "connected"
statusintWS 升级的 HTTP 状态码。101 = 成功。
node_idstring处理中继的代理节点（例如 scraping-de1）

​
Error

连接失败或发生错误时发送。此消息发送后 WebSocket 将关闭。 
{
  "type": "error",
  "message": "Invalid or missing API key"
}
FieldTypeDescription
typestring始终为 "error"
messagestring人类可读的错误描述

​
中继帧

在 connected 消息之后，所有后续帧均为原始中继 — 无 JSON 包装。文本帧保持为文本，二进制帧保持为二进制。

​
关闭代码

CodeMeaning
1000正常关闭（您或目标关闭了连接）
1008策略违规 — API 密钥无效、速率限制或连接超时
1011内部错误 — 代理节点故障或目标不可达

​
错误场景

ScenarioWhat happens
10 秒内未发送连接消息网关以代码 1008 关闭
API 密钥无效网关发送错误 JSON，以 1008 关闭
超出速率限制网关发送错误 JSON，以 1008 关闭
目标拒绝连接网关发送错误 JSON，以 1011 关闭
无可用代理节点网关发送错误 JSON，以 1011 关闭
目标关闭连接网关转发关闭帧，包含目标的代码和原因
客户端关闭连接网关将关闭转发到目标，清理资源
代理节点在中继过程中崩溃网关以 1011 关闭

​
帧流程图

​
速率限制

WebSocket 连接在连接时（连接消息验证通过后）从您的速率限制桶中消耗 1 个令牌。后续帧不消耗令牌。如果您的桶为空，网关会发送错误并以 1008 关闭连接。

​
使用 wscat 测试

# Install
npm install -g wscat

# Connect
wscat -c wss://scraping-api.55-tech.com/ws

# Paste connect message:
{"apiKey":"YOUR_KEY","url":"wss://echo.websocket.events"}

# After "connected" response, type messages to relay:
hello world

# The echo server will send back your message

​
使用 Python 测试

import asyncio
import json
import websockets

async def test():
    async with websockets.connect("wss://scraping-api.55-tech.com/ws") as ws:
        await ws.send(json.dumps({
            "apiKey": "YOUR_API_KEY",
            "url": "wss://echo.websocket.events",
        }))

        resp = json.loads(await ws.recv())
        print(f"Status: {resp}")

        if resp["type"] == "connected":
            await ws.send("test message")
            reply = await ws.recv()
            print(f"Echo: {reply}")

asyncio.run(test())