WebSocket 管理后台

概述

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

🌐

多协议支持

WebSocket / SSE / Long Polling

🔒

项目隔离

独立 Durable Object 实例

📱

离线消息

3天自动过期存储

🎥

WebRTC

视频/语音通话支持

管理 API

所有管理 API 需要在请求头中携带 Admin Token：

Authorization: Bearer <admin-token>

方法	路径	描述	请求体
POST	/project	创建项目	{"key": "xxx", "name": "xxx"}
GET	/project	列出项目	-
DELETE	/project?key=xxx	删除项目	-
POST	/token	生成令牌	{"projectKey": "xxx"}
DELETE	/token?projectKey=xxx&token=xxx	删除令牌	-
PATCH	/token	修改令牌到期时间	{"projectKey": "xxx", "token": "xxx", "expiresAt": xxx}

邮件发送 API

使用 POST 方式发送邮件，通过 project 和 token 参数进行身份验证。

邮件发送通过 MailChannels 服务实现，需要在域名 DNS 中配置 SPF 记录。

方法	路径	描述
POST	/mail?project=xxx&token=xxx	发送邮件

请求参数

to (必填): 收件人邮箱，支持字符串或数组

subject (必填): 邮件主题

text: 纯文本内容

html: HTML 内容

from: 发件人邮箱（默认 noreply@域名）

fromName: 发件人名称（默认 WebSocket Server）

示例请求

POST /mail?project=myproject&token=xxx
Content-Type: application/json

{
  "to": "user@example.com",
  "subject": "测试邮件",
  "text": "这是一封测试邮件",
  "html": "<p>这是一封 <strong>测试邮件</strong></p>",
  "fromName": "通知服务"
}

响应示例

{
  "status": "success",
  "msg": "Email sent successfully",
  "rateLimit": {
    "allowed": true,
    "count": 1,
    "max": 10
  }
}

频率限制

每个令牌每分钟最多发送 10 封邮件。超过限制将返回 429 状态码。

DNS 配置要求

为了使邮件能正常发送，需要在域名的 DNS 记录中添加以下配置：

1. 域名锁记录（必需）

证明你拥有该域名，MailChannels 才能代发邮件：

TXT _mailchannels v=mc1 cfid=你的 Cloudflare Account ID

2. SPF 记录（必需）

允许 MailChannels 代表你的域名发送邮件：

TXT @ v=spf1 include:spf.mailchannels.net ~all

3. DKIM 记录（可选但推荐）

增加邮件真实性验证，提高送达率：

CNAME _dmarc.yourdomain.com → dmarc.mailchannels.net

配置完成后，需要等待 DNS 记录生效（通常 5-15 分钟），邮件才能正常发送。

连接方式

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

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

全双工通信，实时性最好，推荐使用

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

服务端单向推送，WebSocket 不可用时的降级方案

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

HTTP 轮询，兼容性最好，延迟最高

mode 参数:

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

示例代码

WebSocket 连接

const ws = new WebSocket('wss://scws.ccwu.cc/ws?project=myproject&token=xxx&mode=long');

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'bind', uid: 'user_1' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'connected': console.log('Connected:', msg.connId); break;
    case 'bind_success': console.log('Bound:', msg.uid); break;
    case 'direct': console.log('Received:', msg); break;
    case 'ping': ws.send(JSON.stringify({ type: 'pong' })); break;
  }
};

// 发送消息
ws.send(JSON.stringify({ type: 'send', to: 'user_2', msg: 'Hello' }));
ws.send(JSON.stringify({ type: 'broadcast', msg: 'Hi everyone' }));

SSE 连接

const eventSource = new EventSource('https://scws.ccwu.cc/sse?project=myproject&token=xxx&mode=long');

eventSource.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('Received:', msg);
};

// 发送消息（通过 HTTP POST）
fetch('https://scws.ccwu.cc/sse', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'send', to: 'user_2', msg: 'Hello' })
});

WebRTC 视频通话

const ws = new WebSocket('wss://scws.ccwu.cc/ws?project=myproject&token=xxx&mode=long');

let pc = null;
let localStream = null;

// 连接并绑定 UID
ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'bind', uid: 'user_1' }));
  ws.send(JSON.stringify({ type: 'room_join', roomId: 'room_123' }));
};

