root/video_socket-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
600f64dc6d41ef7363a0149c1fdb180e63ca046a
video_socket-server/.qoder/repowiki/zh/content/API 参考.md
stary 6c13817527 修改
2026-05-16 13:24:02 +08:00

16 KiB
Raw Blame History

API 参考

**本文引用的文件** - [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)

目录

  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 轮询两种信令实现。

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

图表来源

章节来源

核心组件

  • 服务启动与配置：命令行参数解析、HTTPS/HTTP 选择、日志级别、信令协议类型与通信模式
  • Express 服务：CORS、JSON/URL 编码、静态资源、/config、/signaling 路由挂载、Swagger 文档
  • WebSocket 信令：连接生命周期、消息分发、广播、心跳与超时处理
  • HTTP 轮询信令：会话管理、连接管理、Offer/Answer/Candidate 存取、房间与用户信息查询
  • 数据模型：Offer、Answer、Candidate 结构体
  • 客户端封装：HTTP 与 WebSocket 两类信令客户端，Peer 连接控制

章节来源

架构总览

系统支持两种信令模式：

  • WebSocket：低延迟、全双工、事件驱动
  • HTTP 轮询：兼容性好、部署简单、适合受限网络环境
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

图表来源

详细组件分析

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；若长时间无活动则断开
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"

图表来源

章节来源

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）
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(["结束"])

图表来源

章节来源

信令消息数据结构

  • Offer
    • 字段：sdp、datetime、polite
    • 场景：发起端创建本地 offer 并通过信令通道发送给对端
  • Answer
    • 字段：sdp、datetime
    • 场景：应答端收到 offer 后创建 answer 并回传
  • Candidate
    • 字段：candidate、sdpMLineIndex、sdpMid、datetime
    • 场景：ICE 候选者收集阶段持续发送，帮助建立 P2P 连接
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
}

图表来源

章节来源

Swagger 自动生成的 API 文档

  • 生成与访问
    • 初始化 Swagger，自动扫描 /src/class/httphandler.ts 与 /src/signaling.ts 中的注释
    • 访问地址：/api-docs（根据运行协议与端口动态生成）
  • 安全方案
    • sessionAuth：通过请求头 "session-id" 进行认证

章节来源

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 → 接收对端信令 → 断开连接

章节来源

依赖关系分析

  • 服务端依赖
    • 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
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

图表来源

章节来源

性能考量

  • WebSocket
    • 低延迟、高吞吐，适合高频信令与实时交互
    • 心跳检测与超时断开避免僵尸连接占用资源
  • HTTP 轮询
    • 增量查询 fromtime 参数减少无效传输
    • 会话超时清理机制降低内存占用
  • 服务器配置
    • 日志级别可调，生产环境建议调整以减少 I/O 开销
    • HTTPS 证书启用时建议使用强密码套件与现代 TLS 版本

故障排查指南

  • 常见错误与处理
    • 404 会话不存在：检查 session-id 是否正确传递
    • 400 参数缺失：确保请求体包含 connectionId
    • 400 连接 ID 已被使用（私有模式）：更换唯一 connectionId
    • 会话超时：定期轮询或保持 WebSocket 连接活跃
  • 测试参考
    • WebSocket 单测验证公共/私有模式下的消息转发与断开行为
    • HTTP 单测验证会话创建/删除、连接管理、信令存取与超时清理

章节来源

结论

本项目提供了完整的 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 候选者
Reference in New Issue View Git Blame Copy Permalink