修改

2026-05-16 13:24:02 +08:00
parent eae60714b4
commit 6c13817527
42 changed files with 15921 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/项目概述.md
+++ b/.qoder/repowiki/zh/content/项目概述.md
@@ -0,0 +1,439 @@
+# 项目概述
+
+<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)