ws.onmessage = async (event) => {
  const msg = JSON.parse(event.data);
  
  if (msg.type === 'webrtc_offer') {
    // 收到通话请求
    pc = new RTCPeerConnection({
      iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
    });
    
    // 添加本地流
    localStream.getTracks().forEach(track => pc.addTrack(track, localStream));
    
    // 处理远端流
    pc.ontrack = (e) => {
      document.getElementById('remoteVideo').srcObject = e.streams[0];
    };
    
    // 发送 ICE Candidate
    pc.onicecandidate = (e) => {
      if (e.candidate) {
        ws.send(JSON.stringify({
          type: 'webrtc_ice',
          roomId: 'room_123',
          to: msg.from,
          candidate: e.candidate.toJSON()
        }));
      }
    };
    
    // 设置远端描述并发送应答
    await pc.setRemoteDescription(new RTCSessionDescription(msg.sdp));
    const answer = await pc.createAnswer();
    await pc.setLocalDescription(answer);
    ws.send(JSON.stringify({
      type: 'webrtc_answer',
      roomId: 'room_123',
      to: msg.from,
      sdp: answer
    }));
  }
  
  if (msg.type === 'webrtc_answer') {
    await pc.setRemoteDescription(new RTCSessionDescription(msg.sdp));
  }
  
  if (msg.type === 'webrtc_ice') {
    await pc.addIceCandidate(new RTCIceCandidate(msg.candidate));
  }
};

// 发起通话
async function startCall(targetUid) {
  localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
  document.getElementById('localVideo').srcObject = localStream;
  
  pc = new RTCPeerConnection({
    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
  });
  
  localStream.getTracks().forEach(track => pc.addTrack(track, localStream));
  
  pc.ontrack = (e) => {
    document.getElementById('remoteVideo').srcObject = e.streams[0];
  };
  
  pc.onicecandidate = (e) => {
    if (e.candidate) {
      ws.send(JSON.stringify({
        type: 'webrtc_ice',
        roomId: 'room_123',
        to: targetUid,
        candidate: e.candidate.toJSON()
      }));
    }
  };
  
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);
  ws.send(JSON.stringify({
    type: 'webrtc_offer',
    roomId: 'room_123',
    to: targetUid,
    sdp: offer
  }));
}

// 开始通话
startCall('user_2');

发送邮件

