439 lines
16 KiB
Markdown
439 lines
16 KiB
Markdown
# 项目概述
|
||
|
||
<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/signaling.ts](file://src/signaling.ts)
|
||
- [client/public/bidirectional/js/main.js](file://client/public/bidirectional/js/main.js)
|
||
- [client/public/onebyone/main.js](file://client/public/onebyone/main.js)
|
||
- [client/src/peer.js](file://client/src/peer.js)
|
||
- [client/src/sender.js](file://client/src/sender.js)
|
||
- [package.json](file://package.json)
|
||
- [client/package.json](file://client/package.json)
|
||
- [src/log.ts](file://src/log.ts)
|
||
- [src/class/options.ts](file://src/class/options.ts)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
Video Socket Server 是一个基于 WebRTC 的实时双向视频通信服务端与前端示例项目，支持两种信令模式（WebSocket 与 HTTP 轮询）与两种通信模式（公共模式与私有模式）。项目旨在为 Unity Render Streaming、远程视频监控、在线教育等场景提供低延迟、高可靠性的视频传输基础设施。
|
||
|
||
- 核心目标
|
||
- 提供稳定可靠的 WebRTC 信令与媒体转发能力
|
||
- 支持公共模式（广播式）与私有模式（点对点/一对多）
|
||
- 提供 WebSocket 与 HTTP 两种信令通道，适配不同网络环境
|
||
- 提供丰富的前端示例，覆盖双向视频通话、一对一通话、输入遥测等
|
||
|
||
- 技术定位
|
||
- 后端：Node.js + TypeScript + Express.js
|
||
- 前端：原生 JavaScript（ES Modules），结合 WebRTC API
|
||
- 协议：WebSocket（ws:// 或 wss://）与 HTTP RESTful 接口
|
||
- 数据结构：Offer/Answer 与 ICE Candidate 的信令封装
|
||
|
||
- 主要应用场景
|
||
- Unity Render Streaming：通过 WebRTC 实现远端渲染画面的低延迟传输
|
||
- 远程视频监控：支持多路摄像头与回放控制
|
||
- 在线教育：支持课堂互动、屏幕共享与聊天
|
||
|
||
**章节来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
|
||
|
||
## 项目结构
|
||
项目采用前后端分离的组织方式：
|
||
- 后端（src）：服务启动、HTTP 路由、WebSocket 信令、日志与配置
|
||
- 前端（client）：静态资源与示例页面，包含多个演示场景（双向视频、一对一通话、输入遥测等）
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "后端(src)"
|
||
IDX["入口: index.ts"]
|
||
SRV["HTTP服务: server.ts"]
|
||
WS["WebSocket信令: websocket.ts"]
|
||
WSH["WS处理器: class/websockethandler.ts"]
|
||
HTH["HTTP处理器: class/httphandler.ts"]
|
||
SIG["信令路由: signaling.ts"]
|
||
LOG["日志: log.ts"]
|
||
OPT["配置: class/options.ts"]
|
||
end
|
||
subgraph "前端(client)"
|
||
PUB["静态资源: public/*"]
|
||
SRC["模块: src/*"]
|
||
end
|
||
IDX --> SRV
|
||
SRV --> SIG
|
||
SRV --> PUB
|
||
SRV --> SRC
|
||
SRV --> WS
|
||
WS --> WSH
|
||
SIG --> HTH
|
||
IDX --> LOG
|
||
IDX --> OPT
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
|
||
- [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-800](file://src/class/httphandler.ts#L1-L800)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
|
||
**章节来源**
|
||
- [package.json:1-60](file://package.json#L1-L60)
|
||
- [client/package.json:1-19](file://client/package.json#L1-L19)
|
||
|
||
## 核心组件
|
||
- 服务入口与启动
|
||
- 解析命令行参数，创建 HTTP/HTTPS 服务器，根据配置选择信令模式
|
||
- 启动 WebSocket 信令或 HTTP 轮询信令
|
||
|
||
- HTTP 服务与静态资源
|
||
- 提供 /config 接口返回运行配置（是否使用 WebSocket、启动模式、日志级别）
|
||
- 提供 /signaling 路由，挂载 HTTP 信令处理器
|
||
- 提供静态页面与模块资源，首页自动指向 client/public/index.html
|
||
|
||
- WebSocket 信令
|
||
- 监听连接、消息、关闭事件，解析多种信令类型（connect/disconnect/offer/answer/candidate/broadcast/ping/pong/call-request/on-message）
|
||
- 将消息分派至 WS 处理器进行业务逻辑处理
|
||
|
||
- WS 处理器（1对多/私有模式）
|
||
- 维护连接组（host 与 participants），支持广播与定向转发
|
||
- 处理 offer/answer/candidate 的路由与转发，支持 participantId 标识
|
||
|
||
- HTTP 信令处理器（HTTP 轮询）
|
||
- 提供会话管理与连接管理接口，支持轮询获取信令消息
|
||
- 支持超时会话清理与断开连接记录
|
||
|
||
- 日志与配置
|
||
- 可配置日志级别，统一输出格式
|
||
- Options 接口定义运行参数（端口、证书、信令类型、通信模式、日志级别）
|
||
|
||
**章节来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
|
||
- [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-800](file://src/class/httphandler.ts#L1-L800)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||
|
||
## 架构总览
|
||
系统采用“HTTP 服务 + WebSocket/HTTP 信令”的双信令架构，支持公共模式与私有模式两种通信策略。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "客户端"
|
||
FE1["双向视频示例<br/>bidirectional/main.js"]
|
||
FE2["一对一通话示例<br/>onebyone/main.js"]
|
||
PEER["Peer类<br/>peer.js"]
|
||
SEND["输入遥测Sender<br/>sender.js"]
|
||
end
|
||
subgraph "服务端"
|
||
HTTP["HTTP服务<br/>server.ts"]
|
||
WS["WebSocket信令<br/>websocket.ts"]
|
||
WSH["WS处理器<br/>websockethandler.ts"]
|
||
HTH["HTTP处理器<br/>httphandler.ts"]
|
||
SIG["信令路由<br/>signaling.ts"]
|
||
end
|
||
FE1 --> |WebSocket/HTTP| HTTP
|
||
FE2 --> |WebSocket/HTTP| HTTP
|
||
HTTP --> SIG
|
||
HTTP --> WS
|
||
WS --> WSH
|
||
SIG --> HTH
|
||
FE1 --> PEER
|
||
FE2 --> PEER
|
||
FE1 --> SEND
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
|
||
- [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-800](file://src/class/httphandler.ts#L1-L800)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [client/public/bidirectional/js/main.js:1-383](file://client/public/bidirectional/js/main.js#L1-L383)
|
||
- [client/public/onebyone/main.js:1-216](file://client/public/onebyone/main.js#L1-L216)
|
||
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)
|
||
- [client/src/sender.js:1-209](file://client/src/sender.js#L1-L209)
|
||
|
||
## 详细组件分析
|
||
|
||
### WebSocket 信令流程（序列图）
|
||
展示客户端通过 WebSocket 发送/接收信令的典型流程。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant WS as "WebSocket服务器"
|
||
participant H as "WS处理器"
|
||
C->>WS : "connect" 连接建立
|
||
WS->>H : "onConnect(connectionId)"
|
||
H-->>C : "connect" {connectionId, role, participantId}
|
||
C->>WS : "offer" {connectionId, sdp}
|
||
WS->>H : "onOffer(ws, message)"
|
||
H-->>C : "offer" 转发/广播
|
||
C->>WS : "answer" {connectionId, sdp}
|
||
WS->>H : "onAnswer(ws, message)"
|
||
H-->>C : "answer" 转发/广播
|
||
C->>WS : "candidate" {connectionId, candidate, sdpMLineIndex, sdpMid}
|
||
WS->>H : "onCandidate(ws, message)"
|
||
H-->>C : "candidate" 转发/广播
|
||
C->>WS : "disconnect" {connectionId}
|
||
WS->>H : "onDisconnect(ws, connectionId)"
|
||
H-->>C : "disconnect" 通知
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/websocket.ts:65-114](file://src/websocket.ts#L65-L114)
|
||
- [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:309-338](file://src/class/websockethandler.ts#L309-L338)
|
||
|
||
**章节来源**
|
||
- [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 信令轮询流程（序列图）
|
||
展示客户端通过 HTTP 轮询获取信令消息的流程。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant S as "HTTP服务"
|
||
participant R as "信令路由"
|
||
participant H as "HTTP处理器"
|
||
C->>S : "PUT /signaling" 创建会话
|
||
S->>R : "路由到 httphandler"
|
||
R->>H : "createSession()"
|
||
H-->>C : "{sessionId}"
|
||
C->>S : "PUT /signaling/connection" {connectionId}
|
||
S->>R : "路由到 httphandler"
|
||
R->>H : "createConnection()"
|
||
H-->>C : "{connectionId, polite}"
|
||
loop 轮询
|
||
C->>S : "GET /signaling/offer?fromtime=..."
|
||
S->>R : "路由到 httphandler"
|
||
R->>H : "getOffer(fromtime)"
|
||
H-->>C : "{offers}"
|
||
end
|
||
C->>S : "POST /signaling/offer" {sdp}
|
||
S->>R : "路由到 httphandler"
|
||
R->>H : "postOffer()"
|
||
H-->>C : "OK"
|
||
C->>S : "DELETE /signaling" 删除会话
|
||
S->>R : "路由到 httphandler"
|
||
R->>H : "deleteSession()"
|
||
H-->>C : "200"
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/server.ts:25-89](file://src/server.ts#L25-L89)
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
- [src/class/httphandler.ts:661-696](file://src/class/httphandler.ts#L661-L696)
|
||
- [src/class/httphandler.ts:268-318](file://src/class/httphandler.ts#L268-L318)
|
||
- [src/class/httphandler.ts:492-501](file://src/class/httphandler.ts#L492-L501)
|
||
- [src/class/httphandler.ts:549-558](file://src/class/httphandler.ts#L549-L558)
|
||
|
||
**章节来源**
|
||
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)
|
||
|
||
### 前端组件与 WebRTC 集成
|
||
- 双向视频示例（bidirectional）
|
||
- 通过 RenderStreaming 管理连接，动态选择 WebSocket 或 HTTP 信令
|
||
- 使用 Peer 类封装 RTCPeerConnection 生命周期与事件
|
||
- 使用 Sender 类实现鼠标/键盘/手柄/触摸的输入遥测与数据通道发送
|
||
|
||
- 一对一通话示例（onebyone）
|
||
- 基于 store/UIRenderer 的状态管理与 UI 渲染
|
||
- 支持通话请求、接听/拒接、媒体切换、录制控制等
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Peer {
|
||
+connectionId
|
||
+polite
|
||
+pc
|
||
+ontrack()
|
||
+ondatachannel()
|
||
+onicecandidate()
|
||
+onnegotiationneeded()
|
||
+getTransceivers()
|
||
+addTrack()
|
||
+addTransceiver()
|
||
+createDataChannel()
|
||
+getStats()
|
||
+onGotDescription()
|
||
+onGotCandidate()
|
||
}
|
||
class Sender {
|
||
+devices
|
||
+addMouse()
|
||
+addKeyboard()
|
||
+addGamepad()
|
||
+addTouchscreen()
|
||
+_queueStateEvent()
|
||
+_queueTextEvent()
|
||
}
|
||
class Observer {
|
||
+channel
|
||
+onNext(message)
|
||
}
|
||
Sender --> Observer : "通过数据通道发送"
|
||
Peer --> Sender : "配合输入遥测"
|
||
```
|
||
|
||
**图表来源**
|
||
- [client/src/peer.js:3-188](file://client/src/peer.js#L3-L188)
|
||
- [client/src/sender.js:14-209](file://client/src/sender.js#L14-L209)
|
||
|
||
**章节来源**
|
||
- [client/public/bidirectional/js/main.js:1-383](file://client/public/bidirectional/js/main.js#L1-L383)
|
||
- [client/public/onebyone/main.js:1-216](file://client/public/onebyone/main.js#L1-L216)
|
||
- [client/src/peer.js:1-188](file://client/src/peer.js#L1-L188)
|
||
- [client/src/sender.js:1-209](file://client/src/sender.js#L1-L209)
|
||
|
||
### 通信模式与连接组（流程图）
|
||
展示私有模式下的连接组管理与消息转发逻辑。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["进入 onConnect"]) --> CheckPrivate{"是否私有模式?"}
|
||
CheckPrivate --> |否| Public["公共模式: 创建连接组(若无)"]
|
||
CheckPrivate --> |是| Private["私有模式: host/参与者管理"]
|
||
Public --> BroadcastOffer["广播 offer 给其他客户端"]
|
||
Private --> HostCheck{"是否已有 host?"}
|
||
HostCheck --> |否| CreateHost["创建 host 并标记为 polite=false"]
|
||
HostCheck --> |是| AddParticipant["添加为 participant 并通知 host"]
|
||
OfferRoute{"消息来源角色"} --> |host| ToParticipants["转发给所有 participants"]
|
||
OfferRoute --> |participant| ToHost["转发给 host"]
|
||
AnswerRoute{"消息来源角色"} --> |host| ToTarget["转发给指定 participant"]
|
||
AnswerRoute --> |participant| ToHost2["转发给 host"]
|
||
CandidateRoute{"消息来源角色"} --> |host| ToParticipants2["转发给所有 participants"]
|
||
CandidateRoute --> |participant| ToHost3["转发给 host"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [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:309-338](file://src/class/websockethandler.ts#L309-L338)
|
||
|
||
**章节来源**
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
|
||
## 依赖分析
|
||
- 后端依赖
|
||
- express：HTTP 服务框架
|
||
- ws：WebSocket 服务器
|
||
- morgan：HTTP 访问日志
|
||
- cors/multer：跨域与文件上传
|
||
- uuid：会话 ID 生成
|
||
- commander：命令行参数解析
|
||
|
||
- 前端依赖
|
||
- Jest（开发）：单元测试
|
||
- ESLint（开发）：代码规范
|
||
- 浏览器原生 WebRTC API
|
||
|
||
```mermaid
|
||
graph LR
|
||
P["package.json"] --> E["express"]
|
||
P --> W["ws"]
|
||
P --> M["morgan"]
|
||
P --> C["cors"]
|
||
P --> U["uuid"]
|
||
P --> CMD["commander"]
|
||
CP["client/package.json"] --> J["jest"]
|
||
CP --> ESL["eslint"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [package.json:14-46](file://package.json#L14-L46)
|
||
- [client/package.json:9-18](file://client/package.json#L9-L18)
|
||
|
||
**章节来源**
|
||
- [package.json:1-60](file://package.json#L1-L60)
|
||
- [client/package.json:1-19](file://client/package.json#L1-L19)
|
||
|
||
## 性能考虑
|
||
- 信令模式选择
|
||
- WebSocket：低延迟、高吞吐，适合实时交互
|
||
- HTTP 轮询：兼容性更好，适合受限网络或代理环境
|
||
|
||
- 通信模式选择
|
||
- 私有模式：host 与 participants 明确分离，便于控制与扩展
|
||
- 公共模式：广播式转发，适合简单场景但需注意带宽与 CPU 开销
|
||
|
||
- 日志与监控
|
||
- 可配置日志级别，避免生产环境过度输出
|
||
- 建议结合浏览器 WebRTC 统计 API 与服务端日志进行性能分析
|
||
|
||
- 媒体参数
|
||
- 合理设置分辨率、帧率与编解码器偏好，平衡画质与延迟
|
||
|
||
[本节为通用指导，无需具体文件分析]
|
||
|
||
## 故障排查指南
|
||
- 启动与证书
|
||
- HTTPS 启用需提供 server.key 与 server.cert；可通过命令行参数指定路径
|
||
- 若证书缺失，服务将以 HTTP 方式启动
|
||
|
||
- 信令类型校验
|
||
- 仅支持 websocket 与 http 两种类型；非法值会被重置为 websocket
|
||
|
||
- WebSocket 心跳与断开
|
||
- 服务器内置心跳检测（ping/pong），长时间无活动将触发断开
|
||
- 客户端需正确处理断开事件并清理资源
|
||
|
||
- HTTP 会话超时
|
||
- 会话在指定时间内无请求将被清理，避免内存泄漏
|
||
- 客户端应定期轮询或及时释放会话
|
||
|
||
**章节来源**
|
||
- [src/index.ts:75-82](file://src/index.ts#L75-L82)
|
||
- [src/websocket.ts:95-113](file://src/websocket.ts#L95-L113)
|
||
- [src/class/httphandler.ts:218-232](file://src/class/httphandler.ts#L218-L232)
|
||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||
|
||
## 结论
|
||
Video Socket Server 提供了完整的 WebRTC 信令与媒体传输方案，具备灵活的信令与通信模式选择、清晰的前后端分离架构，以及丰富的前端示例。通过合理配置与优化，可在多种实际场景中实现高质量的实时视频通信。
|
||
|
||
[本节为总结性内容，无需具体文件分析]
|
||
|
||
## 附录
|
||
- 快速启动
|
||
- 开发模式：执行脚本 dev，启动 HTTPS 服务，监听指定端口
|
||
- 生产模式：构建后运行 build/index.js，或使用打包工具
|
||
|
||
- 常用接口
|
||
- GET /config：获取运行配置
|
||
- GET /signaling/connection-ids：获取所有连接 ID
|
||
- PUT /signaling：创建会话
|
||
- PUT /signaling/connection：创建连接
|
||
- GET /signaling/offer|answer|candidate：轮询获取信令
|
||
- POST /signaling/offer|answer|candidate：推送信令
|
||
- DELETE /signaling：删除会话
|
||
|
||
**章节来源**
|
||
- [src/server.ts:25-89](file://src/server.ts#L25-L89)
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
- [package.json:5-12](file://package.json#L5-L12) |