# 信令路由配置

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