← 首页 📤 发送方 📥 接收方 ⚙️ 管理后台

📖 API 文档

认证方式

所有 /api/* 接口均需 AppID + Token 双因素认证（在管理后台创建应用获取），支持三种传递方式：

方式一：HTTP Header（推荐）

X-App-ID: app_xxxxxxxx
X-App-Token: tok_xxxxxxxx

方式二：Query 参数

GET /api/status?appid=app_xxx&token=tok_xxx

认证失败返回 HTTP 401：

{ "success": false, "error": "缺少 appid 或 token" }
{ "success": false, "error": "appid 或 token 无效" }

信令服务端点

PeerJS 信令基于 WebSocket，路径 /peerjs，无需认证：

// 浏览器 / 桌面应用
import Peer from 'peerjs';
const peer = new Peer('my-id', {
  host: '你的域名',
  port: 443,
  path: '/peerjs',
  secure: true,
});
const conn = peer.connect('target-peer-id');
conn.on('open', () => conn.send('hello'));
peer.on('connection', (conn) => {
  conn.on('data', (data) => console.log(data));
});

在线测试

填入后点击下方各接口的「测试」按钮即可直接调用。

GET /api/status

服务器状态、运行时间、在线人数。

{
  "success": true,
  "server": "peerjs-signaling",
  "uptime": 123.45,
  "peers": 2,
  "app": "应用名称"
}

GET /api/peers

获取所有在线 Peer ID 列表。

{ "success": true, "peers": ["peer-abc123", "peer-xyz789"] }

GET /api/peer/:id

检查指定 Peer 是否在线。

{ "success": true, "id": "peer-abc123", "online": true }

POST /api/generate-id

生成可用的 Peer ID。

请求: { "prefix": "app" }
响应: { "success": true, "id": "app_1694xxx_ab12cd" }

POST /api/broadcast

向所有在线 Peer 广播通知消息。

请求: { "message": "系统维护通知" }
响应: { "success": true, "broadcast": "ok", "peers": 2 }

POST /api/events

上报传输事件。客户端在连接建立/断开、发送完成/失败、接收完成等节点调用；服务器落库后异步推送到应用回调地址。

请求: { "type": "send_done", "peerId": "peer-a", "targetPeerId": "peer-b",
        "fileName": "demo.zip", "fileSize": 123456 }
响应: { "success": true, "eventId": 1 }

GET /api/transfers

查询本应用的传输事件记录（按时间倒序）。可选 Query 参数：peerId、targetPeerId、msgId、type、limit（1-200，默认 50）、before（事件 ID，分页游标）。

GET /api/transfers?type=send_done&limit=20
响应: {
  "success": true,
  "count": 1,
  "events": [ {
    "eventId": 1, "type": "send_done",
    "peerId": "peer-a", "targetPeerId": "peer-b",
    "fileName": "demo.zip", "fileSize": 123456,
    "callbackStatus": "ok", "callbackAttempts": 1,
    "createdAt": "2026-09-07T06:00:00.000Z"
  } ]
}

对接示例

JavaScript

fetch('https://你的域名/api/status', {
  headers: {
    'X-App-ID': 'app_xxx',
    'X-App-Token': 'tok_xxx',
  }
}).then(r => r.json()).then(console.log);

Python

import requests
resp = requests.get(
    'https://你的域名/api/status',
    headers={'X-App-ID': 'app_xxx', 'X-App-Token': 'tok_xxx'}
)
print(resp.json())