Files

stary 6c13817527 修改

2026-05-16 13:24:02 +08:00

16 KiB

Raw Blame History

服务器入口点

**本文引用的文件** - [src/index.ts](file://src/index.ts) - [src/server.ts](file://src/server.ts) - [src/class/options.ts](file://src/class/options.ts) - [src/websocket.ts](file://src/websocket.ts) - [src/class/websockethandler.ts](file://src/class/websockethandler.ts) - [src/class/httphandler.ts](file://src/class/httphandler.ts) - [src/signaling.ts](file://src/signaling.ts) - [src/log.ts](file://src/log.ts) - [package.json](file://package.json)

简介

本文件聚焦于服务器入口点模块，系统性阐述 RenderStreaming 类的设计与实现，覆盖命令行参数解析、配置选项处理、服务器启动流程、HTTPS 与 HTTP 信令协议选择、通信模式（公开/私有）以及启动时的参数验证与默认值处理。同时提供多种启动配置示例、最佳实践建议、错误处理与配置验证的实现细节。

项目结构

服务器入口点位于后端源码的入口文件中，配合 Express 应用创建、HTTP 信令路由、WebSocket 信令服务以及日志模块共同构成完整的启动与运行体系。

graph TB
A["src/index.ts<br/>入口与启动"] --> B["src/server.ts<br/>Express应用创建"]
A --> C["src/websocket.ts<br/>WebSocket信令服务"]
A --> D["src/class/options.ts<br/>配置接口"]
B --> E["src/signaling.ts<br/>HTTP信令路由"]
E --> F["src/class/httphandler.ts<br/>HTTP信令处理器"]
C --> G["src/class/websockethandler.ts<br/>WebSocket信令处理器"]
A --> H["src/log.ts<br/>日志模块"]
I["package.json<br/>脚本与构建配置"] --> A

图表来源

章节来源

核心组件

RenderStreaming：负责命令行参数解析、配置读取、HTTP/HTTPS 服务器创建、信令协议选择与启动。
Options 接口：统一承载端口、HTTPS 文件、信令类型、通信模式、日志级别等配置项。
createServer：基于 Options 构建 Express 应用，挂载静态资源、Swagger 文档、HTTP 信令路由与上传接口。
WSSignaling：当信令类型为 WebSocket 时，启动 WebSocket 信令服务并交由 websockethandler 处理。
HTTP 信令处理器：提供会话管理、offer/answer/candidate 的存储与查询接口。
日志模块：统一输出级别控制与格式化输出。

章节来源

架构总览

RenderStreaming.run 是主入口，内部使用 commandeer 解析命令行参数，随后根据配置创建 Express 应用；若启用 HTTPS，则以密钥与证书文件创建 HTTPS 服务器；否则使用 HTTP。随后根据信令类型选择 WebSocket 或 HTTP 信令通道，并打印启动信息与地址。

sequenceDiagram
participant CLI as "命令行"
participant RS as "RenderStreaming"
participant CS as "createServer"
participant APP as "Express应用"
participant WS as "WSSignaling"
participant LOG as "日志模块"
CLI->>RS : 传入 argv
RS->>RS : 解析命令行参数与环境变量
RS->>CS : 传入 Options
CS-->>APP : 返回 Express 应用
RS->>RS : 判断 secure 与 type
alt HTTPS 启用
RS->>RS : 读取 keyfile/certfile
RS->>APP : 创建 HTTPS 服务器
else HTTP
RS->>APP : 创建 HTTP 服务器
end
opt type=websocket
RS->>WS : 初始化 WebSocket 信令
WS->>LOG : 输出 ws 地址
end
RS->>LOG : 输出启动模式与日志级别

图表来源

章节来源

src/index.ts:14-109

详细组件分析

RenderStreaming 类设计与实现

命令行参数解析与默认值
- 使用 commandeer 定义选项：端口、HTTPS 开关与证书文件、信令类型（websocket/http）、通信模式（public/private）、日志级别。
- 默认值策略：端口默认 80；HTTPS 默认开启；信令类型默认 websocket；通信模式默认 public；日志默认 dev。
- 环境变量回退：PORT、SECURE、KEYFILE、CERTFILE、TYPE、MODE、LOGGING。
配置读取与校验
- 读取 program.opts() 并构造 Options 对象，对 secure 与 type 进行布尔化与类型修正。
- 若 type 非 websocket 且非 http，则警告并强制回退为 websocket。
服务器启动
- 创建 Express 应用：createServer(options)。
- HTTPS：读取 keyfile/certfile 并创建 https.Server；HTTP：直接 app.listen。
- 打印监听地址（支持多网卡 IPv4）。
- 依据 type 启动 WebSocket 信令或提示使用 HTTP 轮询。
- 输出当前通信模式。

flowchart TD
Start(["入口 run(argv)"]) --> Parse["解析命令行与环境变量"]
Parse --> BuildOpts["构造 Options 对象"]
BuildOpts --> TypeCheck{"type 是否为 websocket 或 http"}
TypeCheck --> |否| Warn["记录警告并回退为 websocket"]
TypeCheck --> |是| CreateApp["createServer(options)"]
Warn --> CreateApp
CreateApp --> Secure{"secure 为真？"}
Secure --> |是| HTTPS["读取 key/cert 并创建 https.Server"]
Secure --> |否| HTTP["app.listen()"]
HTTPS --> PrintAddr["打印监听地址"]
HTTP --> PrintAddr
PrintAddr --> Mode["输出启动模式"]
Mode --> End(["完成"])

图表来源

src/index.ts:14-109

章节来源

src/index.ts:14-109

Options 配置管理

字段定义：secure、port、keyfile、certfile、type、mode、logging。
作用范围：贯穿 Express 应用、HTTPS 服务器、WebSocket/HTTP 信令、日志级别控制。
默认值与回退：参见“命令行参数解析与默认值”小节。

章节来源

服务器启动流程与 Express 应用

createServer 负责：
- 重置 HTTP 信令处理器模式（resetHandler）。
- 条件化 Morgan 日志（logging != "none"）。
- CORS、URL 编码、JSON 解析。
- 提供 /config 接口返回当前信令类型、启动模式与日志级别。
- 挂载 /signaling 路由（HTTP 信令）。
- 提供静态页面与模块目录。
- 初始化 Swagger 文档。
- 配置头像上传接口与目录结构。

sequenceDiagram
participant RS as "RenderStreaming"
participant CS as "createServer"
participant APP as "Express 应用"
participant SIG as "HTTP 信令路由"
participant HH as "HTTP 信令处理器"
RS->>CS : 传入 Options
CS->>APP : 初始化中间件与静态资源
CS->>SIG : 挂载 /signaling 路由
SIG->>HH : 调用处理器函数
CS-->>RS : 返回 APP 实例

图表来源

章节来源

src/server.ts:14-89

WebSocket 信令服务

WSSignaling 在 HTTP 服务器上创建 ws.Server，并根据通信模式初始化 websockethandler。
连接生命周期：connection、message、close。
支持的消息类型：connect/disconnect、offer/answer/candidate、broadcast、call-request、on-message（含 ping/pong 心跳）。
私有模式下的主机与参与者角色管理、广播与单播路由。

classDiagram
class WSSignaling {
+server
+wss
+constructor(server, mode)
}
class WebSocketHandler {
+reset(mode)
+add(ws)
+remove(ws)
+onConnect(ws, connectionId)
+onDisconnect(ws, connectionId)
+onOffer(ws, message)
+onAnswer(ws, message)
+onCandidate(ws, message)
+onBroadcast(ws, message)
+onCallConnectionId(ws, message)
+onMessage(ws, message)
}
WSSignaling --> WebSocketHandler : "初始化与消息分发"

图表来源

章节来源

HTTP 信令处理器

会话与连接管理：会话 ID、连接 ID、连接对（connectionPair），私有模式下双向绑定。
信令存储：Offer/Answer/Candidate 结构与时间戳，按会话与连接维度组织。
查询接口：/signaling、/signaling/connection、/signaling/offer、/signaling/answer、/signaling/candidate。
写入接口：POST /signaling/offer、/answer、/candidate。
会话超时清理：定期检查并删除超时会话。
房间与用户统计：聚合连接对信息，输出房间列表与用户数。

flowchart TD
S(["HTTP 信令请求"]) --> CheckSID["校验 session-id"]
CheckSID --> Route{"路由类型"}
Route --> |GET| GetOps["查询操作<br/>getAll/getOffer/getAnswer/getCandidate/getConnection"]
Route --> |PUT| PutOps["写入/创建操作<br/>createSession/createConnection"]
Route --> |DELETE| DelOps["删除操作<br/>deleteSession/deleteConnection"]
GetOps --> Store["按会话/连接维度读取存储"]
PutOps --> Store
DelOps --> Store
Store --> Resp["返回 JSON 响应"]

图表来源

章节来源

日志模块

日志级别枚举：none/error/warn/log/info，默认 info。
级别解析：字符串到枚举的映射，未知值回退为 info。
输出格式：ISO 时间戳 + 大写级别前缀 + 参数。

章节来源

src/log.ts:1-51

依赖关系分析

入口依赖：commander（参数解析）、express（Web 框架）、https/http（服务器）、fs/os（证书读取与地址枚举）、ws（WebSocket）、morgan（HTTP 日志）、cors/multer/swagger（中间件与静态资源）。
入口与应用：RenderStreaming 依赖 createServer；createServer 依赖 HTTP 信令路由与处理器。
信令通道：WebSocket 与 HTTP 二选一，分别由 WSSignaling 与 HTTP 信令处理器承担。

graph TB
IDX["src/index.ts"] --> CMDR["commander"]
IDX --> EXP["express"]
IDX --> HTTPS["https"]
IDX --> FS["fs"]
IDX --> OS["os"]
IDX --> WSS["ws"]
IDX --> MORGAN["morgan"]
IDX --> CORS["cors"]
IDX --> MULTER["multer"]
IDX --> SWAG["swagger"]
IDX --> SVR["src/server.ts"]
IDX --> WS["src/websocket.ts"]
SVR --> SIG["src/signaling.ts"]
SIG --> HHT["src/class/httphandler.ts"]
WS --> WHH["src/class/websockethandler.ts"]

图表来源

章节来源

性能考量

服务器启动阶段：
- HTTPS 证书文件读取发生在启动时，建议确保文件存在与权限正确，避免启动失败。
- 日志级别为 none 时可减少 I/O 开销。
WebSocket 信令：
- 私有模式下按连接组进行消息路由，避免全量广播带来的网络压力。
- 心跳检测可及时清理长时间无活动的连接，降低资源占用。
HTTP 信令：
- 会话超时机制定期清理无效会话，防止内存泄漏。
- GET 查询支持 fromtime 过滤，减少不必要的数据传输。

[本节为通用指导，无需具体文件引用]

故障排查指南

启动失败（HTTPS）
- 症状：启动时报证书文件读取错误。
- 排查：确认 keyfile/certfile 路径正确且可读；secure 为 true 时必须提供有效证书。
- 参考：入口读取证书文件与创建 HTTPS 服务器的逻辑。
信令类型异常
- 症状：type 非 websocket 或 http 时被强制回退。
- 排查：检查命令行参数与环境变量 TYPE；确保只使用受支持的类型。
通信模式问题
- 症状：私有模式下连接对冲突或无法建立双向配对。
- 排查：确认 connectionId 未被重复使用；检查连接对映射与会话 ID 关联。
日志级别
- 症状：日志过多或过少。
- 排查：调整 logging 或使用 setLogLevel 控制输出级别。
上传接口失败
- 症状：头像上传报错或重命名失败。
- 排查：确认 uploads 目录存在且具备写权限；检查 userId 与文件扩展名处理。

章节来源

结论

RenderStreaming 将命令行参数解析、配置读取、服务器创建与信令通道选择整合为统一入口，结合 HTTP 与 WebSocket 两种信令模式满足不同部署场景需求。通过 Options 接口集中管理配置，配合 HTTP/WS 信令处理器实现可靠的信令传递与连接管理。建议在生产环境中优先使用 HTTPS 与 WebSocket，并合理设置日志级别与会话超时策略。

[本节为总结性内容，无需具体文件引用]

附录

启动配置示例与最佳实践

使用 HTTPS 并自定义端口与证书
- 示例：node ./build/index.js -s -p 8443 -k ./server.key -c ./server.cert
- 最佳实践：将证书置于安全目录，限制文件权限；使用强密码保护私钥。
使用 HTTP（不推荐生产）
- 示例：node ./build/index.js -p 8080 -s false
- 最佳实践：仅限开发调试；如需生产请改用 HTTPS。
选择 HTTP 轮询信令
- 示例：node ./build/index.js -t http -p 8080 -m private
- 最佳实践：客户端需实现轮询拉取信令；注意带宽与延迟。
选择 WebSocket 信令与私有模式
- 示例：node ./build/index.js -t websocket -p 8080 -m private
- 最佳实践：私有模式适合点对点或小房间；公共模式适合广播场景。
自定义日志级别
- 示例：node ./build/index.js -l combined -p 8080
- 可选值：combined/dev/short/tiny/none；none 会禁用日志输出。
使用 npm 脚本
- 开发：npm run dev
- 生产：npm start
- 参考：package.json 中 scripts 与 bin 配置。

章节来源

16 KiB Raw Blame History Unescape Escape

服务器入口点

目录

简介

项目结构

核心组件

架构总览

详细组件分析

RenderStreaming 类设计与实现

Options 配置管理

服务器启动流程与 Express 应用

WebSocket 信令服务

HTTP 信令处理器

日志模块

依赖关系分析

性能考量

故障排查指南

结论

附录

启动配置示例与最佳实践

16 KiB

Raw Blame History