修改

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,403 @@
+# 信令路由系统
+
+<cite>
+**本文档引用的文件**
+- [src/index.ts](file://src/index.ts)
+- [src/server.ts](file://src/server.ts)
+- [src/signaling.ts](file://src/signaling.ts)
+- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
+- [src/class/httphandler.ts](file://src/class/httphandler.ts)
+- [src/websocket.ts](file://src/websocket.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/log.ts](file://src/log.ts)
+- [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. [附录](#附录)
+
+## 简介
+本文件为信令路由系统模块的技术文档，聚焦于 WebSocket 与 HTTP 轮询两种信令模式的实现机制与运行流程。文档详细说明了 HTTP 轮询信令处理器的会话管理、消息缓存与轮询接口设计；解释了信令消息的路由规则、负载均衡与错误恢复机制；并提供不同信令模式的选择指南与性能对比，以及路由配置优化与扩展开发的最佳实践。
+
+## 项目结构
+系统采用分层架构，主要由入口启动、HTTP 服务器、WebSocket 信令、HTTP 轮询处理器、数据模型与日志等模块组成。Express 提供 HTTP 服务与路由，WebSocket 作为实时信令通道，HTTP 轮询提供兼容性支持。Swagger 文档自动生成 API 接口说明，便于调试与集成。
+
+```mermaid
+graph TB
+A["入口启动<br/>src/index.ts"] --> B["HTTP服务器<br/>src/server.ts"]
+B --> C["信令路由<br/>src/signaling.ts"]
+C --> D["WebSocket处理器<br/>src/class/websockethandler.ts"]
+C --> E["HTTP轮询处理器<br/>src/class/httphandler.ts"]
+D --> F["WebSocket信令服务<br/>src/websocket.ts"]
+E --> G["数据模型<br/>Offer/Answer/Candidate"]
+B --> H["Swagger文档<br/>src/swagger.ts"]
+B --> I["日志系统<br/>src/log.ts"]
+```
+
+**图表来源**
+- [src/index.ts:1-109](file://src/index.ts#L1-L109)
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
+- [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/websocket.ts:1-118](file://src/websocket.ts#L1-L118)
+- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+
+**章节来源**
+- [src/index.ts:13-109](file://src/index.ts#L13-L109)
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+
+## 核心组件
+- 信令路由模块：统一暴露 HTTP 轮询接口，包含会话管理、连接管理、信令消息收发与轮询查询。
+- WebSocket 信令模块：基于 ws 库，负责实时双向通信、连接组管理与消息广播。
+- 数据模型：Offer、Answer、Candidate 三类信令消息的数据结构封装。
+- 日志与配置：统一日志级别控制与启动参数解析。
+- Swagger 文档：自动生成 API 文档，支持会话认证头 session-id。
+
+**章节来源**
+- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
+- [src/class/websockethandler.ts:44-168](file://src/class/websockethandler.ts#L44-L168)
+- [src/class/httphandler.ts:91-213](file://src/class/httphandler.ts#L91-L213)
+- [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:44-57](file://src/swagger.ts#L44-L57)
+
+## 架构概览
+系统支持两种信令模式：
+- WebSocket 模式：长连接、低延迟、高吞吐，适合实时互动场景。
+- HTTP 轮询模式：基于 RESTful 接口，客户端周期性轮询获取信令，适配受限网络环境。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant HTTP as "HTTP服务器<br/>src/server.ts"
+participant Router as "信令路由<br/>src/signaling.ts"
+participant WS as "WebSocket处理器<br/>src/class/websockethandler.ts"
+participant WS_Srv as "WebSocket服务<br/>src/websocket.ts"
+participant HTTP_Handler as "HTTP处理器<br/>src/class/httphandler.ts"
+rect rgb(255,255,255)
+Note over Client,HTTP : WebSocket模式
+Client->>WS_Srv : 建立WebSocket连接
+WS_Srv->>WS : 分发消息类型
+WS-->>Client : 实时转发信令
+end
+rect rgb(255,255,255)
+Note over Client,HTTP : HTTP轮询模式
+Client->>HTTP : 发送session-id头
+HTTP->>Router : 路由到signaling
+Router->>HTTP_Handler : 会话校验与处理
+HTTP_Handler-->>Client : 返回信令消息列表
+end
+```
+
+**图表来源**
+- [src/websocket.ts:27-116](file://src/websocket.ts#L27-L116)
+- [src/class/websockethandler.ts:72-206](file://src/class/websockethandler.ts#L72-L206)
+- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+- [src/signaling.ts:6-23](file://src/signaling.ts#L6-L23)
+
+## 详细组件分析
+
+### WebSocket 信令处理器
+WebSocket 处理器负责连接生命周期管理、消息路由与广播。核心能力包括：
+- 连接组管理：host 与 participants 的角色区分与消息定向转发。
+- 心跳检测：定期 ping/pong 维持连接活性，超时自动断开。
+- 广播与定向路由：根据消息类型与角色进行组内广播或跨角色转发。
+- 会话与连接映射：维护客户端到连接 ID 的映射，支持多连接场景。
+
+```mermaid
+classDiagram
+class WebSocket处理器 {
+reset(mode) void
+add(ws) void
+remove(ws) void
+onConnect(ws, connectionId) void
+onDisconnect(ws, connectionId) void
+onOffer(ws, message) void
+onAnswer(ws, message) void
+onCandidate(ws, message) void
+onBroadcast(ws, message) void
+onMessage(ws, message) void
+AddHeartbeat(ws, connectionId) void
+RemoveHeartbeat(ws) void
+onGetAllConnectionIds() string[]
+isHost(ws, connectionId) bool
+broadcastToGroup(connectionId, senderWs, message) void
+}
+class 连接组 {
+host WebSocket
+participants Set~WebSocket~
+}
+WebSocket处理器 --> 连接组 : "管理"
+```
+
+**图表来源**
+- [src/class/websockethandler.ts:13-37](file://src/class/websockethandler.ts#L13-L37)
+- [src/class/websockethandler.ts:44-168](file://src/class/websockethandler.ts#L44-L168)
+- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
+
+**章节来源**
+- [src/class/websockethandler.ts:44-168](file://src/class/websockethandler.ts#L44-L168)
+- [src/class/websockethandler.ts:208-338](file://src/class/websockethandler.ts#L208-L338)
+- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
+
+### HTTP 轮询信令处理器
+HTTP 轮询处理器以 RESTful API 形式提供信令服务，核心功能包括：
+- 会话管理：创建、删除会话，维护会话存活时间戳。
+- 连接管理：创建、删除连接，支持私有模式下的连接对映射。
+- 消息缓存：Offer、Answer、Candidate 按会话与连接 ID 缓存，支持 fromtime 过滤。
+- 断开连接记录：记录断开连接的连接 ID 与时间戳，供轮询查询。
+- 轮询接口：提供 /signaling 与子资源的 GET/POST/PUT/DELETE 接口，统一通过 session-id 头进行鉴权。
+
+```mermaid
+flowchart TD
+Start(["HTTP请求进入"]) --> CheckSession["检查session-id头"]
+CheckSession --> SessionExists{"会话存在？"}
+SessionExists --> |否| Return404["返回404"]
+SessionExists --> |是| UpdateLast["更新最后请求时间"]
+UpdateLast --> Route["路由到具体处理器"]
+Route --> CreateSession["创建会话"]
+Route --> DeleteSession["删除会话"]
+Route --> CreateConnection["创建连接"]
+Route --> DeleteConnection["删除连接"]
+Route --> PostOffer["提交Offer"]
+Route --> PostAnswer["提交Answer"]
+Route --> PostCandidate["提交Candidate"]
+Route --> GetOffer["获取Offer列表"]
+Route --> GetAnswer["获取Answer列表"]
+Route --> GetCandidate["获取Candidate列表"]
+Route --> GetAll["获取所有信令消息"]
+CreateSession --> ReturnOK["返回JSON"]
+DeleteSession --> ReturnOK
+CreateConnection --> ReturnOK
+DeleteConnection --> ReturnOK
+PostOffer --> ReturnOK
+PostAnswer --> ReturnOK
+PostCandidate --> ReturnOK
+GetOffer --> ReturnJSON["返回JSON"]
+GetAnswer --> ReturnJSON
+GetCandidate --> ReturnJSON
+GetAll --> ReturnJSON
+Return404 --> End(["结束"])
+ReturnOK --> End
+ReturnJSON --> End
+```
+
+**图表来源**
+- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+- [src/class/httphandler.ts:664-675](file://src/class/httphandler.ts#L664-L675)
+- [src/class/httphandler.ts:689-696](file://src/class/httphandler.ts#L689-L696)
+- [src/class/httphandler.ts:739-783](file://src/class/httphandler.ts#L739-L783)
+- [src/class/httphandler.ts:815-828](file://src/class/httphandler.ts#L815-L828)
+- [src/class/httphandler.ts:855-886](file://src/class/httphandler.ts#L855-L886)
+- [src/class/httphandler.ts:913-952](file://src/class/httphandler.ts#L913-L952)
+- [src/class/httphandler.ts:985-998](file://src/class/httphandler.ts#L985-L998)
+- [src/class/httphandler.ts:615-641](file://src/class/httphandler.ts#L615-L641)
+
+**章节来源**
+- [src/class/httphandler.ts:91-120](file://src/class/httphandler.ts#L91-L120)
+- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+- [src/class/httphandler.ts:218-232](file://src/class/httphandler.ts#L218-L232)
+- [src/class/httphandler.ts:274-297](file://src/class/httphandler.ts#L274-L297)
+- [src/class/httphandler.ts:398-407](file://src/class/httphandler.ts#L398-L407)
+- [src/class/httphandler.ts:440-447](file://src/class/httphandler.ts#L440-L447)
+- [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/class/httphandler.ts:615-641](file://src/class/httphandler.ts#L615-L641)
+- [src/class/httphandler.ts:739-783](file://src/class/httphandler.ts#L739-L783)
+- [src/class/httphandler.ts:815-828](file://src/class/httphandler.ts#L815-L828)
+- [src/class/httphandler.ts:855-886](file://src/class/httphandler.ts#L855-L886)
+- [src/class/httphandler.ts:913-952](file://src/class/httphandler.ts#L913-L952)
+- [src/class/httphandler.ts:985-998](file://src/class/httphandler.ts#L985-L998)
+
+### 信令消息模型
+Offer、Answer、Candidate 三类消息分别封装 SDP 描述、ICE 候选者信息与时间戳，确保消息缓存与查询的一致性。
+
+```mermaid
+classDiagram
+class Offer {
+string sdp
+number datetime
+boolean polite
+constructor(sdp, datetime, polite)
+}
+class Answer {
+string sdp
+number datetime
+constructor(sdp, datetime)
+}
+class Candidate {
+string candidate
+number sdpMLineIndex
+string sdpMid
+number datetime
+constructor(candidate, sdpMLineIndex, sdpMid, 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)
+
+### WebSocket 信令服务
+WebSocket 服务监听连接事件，解析消息类型并调用处理器对应方法，支持 ping/pong 心跳与广播消息。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant WS_Srv as "WebSocket服务<br/>src/websocket.ts"
+participant Handler as "WebSocket处理器<br/>src/class/websockethandler.ts"
+Client->>WS_Srv : 建立连接
+WS_Srv->>Handler : add(ws)
+Client->>WS_Srv : 发送消息
+WS_Srv->>Handler : 根据type分发
+Handler-->>Client : 转发信令或广播
+Client-->>WS_Srv : 关闭连接
+WS_Srv->>Handler : remove(ws)
+```
+
+**图表来源**
+- [src/websocket.ts:27-116](file://src/websocket.ts#L27-L116)
+- [src/class/websockethandler.ts:72-137](file://src/class/websockethandler.ts#L72-L137)
+
+**章节来源**
+- [src/websocket.ts:27-116](file://src/websocket.ts#L27-L116)
+- [src/class/websockethandler.ts:72-137](file://src/class/websockethandler.ts#L72-L137)
+
+## 依赖关系分析
+- 入口模块负责解析命令行参数、创建 HTTP 服务器与选择信令模式。
+- 服务器模块装配 CORS、静态资源、Swagger 文档与 /signaling 路由。
+- 信令路由模块挂载到 /signaling，内部通过中间件校验 session-id。
+- WebSocket 与 HTTP 处理器共享通信模式配置，保证行为一致性。
+
+```mermaid
+graph TB
+Index["入口<br/>src/index.ts"] --> Server["服务器<br/>src/server.ts"]
+Server --> Signaling["信令路由<br/>src/signaling.ts"]
+Signaling --> WS_Handler["WebSocket处理器<br/>src/class/websockethandler.ts"]
+Signaling --> HTTP_Handler["HTTP处理器<br/>src/class/httphandler.ts"]
+Server --> Swagger["Swagger<br/>src/swagger.ts"]
+Server --> Log["日志<br/>src/log.ts"]
+```
+
+**图表来源**
+- [src/index.ts:52-91](file://src/index.ts#L52-L91)
+- [src/server.ts:16-41](file://src/server.ts#L16-L41)
+- [src/signaling.ts:10-23](file://src/signaling.ts#L10-L23)
+
+**章节来源**
+- [src/index.ts:52-91](file://src/index.ts#L52-L91)
+- [src/server.ts:16-41](file://src/server.ts#L16-L41)
+- [src/signaling.ts:10-23](file://src/signaling.ts#L10-L23)
+
+## 性能考虑
+- WebSocket 模式
+  - 优势：全双工、低延迟、减少 HTTP 开销；心跳机制保障连接活性。
+  - 注意：连接数增长带来内存与 CPU 压力，需结合负载均衡与连接池策略。
+- HTTP 轮询模式
+  - 优势：兼容性好、易于部署；适合弱网或受限环境。
+  - 注意：频繁轮询增加服务器压力，建议合理设置轮询间隔与缓存策略。
+- 会话超时清理
+  - HTTP 轮询处理器按最后请求时间清理超时会话，避免内存泄漏。
+- 负载均衡与扩展
+  - 建议使用反向代理与多实例部署，结合会话亲和或共享存储实现横向扩展。
+
+[本节为通用性能指导，无需列出具体文件来源]
+
+## 故障排查指南
+- 会话不存在
+  - 症状：HTTP 轮询返回 404。
+  - 排查：确认请求头包含有效的 session-id；检查会话是否被超时清理。
+  - 参考：[src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+- 连接 ID 冲突（私有模式）
+  - 症状：创建连接时报错“连接ID已被使用”。
+  - 排查：检查连接对映射，确保同一 connectionId 仅在两个会话间配对。
+  - 参考：[src/class/httphandler.ts:754-776](file://src/class/httphandler.ts#L754-L776)
+- 信令消息缺失
+  - 症状：轮询未返回预期消息。
+  - 排查：确认 fromtime 参数与消息时间戳；检查是否被超时清理。
+  - 参考：[src/class/httphandler.ts:274-297](file://src/class/httphandler.ts#L274-L297)
+- WebSocket 连接异常断开
+  - 症状：心跳超时触发断开。
+  - 排查：检查客户端 ping/pong 交互；确认网络稳定性。
+  - 参考：[src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
+- Swagger 文档不可用
+  - 症状：/api-docs 无法访问。
+  - 排查：确认 Swagger 初始化与服务器地址配置正确。
+  - 参考：[src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
+
+**章节来源**
+- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+- [src/class/httphandler.ts:754-776](file://src/class/httphandler.ts#L754-L776)
+- [src/class/httphandler.ts:274-297](file://src/class/httphandler.ts#L274-L297)
+- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
+- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
+
+## 结论
+本信令路由系统通过 WebSocket 与 HTTP 轮询两种模式满足不同网络与部署需求。WebSocket 提供低延迟实时通信，HTTP 轮询提供兼容性与易用性。HTTP 处理器通过会话与连接映射、消息缓存与超时清理机制，确保在高并发场景下的稳定性。建议根据业务场景选择合适模式，并结合负载均衡与监控体系持续优化。
+
+[本节为总结性内容，无需列出具体文件来源]
+
+## 附录
+
+### 信令模式选择指南
+- 优先选择 WebSocket：实时性要求高、网络稳定、客户端支持良好。
+- 选择 HTTP 轮询：受限网络、防火墙严格、客户端仅支持 HTTP/HTTPS。
+- 混合策略：在 WebSocket 不可用时回退至 HTTP 轮询，提升兼容性。
+
+[本节为通用指导，无需列出具体文件来源]
+
+### 配置与启动
+- 启动参数
+  - -p/--port：监听端口
+  - -s/--secure：启用 HTTPS
+  - -k/--keyfile/-c/--certfile：证书与密钥文件
+  - -t/--type：信令类型（websocket 或 http）
+  - -m/--mode：通信模式（public 或 private）
+  - -l/--logging：HTTP 日志格式
+- 示例脚本
+  - 开发模式：dev
+  - 生产模式：start
+
+**章节来源**
+- [src/index.ts:20-40](file://src/index.ts#L20-L40)
+- [package.json:5-12](file://package.json#L5-L12)
+
+### API 文档与安全
+- Swagger 文档：/api-docs
+- 认证方式：session-id 头部
+- 会话超时：HTTP 轮询处理器内置超时清理逻辑
+
+**章节来源**
+- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
+- [src/class/httphandler.ts:218-232](file://src/class/httphandler.ts#L218-L232)
+
+### 测试参考
+- WebSocket 单元测试：覆盖公共与私有模式下的连接、消息路由与断开流程。
+- HTTP 单元测试：覆盖会话创建/删除、连接管理、消息提交与轮询查询、超时清理等场景。
+
+**章节来源**
+- [test/websockethandler.test.ts:9-191](file://test/websockethandler.test.ts#L9-L191)
+- [test/httphandler.test.ts:6-510](file://test/httphandler.test.ts#L6-L510)