393 lines
16 KiB
Markdown
393 lines
16 KiB
Markdown
# API 参考
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [src/index.ts](file://src/index.ts)
|
||
- [src/server.ts](file://src/server.ts)
|
||
- [src/websocket.ts](file://src/websocket.ts)
|
||
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
|
||
- [src/class/httphandler.ts](file://src/class/httphandler.ts)
|
||
- [src/class/offer.ts](file://src/class/offer.ts)
|
||
- [src/class/answer.ts](file://src/class/answer.ts)
|
||
- [src/class/candidate.ts](file://src/class/candidate.ts)
|
||
- [src/swagger.ts](file://src/swagger.ts)
|
||
- [src/signaling.ts](file://src/signaling.ts)
|
||
- [client/src/signaling.js](file://client/src/signaling.js)
|
||
- [client/src/peer.js](file://client/src/peer.js)
|
||
- [test/websockethandler.test.ts](file://test/websockethandler.test.ts)
|
||
- [test/httphandler.test.ts](file://test/httphandler.test.ts)
|
||
- [package.json](file://package.json)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件为视频流服务器的完整 API 参考，覆盖以下内容：
|
||
- WebSocket 信令 API：连接建立、消息格式、事件类型与实时交互模式
|
||
- HTTP 轮询 API：端点规范、请求/响应格式、状态码与错误处理
|
||
- Swagger 自动化文档：生成与访问方式
|
||
- 信令消息数据结构：Offer、Answer、Candidate 等字段定义与使用场景
|
||
- 错误代码与处理指南
|
||
- API 使用示例与集成模板
|
||
|
||
## 项目结构
|
||
后端采用 Express 提供 HTTP 服务与静态资源，WebSocket 用于实时信令；HTTP 轮询模式通过 /signaling 路由提供信令存取能力。客户端提供基于 WebSocket 与 HTTP 轮询两种信令实现。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "服务端"
|
||
A["Express 应用<br/>src/server.ts"]
|
||
B["WebSocket 信令<br/>src/websocket.ts"]
|
||
C["HTTP 轮询信令<br/>src/signaling.ts → src/class/httphandler.ts"]
|
||
D["数据模型<br/>src/class/offer.ts / answer.ts / candidate.ts"]
|
||
E["Swagger 文档<br/>src/swagger.ts"]
|
||
end
|
||
subgraph "客户端"
|
||
F["信令封装(HTTP)<br/>client/src/signaling.js"]
|
||
G["信令封装(WebSocket)<br/>client/src/signaling.js"]
|
||
H["Peer 连接控制<br/>client/src/peer.js"]
|
||
end
|
||
A --> B
|
||
A --> C
|
||
A --> E
|
||
B --> D
|
||
C --> D
|
||
F --> A
|
||
G --> B
|
||
H --> F
|
||
H --> G
|
||
```
|
||
|
||
图表来源
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)
|
||
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)
|
||
|
||
章节来源
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
|
||
## 核心组件
|
||
- 服务启动与配置：命令行参数解析、HTTPS/HTTP 选择、日志级别、信令协议类型与通信模式
|
||
- Express 服务：CORS、JSON/URL 编码、静态资源、/config、/signaling 路由挂载、Swagger 文档
|
||
- WebSocket 信令：连接生命周期、消息分发、广播、心跳与超时处理
|
||
- HTTP 轮询信令：会话管理、连接管理、Offer/Answer/Candidate 存取、房间与用户信息查询
|
||
- 数据模型：Offer、Answer、Candidate 结构体
|
||
- 客户端封装：HTTP 与 WebSocket 两类信令客户端，Peer 连接控制
|
||
|
||
章节来源
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)
|
||
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)
|
||
|
||
## 架构总览
|
||
系统支持两种信令模式：
|
||
- WebSocket：低延迟、全双工、事件驱动
|
||
- HTTP 轮询：兼容性好、部署简单、适合受限网络环境
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Server as "Express 服务"
|
||
participant WS as "WebSocket 信令"
|
||
participant HTTP as "HTTP 轮询信令"
|
||
Client->>Server : GET /config
|
||
Server-->>Client : {useWebSocket, startupMode, logging}
|
||
alt WebSocket 模式
|
||
Client->>WS : 建立 ws/wss 连接
|
||
WS-->>Client : "connect"含 role/polite/participantId
|
||
Client->>WS : "offer"/"answer"/"candidate"
|
||
WS-->>Client : 广播/定向转发对应信令
|
||
else HTTP 模式
|
||
Client->>HTTP : PUT "" 创建会话返回 sessionId
|
||
Client->>HTTP : PUT "/connection" 创建连接
|
||
loop 轮询
|
||
Client->>HTTP : GET "" /offer /answer /candidate
|
||
HTTP-->>Client : 返回增量信令
|
||
end
|
||
Client->>HTTP : POST "/offer" /answer /candidate
|
||
Client->>HTTP : DELETE "" 关闭会话
|
||
end
|
||
```
|
||
|
||
图表来源
|
||
- [src/server.ts:25-41](file://src/server.ts#L25-L41)
|
||
- [src/websocket.ts:27-115](file://src/websocket.ts#L27-L115)
|
||
- [src/class/httphandler.ts:664-696](file://src/class/httphandler.ts#L664-L696)
|
||
- [src/class/httphandler.ts:698-828](file://src/class/httphandler.ts#L698-L828)
|
||
- [src/class/httphandler.ts:830-998](file://src/class/httphandler.ts#L830-L998)
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
|
||
## 详细组件分析
|
||
|
||
### WebSocket 信令 API
|
||
- 连接建立
|
||
- 客户端通过 ws/wss 连接到服务端
|
||
- 服务端在连接事件中注册处理器，维护连接集合与连接组
|
||
- 消息格式与事件类型
|
||
- connect/disconnect：建立/断开连接，包含 connectionId、polite、role、participantId
|
||
- offer/answer/candidate：信令三元组，包含 from、to、data（含 sdp 或 candidate/sdpMid/sdpMLineIndex）、participantId
|
||
- ping/pong：心跳机制
|
||
- broadcast/on-message：广播消息与自定义消息
|
||
- participant-joined/participant-left：多参与者的房间模式事件
|
||
- 实时交互模式
|
||
- 公共模式：同一房间内广播
|
||
- 私有模式：host 与特定 participant 或 host 与其他 participants 之间定向转发
|
||
- 心跳与超时
|
||
- 服务端周期发送 ping，客户端回 pong；若长时间无活动则断开
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant S as "WebSocket 信令"
|
||
participant H as "处理器(websockethandler)"
|
||
C->>S : "connect" {connectionId}
|
||
S->>H : onConnect(ws, connectionId)
|
||
H-->>C : "connect" {role, polite, participantId}
|
||
C->>S : "offer"/"answer"/"candidate"
|
||
S->>H : onOffer/onAnswer/onCandidate
|
||
H-->>C : 广播/定向转发对应信令
|
||
C->>S : "ping"
|
||
S-->>C : "pong"
|
||
S->>H : 更新 lastActivity
|
||
C->>S : "disconnect" {connectionId}
|
||
S->>H : onDisconnect
|
||
H-->>C : "disconnect"
|
||
```
|
||
|
||
图表来源
|
||
- [src/websocket.ts:44-115](file://src/websocket.ts#L44-L115)
|
||
- [src/class/websockethandler.ts:145-206](file://src/class/websockethandler.ts#L145-L206)
|
||
- [src/class/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
|
||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||
|
||
章节来源
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
|
||
### HTTP 轮询信令 API
|
||
- 会话与连接管理
|
||
- PUT ""：创建会话，返回 sessionId
|
||
- DELETE ""：删除会话
|
||
- PUT "/connection"：创建连接，返回 connectionId、polite、type、datetime
|
||
- DELETE "/connection"：删除连接
|
||
- 信令存取
|
||
- GET ""：获取所有信令（connect/disconnect/offer/answer/candidate），按 datetime 排序
|
||
- GET "/offer"：获取 offer 列表（可按 fromtime 过滤）
|
||
- GET "/answer"：获取 answer 列表（可按 fromtime 过滤）
|
||
- GET "/candidate"：获取 candidate 列表（可按 fromtime 过滤）
|
||
- GET "/connection"：获取连接列表
|
||
- GET "/connection-ids"：获取所有活跃连接 ID
|
||
- POST "/offer"：提交 offer
|
||
- POST "/answer"：提交 answer
|
||
- POST "/candidate"：提交 candidate
|
||
- 认证与安全
|
||
- 所有受保护路由需携带请求头 "session-id"
|
||
- 房间与用户信息
|
||
- GET "/rooms"：获取房间与用户信息（含 sessionId、connected）
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始"]) --> CreateSession["PUT '' 创建会话"]
|
||
CreateSession --> CreateConn["PUT '/connection' 创建连接"]
|
||
CreateConn --> PollLoop["轮询 GET ''/offer/answer/candidate"]
|
||
PollLoop --> PostOffer["POST '/offer' 提交 offer"]
|
||
PollLoop --> PostAnswer["POST '/answer' 提交 answer"]
|
||
PollLoop --> PostCandidate["POST '/candidate' 提交 candidate"]
|
||
PostOffer --> PollLoop
|
||
PostAnswer --> PollLoop
|
||
PostCandidate --> PollLoop
|
||
PollLoop --> DeleteConn["DELETE '/connection' 删除连接"]
|
||
DeleteConn --> DeleteSession["DELETE '' 删除会话"]
|
||
DeleteSession --> End(["结束"])
|
||
```
|
||
|
||
图表来源
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
- [src/class/httphandler.ts:664-696](file://src/class/httphandler.ts#L664-L696)
|
||
- [src/class/httphandler.ts:698-828](file://src/class/httphandler.ts#L698-L828)
|
||
- [src/class/httphandler.ts:830-998](file://src/class/httphandler.ts#L830-L998)
|
||
- [src/class/httphandler.ts:1041-1076](file://src/class/httphandler.ts#L1041-L1076)
|
||
|
||
章节来源
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||
|
||
### 信令消息数据结构
|
||
- Offer
|
||
- 字段：sdp、datetime、polite
|
||
- 场景：发起端创建本地 offer 并通过信令通道发送给对端
|
||
- Answer
|
||
- 字段：sdp、datetime
|
||
- 场景：应答端收到 offer 后创建 answer 并回传
|
||
- Candidate
|
||
- 字段：candidate、sdpMLineIndex、sdpMid、datetime
|
||
- 场景：ICE 候选者收集阶段持续发送，帮助建立 P2P 连接
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Offer {
|
||
+string sdp
|
||
+number datetime
|
||
+boolean polite
|
||
}
|
||
class Answer {
|
||
+string sdp
|
||
+number datetime
|
||
}
|
||
class Candidate {
|
||
+string candidate
|
||
+number sdpMLineIndex
|
||
+string sdpMid
|
||
+number datetime
|
||
}
|
||
```
|
||
|
||
图表来源
|
||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
|
||
章节来源
|
||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||
|
||
### Swagger 自动生成的 API 文档
|
||
- 生成与访问
|
||
- 初始化 Swagger，自动扫描 /src/class/httphandler.ts 与 /src/signaling.ts 中的注释
|
||
- 访问地址：/api-docs（根据运行协议与端口动态生成）
|
||
- 安全方案
|
||
- sessionAuth：通过请求头 "session-id" 进行认证
|
||
|
||
章节来源
|
||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||
|
||
### API 使用示例与集成模板
|
||
- 客户端封装
|
||
- HTTP 信令封装：Signaling 类，提供 start/stop、createConnection/deleteConnection、sendOffer/sendAnswer/sendCandidate、getAll 等方法
|
||
- WebSocket 信令封装：WebSocketSignaling 类，提供 createConnection/sendOffer/sendAnswer/sendCandidate/sendMessage 等方法
|
||
- Peer 连接控制：Peer 类，封装 RTCPeerConnection、ICE 候选者、状态变化等
|
||
- 示例流程
|
||
- HTTP 模式：创建会话 → 创建连接 → 轮询获取信令 → 发送 offer/answer/candidate → 删除连接/会话
|
||
- WebSocket 模式：建立连接 → 发送 connect → 发送 offer/answer/candidate → 接收对端信令 → 断开连接
|
||
|
||
章节来源
|
||
- [client/src/signaling.js:1-292](file://client/src/signaling.js#L1-L292)
|
||
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)
|
||
|
||
## 依赖关系分析
|
||
- 服务端依赖
|
||
- Express、ws、swagger-jsdoc、swagger-ui-express、uuid、cors、morgan、multer
|
||
- 关键依赖链
|
||
- src/index.ts → src/server.ts → src/signaling.ts → src/class/httphandler.ts
|
||
- src/index.ts → src/websocket.ts → src/class/websockethandler.ts
|
||
- src/swagger.ts → src/class/httphandler.ts 与 src/signaling.ts
|
||
|
||
```mermaid
|
||
graph LR
|
||
pkg["package.json 依赖声明"] --> exp["express"]
|
||
pkg --> wsdep["ws"]
|
||
pkg --> swagger["swagger-jsdoc / swagger-ui-express"]
|
||
pkg --> uuiddep["uuid"]
|
||
pkg --> corsdep["cors"]
|
||
pkg --> morgandep["morgan"]
|
||
pkg --> multerdep["multer"]
|
||
idx["src/index.ts"] --> srv["src/server.ts"]
|
||
idx --> wsc["src/websocket.ts"]
|
||
srv --> sig["src/signaling.ts"]
|
||
sig --> hth["src/class/httphandler.ts"]
|
||
wsc --> wsh["src/class/websockethandler.ts"]
|
||
srv --> swg["src/swagger.ts"]
|
||
swg --> hth
|
||
swg --> sig
|
||
```
|
||
|
||
图表来源
|
||
- [package.json:14-46](file://package.json#L14-L46)
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||
|
||
章节来源
|
||
- [package.json:14-46](file://package.json#L14-L46)
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
|
||
## 性能考量
|
||
- WebSocket
|
||
- 低延迟、高吞吐，适合高频信令与实时交互
|
||
- 心跳检测与超时断开避免僵尸连接占用资源
|
||
- HTTP 轮询
|
||
- 增量查询 fromtime 参数减少无效传输
|
||
- 会话超时清理机制降低内存占用
|
||
- 服务器配置
|
||
- 日志级别可调，生产环境建议调整以减少 I/O 开销
|
||
- HTTPS 证书启用时建议使用强密码套件与现代 TLS 版本
|
||
|
||
## 故障排查指南
|
||
- 常见错误与处理
|
||
- 404 会话不存在：检查 session-id 是否正确传递
|
||
- 400 参数缺失：确保请求体包含 connectionId
|
||
- 400 连接 ID 已被使用（私有模式）：更换唯一 connectionId
|
||
- 会话超时：定期轮询或保持 WebSocket 连接活跃
|
||
- 测试参考
|
||
- WebSocket 单测验证公共/私有模式下的消息转发与断开行为
|
||
- HTTP 单测验证会话创建/删除、连接管理、信令存取与超时清理
|
||
|
||
章节来源
|
||
- [test/websockethandler.test.ts:1-191](file://test/websockethandler.test.ts#L1-L191)
|
||
- [test/httphandler.test.ts:1-510](file://test/httphandler.test.ts#L1-L510)
|
||
|
||
## 结论
|
||
本项目提供了完整的 WebRTC 信令解决方案，支持 WebSocket 与 HTTP 轮询两种模式，满足不同部署与网络环境需求。通过清晰的 API 规范、完善的 Swagger 文档与客户端封装，开发者可快速集成并稳定运行信令服务。
|
||
|
||
## 附录
|
||
- 端点一览（HTTP 轮询）
|
||
- GET /signaling/connection-ids：获取所有活跃连接 ID
|
||
- GET /signaling/connection：获取连接列表
|
||
- GET /signaling/offer：获取 offer 列表（可选 fromtime）
|
||
- GET /signaling/answer：获取 answer 列表（可选 fromtime）
|
||
- GET /signaling/candidate：获取 candidate 列表（可选 fromtime）
|
||
- GET /signaling：获取所有信令（可选 fromtime）
|
||
- PUT /signaling：创建会话（返回 sessionId）
|
||
- DELETE /signaling：删除会话
|
||
- PUT /signaling/connection：创建连接
|
||
- DELETE /signaling/connection：删除连接
|
||
- POST /signaling/offer：提交 offer
|
||
- POST /signaling/answer：提交 answer
|
||
- POST /signaling/candidate：提交 candidate
|
||
- GET /signaling/rooms：获取房间与用户信息
|
||
- 客户端集成要点
|
||
- HTTP 模式：使用 Signaling 类管理会话与轮询
|
||
- WebSocket 模式：使用 WebSocketSignaling 类进行实时信令
|
||
- Peer 控制：使用 Peer 类处理 RTCPeerConnection 生命周期与 ICE 候选者 |