# 信令路由系统

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