Files

stary 6c13817527 修改

2026-05-16 13:24:02 +08:00

18 KiB

Raw Permalink Blame History

信令路由系统

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

简介

本文件为信令路由系统模块的技术文档，聚焦于 WebSocket 与 HTTP 轮询两种信令模式的实现机制与运行流程。文档详细说明了 HTTP 轮询信令处理器的会话管理、消息缓存与轮询接口设计；解释了信令消息的路由规则、负载均衡与错误恢复机制；并提供不同信令模式的选择指南与性能对比，以及路由配置优化与扩展开发的最佳实践。

项目结构

系统采用分层架构，主要由入口启动、HTTP 服务器、WebSocket 信令、HTTP 轮询处理器、数据模型与日志等模块组成。Express 提供 HTTP 服务与路由，WebSocket 作为实时信令通道，HTTP 轮询提供兼容性支持。Swagger 文档自动生成 API 接口说明，便于调试与集成。

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"]

图表来源

章节来源

核心组件

信令路由模块：统一暴露 HTTP 轮询接口，包含会话管理、连接管理、信令消息收发与轮询查询。
WebSocket 信令模块：基于 ws 库，负责实时双向通信、连接组管理与消息广播。
数据模型：Offer、Answer、Candidate 三类信令消息的数据结构封装。
日志与配置：统一日志级别控制与启动参数解析。
Swagger 文档：自动生成 API 文档，支持会话认证头 session-id。

章节来源

架构概览

系统支持两种信令模式：

WebSocket 模式：长连接、低延迟、高吞吐，适合实时互动场景。
HTTP 轮询模式：基于 RESTful 接口，客户端周期性轮询获取信令，适配受限网络环境。

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

图表来源

详细组件分析

WebSocket 信令处理器

WebSocket 处理器负责连接生命周期管理、消息路由与广播。核心能力包括：

连接组管理：host 与 participants 的角色区分与消息定向转发。
心跳检测：定期 ping/pong 维持连接活性，超时自动断开。
广播与定向路由：根据消息类型与角色进行组内广播或跨角色转发。
会话与连接映射：维护客户端到连接 ID 的映射，支持多连接场景。

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处理器 --> 连接组 : "管理"

图表来源

章节来源

HTTP 轮询信令处理器

HTTP 轮询处理器以 RESTful API 形式提供信令服务，核心功能包括：

会话管理：创建、删除会话，维护会话存活时间戳。
连接管理：创建、删除连接，支持私有模式下的连接对映射。
消息缓存：Offer、Answer、Candidate 按会话与连接 ID 缓存，支持 fromtime 过滤。
断开连接记录：记录断开连接的连接 ID 与时间戳，供轮询查询。
轮询接口：提供 /signaling 与子资源的 GET/POST/PUT/DELETE 接口，统一通过 session-id 头进行鉴权。

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

图表来源

章节来源

信令消息模型

Offer、Answer、Candidate 三类消息分别封装 SDP 描述、ICE 候选者信息与时间戳，确保消息缓存与查询的一致性。

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)
}

图表来源

章节来源

WebSocket 信令服务

WebSocket 服务监听连接事件，解析消息类型并调用处理器对应方法，支持 ping/pong 心跳与广播消息。

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)

图表来源

章节来源

依赖关系分析

入口模块负责解析命令行参数、创建 HTTP 服务器与选择信令模式。
服务器模块装配 CORS、静态资源、Swagger 文档与 /signaling 路由。
信令路由模块挂载到 /signaling，内部通过中间件校验 session-id。
WebSocket 与 HTTP 处理器共享通信模式配置，保证行为一致性。

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"]

图表来源

章节来源

性能考虑

WebSocket 模式
- 优势：全双工、低延迟、减少 HTTP 开销；心跳机制保障连接活性。
- 注意：连接数增长带来内存与 CPU 压力，需结合负载均衡与连接池策略。
HTTP 轮询模式
- 优势：兼容性好、易于部署；适合弱网或受限环境。
- 注意：频繁轮询增加服务器压力，建议合理设置轮询间隔与缓存策略。
会话超时清理
- HTTP 轮询处理器按最后请求时间清理超时会话，避免内存泄漏。
负载均衡与扩展
- 建议使用反向代理与多实例部署，结合会话亲和或共享存储实现横向扩展。

[本节为通用性能指导，无需列出具体文件来源]

故障排查指南

会话不存在
- 症状：HTTP 轮询返回 404。
- 排查：确认请求头包含有效的 session-id；检查会话是否被超时清理。
- 参考：src/class/httphandler.ts:128-145
连接 ID 冲突（私有模式）
- 症状：创建连接时报错“连接ID已被使用”。
- 排查：检查连接对映射，确保同一 connectionId 仅在两个会话间配对。
- 参考：src/class/httphandler.ts:754-776
信令消息缺失
- 症状：轮询未返回预期消息。
- 排查：确认 fromtime 参数与消息时间戳；检查是否被超时清理。
- 参考：src/class/httphandler.ts:274-297
WebSocket 连接异常断开
- 症状：心跳超时触发断开。
- 排查：检查客户端 ping/pong 交互；确认网络稳定性。
- 参考：src/class/websockethandler.ts:404-430
Swagger 文档不可用
- 症状：/api-docs 无法访问。
- 排查：确认 Swagger 初始化与服务器地址配置正确。
- 参考：src/swagger.ts:16-65

章节来源

结论

本信令路由系统通过 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

章节来源

API 文档与安全

Swagger 文档：/api-docs
认证方式：session-id 头部
会话超时：HTTP 轮询处理器内置超时清理逻辑

章节来源

测试参考

WebSocket 单元测试：覆盖公共与私有模式下的连接、消息路由与断开流程。
HTTP 单元测试：覆盖会话创建/删除、连接管理、消息提交与轮询查询、超时清理等场景。

章节来源

18 KiB Raw Permalink Blame History Unescape Escape

信令路由系统

目录

简介

项目结构

核心组件

架构概览

详细组件分析

WebSocket 信令处理器

HTTP 轮询信令处理器

信令消息模型

WebSocket 信令服务

依赖关系分析

性能考虑

故障排查指南

结论

附录

信令模式选择指南

配置与启动

API 文档与安全

测试参考

18 KiB

Raw Permalink Blame History