video_socket-server/.qoder/repowiki/zh/content/信令系统/信令路由配置.md

信令路由配置

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

目录

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 两类处理器分别管理会话、连接、信令消息与广播。

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
• src/server.ts:14-89
• src/signaling.ts:4-24
• src/websocket.ts:6-118
• src/class/websockethandler.ts:63-137
• src/class/httphandler.ts:110-120

章节来源

• src/index.ts:13-109
• src/server.ts:14-89

核心组件

• 选项解析与启动流程：命令行参数解析、HTTPS/HTTP 选择、端口、日志级别、信令模式与通信模式。
• Express 应用与中间件：CORS、日志、静态资源、上传接口、Swagger。
• HTTP 信令路由：/signaling 下的 GET/PUT/DELETE/POST 路由，配合会话 ID 中间件。
• WebSocket 信令服务：独立于 HTTP 的 ws 服务器，消息类型与广播逻辑。
• 处理器：HTTP 处理器（会话/连接/信令存储与查询）、WebSocket 处理器（连接组、广播、心跳）。

章节来源

• src/index.ts:16-42
• src/server.ts:18-22
• src/signaling.ts:6-24
• src/websocket.ts:15-118
• src/class/httphandler.ts:110-120
• src/class/websockethandler.ts:63-137

架构总览

信令服务器同时支持 HTTP 与 WebSocket 两种模式：

• HTTP 模式：通过 /signaling 路由进行轮询式信令交换，依赖 session-id 请求头进行会话隔离。
• WebSocket 模式：通过独立的 ws 服务器进行实时双向通信，支持广播、1对多连接组、心跳检测与断线通知。

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
• src/signaling.ts:6-24
• src/class/httphandler.ts:661-675
• src/class/httphandler.ts:492-501
• src/websocket.ts:27-115
• src/class/websockethandler.ts:145-168

详细组件分析

HTTP 信令路由与中间件

• 路由挂载：/signaling 下的 GET/PUT/DELETE/POST 路由，统一由 HTTP 处理器实现。
• 会话中间件：校验请求头 session-id 是否存在，不存在则返回 404；存在则更新会话最后请求时间。
• 会话与连接管理：创建/删除会话、创建/删除连接、查询连接列表、查询所有信令消息。
• 信令存储与查询：Offer/Answer/Candidate 存储与按时间过滤查询；公共/私有模式下的路由差异。
• CORS 与日志：全局启用 CORS（允许任意源），按配置输出 HTTP 访问日志。

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
• src/class/httphandler.ts:128-145
• src/class/httphandler.ts:398-407

章节来源

• src/signaling.ts:6-24
• src/class/httphandler.ts:128-145
• src/class/httphandler.ts:398-407

WebSocket 信令服务与消息分发

• 服务器创建：基于现有 HTTP 服务器创建 ws 服务器，独立于 HTTP。
• 连接生命周期：连接建立、消息处理、断开清理。
• 消息类型：connect/disconnect/offer/answer/candidate/broadcast/ping/pong/call-request/on-message。
• 1对多模式：host 与 participants 的角色与消息路由；广播到组内成员；断线通知。
• 心跳检测：定期 ping/pong，超时自动断开。

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
• src/class/websockethandler.ts:145-301
• src/class/websockethandler.ts:370-402

章节来源

• src/websocket.ts:15-118
• src/class/websockethandler.ts:145-301
• src/class/websockethandler.ts:370-402

选项与启动流程

• 命令行参数：端口、HTTPS 开关、证书路径、信令类型（websocket/http）、通信模式（public/private）、日志级别。
• 服务器创建：根据 secure 选择 HTTPS 或 HTTP；读取 key/cert 文件；监听端口并打印访问地址。
• 信令类型校验：非 websocket/http 的值将被修正为 websocket 并给出警告。
• WebSocket 启动：当 type 为 websocket 时，创建 WSSignaling 实例并传入通信模式。

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
• src/index.ts:55-82
• src/index.ts:87-88

章节来源

• src/index.ts:20-42
• src/index.ts:55-82
• src/index.ts:87-88

CORS 与静态资源

• CORS：全局启用，允许任意源访问。
• 静态资源：/ 与 /module 路径的静态文件服务。
• 上传接口：multer 存储头像到 uploads/avatars，重命名为以 userId 命名的文件并返回访问路径。

章节来源

• src/server.ts:22
• src/server.ts:27-28
• src/server.ts:62-86

Swagger 文档

• 自动扫描 HTTP 处理器与路由文件，生成 OpenAPI 文档，暴露 /api-docs。
• 使用 session-id 作为 API Key 安全方案。

章节来源

• src/swagger.ts:16-65

依赖关系分析

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
• src/server.ts:14-89
• src/signaling.ts:4-24
• src/websocket.ts:6-118
• src/class/httphandler.ts:110-120
• src/class/websockethandler.ts:63-137
• src/swagger.ts:16-65
• src/log.ts:15-24
• src/class/options.ts:1-10
• package.json:14-27

章节来源

• src/index.ts:13-109
• src/server.ts:14-89
• package.json:14-27

性能考量

• 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
• src/class/httphandler.ts:218-232
• src/index.ts:78-82
• src/server.ts:22
• src/server.ts:44-57

结论

本信令服务器通过 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
• package.json:9-10

启动流程与配置参数

• 启动命令示例：参考 package.json 中的 start/dev 脚本，包含端口、模式、证书等参数。
• 服务器启动：根据 secure 决定 HTTPS/HTTP；打印访问地址；根据 type 启动 WebSocket 或记录 HTTP 轮询模式。

章节来源

• package.json:9-10
• src/index.ts:55-82

路由配置最佳实践

• 优先使用 WebSocket：实时性要求高时采用 WebSocket，HTTP 轮询仅用于兼容性或受限网络。
• 明确通信模式：public 模式下跨会话广播；private 模式下严格按连接组路由。
• 控制日志级别：生产环境避免高频日志，必要时仅保留 warn/info。
• CORS 与静态资源：生产环境建议限制 CORS 源，静态资源开启缓存策略。

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

实际配置示例与部署注意事项

• 示例：使用 HTTPS，端口 8080，private 模式，WebSocket 信令。
• 部署：确保 server.key 与 server.cert 存在；防火墙开放端口；反向代理（如 Nginx）可前置以支持 TLS 终止与负载均衡。

章节来源

• package.json:9-10
• src/index.ts:55-65