18 KiB
18 KiB
服务器核心
**本文引用的文件** - [src/index.ts](file://src/index.ts) - [src/server.ts](file://src/server.ts) - [src/websocket.ts](file://src/websocket.ts) - [src/signaling.ts](file://src/signaling.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/swagger.ts](file://src/swagger.ts) - [src/log.ts](file://src/log.ts) - [src/服务端接口与WebSocket消息类型.md](file://src/服务端接口与WebSocket消息类型.md) - [package.json](file://package.json) - [run.bat](file://run.bat)目录
简介
本文件面向服务器核心模块，系统化阐述以下主题：
- 服务器入口点的设计与实现：命令行参数解析、配置加载与服务器启动流程
- HTTP 服务器与 WebSocket 服务器的配置与管理：HTTPS 支持、CORS 配置、中间件集成
- 信令路由系统：HTTP 轮询与 WebSocket 的路由处理
- 日志系统集成与配置选项
- 性能优化建议与监控指标
- 具体的代码示例与配置文件模板
项目结构
服务器核心由入口模块、Express 服务器装配、信令路由、WebSocket 信令服务器以及日志与 Swagger 文档配置组成。核心文件如下：
- 入口与启动：src/index.ts
- 服务器装配：src/server.ts
- 信令路由（HTTP）：src/signaling.ts
- WebSocket 信令：src/websocket.ts
- HTTP 信令处理器：src/class/httphandler.ts
- WebSocket 信令处理器：src/class/websockethandler.ts
- 配置选项接口：src/class/options.ts
- Swagger 文档：src/swagger.ts
- 日志工具：src/log.ts
- 接口与消息类型文档：src/服务端接口与WebSocket消息类型.md
- 启动脚本与包配置：package.json、run.bat
graph TB
A["入口模块<br/>src/index.ts"] --> B["服务器装配<br/>src/server.ts"]
B --> C["HTTP 信令路由<br/>src/signaling.ts"]
B --> D["静态资源与上传<br/>src/server.ts"]
A --> E["WebSocket 信令服务器<br/>src/websocket.ts"]
C --> F["HTTP 信令处理器<br/>src/class/httphandler.ts"]
E --> G["WebSocket 信令处理器<br/>src/class/websockethandler.ts"]
B --> H["Swagger 文档<br/>src/swagger.ts"]
A --> I["日志工具<br/>src/log.ts"]
A --> J["配置选项接口<br/>src/class/options.ts"]
图表来源
- src/index.ts:1-109
- src/server.ts:14-89
- src/signaling.ts:1-25
- src/websocket.ts:6-118
- src/class/httphandler.ts:1-1130
- src/class/websockethandler.ts:1-479
- src/swagger.ts:16-65
- src/log.ts:1-51
- src/class/options.ts:1-10
章节来源
核心组件
- 入口与配置装载
- 使用命令行参数解析器装载配置，支持端口、HTTPS、证书、信令类型、通信模式、日志级别等选项
- 根据配置创建 Express 应用与 HTTP/HTTPS 服务器实例
- Express 服务器装配
- 配置日志中间件、CORS、JSON/URL 编码解析、静态资源、Swagger 文档、头像上传接口
- 信令路由
- HTTP 轮询：基于会话 ID 的 REST 接口，支持增量拉取
- WebSocket：基于连接组的 1 对多路由，支持私有模式与公共模式
- 日志系统
- 支持多等级日志输出，可通过配置调整日志级别
- Swagger 文档
- 自动生成 API 文档，支持会话认证头
章节来源
- src/index.ts:14-109
- src/server.ts:14-89
- src/class/httphandler.ts:1112-1129
- src/class/websockethandler.ts:478
- src/log.ts:1-51
- src/swagger.ts:16-65
架构总览
服务器采用“入口模块 + Express 服务器 + 信令路由 + WebSocket 信令”的分层架构。入口模块负责参数解析与服务器启动；Express 负责 HTTP 层面的中间件、静态资源与 API；信令路由在 HTTP 层提供轮询接口，在 WebSocket 层提供实时消息分发。
graph TB
subgraph "入口与服务器"
R["入口模块<br/>src/index.ts"]
S["服务器装配<br/>src/server.ts"]
end
subgraph "HTTP 层"
SIG["HTTP 信令路由<br/>src/signaling.ts"]
SW["Swagger 文档<br/>src/swagger.ts"]
LOG["日志工具<br/>src/log.ts"]
end
subgraph "WebSocket 层"
WS["WebSocket 信令服务器<br/>src/websocket.ts"]
WSH["WebSocket 处理器<br/>src/class/websockethandler.ts"]
end
subgraph "信令处理器"
HTH["HTTP 信令处理器<br/>src/class/httphandler.ts"]
end
R --> S
S --> SIG
S --> SW
S --> LOG
R --> WS
WS --> WSH
SIG --> HTH
图表来源
- src/index.ts:13-109
- src/server.ts:14-89
- src/signaling.ts:1-25
- src/websocket.ts:6-118
- src/class/httphandler.ts:1-1130
- src/class/websockethandler.ts:1-479
- src/swagger.ts:16-65
- src/log.ts:1-51
详细组件分析
入口模块与启动流程
- 命令行参数解析
- 支持端口、HTTPS、证书文件、信令类型（websocket/http）、通信模式（public/private）、日志级别等
- 环境变量可作为默认值来源
- 服务器创建与启动
- 根据 secure 选项创建 HTTP 或 HTTPS 服务器
- 启动后打印访问地址（IPv4）
- 信令类型与模式
- 校验信令类型，不支持则回退为 websocket
- 根据模式启动 WebSocket 信令服务器
sequenceDiagram
participant CLI as "命令行"
participant Entry as "入口模块<br/>src/index.ts"
participant Server as "服务器装配<br/>src/server.ts"
participant WS as "WebSocket 信令<br/>src/websocket.ts"
CLI->>Entry : 传入参数/环境变量
Entry->>Entry : 解析参数/构造 Options
Entry->>Server : createServer(options)
Server-->>Entry : Express 应用实例
Entry->>Entry : 根据 secure 创建 HTTP/HTTPS 服务器
Entry->>Entry : 校验信令类型/打印访问地址
Entry->>WS : 启动 WebSocket 信令服务器(模式)
WS-->>Entry : 连接事件/消息处理就绪
图表来源
章节来源
HTTP 服务器与中间件配置
- 中间件与静态资源
- 日志中间件：支持多种日志格式（combined/dev/short/tiny/none）
- CORS：允许任意来源
- JSON/URL 编码解析
- 静态资源：首页、模块资源
- API 与路由
- /config：返回服务器配置（是否使用 WebSocket、启动模式、日志级别）
- /signaling：挂载信令路由
- /api/upload/avatar：头像上传（临时文件名，服务端重命名为 userId.{ext}）
- /uploads：头像目录静态访问
- Swagger 文档
- 自动扫描 HTTP 处理器注释，生成 API 文档
flowchart TD
Start(["请求进入"]) --> LogCheck{"日志级别是否为 none?"}
LogCheck --> |否| UseLog["使用 Morgan 日志中间件"]
LogCheck --> |是| SkipLog["跳过日志"]
UseLog --> CORS["CORS 允许任意来源"]
SkipLog --> CORS
CORS --> Parse["JSON/URL 编码解析"]
Parse --> Config["GET /config 返回配置"]
Config --> Signaling["挂载 /signaling 路由"]
Signaling --> Static["静态资源与模块资源"]
Static --> Upload["POST /api/upload/avatar 头像上传"]
Upload --> Swagger["初始化 Swagger 文档"]
Swagger --> End(["完成"])
图表来源
章节来源
信令路由系统（HTTP 轮询）
- 会话与连接管理
- 会话超时：10 秒无请求自动删除
- 连接对：私有模式下通过 connectionId 建立 host/participants 关系
- 路由与处理器
- 无需会话 ID 的路由：/signaling/connection-ids
- 需要会话 ID 的路由：统一中间件校验 session-id
- 提供连接、offer、answer、candidate 的增删改查与增量拉取
- 增量拉取
- fromtime 查询参数用于增量获取消息，避免重复传输
sequenceDiagram
participant Client as "客户端"
participant Router as "HTTP 路由<br/>src/signaling.ts"
participant Handler as "HTTP 处理器<br/>src/class/httphandler.ts"
Client->>Router : GET /signaling?fromtime=...
Router->>Handler : checkSessionId 中间件
Handler-->>Router : 校验通过
Router->>Handler : getAnswer/getOffer/getCandidate/getAll
Handler-->>Router : 返回增量信令消息
Router-->>Client : JSON 响应
图表来源
章节来源
WebSocket 信令服务器
- 连接与路由
- 基于 ws 的 WebSocket 服务器，与 HTTP 服务器共享端口
- 私有模式：1 个 host + 多个 participants，支持单播/广播
- 公共模式：全连通，消息广播给所有其他客户端
- 消息类型与处理
- 生命周期：connect/disconnect/participant-joined/participant-left
- WebRTC：offer/answer/candidate（双向，按模式路由）
- 控制：ping/pong（可选心跳）
- 自定义：on-message/broadcast/call-request
- 心跳检测（可选）
- 定时发送 ping，超时断开
sequenceDiagram
participant Client as "客户端"
participant WS as "WebSocket 信令服务器<br/>src/websocket.ts"
participant WSH as "WebSocket 处理器<br/>src/class/websockethandler.ts"
Client->>WS : 连接 ws : //host : port
WS->>WSH : add(ws)
Client->>WS : {"type" : "connect","connectionId" : id}
WS->>WSH : onConnect(ws,id)
WSH-->>Client : {"type" : "connect","role" : "host|participant","participantId" : pid}
Client->>WS : {"type" : "offer","data" : {"sdp" : ...,"connectionId" : id}}
WS->>WSH : onOffer(ws,msg)
WSH-->>Client : 根据模式路由到 host 或 participants
Client->>WS : {"type" : "disconnect","connectionId" : id}
WS->>WSH : onDisconnect(ws,id)
WSH-->>Client : {"type" : "disconnect","reason" : "host-left"|normal}
图表来源
章节来源
日志系统集成与配置
- 日志等级
- 支持 none/error/warn/log/info 等等级
- 可通过配置字符串解析为等级枚举
- 输出行为
- 根据等级决定是否输出
- 统一时间戳与前缀格式
- 使用场景
- 启动信息、访问日志、错误告警、运行时事件
章节来源
Swagger 文档与 API 文档
- 自动扫描
- 扫描 HTTP 处理器与路由文件，提取注释生成 OpenAPI 文档
- 安全方案
- 会话认证头：session-id
- 访问
- /api-docs
章节来源
依赖分析
- 入口模块依赖
- 命令行解析、HTTPS/HTTP 服务器、WebSocket 信令、日志工具、配置选项
- 服务器装配依赖
- Express、Morgan、CORS、Multer、Swagger UI、静态资源
- 信令处理器依赖
- UUID、WebSocket 处理器、日志工具
- 文档与脚本
- Swagger 配置、NPM 脚本、批处理脚本
graph TB
IDX["src/index.ts"] --> SRV["src/server.ts"]
IDX --> WSC["src/websocket.ts"]
SRV --> SIG["src/signaling.ts"]
SRV --> SWG["src/swagger.ts"]
SRV --> LOG["src/log.ts"]
SIG --> HTH["src/class/httphandler.ts"]
WSC --> WSH["src/class/websockethandler.ts"]
IDX --> OPT["src/class/options.ts"]
图表来源
- src/index.ts:13-109
- src/server.ts:14-89
- src/signaling.ts:1-25
- src/websocket.ts:6-118
- src/class/httphandler.ts:1-1130
- src/class/websockethandler.ts:1-479
- src/swagger.ts:16-65
- src/log.ts:1-51
- src/class/options.ts:1-10
章节来源
性能考量
- 服务器启动与监听
- 仅监听 IPv4 地址，避免 IPv6 广播带来的额外开销
- HTTP 轮询
- 使用 fromtime 增量拉取，降低带宽与 CPU 开销
- 会话超时 10 秒，及时释放内存与连接资源
- WebSocket
- 私有模式下按连接组路由，避免广播风暴
- 可选心跳检测，超时断开异常连接
- 中间件
- 日志级别可设为 none 以禁用日志输出
- CORS 允许任意来源，生产环境建议限制来源
- 存储与上传
- 头像上传使用磁盘存储，建议结合 CDN 与缩略图策略
[本节为通用性能建议，不直接分析具体文件]
故障排查指南
- 启动失败（HTTPS 证书）
- 确认证书与密钥文件路径正确，secure 选项开启
- 无法访问 /api-docs
- 确认 Swagger 初始化成功，服务器 URL 与端口一致
- HTTP 轮询无响应
- 检查 session-id 请求头是否正确传递
- 确认会话未超时（10 秒）
- WebSocket 无法连接
- 检查 ws:// 地址与端口，确认服务器已启动
- 查看心跳/断线日志（如启用）
- 头像上传失败
- 检查 uploads 目录权限与磁盘空间
- 确认 userId 参数与文件大小限制
章节来源
- src/index.ts:55-74
- src/server.ts:44-83
- src/class/httphandler.ts:128-145
- src/class/websockethandler.ts:404-430
结论
服务器核心模块通过清晰的分层设计实现了高性能、可扩展的信令服务。入口模块负责配置与启动，Express 提供稳定的 HTTP 层，WebSocket 提供低延迟的实时通信，HTTP 轮询满足兼容性需求。配合日志与 Swagger，系统具备良好的可观测性与可维护性。
[本节为总结性内容，不直接分析具体文件]
附录
命令行参数与环境变量
- 端口：-p/--port，默认 80
- HTTPS：-s/--secure，默认启用
- 证书：-k/--keyfile、-c/--certfile
- 信令类型：-t/--type，websocket 或 http
- 通信模式：-m/--mode，public 或 private
- 日志级别：-l/--logging，combined/dev/short/tiny/none
章节来源
HTTPS 与证书
- 启用 HTTPS 时需提供 server.key 与 server.cert
- 启动后打印 https:// 地址
章节来源
CORS 配置
- 允许任意来源（*）
章节来源
Swagger 文档访问
- /api-docs
章节来源
头像上传 API
- POST /api/upload/avatar
- 参数：userId（body）、avatar（file）
- 响应：success、avatarUrl、message
章节来源
服务器启动脚本
- package.json scripts
- start：构建并启动
- dev：开发模式
- run.bat：Windows 批处理示例
章节来源
服务器核心类图（代码级）
classDiagram
class RenderStreaming {
+run(argv)
+app
+server?
+options
+constructor(options)
+getIPAddress()
}
class WSSignaling {
+server
+wss
+constructor(server, mode)
}
class HttpHandler {
+reset(mode)
+checkSessionId(req,res,next)
+getAll(req,res)
+getConnection(req,res)
+getOffer(req,res)
+getAnswer(req,res)
+getCandidate(req,res)
+createSession(req,res)
+deleteSession(req,res)
+createConnection(req,res)
+deleteConnection(req,res)
+postOffer(req,res)
+postAnswer(req,res)
+postCandidate(req,res)
+onGetConnections(req,res)
+getAllConnectionIds(req,res)
}
class WebSocketHandler {
+reset(mode)
+add(ws)
+remove(ws)
+onConnect(ws,connectionId)
+onDisconnect(ws,connectionId)
+onOffer(ws,message)
+onAnswer(ws,message)
+onCandidate(ws,message)
+onCallConnectionId(ws,message)
+onBroadcast(ws,message)
+onGetAllConnectionIds()
+onMessage(ws,message)
+isHost(ws,connectionId)
+broadcastToGroup(connectionId,senderWs,message)
}
RenderStreaming --> WSSignaling : "启动"
WSSignaling --> WebSocketHandler : "使用"
RenderStreaming --> HttpHandler : "使用"
图表来源