WebSocket 管理后台

概述

这是一个部署在 Cloudflare Workers 上的多项目隔离 WebSocket 服务器，支持 WebSocket、SSE（Server-Sent Events）和 Long Polling 三种传输方式。

管理 API

认证方式: 所有管理 API 需要在请求头中携带 Admin Token：

Authorization: Bearer <admin-token>

创建项目

POST /project
{"key": "myproject", "name": "我的项目"}

生成令牌

POST /token
{"projectKey": "myproject"}

列出项目

GET /project

删除项目

DELETE /project?key=myproject

删除令牌

DELETE /token?projectKey=myproject&token=xxx

修改令牌到期时间

PATCH /token
{"projectKey": "myproject", "token": "xxx", "expiresAt": 1719470400000}

连接方式

所有连接方式都需要携带 project、token 和 mode 参数。

WebSocket

wss://scws.ccwu.cc/ws?project=myproject&token=xxx&mode=long

SSE

https://scws.ccwu.cc/sse?project=myproject&token=xxx&mode=long

Long Polling

https://scws.ccwu.cc/poll?project=myproject&token=xxx&mode=long

消息协议

绑定 UID

{"type": "bind", "uid": "user_1"}

广播消息

{"type": "broadcast", "msg": "Hello World"}

一对一消息

{"type": "send", "to": "user_2", "msg": "你好"}
// 或使用别名: {"type": "unicast", "to": "user_2", "msg": "你好"}

群发消息

{"type": "multicast", "to": ["user_2", "user_3"], "msg": "大家好"}

获取在线列表

{"type": "list"}

查询用户在线状态

{"type": "online", "uid": "user_1"}
// 返回: {"type": "online_result", "uid": "user_1", "online": true}

服务器返回消息类型

所有连接（WebSocket/SSE/Polling）建立后，服务器会返回以下消息：

连接成功

{"type": "connected", "connId": "xxx"}

绑定成功

{"type": "bind_success", "uid": "user_1"}

一对一消息（收到）

{"type": "direct", "from": "user_1", "to": "user_2", "msg": "你好", "timestamp": 1234567890}

广播消息（收到）

{"type": "broadcast", "msg": "大家好", "timestamp": 1234567890}

发送成功（仅发送方收到）

{"type": "send_success", "to": "user_2"}
// 离线消息: {"type": "send_success", "to": "user_2", "offline": true}
// 群发: {"type": "send_success", "to": ["user_2", "user_3"], "offline": ["user_4"]}

查询在线结果

{"type": "online_result", "uid": "user_1", "online": true}

在线用户列表

{"type": "list", "uids": ["user_1", "user_2"]}

用户上线通知

{"type": "online", "uid": "user_1", "timestamp": 1234567890}

用户下线通知

{"type": "offline", "uid": "user_1", "timestamp": 1234567890}

心跳（长连接模式）

{"type": "ping"}

客户端需回复：{"type": "pong"}

错误消息

{"type": "error", "msg": "Unknown message type"}

离线消息

一对一消息和群发消息支持离线存储：

• 当目标用户不在线时，消息会自动存入 KV
• 消息存储时间：3天（自动过期）
• 用户上线后自动接收离线消息

连接模式

• short: 短连接模式，无服务端心跳（默认）
• long: 长连接模式，服务端每 15 秒发送一次 ping 消息

传输降级策略

WebSocket → SSE → Long Polling

跨域支持 (CORS)

所有 API 和连接端点均支持跨域请求：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

项目隔离说明

每个项目使用独立的 Durable Object 实例，不同项目的连接互不干扰，广播消息只在项目内部传播。

WebRTC 支持

服务器可作为 WebRTC 信令服务器，用于交换 SDP 和 ICE Candidates，支持视频通话和纯语音通话。

通话模式

• 视频通话: 同时传输视频和音频，需要摄像头和麦克风权限
• 语音通话: 仅传输音频，只需要麦克风权限

房间管理

// 创建房间（自动生成ID）
{"type": "room_create", "roomId": "room_123"}
// 返回: {"type": "room_created", "roomId": "xxx"}

// 加入房间（需先绑定UID）
{"type": "room_join", "roomId": "room_123"}
// 返回: {"type": "room_joined", "roomId": "xxx", "users": ["user1", "user2"]}

// 离开房间
{"type": "room_leave", "roomId": "room_123"}
// 返回: {"type": "room_left", "roomId": "xxx"}

// 查询房间列表
{"type": "room_list"}
// 返回: {"type": "room_list_result", "rooms": ["room_123", "room_456"]}

// 查询房间用户
{"type": "room_list", "roomId": "room_123"}
// 返回: {"type": "room_list_result", "roomId": "xxx", "users": ["user1"]}

WebRTC 信令

// 发送 Offer（发起通话）
{"type": "webrtc_offer", "roomId": "room_123", "to": "user2", "sdp": {...}}

// 发送 Answer（应答通话）
{"type": "webrtc_answer", "roomId": "room_123", "to": "user1", "sdp": {...}}

// 发送 ICE Candidate（网络候选）
{"type": "webrtc_ice", "roomId": "room_123", "to": "user2", "candidate": {...}}

房间事件通知

// 用户加入房间
{"type": "room_user_joined", "roomId": "xxx", "uid": "user2"}

// 用户离开房间
{"type": "room_user_left", "roomId": "xxx", "uid": "user1"}

WebRTC 工作流程

1. 客户端 A 和 B 分别连接服务器并绑定 UID
2. A 创建房间，B 加入同一房间
3. A 发起通话请求（webrtc_offer）
4. B 收到请求后发送应答（webrtc_answer）
5. 双方交换 ICE Candidates（webrtc_ice）
6. P2P 连接建立，开始音视频传输

STUN 服务器

服务器使用 Google STUN 服务进行 NAT 穿透：
stun:stun.l.google.com:19302

技术栈

• 运行环境: Cloudflare Workers
• 状态管理: Cloudflare Durable Objects
• 配置存储: Cloudflare Workers KV
• 协议支持: WebSocket, SSE, Long Polling