378 lines
16 KiB
Markdown
378 lines
16 KiB
Markdown
# 服务器入口点
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件聚焦于服务器入口点模块，系统性阐述 RenderStreaming 类的设计与实现，覆盖命令行参数解析、配置选项处理、服务器启动流程、HTTPS 与 HTTP 信令协议选择、通信模式（公开/私有）以及启动时的参数验证与默认值处理。同时提供多种启动配置示例、最佳实践建议、错误处理与配置验证的实现细节。
|
||
|
||
## 项目结构
|
||
服务器入口点位于后端源码的入口文件中，配合 Express 应用创建、HTTP 信令路由、WebSocket 信令服务以及日志模块共同构成完整的启动与运行体系。
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||
- [src/class/websockethandler.ts:63-66](file://src/class/websockethandler.ts#L63-L66)
|
||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||
- [package.json:5-12](file://package.json#L5-L12)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [package.json:5-12](file://package.json#L5-L12)
|
||
|
||
## 核心组件
|
||
- RenderStreaming：负责命令行参数解析、配置读取、HTTP/HTTPS 服务器创建、信令协议选择与启动。
|
||
- Options 接口：统一承载端口、HTTPS 文件、信令类型、通信模式、日志级别等配置项。
|
||
- createServer：基于 Options 构建 Express 应用，挂载静态资源、Swagger 文档、HTTP 信令路由与上传接口。
|
||
- WSSignaling：当信令类型为 WebSocket 时，启动 WebSocket 信令服务并交由 websockethandler 处理。
|
||
- HTTP 信令处理器：提供会话管理、offer/answer/candidate 的存储与查询接口。
|
||
- 日志模块：统一输出级别控制与格式化输出。
|
||
|
||
**章节来源**
|
||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/websockethandler.ts:63-66](file://src/class/websockethandler.ts#L63-L66)
|
||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||
|
||
## 架构总览
|
||
RenderStreaming.run 是主入口，内部使用 commandeer 解析命令行参数，随后根据配置创建 Express 应用；若启用 HTTPS，则以密钥与证书文件创建 HTTPS 服务器；否则使用 HTTP。随后根据信令类型选择 WebSocket 或 HTTP 信令通道，并打印启动信息与地址。
|
||
|
||
```mermaid
|
||
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](file://src/index.ts#L14-L109)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/websocket.ts:15-118](file://src/websocket.ts#L15-L118)
|
||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:14-109](file://src/index.ts#L14-L109)
|
||
|
||
## 详细组件分析
|
||
|
||
### 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 轮询。
|
||
- 输出当前通信模式。
|
||
|
||
```mermaid
|
||
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](file://src/index.ts#L14-L109)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:14-109](file://src/index.ts#L14-L109)
|
||
|
||
### Options 配置管理
|
||
- 字段定义：secure、port、keyfile、certfile、type、mode、logging。
|
||
- 作用范围：贯穿 Express 应用、HTTPS 服务器、WebSocket/HTTP 信令、日志级别控制。
|
||
- 默认值与回退：参见“命令行参数解析与默认值”小节。
|
||
|
||
**章节来源**
|
||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||
- [src/index.ts:20-41](file://src/index.ts#L20-L41)
|
||
|
||
### 服务器启动流程与 Express 应用
|
||
- createServer 负责：
|
||
- 重置 HTTP 信令处理器模式（resetHandler）。
|
||
- 条件化 Morgan 日志（logging != "none"）。
|
||
- CORS、URL 编码、JSON 解析。
|
||
- 提供 /config 接口返回当前信令类型、启动模式与日志级别。
|
||
- 挂载 /signaling 路由（HTTP 信令）。
|
||
- 提供静态页面与模块目录。
|
||
- 初始化 Swagger 文档。
|
||
- 配置头像上传接口与目录结构。
|
||
|
||
```mermaid
|
||
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](file://src/server.ts#L14-L89)
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||
|
||
**章节来源**
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
|
||
### WebSocket 信令服务
|
||
- WSSignaling 在 HTTP 服务器上创建 ws.Server，并根据通信模式初始化 websockethandler。
|
||
- 连接生命周期：connection、message、close。
|
||
- 支持的消息类型：connect/disconnect、offer/answer/candidate、broadcast、call-request、on-message（含 ping/pong 心跳）。
|
||
- 私有模式下的主机与参与者角色管理、广播与单播路由。
|
||
|
||
```mermaid
|
||
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 : "初始化与消息分发"
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/websockethandler.ts:63-66](file://src/class/websockethandler.ts#L63-L66)
|
||
|
||
**章节来源**
|
||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||
- [src/class/websockethandler.ts:145-473](file://src/class/websockethandler.ts#L145-L473)
|
||
|
||
### HTTP 信令处理器
|
||
- 会话与连接管理：会话 ID、连接 ID、连接对（connectionPair），私有模式下双向绑定。
|
||
- 信令存储：Offer/Answer/Candidate 结构与时间戳，按会话与连接维度组织。
|
||
- 查询接口：/signaling、/signaling/connection、/signaling/offer、/signaling/answer、/signaling/candidate。
|
||
- 写入接口：POST /signaling/offer、/answer、/candidate。
|
||
- 会话超时清理：定期检查并删除超时会话。
|
||
- 房间与用户统计：聚合连接对信息，输出房间列表与用户数。
|
||
|
||
```mermaid
|
||
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 响应"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:398-998](file://src/class/httphandler.ts#L398-L998)
|
||
|
||
**章节来源**
|
||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||
- [src/class/httphandler.ts:398-998](file://src/class/httphandler.ts#L398-L998)
|
||
|
||
### 日志模块
|
||
- 日志级别枚举：none/error/warn/log/info，默认 info。
|
||
- 级别解析：字符串到枚举的映射，未知值回退为 info。
|
||
- 输出格式：ISO 时间戳 + 大写级别前缀 + 参数。
|
||
|
||
**章节来源**
|
||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||
|
||
## 依赖关系分析
|
||
- 入口依赖：commander（参数解析）、express（Web 框架）、https/http（服务器）、fs/os（证书读取与地址枚举）、ws（WebSocket）、morgan（HTTP 日志）、cors/multer/swagger（中间件与静态资源）。
|
||
- 入口与应用：RenderStreaming 依赖 createServer；createServer 依赖 HTTP 信令路由与处理器。
|
||
- 信令通道：WebSocket 与 HTTP 二选一，分别由 WSSignaling 与 HTTP 信令处理器承担。
|
||
|
||
```mermaid
|
||
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"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/index.ts:1-11](file://src/index.ts#L1-L11)
|
||
- [src/server.ts:1-12](file://src/server.ts#L1-L12)
|
||
- [src/websocket.ts:1-4](file://src/websocket.ts#L1-L4)
|
||
- [src/signaling.ts:1-3](file://src/signaling.ts#L1-L3)
|
||
- [src/class/httphandler.ts:5-11](file://src/class/httphandler.ts#L5-L11)
|
||
- [src/class/websockethandler.ts:3-8](file://src/class/websockethandler.ts#L3-L8)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:1-11](file://src/index.ts#L1-L11)
|
||
- [src/server.ts:1-12](file://src/server.ts#L1-L12)
|
||
|
||
## 性能考量
|
||
- 服务器启动阶段：
|
||
- HTTPS 证书文件读取发生在启动时，建议确保文件存在与权限正确，避免启动失败。
|
||
- 日志级别为 none 时可减少 I/O 开销。
|
||
- WebSocket 信令：
|
||
- 私有模式下按连接组进行消息路由，避免全量广播带来的网络压力。
|
||
- 心跳检测可及时清理长时间无活动的连接，降低资源占用。
|
||
- HTTP 信令：
|
||
- 会话超时机制定期清理无效会话，防止内存泄漏。
|
||
- GET 查询支持 fromtime 过滤，减少不必要的数据传输。
|
||
|
||
[本节为通用指导，无需具体文件引用]
|
||
|
||
## 故障排查指南
|
||
- 启动失败（HTTPS）
|
||
- 症状：启动时报证书文件读取错误。
|
||
- 排查：确认 keyfile/certfile 路径正确且可读；secure 为 true 时必须提供有效证书。
|
||
- 参考：入口读取证书文件与创建 HTTPS 服务器的逻辑。
|
||
- 信令类型异常
|
||
- 症状：type 非 websocket 或 http 时被强制回退。
|
||
- 排查：检查命令行参数与环境变量 TYPE；确保只使用受支持的类型。
|
||
- 通信模式问题
|
||
- 症状：私有模式下连接对冲突或无法建立双向配对。
|
||
- 排查：确认 connectionId 未被重复使用；检查连接对映射与会话 ID 关联。
|
||
- 日志级别
|
||
- 症状：日志过多或过少。
|
||
- 排查：调整 logging 或使用 setLogLevel 控制输出级别。
|
||
- 上传接口失败
|
||
- 症状：头像上传报错或重命名失败。
|
||
- 排查：确认 uploads 目录存在且具备写权限；检查 userId 与文件扩展名处理。
|
||
|
||
**章节来源**
|
||
- [src/index.ts:55-82](file://src/index.ts#L55-L82)
|
||
- [src/class/websockethandler.ts:150-167](file://src/class/websockethandler.ts#L150-L167)
|
||
- [src/class/httphandler.ts:754-782](file://src/class/httphandler.ts#L754-L782)
|
||
- [src/log.ts:11-24](file://src/log.ts#L11-L24)
|
||
- [src/server.ts:62-83](file://src/server.ts#L62-L83)
|
||
|
||
## 结论
|
||
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 配置。
|
||
|
||
**章节来源**
|
||
- [package.json:5-12](file://package.json#L5-L12)
|
||
- [src/index.ts:20-29](file://src/index.ts#L20-L29) |