403 lines
18 KiB
Markdown
403 lines
18 KiB
Markdown
# 信令路由系统
|
||
|
||
<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) |