// 发送邮件 (POST 请求)
async function sendEmail(projectKey, token) {
  const response = await fetch(`https://scws.ccwu.cc/mail?project=${projectKey}&token=${token}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      to: 'user@example.com',
      subject: '通知邮件',
      text: '这是一封重要的通知邮件',
      html: '<p>这是一封 <strong>重要</strong> 的通知邮件</p>',
      fromName: '系统通知'
    })
  });
  
  const result = await response.json();
  if (response.ok) {
    console.log('邮件发送成功:', result);
  } else {
    console.error('发送失败:', result);
  }
}

// 使用
sendEmail('myproject', 'xxx');

WebSocket 连接 (Java-WebSocket)

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import java.net.URI;

public class WsClient extends WebSocketClient {
    public WsClient(URI serverUri) {
        super(serverUri);
    }

    @Override
    public void onOpen(ServerHandshake handshakedata) {
        send("{\"type\": \"bind\", \"uid\": \"user_1\"}");
    }

    @Override
    public void onMessage(String message) {
        System.out.println("Received: " + message);
    }

    @Override
    public void onClose(int code, String reason, boolean remote) {}

    @Override
    public void onError(Exception ex) {
        ex.printStackTrace();
    }

    public static void main(String[] args) {
        WsClient client = new WsClient(
            new URI("wss://scws.ccwu.cc/ws?project=myproject&token=xxx&mode=long")
        );
        client.connect();
        // 发送消息
        client.send("{\"type\": \"send\", \"to\": \"user_2\", \"msg\": \"Hello\"}");
    }
}

Maven 依赖

<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.3</version>
</dependency>

WebRTC 示例 (需使用 WebView 或 JavaFX)

// Java WebRTC 需要借助 WebView 或 JavaFX 来使用浏览器 API
// 这里展示信令部分的消息处理逻辑

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import java.net.URI;
import org.json.JSONObject;

public class WebRTCSignaling {
    private WebSocketClient ws;
    private String roomId = "room_123";
    
    public void connect() {
        ws = new WebSocketClient(new URI("wss://scws.ccwu.cc/ws?project=myproject&token=xxx&mode=long")) {
            @Override
            public void onOpen(ServerHandshake handshakedata) {
                // 绑定 UID 并加入房间
                send(new JSONObject()
                    .put("type", "bind")
                    .put("uid", "user_1").toString());
                send(new JSONObject()
                    .put("type", "room_join")
                    .put("roomId", roomId).toString());
            }
            
            @Override
            public void onMessage(String message) {
                JSONObject msg = new JSONObject(message);
                String type = msg.getString("type");
                
                if (type.equals("webrtc_offer")) {
                    // 收到 Offer，需要通过 WebView/JavaFX 处理
                    JSONObject sdp = msg.getJSONObject("sdp");
                    System.out.println("Received offer from: " + msg.getString("from"));
                    // TODO: 在 WebView 中调用 setRemoteDescription 并创建 Answer
                    
                } else if (type.equals("webrtc_answer")) {
                    // 收到 Answer
                    System.out.println("Received answer from: " + msg.getString("from"));
                    // TODO: 在 WebView 中调用 setRemoteDescription
                    
                } else if (type.equals("webrtc_ice")) {
                    // 收到 ICE Candidate
                    JSONObject candidate = msg.getJSONObject("candidate");
                    System.out.println("Received ICE candidate");
                    // TODO: 在 WebView 中调用 addIceCandidate
                }
            }
            
            @Override
            public void onClose(int code, String reason, boolean remote) {}
            
            @Override
            public void onError(Exception ex) {
                ex.printStackTrace();
            }
        };
        ws.connect();
    }
    
    // 发送 Offer
    public void sendOffer(String targetUid, JSONObject sdp) {
        ws.send(new JSONObject()
            .put("type", "webrtc_offer")
            .put("roomId", roomId)
            .put("to", targetUid)
            .put("sdp", sdp).toString());
    }
    
    // 发送 Answer
    public void sendAnswer(String targetUid, JSONObject sdp) {
        ws.send(new JSONObject()
            .put("type", "webrtc_answer")
            .put("roomId", roomId)
            .put("to", targetUid)
            .put("sdp", sdp).toString());
    }
    
    // 发送 ICE Candidate
    public void sendIceCandidate(String targetUid, JSONObject candidate) {
        ws.send(new JSONObject()
            .put("type", "webrtc_ice")
            .put("roomId", roomId)
            .put("to", targetUid)
            .put("candidate", candidate).toString());
    }
}

// 推荐方案：使用 Java WebView 调用 JavaScript WebRTC API
// 或者使用专门的 Java WebRTC 库如 Jitsi、Asterisk Java Interface

发送邮件

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class MailSender {
    public static void sendEmail(String projectKey, String token) throws Exception {
        String json = "{\"to\":\"user@example.com\",\"subject\":\"通知邮件\",\"text\":\"这是一封重要的通知邮件\",\"fromName\":\"系统通知\"}";
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://scws.ccwu.cc/mail?project=" + projectKey + "&token=" + token))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        
        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("Response: " + response.statusCode());
        System.out.println("Body: " + response.body());
    }
    
    public static void main(String[] args) throws Exception {
        sendEmail("myproject", "xxx");
    }
}

WebSocket 连接 (websockets)

import asyncio
import websockets
import json

async def connect():
    uri = "wss://scws.ccwu.cc/ws?project=myproject&token=xxx&mode=long"
    async with websockets.connect(uri) as ws:
        # 绑定 UID
        await ws.send(json.dumps({"type": "bind", "uid": "user_1"}))
        
        async for message in ws:
            msg = json.loads(message)
            print(f"Received: {msg}")
            
            if msg["type"] == "ping":
                await ws.send(json.dumps({"type": "pong"}))

asyncio.run(connect())

SSE 连接 (sseclient-py)

from sseclient import SSEClient
import requests
import json

# 连接 SSE
messages = SSEClient('https://scws.ccwu.cc/sse?project=myproject&token=xxx&mode=long')

for msg in messages:
    if msg.data:
        print(json.loads(msg.data))

# 发送消息
requests.post(
    'https://scws.ccwu.cc/sse',
    json={"type": "send", "to": "user_2", "msg": "Hello"}
)

安装依赖

pip install websockets sseclient-py requests

WebRTC 示例 (aiortc)

# Python WebRTC 可使用 aiortc 库（纯 Python 实现）
# 安装: pip install aiortc

import asyncio
import websockets
import json
from aiortc import RTCPeerConnection, RTCSessionDescription, RTCIceCandidate
from aiortc.contrib.media import MediaPlayer

class WebRTCClient:
    def __init__(self):
        self.pc = None
        self.ws = None
        self.room_id = "room_123"
        
    async def connect(self):
        uri = "wss://scws.ccwu.cc/ws?project=myproject&token=xxx&mode=long"
        self.ws = await websockets.connect(uri)
        
        # 绑定 UID 并加入房间
        await self.ws.send(json.dumps({"type": "bind", "uid": "user_1"}))
        await self.ws.send(json.dumps({"type": "room_join", "roomId": self.room_id}))
        
        # 处理消息
        await self.handle_messages()
    
    async def handle_messages(self):
        while True:
            message = await self.ws.recv()
            msg = json.loads(message)
            
            if msg["type"] == "webrtc_offer":
                # 收到 Offer
                await self.handle_offer(msg)
            elif msg["type"] == "webrtc_answer":
                # 收到 Answer
                await self.handle_answer(msg)
            elif msg["type"] == "webrtc_ice":
                # 收到 ICE Candidate
                await self.handle_ice(msg)
    
    async def handle_offer(self, msg):
        self.pc = RTCPeerConnection(configuration={
            "iceServers": [{"urls": "stun:stun.l.google.com:19302"}]
        })
        
        # 设置远端描述
        offer = RTCSessionDescription(msg["sdp"]["sdp"], "offer")
        await self.pc.setRemoteDescription(offer)
        
        # 创建 Answer
        answer = await self.pc.createAnswer()
        await self.pc.setLocalDescription(answer)
        
        # 发送 Answer
        await self.ws.send(json.dumps({
            "type": "webrtc_answer",
            "roomId": self.room_id,
            "to": msg["from"],
            "sdp": {"sdp": self.pc.localDescription.sdp, "type": "answer"}
        }))
    
    async def handle_answer(self, msg):
        answer = RTCSessionDescription(msg["sdp"]["sdp"], "answer")
        await self.pc.setRemoteDescription(answer)
    
    async def handle_ice(self, msg):
        candidate = RTCIceCandidate(
            sdpMid=msg["candidate"]["sdpMid"],
            sdpMLineIndex=msg["candidate"]["sdpMLineIndex"],
            candidate=msg["candidate"]["candidate"]
        )
        await self.pc.addIceCandidate(candidate)
    
    async def start_call(self, target_uid):
        # 创建 PeerConnection
        self.pc = RTCPeerConnection(configuration={
            "iceServers": [{"urls": "stun:stun.l.google.com:19302"}]
        })
        
        # 添加本地音视频（摄像头/麦克风）
        # player = MediaPlayer("video=0", format="avfoundation")  # macOS
        # self.pc.addTrack(player.video)
        # self.pc.addTrack(player.audio)
        
        # 监听 ICE Candidate
        @self.pc.on("icecandidate")
        def on_icecandidate(candidate):
            if candidate:
                await self.ws.send(json.dumps({
                    "type": "webrtc_ice",
                    "roomId": self.room_id,
                    "to": target_uid,
                    "candidate": {
                        "sdpMid": candidate.sdpMid,
                        "sdpMLineIndex": candidate.sdpMLineIndex,
                        "candidate": candidate.candidate
                    }
                }))
        
        # 创建 Offer
        offer = await self.pc.createOffer()
        await self.pc.setLocalDescription(offer)
        
        # 发送 Offer
        await self.ws.send(json.dumps({
            "type": "webrtc_offer",
            "roomId": self.room_id,
            "to": target_uid,
            "sdp": {"sdp": self.pc.localDescription.sdp, "type": "offer"}
        }))

# 使用
async def main():
    client = WebRTCClient()
    await client.connect()

asyncio.run(main())

发送邮件

import requests
import json

def send_email(project_key, token):
    url = f"https://scws.ccwu.cc/mail?project={project_key}&token={token}"
    payload = {
        "to": "user@example.com",
        "subject": "通知邮件",
        "text": "这是一封重要的通知邮件",
        "html": "<p>这是一封 <strong>重要</strong> 的通知邮件</p>",
        "fromName": "系统通知"
    }
    
    response = requests.post(url, json=payload)
    result = response.json()
    
    if response.status_code == 200:
        print("邮件发送成功:", result)
    else:
        print("发送失败:", result)

# 使用
send_email("myproject", "xxx")

消息协议

bind

绑定 UID

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

broadcast

广播消息

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

send

一对一消息

{"type": "send", "to": "user_2", "msg": "Hi"}

multicast

群发消息

{"type": "multicast", "to": ["u1","u2"], "msg": "Hi"}

list

获取在线列表

{"type": "list"}

online

查询在线状态

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

服务器返回消息

类型	说明	示例
connected	连接成功	{"type": "connected", "connId": "xxx"}
bind_success	绑定成功	{"type": "bind_success", "uid": "user_1"}
direct	收到一对一消息	{"type": "direct", "from": "u1", "to": "u2", "msg": "..."}
broadcast	收到广播消息	{"type": "broadcast", "msg": "...", "timestamp": xxx}
send_success	发送成功	{"type": "send_success", "to": "user_2"}
online_result	查询在线结果	{"type": "online_result", "uid": "u1", "online": true}
list	在线用户列表	{"type": "list", "uids": ["u1", "u2"]}
online	用户上线通知	{"type": "online", "uid": "u1", "timestamp": xxx}
offline	用户下线通知	{"type": "offline", "uid": "u1", "timestamp": xxx}
ping	心跳（长连接）	{"type": "ping"}
error	错误消息	{"type": "error", "msg": "..."}

离线消息

💾

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

// 发送离线消息时返回
{"type": "send_success", "to": "user_2", "offline": true}

// 群发时返回在线和离线用户
{"type": "send_success", "to": ["user_2"], "offline": ["user_3"]}

WebRTC 支持

服务器可作为 WebRTC 信令服务器，用于交换 SDP 和 ICE Candidates。

通话模式

🎥

视频通话

同时传输视频和音频

需要：摄像头 + 麦克风

🎤

语音通话

仅传输音频

需要：麦克风

房间管理

room_create

创建房间

{"type": "room_create", "roomId": "r1"}

room_join

加入房间

{"type": "room_join", "roomId": "r1"}

room_leave

离开房间

{"type": "room_leave", "roomId": "r1"}

WebRTC 信令

// 发送 Offer
{"type": "webrtc_offer", "roomId": "r1", "to": "user2", "sdp": {...}}

// 发送 Answer
{"type": "webrtc_answer", "roomId": "r1", "to": "user1", "sdp": {...}}

// 发送 ICE Candidate
{"type": "webrtc_ice", "roomId": "r1", "to": "user2", "candidate": {...}}

工作流程

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

STUN 服务器

stun:stun.l.google.com:19302

技术栈

☁️

Cloudflare Workers

运行环境

🔄

Durable Objects

状态管理

🗄️

Workers KV

配置存储

🔗

WebSocket/SSE/Polling

协议支持

管理员登录

WebSocket 管理后台

创建新项目

项目列表 刷新

连接配置

发送消息

接收消息 (未连接)

WebRTC 音视频通话测试

本地视频

通话控制

远端视频

通话日志

邮件发送测试

WebSocket Server API 技术文档

概述

管理 API

邮件发送 API

请求参数

示例请求

响应示例

频率限制

DNS 配置要求

1. 域名锁记录（必需）

2. SPF 记录（必需）

3. DKIM 记录（可选但推荐）

连接方式

示例代码

WebSocket 连接

SSE 连接

WebRTC 视频通话

发送邮件

WebSocket 连接 (Java-WebSocket)

Maven 依赖

WebRTC 示例 (需使用 WebView 或 JavaFX)

发送邮件

WebSocket 连接 (websockets)

SSE 连接 (sseclient-py)

安装依赖

WebRTC 示例 (aiortc)

发送邮件

消息协议

服务器返回消息

离线消息

WebRTC 支持

通话模式

房间管理

WebRTC 信令

工作流程

STUN 服务器

技术栈

操作日志 清空

项目列表

操作日志