340 lines
15 KiB
Markdown
340 lines
15 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/websocket.ts](file://src/websocket.ts)
|
||
- [src/class/httphandler.ts](file://src/class/httphandler.ts)
|
||
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
|
||
- [src/class/options.ts](file://src/class/options.ts)
|
||
- [src/log.ts](file://src/log.ts)
|
||
- [src/swagger.ts](file://src/swagger.ts)
|
||
- [package.json](file://package.json)
|
||
- [test/httphandler.test.ts](file://test/httphandler.test.ts)
|
||
- [test/websockethandler.test.ts](file://test/websockethandler.test.ts)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向信令服务器的路由配置与运行机制，覆盖 WebSocket 与 HTTP 两种信令模式的路由规则、中间件与消息分发逻辑、端点配置项（端口、SSL 证书、CORS）、启动流程与配置参数、最佳实践与性能优化、故障排除与常见问题，以及实际配置示例与部署注意事项。
|
||
|
||
## 项目结构
|
||
- 应用入口与启动：命令行参数解析、HTTP/HTTPS 服务器创建、WebSocket 信令服务启动。
|
||
- 服务器配置：Express 中间件、CORS、日志、静态资源、Swagger 文档。
|
||
- 信令路由：HTTP 路由挂载至 /signaling；WebSocket 信令服务独立于 HTTP 服务。
|
||
- 处理器：HTTP 与 WebSocket 两类处理器分别管理会话、连接、信令消息与广播。
|
||
|
||
```mermaid
|
||
graph TB
|
||
A["命令行入口<br/>src/index.ts"] --> B["Express 应用创建<br/>src/server.ts"]
|
||
B --> C["HTTP 信令路由挂载<br/>src/signaling.ts"]
|
||
B --> D["静态资源与上传接口<br/>src/server.ts"]
|
||
B --> E["Swagger 文档<br/>src/swagger.ts"]
|
||
A --> F["HTTPS/HTTP 服务器启动<br/>src/index.ts"]
|
||
F --> G["WebSocket 信令服务<br/>src/websocket.ts"]
|
||
G --> H["WebSocket 处理器<br/>src/class/websockethandler.ts"]
|
||
C --> I["HTTP 处理器<br/>src/class/httphandler.ts"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/websockethandler.ts:63-137](file://src/class/websockethandler.ts#L63-L137)
|
||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
|
||
## 核心组件
|
||
- 选项解析与启动流程：命令行参数解析、HTTPS/HTTP 选择、端口、日志级别、信令模式与通信模式。
|
||
- Express 应用与中间件：CORS、日志、静态资源、上传接口、Swagger。
|
||
- HTTP 信令路由：/signaling 下的 GET/PUT/DELETE/POST 路由，配合会话 ID 中间件。
|
||
- WebSocket 信令服务：独立于 HTTP 的 ws 服务器，消息类型与广播逻辑。
|
||
- 处理器：HTTP 处理器（会话/连接/信令存储与查询）、WebSocket 处理器（连接组、广播、心跳）。
|
||
|
||
**章节来源**
|
||
- [src/index.ts:16-42](file://src/index.ts#L16-L42)
|
||
- [src/server.ts:18-22](file://src/server.ts#L18-L22)
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
- [src/websocket.ts:15-118](file://src/websocket.ts#L15-L118)
|
||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||
- [src/class/websockethandler.ts:63-137](file://src/class/websockethandler.ts#L63-L137)
|
||
|
||
## 架构总览
|
||
信令服务器同时支持 HTTP 与 WebSocket 两种模式：
|
||
- HTTP 模式：通过 /signaling 路由进行轮询式信令交换，依赖 session-id 请求头进行会话隔离。
|
||
- WebSocket 模式：通过独立的 ws 服务器进行实时双向通信，支持广播、1对多连接组、心跳检测与断线通知。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant HTTP as "HTTP 服务器<br/>Express"
|
||
participant Sig as "HTTP 信令路由<br/>/signaling"
|
||
participant Hdl as "HTTP 处理器"
|
||
participant WS as "WebSocket 服务器"
|
||
participant WSH as "WebSocket 处理器"
|
||
Client->>HTTP : "GET /config"
|
||
HTTP-->>Client : "{useWebSocket, startupMode, logging}"
|
||
Client->>HTTP : "PUT /signaling (创建会话)"
|
||
HTTP->>Sig : "路由匹配"
|
||
Sig->>Hdl : "createSession()"
|
||
Hdl-->>HTTP : "返回 sessionId"
|
||
HTTP-->>Client : "sessionId"
|
||
Note over Client,HTTP : "HTTP 轮询模式"
|
||
Client->>HTTP : "GET /signaling/offer?fromtime=..."
|
||
HTTP->>Sig : "路由匹配"
|
||
Sig->>Hdl : "getOffer()"
|
||
Hdl-->>HTTP : "返回 offer 列表"
|
||
HTTP-->>Client : "信令数据"
|
||
Note over Client,WS : "WebSocket 实时模式"
|
||
Client->>WS : "建立 ws : //... 连接"
|
||
WS->>WSH : "connection 事件"
|
||
WSH->>Client : "connect 消息"
|
||
Client->>WS : "发送 offer/answer/candidate"
|
||
WS->>WSH : "onOffer/onAnswer/onCandidate"
|
||
WSH-->>Client : "转发对应信令"
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/server.ts:25-29](file://src/server.ts#L25-L29)
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
- [src/class/httphandler.ts:661-675](file://src/class/httphandler.ts#L661-L675)
|
||
- [src/class/httphandler.ts:492-501](file://src/class/httphandler.ts#L492-L501)
|
||
- [src/websocket.ts:27-115](file://src/websocket.ts#L27-L115)
|
||
- [src/class/websockethandler.ts:145-168](file://src/class/websockethandler.ts#L145-L168)
|
||
|
||
## 详细组件分析
|
||
|
||
### HTTP 信令路由与中间件
|
||
- 路由挂载：/signaling 下的 GET/PUT/DELETE/POST 路由，统一由 HTTP 处理器实现。
|
||
- 会话中间件：校验请求头 session-id 是否存在，不存在则返回 404；存在则更新会话最后请求时间。
|
||
- 会话与连接管理：创建/删除会话、创建/删除连接、查询连接列表、查询所有信令消息。
|
||
- 信令存储与查询：Offer/Answer/Candidate 存储与按时间过滤查询；公共/私有模式下的路由差异。
|
||
- CORS 与日志：全局启用 CORS（允许任意源），按配置输出 HTTP 访问日志。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["HTTP 请求进入 /signaling"]) --> CheckSession["检查 session-id 头部"]
|
||
CheckSession --> SessionExists{"会话存在？"}
|
||
SessionExists --> |否| Return404["返回 404"]
|
||
SessionExists --> |是| UpdateTime["更新会话最后请求时间"]
|
||
UpdateTime --> RouteMatch["匹配具体路由"]
|
||
RouteMatch --> Handler["调用对应 HTTP 处理器函数"]
|
||
Handler --> Store["存储/查询信令数据"]
|
||
Store --> Response["返回 JSON 响应"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||
- [src/class/httphandler.ts:398-407](file://src/class/httphandler.ts#L398-L407)
|
||
|
||
**章节来源**
|
||
- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
|
||
- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||
- [src/class/httphandler.ts:398-407](file://src/class/httphandler.ts#L398-L407)
|
||
|
||
### WebSocket 信令服务与消息分发
|
||
- 服务器创建：基于现有 HTTP 服务器创建 ws 服务器，独立于 HTTP。
|
||
- 连接生命周期：连接建立、消息处理、断开清理。
|
||
- 消息类型：connect/disconnect/offer/answer/candidate/broadcast/ping/pong/call-request/on-message。
|
||
- 1对多模式：host 与 participants 的角色与消息路由；广播到组内成员；断线通知。
|
||
- 心跳检测：定期 ping/pong，超时自动断开。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant WS as "WebSocket 服务器"
|
||
participant WSH as "WebSocket 处理器"
|
||
participant C1 as "客户端1(host)"
|
||
participant C2 as "客户端2(participant)"
|
||
WS->>WSH : "connection(ws)"
|
||
WSH->>C1 : "connect {role : host}"
|
||
WSH->>C2 : "connect {role : participant}"
|
||
C1->>WS : "offer {connectionId, sdp}"
|
||
WS->>WSH : "onOffer"
|
||
WSH-->>C2 : "转发 offer"
|
||
C2->>WS : "answer {connectionId, sdp}"
|
||
WS->>WSH : "onAnswer"
|
||
WSH-->>C1 : "转发 answer"
|
||
C1->>WS : "broadcast {message}"
|
||
WS->>WSH : "onBroadcast"
|
||
WSH-->>C2 : "广播消息"
|
||
C1->>WS : "disconnect"
|
||
WS->>WSH : "onDisconnect"
|
||
WSH-->>C2 : "通知 host 离开"
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/websocket.ts:27-115](file://src/websocket.ts#L27-L115)
|
||
- [src/class/websockethandler.ts:145-301](file://src/class/websockethandler.ts#L145-L301)
|
||
- [src/class/websockethandler.ts:370-402](file://src/class/websockethandler.ts#L370-L402)
|
||
|
||
**章节来源**
|
||
- [src/websocket.ts:15-118](file://src/websocket.ts#L15-L118)
|
||
- [src/class/websockethandler.ts:145-301](file://src/class/websockethandler.ts#L145-L301)
|
||
- [src/class/websockethandler.ts:370-402](file://src/class/websockethandler.ts#L370-L402)
|
||
|
||
### 选项与启动流程
|
||
- 命令行参数：端口、HTTPS 开关、证书路径、信令类型（websocket/http）、通信模式（public/private）、日志级别。
|
||
- 服务器创建：根据 secure 选择 HTTPS 或 HTTP；读取 key/cert 文件；监听端口并打印访问地址。
|
||
- 信令类型校验：非 websocket/http 的值将被修正为 websocket 并给出警告。
|
||
- WebSocket 启动：当 type 为 websocket 时，创建 WSSignaling 实例并传入通信模式。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Parse["解析命令行参数"] --> CreateApp["创建 Express 应用"]
|
||
CreateApp --> Secure{"secure ?"}
|
||
Secure --> |是| HTTPS["创建 HTTPS 服务器"]
|
||
Secure --> |否| HTTP["创建 HTTP 服务器"]
|
||
HTTPS --> Listen["监听端口并打印地址"]
|
||
HTTP --> Listen
|
||
Listen --> Type{"type == http ?"}
|
||
Type --> |是| LogHttp["记录使用 HTTP 轮询"]
|
||
Type --> |否| FixType["修正为 websocket 并记录警告"]
|
||
LogHttp --> Done
|
||
FixType --> Done
|
||
Done --> WS{"type == websocket ?"}
|
||
WS --> |是| StartWS["启动 WebSocket 信令服务"]
|
||
WS --> |否| End
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/index.ts:20-42](file://src/index.ts#L20-L42)
|
||
- [src/index.ts:55-82](file://src/index.ts#L55-L82)
|
||
- [src/index.ts:87-88](file://src/index.ts#L87-L88)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:20-42](file://src/index.ts#L20-L42)
|
||
- [src/index.ts:55-82](file://src/index.ts#L55-L82)
|
||
- [src/index.ts:87-88](file://src/index.ts#L87-L88)
|
||
|
||
### CORS 与静态资源
|
||
- CORS：全局启用，允许任意源访问。
|
||
- 静态资源：/ 与 /module 路径的静态文件服务。
|
||
- 上传接口：multer 存储头像到 uploads/avatars，重命名为以 userId 命名的文件并返回访问路径。
|
||
|
||
**章节来源**
|
||
- [src/server.ts:22](file://src/server.ts#L22)
|
||
- [src/server.ts:27-28](file://src/server.ts#L27-L28)
|
||
- [src/server.ts:62-86](file://src/server.ts#L62-L86)
|
||
|
||
### Swagger 文档
|
||
- 自动扫描 HTTP 处理器与路由文件，生成 OpenAPI 文档，暴露 /api-docs。
|
||
- 使用 session-id 作为 API Key 安全方案。
|
||
|
||
**章节来源**
|
||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||
|
||
## 依赖关系分析
|
||
|
||
```mermaid
|
||
graph LR
|
||
Index["src/index.ts"] --> Server["src/server.ts"]
|
||
Index --> WS["src/websocket.ts"]
|
||
Server --> Sig["src/signaling.ts"]
|
||
Sig --> Hdl["src/class/httphandler.ts"]
|
||
WS --> WSH["src/class/websockethandler.ts"]
|
||
Server --> Swagger["src/swagger.ts"]
|
||
Server --> Log["src/log.ts"]
|
||
Index --> Opt["src/class/options.ts"]
|
||
Package["package.json"] --> Server
|
||
Package --> WS
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||
- [src/class/websockethandler.ts:63-137](file://src/class/websockethandler.ts#L63-L137)
|
||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||
- [src/log.ts:15-24](file://src/log.ts#L15-L24)
|
||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||
- [package.json:14-27](file://package.json#L14-L27)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [package.json:14-27](file://package.json#L14-L27)
|
||
|
||
## 性能考量
|
||
- HTTP 轮询 vs WebSocket：WebSocket 适合低延迟实时通信；HTTP 轮询简单但有额外网络开销。
|
||
- 会话超时：HTTP 处理器按 10 秒超时清理长时间无请求的会话，避免内存泄漏。
|
||
- 广播与路由：WebSocket 广播需注意组内成员数量，避免大规模广播造成拥塞。
|
||
- 日志级别：生产环境建议降低日志级别，减少 I/O 压力。
|
||
- 静态资源与上传：确保上传目录存在并限制文件大小，避免磁盘压力。
|
||
|
||
[本节为通用指导，无需列出具体文件来源]
|
||
|
||
## 故障排除指南
|
||
- 会话不存在：HTTP 路由在缺少 session-id 或会话不存在时返回 404。
|
||
- 会话超时：长时间无请求导致会话被清理，重新创建会话并获取新的 session-id。
|
||
- 信令类型错误：非 websocket/http 的 type 将被修正为 websocket 并记录警告。
|
||
- CORS 问题：默认允许任意源，若遇到跨域，请检查客户端与服务器同源策略。
|
||
- 上传失败：确认 uploads/avatars 目录存在且可写，检查文件名重命名逻辑。
|
||
|
||
**章节来源**
|
||
- [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/index.ts:78-82](file://src/index.ts#L78-L82)
|
||
- [src/server.ts:22](file://src/server.ts#L22)
|
||
- [src/server.ts:44-57](file://src/server.ts#L44-L57)
|
||
|
||
## 结论
|
||
本信令服务器通过 Express 提供 HTTP 轮询与 WebSocket 实时两种信令模式，结合会话与连接管理、CORS、日志与 Swagger 文档，形成完整的信令基础设施。合理配置端口、SSL 证书与通信模式，可满足不同场景需求；通过测试用例可验证 HTTP 与 WebSocket 的行为一致性。
|
||
|
||
[本节为总结性内容，无需列出具体文件来源]
|
||
|
||
## 附录
|
||
|
||
### 信令端点配置选项
|
||
- 端口：通过命令行参数 -p/--port 指定，默认来自环境变量 PORT。
|
||
- SSL 证书：通过 -s/--secure 开启 HTTPS，-k/--keyfile 与 -c/--certfile 指定密钥与证书路径。
|
||
- 信令类型：-t/--type 选择 websocket 或 http。
|
||
- 通信模式：-m/--mode 选择 public 或 private。
|
||
- 日志级别：-l/--logging 选择 combined/dev/short/tiny 或 none。
|
||
|
||
**章节来源**
|
||
- [src/index.ts:20-29](file://src/index.ts#L20-L29)
|
||
- [package.json:9-10](file://package.json#L9-L10)
|
||
|
||
### 启动流程与配置参数
|
||
- 启动命令示例：参考 package.json 中的 start/dev 脚本，包含端口、模式、证书等参数。
|
||
- 服务器启动：根据 secure 决定 HTTPS/HTTP；打印访问地址；根据 type 启动 WebSocket 或记录 HTTP 轮询模式。
|
||
|
||
**章节来源**
|
||
- [package.json:9-10](file://package.json#L9-L10)
|
||
- [src/index.ts:55-82](file://src/index.ts#L55-L82)
|
||
|
||
### 路由配置最佳实践
|
||
- 优先使用 WebSocket：实时性要求高时采用 WebSocket，HTTP 轮询仅用于兼容性或受限网络。
|
||
- 明确通信模式：public 模式下跨会话广播；private 模式下严格按连接组路由。
|
||
- 控制日志级别：生产环境避免高频日志，必要时仅保留 warn/info。
|
||
- CORS 与静态资源：生产环境建议限制 CORS 源，静态资源开启缓存策略。
|
||
|
||
[本节为通用指导，无需列出具体文件来源]
|
||
|
||
### 实际配置示例与部署注意事项
|
||
- 示例：使用 HTTPS，端口 8080，private 模式，WebSocket 信令。
|
||
- 部署：确保 server.key 与 server.cert 存在；防火墙开放端口；反向代理（如 Nginx）可前置以支持 TLS 终止与负载均衡。
|
||
|
||
**章节来源**
|
||
- [package.json:9-10](file://package.json#L9-L10)
|
||
- [src/index.ts:55-65](file://src/index.ts#L55-L65) |