修改
This commit is contained in:
588
.qoder/repowiki/zh/content/服务器核心/HTTP 服务器配置.md
Normal file
588
.qoder/repowiki/zh/content/服务器核心/HTTP 服务器配置.md
Normal file
@@ -0,0 +1,588 @@
|
||||
# HTTP 服务器配置
|
||||
|
||||
<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/class/httphandler.ts](file://src/class/httphandler.ts)
|
||||
- [src/signaling.ts](file://src/signaling.ts)
|
||||
- [src/websocket.ts](file://src/websocket.ts)
|
||||
- [src/swagger.ts](file://src/swagger.ts)
|
||||
- [src/log.ts](file://src/log.ts)
|
||||
- [package.json](file://package.json)
|
||||
- [run.bat](file://run.bat)
|
||||
- [server.cert](file://server.cert)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [HTTPS 服务器配置](#https-服务器配置)
|
||||
7. [CORS 配置](#cors-配置)
|
||||
8. [日志记录中间件](#日志记录中间件)
|
||||
9. [错误处理机制](#错误处理机制)
|
||||
10. [性能优化建议](#性能优化建议)
|
||||
11. [安全配置最佳实践](#安全配置最佳实践)
|
||||
12. [配置示例](#配置示例)
|
||||
13. [故障排除指南](#故障排除指南)
|
||||
14. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本项目是一个基于 Node.js 和 Express 的 WebRTC 信令服务器，提供了完整的 HTTP 和 WebSocket 服务器配置功能。该系统支持 HTTPS 加密传输、CORS 跨域资源共享、详细的日志记录、文件上传处理以及 RESTful API 接口。系统采用模块化设计，支持公共模式和私有模式两种通信方式，适用于视频流媒体应用的信令传输需求。
|
||||
|
||||
## 项目结构
|
||||
|
||||
该项目采用清晰的模块化架构，主要包含以下核心目录和文件：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "项目根目录"
|
||||
A[package.json] --> B[src/]
|
||||
C[client/] --> D[public/]
|
||||
E[client/src/] --> F[测试文件]
|
||||
G[test/] --> H[单元测试]
|
||||
end
|
||||
subgraph "源代码目录 (src/)"
|
||||
B --> I[index.ts]
|
||||
B --> J[server.ts]
|
||||
B --> K[class/]
|
||||
B --> L[websocket.ts]
|
||||
B --> M[signaling.ts]
|
||||
B --> N[swagger.ts]
|
||||
B --> O[log.ts]
|
||||
subgraph "class/"
|
||||
K --> P[options.ts]
|
||||
K --> Q[httphandler.ts]
|
||||
K --> R[websockethandler.ts]
|
||||
K --> S[offer.ts]
|
||||
K --> T[answer.ts]
|
||||
K --> U[candidate.ts]
|
||||
end
|
||||
end
|
||||
subgraph "客户端资源"
|
||||
D --> V[HTML页面]
|
||||
D --> W[CSS样式]
|
||||
D --> X[JavaScript文件]
|
||||
E --> Y[源代码文件]
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
|
||||
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
|
||||
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 服务器启动器 (RenderStreaming)
|
||||
|
||||
`RenderStreaming` 类是整个应用程序的入口点，负责解析命令行参数、创建 Express 应用程序、配置 HTTPS 服务器以及启动 WebSocket 信令服务。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class RenderStreaming {
|
||||
+Options options
|
||||
+Application app
|
||||
+Server server
|
||||
+run(argv) RenderStreaming
|
||||
+constructor(options)
|
||||
+getIPAddress() string[]
|
||||
}
|
||||
class Options {
|
||||
+boolean secure
|
||||
+number port
|
||||
+string keyfile
|
||||
+string certfile
|
||||
+string type
|
||||
+string mode
|
||||
+string logging
|
||||
}
|
||||
class WSSignaling {
|
||||
+Server server
|
||||
+WebSocketServer wss
|
||||
+constructor(server, mode)
|
||||
}
|
||||
RenderStreaming --> Options : 使用
|
||||
RenderStreaming --> WSSignaling : 启动
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||||
|
||||
### Express 应用程序配置
|
||||
|
||||
Express 应用程序通过 `createServer` 函数进行配置，集成了多种中间件和路由处理功能。
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:52-109](file://src/index.ts#L52-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用双服务器架构，同时支持 HTTP 和 WebSocket 协议：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "客户端层"
|
||||
A[Web浏览器]
|
||||
B[移动应用]
|
||||
C[桌面应用]
|
||||
end
|
||||
subgraph "服务器层"
|
||||
D[HTTP服务器]
|
||||
E[HTTPS服务器]
|
||||
F[WebSocket服务器]
|
||||
subgraph "Express中间件"
|
||||
G[Morgan日志]
|
||||
H[CORS跨域]
|
||||
I[JSON解析]
|
||||
J[静态资源]
|
||||
K[文件上传]
|
||||
end
|
||||
subgraph "业务逻辑层"
|
||||
L[HTTP信令处理器]
|
||||
M[WebSocket信令处理器]
|
||||
N[会话管理器]
|
||||
end
|
||||
end
|
||||
subgraph "外部服务"
|
||||
O[WebRTC客户端]
|
||||
P[API消费者]
|
||||
Q[文件存储]
|
||||
end
|
||||
A --> D
|
||||
B --> E
|
||||
C --> F
|
||||
D --> G
|
||||
E --> G
|
||||
F --> M
|
||||
G --> L
|
||||
H --> L
|
||||
I --> L
|
||||
J --> L
|
||||
K --> L
|
||||
L --> N
|
||||
M --> N
|
||||
N --> O
|
||||
L --> P
|
||||
K --> Q
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/index.ts:55-88](file://src/index.ts#L55-L88)
|
||||
- [src/server.ts:18-41](file://src/server.ts#L18-L41)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### HTTP 服务器配置
|
||||
|
||||
HTTP 服务器通过 Express 框架实现，配置了完整的中间件栈和路由系统。
|
||||
|
||||
#### 中间件配置流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([服务器启动]) --> CreateApp["创建Express应用"]
|
||||
CreateApp --> ConfigLogging["配置日志中间件<br/>morgan(config.logging)"]
|
||||
ConfigLogging --> EnableCORS["启用CORS<br/>允许所有来源"]
|
||||
EnableCORS --> ParseBody["配置请求体解析<br/>JSON和URL编码"]
|
||||
ParseBody --> SetupRoutes["设置路由处理"]
|
||||
SetupRoutes --> StaticFiles["配置静态资源<br/>客户端文件"]
|
||||
StaticFiles --> UploadConfig["配置文件上传<br/>Multer中间件"]
|
||||
UploadConfig --> SwaggerInit["初始化Swagger文档"]
|
||||
SwaggerInit --> Ready([服务器就绪])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/server.ts:18-41](file://src/server.ts#L18-L41)
|
||||
|
||||
#### 路由系统架构
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "根路由 (/)"
|
||||
A[GET /] --> B[返回主页]
|
||||
C[GET /config] --> D[返回服务器配置]
|
||||
end
|
||||
subgraph "信令路由 (/signaling)"
|
||||
E[子路由] --> F[HTTP信令处理器]
|
||||
G[/connection] --> H[连接管理]
|
||||
I[/offer] --> J[Offer消息处理]
|
||||
K[/answer] --> L[Answer消息处理]
|
||||
M[/candidate] --> N[Candidate消息处理]
|
||||
end
|
||||
subgraph "静态资源"
|
||||
O[public/] --> P[HTML/CSS/JS]
|
||||
Q[/module] --> R[源代码文件]
|
||||
S[/uploads] --> T[用户上传文件]
|
||||
end
|
||||
subgraph "API文档"
|
||||
U[Swagger UI] --> V[在线API文档]
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/server.ts:25-41](file://src/server.ts#L25-L41)
|
||||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||||
|
||||
**章节来源**
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
|
||||
### WebSocket 服务器配置
|
||||
|
||||
WebSocket 服务器提供实时双向通信能力，支持 WebRTC 信令传输。
|
||||
|
||||
#### WebSocket 连接处理流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端
|
||||
participant WS as WebSocket服务器
|
||||
participant Handler as 信令处理器
|
||||
participant Session as 会话管理器
|
||||
Client->>WS : 建立WebSocket连接
|
||||
WS->>Handler : 触发connection事件
|
||||
Handler->>Session : 添加新连接
|
||||
Handler->>Client : 发送connect确认
|
||||
loop 信令消息循环
|
||||
Client->>Handler : 发送信令消息
|
||||
Handler->>Handler : 解析消息类型
|
||||
alt offer消息
|
||||
Handler->>Session : 存储Offer
|
||||
Handler->>Client : 广播Offer
|
||||
else answer消息
|
||||
Handler->>Session : 存储Answer
|
||||
Handler->>Client : 转发Answer
|
||||
else candidate消息
|
||||
Handler->>Session : 存储Candidate
|
||||
Handler->>Client : 转发Candidate
|
||||
end
|
||||
end
|
||||
Client->>WS : 断开连接
|
||||
WS->>Handler : 触发close事件
|
||||
Handler->>Session : 移除连接
|
||||
Handler->>Client : 发送断开通知
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/websocket.ts:27-115](file://src/websocket.ts#L27-L115)
|
||||
|
||||
**章节来源**
|
||||
- [src/websocket.ts:1-118](file://src/websocket.ts#L1-L118)
|
||||
|
||||
### 会话管理器
|
||||
|
||||
会话管理器负责维护客户端连接状态和信令消息队列。
|
||||
|
||||
#### 会话状态管理
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 会话创建
|
||||
会话创建 --> 连接等待 : 创建会话
|
||||
连接等待 --> Offer发送 : 连接建立
|
||||
Offer发送 --> Answer接收 : 发送Offer
|
||||
Answer接收 --> Candidate交换 : 接收Answer
|
||||
Candidate交换 --> 信令完成 : 交换Candidate
|
||||
信令完成 --> 连接断开 : 通话结束
|
||||
连接断开 --> [*]
|
||||
state 连接等待 {
|
||||
[*] --> 等待参与者
|
||||
等待参与者 --> 等待Offer : 收到连接
|
||||
等待Offer --> Offer发送 : 收到Offer
|
||||
}
|
||||
state 信令完成 {
|
||||
[*] --> 保持连接
|
||||
保持连接 --> Candidate交换 : 有新Candidate
|
||||
Candidate交换 --> 保持连接 : Candidate同步
|
||||
}
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/class/httphandler.ts:110-120](file://src/class/httphandler.ts#L110-L120)
|
||||
|
||||
**章节来源**
|
||||
- [src/class/httphandler.ts:106-120](file://src/class/httphandler.ts#L106-L120)
|
||||
|
||||
## HTTPS 服务器配置
|
||||
|
||||
### SSL 证书配置
|
||||
|
||||
HTTPS 服务器通过读取 PEM 格式的密钥和证书文件来建立安全连接。
|
||||
|
||||
#### HTTPS 服务器启动流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([检查HTTPS配置]) --> SecureEnabled{"secure参数启用?"}
|
||||
SecureEnabled --> |是| LoadCert["读取SSL证书文件"]
|
||||
SecureEnabled --> |否| StartHTTP["启动HTTP服务器"]
|
||||
LoadCert --> CertLoaded{"证书文件存在?"}
|
||||
CertLoaded --> |是| CreateHTTPS["创建HTTPS服务器"]
|
||||
CertLoaded --> |否| ErrorCert["证书文件不存在"]
|
||||
CreateHTTPS --> ListenHTTPS["监听HTTPS端口"]
|
||||
StartHTTP --> ListenHTTP["监听HTTP端口"]
|
||||
ListenHTTPS --> LogHTTPS["记录HTTPS地址"]
|
||||
ListenHTTP --> LogHTTP["记录HTTP地址"]
|
||||
LogHTTPS --> Ready([服务器就绪])
|
||||
LogHTTP --> Ready
|
||||
ErrorCert --> Error([启动失败])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
|
||||
### 证书文件处理
|
||||
|
||||
系统支持自定义证书文件路径配置，默认使用 `server.key` 和 `server.cert` 文件。
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
|
||||
- [package.json:9](file://package.json#L9)
|
||||
|
||||
## CORS 配置
|
||||
|
||||
### 跨域资源共享设置
|
||||
|
||||
系统默认启用了 CORS 中间件，允许来自任何来源的跨域请求。
|
||||
|
||||
#### CORS 配置分析
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[CORS中间件] --> B[Origin: *]
|
||||
A --> C[方法: GET, POST, PUT, DELETE]
|
||||
A --> D[头部: 自动处理]
|
||||
A --> E[凭证: 允许]
|
||||
B --> F[允许所有来源]
|
||||
C --> G[支持RESTful操作]
|
||||
D --> H[自动预检请求]
|
||||
E --> I[支持认证请求]
|
||||
F --> J[简化客户端集成]
|
||||
G --> K[完整的API访问]
|
||||
H --> L[减少开发复杂度]
|
||||
I --> M[增强安全性]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/server.ts:22](file://src/server.ts#L22)
|
||||
|
||||
**章节来源**
|
||||
- [src/server.ts:22](file://src/server.ts#L22)
|
||||
|
||||
## 日志记录中间件
|
||||
|
||||
### Morgan 日志系统
|
||||
|
||||
系统使用 Morgan 中间件提供详细的 HTTP 请求日志记录。
|
||||
|
||||
#### 日志级别配置
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[日志配置] --> B[none - 禁用日志]
|
||||
A --> C[combined - 详细日志]
|
||||
A --> D[dev - 开发友好]
|
||||
A --> E[short - 简洁日志]
|
||||
A --> F[tiny - 最简日志]
|
||||
B --> G[生产环境推荐]
|
||||
C --> H[完整请求详情]
|
||||
D --> I[开发调试]
|
||||
E --> J[基本请求信息]
|
||||
F --> K[最小化开销]
|
||||
H --> L[适合生产监控]
|
||||
I --> M[适合开发调试]
|
||||
J --> N[适合快速部署]
|
||||
K --> O[适合性能敏感场景]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/index.ts:28](file://src/index.ts#L28)
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:18-20](file://src/index.ts#L18-L20)
|
||||
- [src/log.ts:15-24](file://src/log.ts#L15-L24)
|
||||
|
||||
## 错误处理机制
|
||||
|
||||
### 统一日志系统
|
||||
|
||||
系统实现了统一的日志记录机制，支持多种日志级别和格式化输出。
|
||||
|
||||
#### 错误处理流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[请求到达] --> B[中间件处理]
|
||||
B --> C{处理成功?}
|
||||
C --> |是| D[正常响应]
|
||||
C --> |否| E[捕获错误]
|
||||
E --> F[记录错误日志]
|
||||
F --> G[返回错误响应]
|
||||
G --> H[客户端处理]
|
||||
D --> I[记录成功日志]
|
||||
I --> H
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
|
||||
**章节来源**
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
### 服务器性能调优
|
||||
|
||||
基于现有代码结构，以下是针对该 HTTP 服务器的性能优化建议：
|
||||
|
||||
#### 内存管理优化
|
||||
- 实现会话超时清理机制，避免内存泄漏
|
||||
- 使用连接池管理数据库连接
|
||||
- 实施缓存策略减少重复计算
|
||||
|
||||
#### 网络性能优化
|
||||
- 启用 HTTP/2 支持提升传输效率
|
||||
- 实现 gzip 压缩减少带宽占用
|
||||
- 配置适当的缓存头提高静态资源加载速度
|
||||
|
||||
#### 并发处理优化
|
||||
- 使用集群模式支持多核 CPU
|
||||
- 实现请求队列管理防止过载
|
||||
- 优化中间件执行顺序减少不必要的处理
|
||||
|
||||
## 安全配置最佳实践
|
||||
|
||||
### HTTPS 安全配置
|
||||
|
||||
#### 证书管理
|
||||
- 使用受信任的 CA 机构签发的证书
|
||||
- 定期更新证书并配置自动续期
|
||||
- 实施证书透明度日志监控
|
||||
|
||||
#### 加密协议配置
|
||||
- 启用 TLS 1.2+ 版本
|
||||
- 配置强加密套件
|
||||
- 禁用不安全的加密算法
|
||||
|
||||
#### 安全中间件
|
||||
- 实施内容安全策略 (CSP)
|
||||
- 启用 HTTP 严格传输安全 (HSTS)
|
||||
- 配置跨站请求伪造 (CSRF) 保护
|
||||
|
||||
## 配置示例
|
||||
|
||||
### 基础配置示例
|
||||
|
||||
以下是一些常见的服务器配置示例：
|
||||
|
||||
#### 开发环境配置
|
||||
```bash
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
|
||||
# 或使用命令行参数
|
||||
node ./build/index.js -s=false -p 8080 -m public -l dev
|
||||
```
|
||||
|
||||
#### 生产环境配置
|
||||
```bash
|
||||
# 构建生产版本
|
||||
npm run build
|
||||
|
||||
# 启动生产服务器
|
||||
npm run start
|
||||
|
||||
# 或使用自定义参数
|
||||
node ./build/index.js -s=true -p 443 -m private -k ./server.key -c ./server.cert -l combined
|
||||
```
|
||||
|
||||
#### 批处理脚本配置
|
||||
```batch
|
||||
@echo off
|
||||
pushd %~dp0
|
||||
call npm run build
|
||||
call npm run start
|
||||
popd
|
||||
pause
|
||||
|
||||
# 自定义运行参数
|
||||
node ./build/index.js -s -p 8080 -m private -k ./server.key -c ./server.cert -l dev
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [package.json:9-12](file://package.json#L9-L12)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题诊断
|
||||
|
||||
#### HTTPS 证书问题
|
||||
- **问题**: 证书文件不存在或权限不足
|
||||
- **解决方案**: 确保证书文件路径正确，检查文件权限，验证证书格式
|
||||
|
||||
#### 端口占用问题
|
||||
- **问题**: 端口被其他进程占用
|
||||
- **解决方案**: 更换端口号，使用 `netstat` 检查端口占用情况
|
||||
|
||||
#### CORS 阻挡问题
|
||||
- **问题**: 跨域请求被浏览器阻止
|
||||
- **解决方案**: 检查 CORS 配置，确保 Origin 设置正确
|
||||
|
||||
#### 日志级别问题
|
||||
- **问题**: 日志输出过多或过少
|
||||
- **解决方案**: 调整日志级别配置，根据环境选择合适的日志格式
|
||||
|
||||
### 调试技巧
|
||||
|
||||
#### 启用详细日志
|
||||
```javascript
|
||||
// 在开发环境中使用详细日志
|
||||
node ./build/index.js -l dev
|
||||
```
|
||||
|
||||
#### 检查服务器状态
|
||||
```javascript
|
||||
// 查看服务器配置
|
||||
curl http://localhost:8080/config
|
||||
```
|
||||
|
||||
#### 测试 API 接口
|
||||
```javascript
|
||||
// 测试信令接口
|
||||
curl -X GET http://localhost:8080/signaling
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:28](file://src/index.ts#L28)
|
||||
- [src/server.ts:25](file://src/server.ts#L25)
|
||||
|
||||
## 结论
|
||||
|
||||
本 HTTP 服务器配置模块提供了完整的 WebRTC 信令服务器解决方案，具有以下特点：
|
||||
|
||||
### 核心优势
|
||||
- **模块化设计**: 清晰的组件分离便于维护和扩展
|
||||
- **灵活配置**: 支持多种运行模式和配置选项
|
||||
- **完整功能**: 集成 HTTP、HTTPS、WebSocket、文件上传等多种功能
|
||||
- **易于部署**: 提供构建脚本和批处理文件简化部署流程
|
||||
|
||||
### 技术特色
|
||||
- **双协议支持**: 同时支持 HTTP Polling 和 WebSocket 两种信令方式
|
||||
- **会话管理**: 完善的会话生命周期管理和超时处理机制
|
||||
- **安全考虑**: HTTPS 加密传输和 CORS 跨域配置
|
||||
- **可观测性**: 详细的日志记录和 Swagger API 文档
|
||||
|
||||
### 适用场景
|
||||
该服务器适用于视频会议、在线教育、远程协作等需要实时音视频通信的应用场景。通过合理的配置和优化，可以满足不同规模和性能要求的部署需求。
|
||||
305
.qoder/repowiki/zh/content/服务器核心/WebSocket 服务器.md
Normal file
305
.qoder/repowiki/zh/content/服务器核心/WebSocket 服务器.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# WebSocket 服务器
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [src/index.ts](file://src/index.ts)
|
||||
- [src/server.ts](file://src/server.ts)
|
||||
- [src/websocket.ts](file://src/websocket.ts)
|
||||
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
|
||||
- [src/class/offer.ts](file://src/class/offer.ts)
|
||||
- [src/class/answer.ts](file://src/class/answer.ts)
|
||||
- [src/class/candidate.ts](file://src/class/candidate.ts)
|
||||
- [src/log.ts](file://src/log.ts)
|
||||
- [src/signaling.ts](file://src/signaling.ts)
|
||||
- [src/swagger.ts](file://src/swagger.ts)
|
||||
- [client/src/signaling.js](file://client/src/signaling.js)
|
||||
- [package.json](file://package.json)
|
||||
- [test/websockethandler.test.ts](file://test/websockethandler.test.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本技术文档围绕 WebSocket 服务器模块进行深入解析，重点覆盖以下方面：
|
||||
- WebSocket 服务器的创建与配置（含 HTTPS/WSS、日志与启动流程）
|
||||
- 连接生命周期管理（连接建立、断开、广播、消息路由）
|
||||
- WSSignaling 类的职责与实现要点（事件监听、消息分发、心跳与超时）
|
||||
- WebSocketHandler 的核心能力（连接组模型、1对多/多对多路由、广播机制）
|
||||
- 连接调试与监控方法（日志级别、Swagger 文档、心跳检测）
|
||||
- 连接池管理、心跳检测与断线重连策略
|
||||
|
||||
## 项目结构
|
||||
后端采用 Express 提供 HTTP/HTTPS 服务与静态资源，WebSocket 信令在独立模块中运行；同时保留 HTTP 轮询信令作为备选方案。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "服务端进程"
|
||||
A["Express 应用<br/>src/server.ts"]
|
||||
B["HTTP(S) 服务器<br/>src/index.ts"]
|
||||
C["WebSocket 信令服务器<br/>src/websocket.ts"]
|
||||
D["WebSocket 处理器<br/>src/class/websockethandler.ts"]
|
||||
E["HTTP 信令路由<br/>src/signaling.ts"]
|
||||
F["Swagger 文档<br/>src/swagger.ts"]
|
||||
end
|
||||
subgraph "客户端"
|
||||
G["浏览器/前端页面<br/>client/public"]
|
||||
H["信令客户端封装<br/>client/src/signaling.js"]
|
||||
end
|
||||
H --> |"WebSocket"| C
|
||||
H --> |"HTTP 轮询"| E
|
||||
B --> |"创建/绑定"| C
|
||||
A --> |"挂载路由/静态资源"| G
|
||||
A --> |"注册 HTTP 信令路由"| E
|
||||
A --> |"初始化 Swagger"| F
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||||
- [src/server.ts:14-42](file://src/server.ts#L14-L42)
|
||||
- [src/websocket.ts:15-116](file://src/websocket.ts#L15-L116)
|
||||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||||
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
## 核心组件
|
||||
- WSSignaling：WebSocket 信令服务器入口，负责监听连接、消息解析与分发至 WebSocketHandler。
|
||||
- WebSocketHandler：核心业务逻辑，维护连接组、1对多/多对多路由、广播、心跳与断线清理。
|
||||
- 数据模型：Offer、Answer、Candidate 用于封装信令数据。
|
||||
- 日志系统：统一日志级别控制与输出格式。
|
||||
- HTTP 信令路由：保留 HTTP 轮询信令通道，便于兼容与调试。
|
||||
- Swagger 文档：自动生成 API 文档，支持会话认证与信令接口说明。
|
||||
|
||||
章节来源
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
## 架构总览
|
||||
WebSocket 服务器在 HTTP(S) 之上提供实时信令通道，客户端可通过 WebSocket 或 HTTP 轮询两种方式接入。WebSocket 信令以“连接组”为核心组织多端通信，支持广播与定向转发。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端<br/>client/src/signaling.js"
|
||||
participant WS as "WSSignaling<br/>src/websocket.ts"
|
||||
participant Handler as "WebSocketHandler<br/>src/class/websockethandler.ts"
|
||||
Client->>WS : "WebSocket 连接建立"
|
||||
WS->>Handler : "add(ws)"
|
||||
WS-->>Client : "connect 消息role/polite/participantId"
|
||||
Client->>WS : "发送信令消息offer/answer/candidate/on-message/broadcast"
|
||||
WS->>Handler : "根据消息类型分发"
|
||||
Handler-->>Client : "转发/广播结果含 participantId"
|
||||
Client-->>WS : "断开连接/心跳 ping/pong"
|
||||
WS->>Handler : "remove(ws)/心跳检测"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/websocket.ts:27-116](file://src/websocket.ts#L27-L116)
|
||||
- [src/class/websockethandler.ts:72-137](file://src/class/websockethandler.ts#L72-L137)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
- [client/src/signaling.js:152-292](file://client/src/signaling.js#L152-L292)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### WSSignaling 类
|
||||
职责与行为：
|
||||
- 接收 HTTP 服务器实例，创建 ws.Server 并绑定到同一端口。
|
||||
- 注册 connection 事件：为新连接调用处理器 add，并在关闭时 remove。
|
||||
- 注册 message 事件：解析 JSON 消息，按 type 分发到对应处理器（connect/disconnect/offer/answer/candidate/ping/pong/broadcast/on-message/call-request）。
|
||||
- 内置 ping/pong 心跳：收到 ping 回复 pong，收到 pong 更新 lastActivity；注释掉的心跳定时器可在需要时启用。
|
||||
|
||||
实现要点：
|
||||
- 模式切换：通过 reset(mode) 设置 isPrivate，影响连接组与路由行为。
|
||||
- 消息格式：支持 participantId 字段以区分多参与者场景。
|
||||
- 日志：统一通过 log 输出接收到的消息与关键事件。
|
||||
|
||||
章节来源
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/class/websockethandler.ts:63-66](file://src/class/websockethandler.ts#L63-L66)
|
||||
|
||||
### WebSocketHandler 核心功能
|
||||
- 连接组模型：Map<string, ConnectionGroup>，每个连接组包含 host 与多个 participants。
|
||||
- 连接管理：add/remove 维护 clients 映射与连接组；onConnect/onDisconnect 实现 1对多/多对多角色分配。
|
||||
- 信令路由：
|
||||
- offer/answer/candidate：host 与 participants 之间双向转发；私有模式下支持按 participantId 精确路由。
|
||||
- broadcast：支持全局广播与按连接组广播。
|
||||
- on-message：支持聊天消息等扩展消息的组内转发。
|
||||
- 心跳与超时：提供心跳初始化/清理函数，注释掉的定时器默认不启用；可按需开启。
|
||||
- 辅助能力：获取所有连接组 ID、判断是否 host、组内广播工具。
|
||||
|
||||
```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)
|
||||
+onMessage(ws, message)
|
||||
+AddHeartbeat(ws, connectionId)
|
||||
+RemoveHeartbeat(ws)
|
||||
+isHost(ws, connectionId)
|
||||
+broadcastToGroup(connectionId, senderWs, message)
|
||||
}
|
||||
WSSignaling --> WebSocketHandler : "消息分发"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/class/websockethandler.ts:63-479](file://src/class/websockethandler.ts#L63-L479)
|
||||
|
||||
章节来源
|
||||
- [src/class/websockethandler.ts:139-206](file://src/class/websockethandler.ts#L139-L206)
|
||||
- [src/class/websockethandler.ts:208-338](file://src/class/websockethandler.ts#L208-L338)
|
||||
- [src/class/websockethandler.ts:340-402](file://src/class/websockethandler.ts#L340-L402)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
|
||||
### 数据模型
|
||||
- Offer：封装 SDP、时间戳与是否“polite”标记。
|
||||
- Answer：封装 SDP 与时间戳。
|
||||
- Candidate：封装 ICE 候选项与 SDP 元信息及时间戳。
|
||||
|
||||
章节来源
|
||||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||||
|
||||
### 启动与配置
|
||||
- 命令行参数：端口、HTTPS 开关与证书、信令类型（websocket/http）、通信模式（public/private）、日志级别。
|
||||
- HTTPS：当 secure=true 时使用 server.key/server.cert 创建 https.Server。
|
||||
- 信令类型：type=websocket 时启动 WSSignaling；否则提示并回退为 websocket。
|
||||
- 日志：统一通过 log 模块输出启动信息与运行日志。
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:14-109](file://src/index.ts#L14-L109)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
|
||||
### HTTP 信令与 Swagger
|
||||
- HTTP 信令路由：提供会话管理与信令 CRUD 接口，支持会话认证（session-id）。
|
||||
- Swagger：自动扫描 httphandler.ts 与 signaling.ts，生成 API 文档，支持会话认证与信令接口说明。
|
||||
|
||||
章节来源
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
- [src/class/httphandler.ts:1112-1130](file://src/class/httphandler.ts#L1112-L1130)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
## 依赖关系分析
|
||||
- 运行时依赖：ws（WebSocket）、express（HTTP）、morgan（日志）、swagger-ui-express（文档）、uuid（会话 ID）。
|
||||
- 构建与测试：TypeScript、Jest、ESLint、ts-jest 等。
|
||||
- 客户端：浏览器通过 WebSocket 或 HTTP 轮询与服务端交互。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
P["package.json 依赖声明"] --> WS["ws"]
|
||||
P --> EXP["express"]
|
||||
P --> MORGAN["morgan"]
|
||||
P --> SWG["swagger-ui-express"]
|
||||
P --> UUID["uuid"]
|
||||
IDX["src/index.ts"] --> SRV["src/server.ts"]
|
||||
IDX --> WSC["src/websocket.ts"]
|
||||
WSC --> WSH["src/class/websockethandler.ts"]
|
||||
SRV --> SIG["src/signaling.ts"]
|
||||
SRV --> SWG
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [package.json:14-46](file://package.json#L14-L46)
|
||||
- [src/index.ts:7-11](file://src/index.ts#L7-L11)
|
||||
- [src/server.ts:5-9](file://src/server.ts#L5-L9)
|
||||
- [src/websocket.ts:1-4](file://src/websocket.ts#L1-L4)
|
||||
- [src/class/websockethandler.ts:5-8](file://src/class/websockethandler.ts#L5-L8)
|
||||
- [src/signaling.ts:1-3](file://src/signaling.ts#L1-L3)
|
||||
- [src/swagger.ts:5-9](file://src/swagger.ts#L5-L9)
|
||||
|
||||
章节来源
|
||||
- [package.json:14-60](file://package.json#L14-L60)
|
||||
- [src/index.ts:7-11](file://src/index.ts#L7-L11)
|
||||
- [src/server.ts:5-9](file://src/server.ts#L5-L9)
|
||||
- [src/websocket.ts:1-4](file://src/websocket.ts#L1-L4)
|
||||
- [src/class/websockethandler.ts:5-8](file://src/class/websockethandler.ts#L5-L8)
|
||||
- [src/signaling.ts:1-3](file://src/signaling.ts#L1-L3)
|
||||
- [src/swagger.ts:5-9](file://src/swagger.ts#L5-L9)
|
||||
|
||||
## 性能考量
|
||||
- 连接组规模：每组 participants 使用 Set 存储，查找与删除均为 O(1)，适合中小规模并发。
|
||||
- 广播策略：组内广播遍历 participants，建议限制单组成员数量或引入分区策略。
|
||||
- 心跳检测：当前注释掉定时器，避免不必要的 CPU 占用；如启用需合理设置周期与超时阈值。
|
||||
- 日志级别：生产环境建议提升日志级别，减少高频日志输出对性能的影响。
|
||||
- HTTPS 证书：WSS 需要正确配置证书与密钥，确保握手与传输安全。
|
||||
|
||||
## 故障排查指南
|
||||
- 启动与网络
|
||||
- 确认端口占用与防火墙放行。
|
||||
- HTTPS 模式检查 server.key 与 server.cert 是否存在且可读。
|
||||
- WebSocket 连接
|
||||
- 检查客户端 WebSocket URL（ws/wss）与主机一致。
|
||||
- 观察浏览器开发者工具 Network 面板中的 WebSocket 握手与帧。
|
||||
- 信令消息
|
||||
- 使用 Swagger 文档校验 HTTP 信令接口（PUT/GET/POST/DELETE）参数与会话 ID。
|
||||
- 对照客户端 signaling.js 的消息构造与事件派发。
|
||||
- 日志定位
|
||||
- 调整日志级别（info/warn/error/log），关注连接建立、断开、广播与路由关键节点。
|
||||
- 自动化测试
|
||||
- 参考单元测试用例，验证 public/private 模式下的连接、offer/answer/candidate 转发与广播行为。
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:55-88](file://src/index.ts#L55-L88)
|
||||
- [src/log.ts:11-51](file://src/log.ts#L11-L51)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
- [client/src/signaling.js:152-292](file://client/src/signaling.js#L152-L292)
|
||||
- [test/websockethandler.test.ts:1-191](file://test/websockethandler.test.ts#L1-L191)
|
||||
|
||||
## 结论
|
||||
该 WebSocket 服务器模块以简洁清晰的职责划分实现了 WebRTC 信令的核心需求：支持 WebSocket 与 HTTP 两种信令通道、基于连接组的 1对多/多对多路由、广播与定向转发、以及可扩展的消息类型。通过日志与 Swagger 的配合，具备良好的可观测性与可维护性。建议在高并发场景下进一步优化广播与心跳策略，并完善断线重连与幂等处理。
|
||||
|
||||
## 附录
|
||||
|
||||
### WebSocket 连接调试与监控
|
||||
- 浏览器开发者工具：Network 面板查看握手、帧与错误。
|
||||
- Swagger 文档：访问 /api-docs，使用 session-id 头部进行认证，查看 HTTP 信令接口。
|
||||
- 日志：通过命令行参数设置日志级别，观察连接、断开、广播与路由事件。
|
||||
- 心跳：若启用心跳定时器，注意 ping/pong 的周期与超时阈值配置。
|
||||
|
||||
章节来源
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
- [src/log.ts:11-51](file://src/log.ts#L11-L51)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
|
||||
### 连接池管理、心跳检测与断线重连
|
||||
- 连接池管理：clients 与 connectionGroup 维护连接映射与组关系，remove 时清理并广播断开事件。
|
||||
- 心跳检测：提供 AddHeartbeat/RemoveHeartbeat，当前代码注释掉定时器；可按需启用。
|
||||
- 断线重连：客户端应实现指数退避与自动重连逻辑；服务端在断开时通知组内成员并清理资源。
|
||||
|
||||
章节来源
|
||||
- [src/class/websockethandler.ts:115-137](file://src/class/websockethandler.ts#L115-L137)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
- [client/src/signaling.js:230-241](file://client/src/signaling.js#L230-L241)
|
||||
403
.qoder/repowiki/zh/content/服务器核心/信令路由系统.md
Normal file
403
.qoder/repowiki/zh/content/服务器核心/信令路由系统.md
Normal file
@@ -0,0 +1,403 @@
|
||||
# 信令路由系统
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [src/index.ts](file://src/index.ts)
|
||||
- [src/server.ts](file://src/server.ts)
|
||||
- [src/signaling.ts](file://src/signaling.ts)
|
||||
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
|
||||
- [src/class/httphandler.ts](file://src/class/httphandler.ts)
|
||||
- [src/websocket.ts](file://src/websocket.ts)
|
||||
- [src/class/offer.ts](file://src/class/offer.ts)
|
||||
- [src/class/answer.ts](file://src/class/answer.ts)
|
||||
- [src/class/candidate.ts](file://src/class/candidate.ts)
|
||||
- [src/swagger.ts](file://src/swagger.ts)
|
||||
- [src/log.ts](file://src/log.ts)
|
||||
- [test/websockethandler.test.ts](file://test/websockethandler.test.ts)
|
||||
- [test/httphandler.test.ts](file://test/httphandler.test.ts)
|
||||
- [package.json](file://package.json)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件为信令路由系统模块的技术文档，聚焦于 WebSocket 与 HTTP 轮询两种信令模式的实现机制与运行流程。文档详细说明了 HTTP 轮询信令处理器的会话管理、消息缓存与轮询接口设计；解释了信令消息的路由规则、负载均衡与错误恢复机制；并提供不同信令模式的选择指南与性能对比，以及路由配置优化与扩展开发的最佳实践。
|
||||
|
||||
## 项目结构
|
||||
系统采用分层架构，主要由入口启动、HTTP 服务器、WebSocket 信令、HTTP 轮询处理器、数据模型与日志等模块组成。Express 提供 HTTP 服务与路由，WebSocket 作为实时信令通道，HTTP 轮询提供兼容性支持。Swagger 文档自动生成 API 接口说明，便于调试与集成。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["入口启动<br/>src/index.ts"] --> B["HTTP服务器<br/>src/server.ts"]
|
||||
B --> C["信令路由<br/>src/signaling.ts"]
|
||||
C --> D["WebSocket处理器<br/>src/class/websockethandler.ts"]
|
||||
C --> E["HTTP轮询处理器<br/>src/class/httphandler.ts"]
|
||||
D --> F["WebSocket信令服务<br/>src/websocket.ts"]
|
||||
E --> G["数据模型<br/>Offer/Answer/Candidate"]
|
||||
B --> H["Swagger文档<br/>src/swagger.ts"]
|
||||
B --> I["日志系统<br/>src/log.ts"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||||
- [src/websocket.ts:1-118](file://src/websocket.ts#L1-L118)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
|
||||
## 核心组件
|
||||
- 信令路由模块：统一暴露 HTTP 轮询接口，包含会话管理、连接管理、信令消息收发与轮询查询。
|
||||
- WebSocket 信令模块：基于 ws 库，负责实时双向通信、连接组管理与消息广播。
|
||||
- 数据模型：Offer、Answer、Candidate 三类信令消息的数据结构封装。
|
||||
- 日志与配置：统一日志级别控制与启动参数解析。
|
||||
- Swagger 文档：自动生成 API 文档，支持会话认证头 session-id。
|
||||
|
||||
**章节来源**
|
||||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||||
- [src/class/websockethandler.ts:44-168](file://src/class/websockethandler.ts#L44-L168)
|
||||
- [src/class/httphandler.ts:91-213](file://src/class/httphandler.ts#L91-L213)
|
||||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||||
- [src/swagger.ts:44-57](file://src/swagger.ts#L44-L57)
|
||||
|
||||
## 架构概览
|
||||
系统支持两种信令模式：
|
||||
- WebSocket 模式：长连接、低延迟、高吞吐，适合实时互动场景。
|
||||
- HTTP 轮询模式：基于 RESTful 接口，客户端周期性轮询获取信令，适配受限网络环境。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant HTTP as "HTTP服务器<br/>src/server.ts"
|
||||
participant Router as "信令路由<br/>src/signaling.ts"
|
||||
participant WS as "WebSocket处理器<br/>src/class/websockethandler.ts"
|
||||
participant WS_Srv as "WebSocket服务<br/>src/websocket.ts"
|
||||
participant HTTP_Handler as "HTTP处理器<br/>src/class/httphandler.ts"
|
||||
rect rgb(255,255,255)
|
||||
Note over Client,HTTP : WebSocket模式
|
||||
Client->>WS_Srv : 建立WebSocket连接
|
||||
WS_Srv->>WS : 分发消息类型
|
||||
WS-->>Client : 实时转发信令
|
||||
end
|
||||
rect rgb(255,255,255)
|
||||
Note over Client,HTTP : HTTP轮询模式
|
||||
Client->>HTTP : 发送session-id头
|
||||
HTTP->>Router : 路由到signaling
|
||||
Router->>HTTP_Handler : 会话校验与处理
|
||||
HTTP_Handler-->>Client : 返回信令消息列表
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/websocket.ts:27-116](file://src/websocket.ts#L27-L116)
|
||||
- [src/class/websockethandler.ts:72-206](file://src/class/websockethandler.ts#L72-L206)
|
||||
- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||||
- [src/signaling.ts:6-23](file://src/signaling.ts#L6-L23)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### WebSocket 信令处理器
|
||||
WebSocket 处理器负责连接生命周期管理、消息路由与广播。核心能力包括：
|
||||
- 连接组管理：host 与 participants 的角色区分与消息定向转发。
|
||||
- 心跳检测：定期 ping/pong 维持连接活性，超时自动断开。
|
||||
- 广播与定向路由：根据消息类型与角色进行组内广播或跨角色转发。
|
||||
- 会话与连接映射：维护客户端到连接 ID 的映射，支持多连接场景。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class WebSocket处理器 {
|
||||
+reset(mode) void
|
||||
+add(ws) void
|
||||
+remove(ws) void
|
||||
+onConnect(ws, connectionId) void
|
||||
+onDisconnect(ws, connectionId) void
|
||||
+onOffer(ws, message) void
|
||||
+onAnswer(ws, message) void
|
||||
+onCandidate(ws, message) void
|
||||
+onBroadcast(ws, message) void
|
||||
+onMessage(ws, message) void
|
||||
+AddHeartbeat(ws, connectionId) void
|
||||
+RemoveHeartbeat(ws) void
|
||||
+onGetAllConnectionIds() string[]
|
||||
+isHost(ws, connectionId) bool
|
||||
+broadcastToGroup(connectionId, senderWs, message) void
|
||||
}
|
||||
class 连接组 {
|
||||
+host WebSocket
|
||||
+participants Set~WebSocket~
|
||||
}
|
||||
WebSocket处理器 --> 连接组 : "管理"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/class/websockethandler.ts:13-37](file://src/class/websockethandler.ts#L13-L37)
|
||||
- [src/class/websockethandler.ts:44-168](file://src/class/websockethandler.ts#L44-L168)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
|
||||
**章节来源**
|
||||
- [src/class/websockethandler.ts:44-168](file://src/class/websockethandler.ts#L44-L168)
|
||||
- [src/class/websockethandler.ts:208-338](file://src/class/websockethandler.ts#L208-L338)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
|
||||
### HTTP 轮询信令处理器
|
||||
HTTP 轮询处理器以 RESTful API 形式提供信令服务，核心功能包括：
|
||||
- 会话管理：创建、删除会话，维护会话存活时间戳。
|
||||
- 连接管理：创建、删除连接，支持私有模式下的连接对映射。
|
||||
- 消息缓存：Offer、Answer、Candidate 按会话与连接 ID 缓存，支持 fromtime 过滤。
|
||||
- 断开连接记录：记录断开连接的连接 ID 与时间戳，供轮询查询。
|
||||
- 轮询接口：提供 /signaling 与子资源的 GET/POST/PUT/DELETE 接口，统一通过 session-id 头进行鉴权。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["HTTP请求进入"]) --> CheckSession["检查session-id头"]
|
||||
CheckSession --> SessionExists{"会话存在？"}
|
||||
SessionExists --> |否| Return404["返回404"]
|
||||
SessionExists --> |是| UpdateLast["更新最后请求时间"]
|
||||
UpdateLast --> Route["路由到具体处理器"]
|
||||
Route --> CreateSession["创建会话"]
|
||||
Route --> DeleteSession["删除会话"]
|
||||
Route --> CreateConnection["创建连接"]
|
||||
Route --> DeleteConnection["删除连接"]
|
||||
Route --> PostOffer["提交Offer"]
|
||||
Route --> PostAnswer["提交Answer"]
|
||||
Route --> PostCandidate["提交Candidate"]
|
||||
Route --> GetOffer["获取Offer列表"]
|
||||
Route --> GetAnswer["获取Answer列表"]
|
||||
Route --> GetCandidate["获取Candidate列表"]
|
||||
Route --> GetAll["获取所有信令消息"]
|
||||
CreateSession --> ReturnOK["返回JSON"]
|
||||
DeleteSession --> ReturnOK
|
||||
CreateConnection --> ReturnOK
|
||||
DeleteConnection --> ReturnOK
|
||||
PostOffer --> ReturnOK
|
||||
PostAnswer --> ReturnOK
|
||||
PostCandidate --> ReturnOK
|
||||
GetOffer --> ReturnJSON["返回JSON"]
|
||||
GetAnswer --> ReturnJSON
|
||||
GetCandidate --> ReturnJSON
|
||||
GetAll --> ReturnJSON
|
||||
Return404 --> End(["结束"])
|
||||
ReturnOK --> End
|
||||
ReturnJSON --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||||
- [src/class/httphandler.ts:664-675](file://src/class/httphandler.ts#L664-L675)
|
||||
- [src/class/httphandler.ts:689-696](file://src/class/httphandler.ts#L689-L696)
|
||||
- [src/class/httphandler.ts:739-783](file://src/class/httphandler.ts#L739-L783)
|
||||
- [src/class/httphandler.ts:815-828](file://src/class/httphandler.ts#L815-L828)
|
||||
- [src/class/httphandler.ts:855-886](file://src/class/httphandler.ts#L855-L886)
|
||||
- [src/class/httphandler.ts:913-952](file://src/class/httphandler.ts#L913-L952)
|
||||
- [src/class/httphandler.ts:985-998](file://src/class/httphandler.ts#L985-L998)
|
||||
- [src/class/httphandler.ts:615-641](file://src/class/httphandler.ts#L615-L641)
|
||||
|
||||
**章节来源**
|
||||
- [src/class/httphandler.ts:91-120](file://src/class/httphandler.ts#L91-L120)
|
||||
- [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/class/httphandler.ts:274-297](file://src/class/httphandler.ts#L274-L297)
|
||||
- [src/class/httphandler.ts:398-407](file://src/class/httphandler.ts#L398-L407)
|
||||
- [src/class/httphandler.ts:440-447](file://src/class/httphandler.ts#L440-L447)
|
||||
- [src/class/httphandler.ts:492-501](file://src/class/httphandler.ts#L492-L501)
|
||||
- [src/class/httphandler.ts:549-558](file://src/class/httphandler.ts#L549-L558)
|
||||
- [src/class/httphandler.ts:615-641](file://src/class/httphandler.ts#L615-L641)
|
||||
- [src/class/httphandler.ts:739-783](file://src/class/httphandler.ts#L739-L783)
|
||||
- [src/class/httphandler.ts:815-828](file://src/class/httphandler.ts#L815-L828)
|
||||
- [src/class/httphandler.ts:855-886](file://src/class/httphandler.ts#L855-L886)
|
||||
- [src/class/httphandler.ts:913-952](file://src/class/httphandler.ts#L913-L952)
|
||||
- [src/class/httphandler.ts:985-998](file://src/class/httphandler.ts#L985-L998)
|
||||
|
||||
### 信令消息模型
|
||||
Offer、Answer、Candidate 三类消息分别封装 SDP 描述、ICE 候选者信息与时间戳，确保消息缓存与查询的一致性。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Offer {
|
||||
+string sdp
|
||||
+number datetime
|
||||
+boolean polite
|
||||
+constructor(sdp, datetime, polite)
|
||||
}
|
||||
class Answer {
|
||||
+string sdp
|
||||
+number datetime
|
||||
+constructor(sdp, datetime)
|
||||
}
|
||||
class Candidate {
|
||||
+string candidate
|
||||
+number sdpMLineIndex
|
||||
+string sdpMid
|
||||
+number datetime
|
||||
+constructor(candidate, sdpMLineIndex, sdpMid, datetime)
|
||||
}
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||||
|
||||
**章节来源**
|
||||
- [src/class/offer.ts:1-11](file://src/class/offer.ts#L1-L11)
|
||||
- [src/class/answer.ts:1-8](file://src/class/answer.ts#L1-L8)
|
||||
- [src/class/candidate.ts:1-12](file://src/class/candidate.ts#L1-L12)
|
||||
|
||||
### WebSocket 信令服务
|
||||
WebSocket 服务监听连接事件，解析消息类型并调用处理器对应方法，支持 ping/pong 心跳与广播消息。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant WS_Srv as "WebSocket服务<br/>src/websocket.ts"
|
||||
participant Handler as "WebSocket处理器<br/>src/class/websockethandler.ts"
|
||||
Client->>WS_Srv : 建立连接
|
||||
WS_Srv->>Handler : add(ws)
|
||||
Client->>WS_Srv : 发送消息
|
||||
WS_Srv->>Handler : 根据type分发
|
||||
Handler-->>Client : 转发信令或广播
|
||||
Client-->>WS_Srv : 关闭连接
|
||||
WS_Srv->>Handler : remove(ws)
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/websocket.ts:27-116](file://src/websocket.ts#L27-L116)
|
||||
- [src/class/websockethandler.ts:72-137](file://src/class/websockethandler.ts#L72-L137)
|
||||
|
||||
**章节来源**
|
||||
- [src/websocket.ts:27-116](file://src/websocket.ts#L27-L116)
|
||||
- [src/class/websockethandler.ts:72-137](file://src/class/websockethandler.ts#L72-L137)
|
||||
|
||||
## 依赖关系分析
|
||||
- 入口模块负责解析命令行参数、创建 HTTP 服务器与选择信令模式。
|
||||
- 服务器模块装配 CORS、静态资源、Swagger 文档与 /signaling 路由。
|
||||
- 信令路由模块挂载到 /signaling，内部通过中间件校验 session-id。
|
||||
- WebSocket 与 HTTP 处理器共享通信模式配置，保证行为一致性。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Index["入口<br/>src/index.ts"] --> Server["服务器<br/>src/server.ts"]
|
||||
Server --> Signaling["信令路由<br/>src/signaling.ts"]
|
||||
Signaling --> WS_Handler["WebSocket处理器<br/>src/class/websockethandler.ts"]
|
||||
Signaling --> HTTP_Handler["HTTP处理器<br/>src/class/httphandler.ts"]
|
||||
Server --> Swagger["Swagger<br/>src/swagger.ts"]
|
||||
Server --> Log["日志<br/>src/log.ts"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||||
- [src/server.ts:16-41](file://src/server.ts#L16-L41)
|
||||
- [src/signaling.ts:10-23](file://src/signaling.ts#L10-L23)
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||||
- [src/server.ts:16-41](file://src/server.ts#L16-L41)
|
||||
- [src/signaling.ts:10-23](file://src/signaling.ts#L10-L23)
|
||||
|
||||
## 性能考虑
|
||||
- WebSocket 模式
|
||||
- 优势：全双工、低延迟、减少 HTTP 开销；心跳机制保障连接活性。
|
||||
- 注意：连接数增长带来内存与 CPU 压力，需结合负载均衡与连接池策略。
|
||||
- HTTP 轮询模式
|
||||
- 优势：兼容性好、易于部署；适合弱网或受限环境。
|
||||
- 注意：频繁轮询增加服务器压力，建议合理设置轮询间隔与缓存策略。
|
||||
- 会话超时清理
|
||||
- HTTP 轮询处理器按最后请求时间清理超时会话，避免内存泄漏。
|
||||
- 负载均衡与扩展
|
||||
- 建议使用反向代理与多实例部署，结合会话亲和或共享存储实现横向扩展。
|
||||
|
||||
[本节为通用性能指导，无需列出具体文件来源]
|
||||
|
||||
## 故障排查指南
|
||||
- 会话不存在
|
||||
- 症状：HTTP 轮询返回 404。
|
||||
- 排查：确认请求头包含有效的 session-id；检查会话是否被超时清理。
|
||||
- 参考：[src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||||
- 连接 ID 冲突（私有模式）
|
||||
- 症状：创建连接时报错“连接ID已被使用”。
|
||||
- 排查：检查连接对映射，确保同一 connectionId 仅在两个会话间配对。
|
||||
- 参考：[src/class/httphandler.ts:754-776](file://src/class/httphandler.ts#L754-L776)
|
||||
- 信令消息缺失
|
||||
- 症状：轮询未返回预期消息。
|
||||
- 排查：确认 fromtime 参数与消息时间戳；检查是否被超时清理。
|
||||
- 参考：[src/class/httphandler.ts:274-297](file://src/class/httphandler.ts#L274-L297)
|
||||
- WebSocket 连接异常断开
|
||||
- 症状：心跳超时触发断开。
|
||||
- 排查：检查客户端 ping/pong 交互；确认网络稳定性。
|
||||
- 参考：[src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
- Swagger 文档不可用
|
||||
- 症状：/api-docs 无法访问。
|
||||
- 排查：确认 Swagger 初始化与服务器地址配置正确。
|
||||
- 参考：[src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
**章节来源**
|
||||
- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||||
- [src/class/httphandler.ts:754-776](file://src/class/httphandler.ts#L754-L776)
|
||||
- [src/class/httphandler.ts:274-297](file://src/class/httphandler.ts#L274-L297)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
## 结论
|
||||
本信令路由系统通过 WebSocket 与 HTTP 轮询两种模式满足不同网络与部署需求。WebSocket 提供低延迟实时通信，HTTP 轮询提供兼容性与易用性。HTTP 处理器通过会话与连接映射、消息缓存与超时清理机制，确保在高并发场景下的稳定性。建议根据业务场景选择合适模式，并结合负载均衡与监控体系持续优化。
|
||||
|
||||
[本节为总结性内容，无需列出具体文件来源]
|
||||
|
||||
## 附录
|
||||
|
||||
### 信令模式选择指南
|
||||
- 优先选择 WebSocket：实时性要求高、网络稳定、客户端支持良好。
|
||||
- 选择 HTTP 轮询：受限网络、防火墙严格、客户端仅支持 HTTP/HTTPS。
|
||||
- 混合策略：在 WebSocket 不可用时回退至 HTTP 轮询，提升兼容性。
|
||||
|
||||
[本节为通用指导，无需列出具体文件来源]
|
||||
|
||||
### 配置与启动
|
||||
- 启动参数
|
||||
- -p/--port：监听端口
|
||||
- -s/--secure：启用 HTTPS
|
||||
- -k/--keyfile/-c/--certfile：证书与密钥文件
|
||||
- -t/--type：信令类型（websocket 或 http）
|
||||
- -m/--mode：通信模式（public 或 private）
|
||||
- -l/--logging：HTTP 日志格式
|
||||
- 示例脚本
|
||||
- 开发模式：dev
|
||||
- 生产模式：start
|
||||
|
||||
**章节来源**
|
||||
- [src/index.ts:20-40](file://src/index.ts#L20-L40)
|
||||
- [package.json:5-12](file://package.json#L5-L12)
|
||||
|
||||
### API 文档与安全
|
||||
- Swagger 文档：/api-docs
|
||||
- 认证方式：session-id 头部
|
||||
- 会话超时：HTTP 轮询处理器内置超时清理逻辑
|
||||
|
||||
**章节来源**
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
- [src/class/httphandler.ts:218-232](file://src/class/httphandler.ts#L218-L232)
|
||||
|
||||
### 测试参考
|
||||
- WebSocket 单元测试：覆盖公共与私有模式下的连接、消息路由与断开流程。
|
||||
- HTTP 单元测试：覆盖会话创建/删除、连接管理、消息提交与轮询查询、超时清理等场景。
|
||||
|
||||
**章节来源**
|
||||
- [test/websockethandler.test.ts:9-191](file://test/websockethandler.test.ts#L9-L191)
|
||||
- [test/httphandler.test.ts:6-510](file://test/httphandler.test.ts#L6-L510)
|
||||
332
.qoder/repowiki/zh/content/服务器核心/日志系统.md
Normal file
332
.qoder/repowiki/zh/content/服务器核心/日志系统.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# 日志系统
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [src/log.ts](file://src/log.ts)
|
||||
- [src/index.ts](file://src/index.ts)
|
||||
- [src/class/httphandler.ts](file://src/class/httphandler.ts)
|
||||
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
|
||||
- [client/src/logger.js](file://client/src/logger.js)
|
||||
- [package.json](file://package.json)
|
||||
- [src/class/options.ts](file://src/class/options.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本技术文档聚焦于视频服务器项目的日志系统模块，系统性阐述日志级别管理、输出格式控制与日志轮转机制现状，解释 LogLevel 枚举的使用场景与差异，说明当前日志输出目标（控制台为主），并给出性能优化建议、调试技巧以及与日志分析与监控告警的集成思路。由于仓库中未发现文件落盘或远程日志服务的直接实现，本文在“输出目标”部分明确指出当前限制，并在“附录”中提供可扩展的实践建议。
|
||||
|
||||
## 项目结构
|
||||
日志系统主要由以下部分组成：
|
||||
- 服务端日志模块：定义日志级别、格式化与输出逻辑
|
||||
- 应用入口：解析命令行参数并调用日志模块进行启动信息输出
|
||||
- 业务处理器：在 HTTP 与 WebSocket 层面使用统一日志模块进行运行态事件记录
|
||||
- 客户端日志模块：提供简易调试开关与条件输出（与服务端日志模块独立）
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["应用入口<br/>src/index.ts"] --> B["日志模块<br/>src/log.ts"]
|
||||
C["HTTP处理器<br/>src/class/httphandler.ts"] --> B
|
||||
D["WebSocket处理器<br/>src/class/websockethandler.ts"] --> B
|
||||
E["客户端日志模块<br/>client/src/logger.js"] -. 独立调试 .-> B
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:11-91](file://src/index.ts#L11-L91)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
- [src/class/httphandler.ts:11](file://src/class/httphandler.ts#L11)
|
||||
- [src/class/websockethandler.ts:8](file://src/class/websockethandler.ts#L8)
|
||||
- [client/src/logger.js:1-30](file://client/src/logger.js#L1-L30)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:11-91](file://src/index.ts#L11-L91)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
- [src/class/httphandler.ts:11](file://src/class/httphandler.ts#L11)
|
||||
- [src/class/websockethandler.ts:8](file://src/class/websockethandler.ts#L8)
|
||||
- [client/src/logger.js:1-30](file://client/src/logger.js#L1-L30)
|
||||
|
||||
## 核心组件
|
||||
- 日志级别枚举与控制
|
||||
- LogLevel 枚举定义了 none、error、warn、log、info 五个级别，数值越大级别越高
|
||||
- 提供 setLogLevel 与 parseLogLevel，支持从字符串解析并动态调整全局日志级别
|
||||
- 日志输出与格式
|
||||
- 输出统一走浏览器/Node 控制台接口，自动添加 ISO 时间戳与大写的级别前缀
|
||||
- 不同级别对应不同的控制台输出方法，便于在浏览器开发者工具中区分
|
||||
- 使用分布
|
||||
- 应用入口在启动阶段输出网络地址、协议类型与模式等关键信息
|
||||
- HTTP 与 WebSocket 处理器在连接建立、断开、超时、信令交互等关键节点输出运行态日志
|
||||
|
||||
章节来源
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
- [src/index.ts:63-90](file://src/index.ts#L63-L90)
|
||||
- [src/class/httphandler.ts:230](file://src/class/httphandler.ts#L230)
|
||||
- [src/class/websockethandler.ts:77](file://src/class/websockethandler.ts#L77)
|
||||
|
||||
## 架构总览
|
||||
日志模块在服务端采用集中式设计：统一的枚举与格式化逻辑，配合各业务模块按需调用。整体调用链路如下：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as "命令行/环境变量"
|
||||
participant App as "应用入口<br/>src/index.ts"
|
||||
participant Log as "日志模块<br/>src/log.ts"
|
||||
participant HTTP as "HTTP处理器<br/>src/class/httphandler.ts"
|
||||
participant WS as "WebSocket处理器<br/>src/class/websockethandler.ts"
|
||||
CLI->>App : 解析参数(-l/-m/-t等)
|
||||
App->>Log : 输出启动信息(info/warn)
|
||||
HTTP->>Log : 关键事件(log/info/warn/error)
|
||||
WS->>Log : 关键事件(log/info/warn/error)
|
||||
Log-->>Console : 控制台输出(带时间戳与级别)
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:63-90](file://src/index.ts#L63-L90)
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
- [src/class/httphandler.ts:230](file://src/class/httphandler.ts#L230)
|
||||
- [src/class/websockethandler.ts:413](file://src/class/websockethandler.ts#L413)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 日志模块（src/log.ts）
|
||||
- 设计要点
|
||||
- 通过全局变量维护当前日志级别，决定是否输出
|
||||
- parseLogLevel 支持从字符串解析级别，默认回退到 info
|
||||
- formatTimestamp 统一 ISO 时间戳格式
|
||||
- 根据级别选择控制台输出方法，便于区分错误、警告、信息与普通日志
|
||||
- 性能与行为
|
||||
- 条件判断在输出前完成，避免不必要的字符串拼接
|
||||
- 控制台输出为同步 I/O，适合开发与调试；生产环境建议结合外部日志采集
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入 log(level, ...args)"]) --> Check["比较 level 与当前级别<br/>与 none 特判"]
|
||||
Check --> |不满足| Exit["直接返回"]
|
||||
Check --> |满足| Stamp["生成 ISO 时间戳"]
|
||||
Stamp --> Prefix["构造前缀: [时间戳] [级别]"]
|
||||
Prefix --> Switch{"根据级别选择输出方法"}
|
||||
Switch --> |error| OutErr["console.error(...)"]
|
||||
Switch --> |warn| OutWarn["console.warn(...)"]
|
||||
Switch --> |info| OutInfo["console.info(...)"]
|
||||
Switch --> |其他| OutLog["console.log(...)"]
|
||||
OutErr --> End(["结束"])
|
||||
OutWarn --> End
|
||||
OutInfo --> End
|
||||
OutLog --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
|
||||
章节来源
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
|
||||
### 应用入口与日志使用（src/index.ts）
|
||||
- 启动阶段日志
|
||||
- 输出 HTTP/HTTPS 地址、信令协议类型、模式等关键信息
|
||||
- 对不支持的信令类型发出警告并回退到默认值
|
||||
- 参数来源
|
||||
- 通过 commander 解析命令行参数，同时兼容环境变量
|
||||
- logging 参数与 morgan 中间件相关（见“依赖关系分析”）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Entrypoint as "应用入口<br/>src/index.ts"
|
||||
participant Log as "日志模块<br/>src/log.ts"
|
||||
Entrypoint->>Log : info("启动地址/模式/协议等")
|
||||
Entrypoint->>Log : warn("不支持的信令类型/回退提示")
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:63-90](file://src/index.ts#L63-L90)
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:11-91](file://src/index.ts#L11-L91)
|
||||
|
||||
### HTTP 处理器中的日志（src/class/httphandler.ts）
|
||||
- 关键节点日志
|
||||
- 会话超时清理：输出被删除的会话 ID
|
||||
- 连接/断开/参与者加入/离开等事件：输出连接 ID 与上下文信息
|
||||
- 错误场景：对非法参数或冲突状态输出警告
|
||||
- 日志级别选择
|
||||
- 一般事件使用 log 或 info
|
||||
- 异常或异常流程使用 warn
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant HTTP as "HTTP处理器<br/>src/class/httphandler.ts"
|
||||
participant Log as "日志模块<br/>src/log.ts"
|
||||
HTTP->>Log : log("超时删除会话 sessionId=...")
|
||||
HTTP->>Log : warn("连接ID已使用/参数缺失等")
|
||||
HTTP->>Log : log("参与者加入/离开/断开连接等")
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/class/httphandler.ts:230](file://src/class/httphandler.ts#L230)
|
||||
- [src/class/httphandler.ts:761](file://src/class/httphandler.ts#L761)
|
||||
|
||||
章节来源
|
||||
- [src/class/httphandler.ts:230](file://src/class/httphandler.ts#L230)
|
||||
- [src/class/httphandler.ts:761](file://src/class/httphandler.ts#L761)
|
||||
|
||||
### WebSocket 处理器中的日志（src/class/websockethandler.ts）
|
||||
- 关键节点日志
|
||||
- 连接建立/断开、参与者加入/离开、主机断开、心跳超时等
|
||||
- 心跳定时器：周期性输出心跳状态与超时检测
|
||||
- 日志级别选择
|
||||
- 事件性信息使用 log
|
||||
- 超时与异常使用 warn
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant WS as "WebSocket处理器<br/>src/class/websockethandler.ts"
|
||||
participant Log as "日志模块<br/>src/log.ts"
|
||||
WS->>Log : log("Add WebSocket/参与者加入/断开连接等")
|
||||
WS->>Log : warn("WebSocket连接超时, closing...")
|
||||
WS->>Log : log("WebSocket连接心跳 lastActivity=...")
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/class/websockethandler.ts:77](file://src/class/websockethandler.ts#L77)
|
||||
- [src/class/websockethandler.ts:154](file://src/class/websockethandler.ts#L154)
|
||||
- [src/class/websockethandler.ts:192](file://src/class/websockethandler.ts#L192)
|
||||
- [src/class/websockethandler.ts:413](file://src/class/websockethandler.ts#L413)
|
||||
- [src/class/websockethandler.ts:420](file://src/class/websockethandler.ts#L420)
|
||||
|
||||
章节来源
|
||||
- [src/class/websockethandler.ts:77](file://src/class/websockethandler.ts#L77)
|
||||
- [src/class/websockethandler.ts:154](file://src/class/websockethandler.ts#L154)
|
||||
- [src/class/websockethandler.ts:192](file://src/class/websockethandler.ts#L192)
|
||||
- [src/class/websockethandler.ts:413](file://src/class/websockethandler.ts#L413)
|
||||
- [src/class/websockethandler.ts:420](file://src/class/websockethandler.ts#L420)
|
||||
|
||||
### 客户端日志模块（client/src/logger.js）
|
||||
- 功能概述
|
||||
- 提供启用/禁用调试开关
|
||||
- 在调试开启时输出 debug/info/log/warn/error 级别消息
|
||||
- 适用场景
|
||||
- 前端调试与本地开发，与服务端日志模块解耦
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["调用 debug/info/log/warn/error"]) --> Check["检查 isDebug 标志"]
|
||||
Check --> |false| Exit["直接返回"]
|
||||
Check --> |true| Console["console.debug/info/log/warn/error(...)"]
|
||||
Console --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [client/src/logger.js:11-29](file://client/src/logger.js#L11-L29)
|
||||
|
||||
章节来源
|
||||
- [client/src/logger.js:1-30](file://client/src/logger.js#L1-L30)
|
||||
|
||||
## 依赖关系分析
|
||||
- 日志模块依赖
|
||||
- 服务端日志模块仅依赖标准控制台输出，无第三方依赖
|
||||
- 客户端日志模块同样依赖浏览器/Node 控制台
|
||||
- HTTP 中间件与日志
|
||||
- 项目包含 morgan（HTTP 请求访问日志中间件），与自研日志模块互补
|
||||
- logging 参数影响 morgan 的日志格式（如 combined/dev/short/tiny 或 none）
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Log["日志模块<br/>src/log.ts"] --> Console["控制台输出"]
|
||||
HTTP["HTTP中间件(morgan)"] --> Console
|
||||
App["应用入口<br/>src/index.ts"] --> Log
|
||||
HTTPMod["HTTP处理器<br/>src/class/httphandler.ts"] --> Log
|
||||
WSMod["WebSocket处理器<br/>src/class/websockethandler.ts"] --> Log
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
- [package.json:21](file://package.json#L21)
|
||||
- [src/index.ts:28](file://src/index.ts#L28)
|
||||
|
||||
章节来源
|
||||
- [package.json:14-27](file://package.json#L14-L27)
|
||||
- [src/index.ts:28](file://src/index.ts#L28)
|
||||
|
||||
## 性能考量
|
||||
- 当前实现特点
|
||||
- 控制台输出为同步 I/O，简单可靠，适合开发与小规模生产调试
|
||||
- 未内置异步写盘或远程上报能力
|
||||
- 性能优化建议
|
||||
- 降低高频事件日志量：将细粒度 log 降级为 info 或在高并发场景减少输出
|
||||
- 使用 parseLogLevel 与 setLogLevel 动态调整级别：生产环境默认 info 或 warn
|
||||
- 结合 morgan 的短格式或关闭策略，减少 HTTP 访问日志对吞吐的影响
|
||||
- 对热点路径的日志进行采样或聚合，避免频繁 I/O
|
||||
- 与 morgan 的协同
|
||||
- logging 参数可选：combined/dev/short/tiny 或 none，按需选择以平衡可观测性与性能
|
||||
|
||||
章节来源
|
||||
- [src/log.ts:15-24](file://src/log.ts#L15-L24)
|
||||
- [src/index.ts:28](file://src/index.ts#L28)
|
||||
- [package.json:21](file://package.json#L21)
|
||||
|
||||
## 故障排查指南
|
||||
- 常见问题定位
|
||||
- 无法看到预期日志：确认当前日志级别是否高于目标级别，或是否被 none 特判拦截
|
||||
- 信令异常：关注 HTTP/WS 处理器中的 warn 与 error 输出，定位参数缺失、冲突或超时
|
||||
- 心跳超时：WebSocket 处理器会输出超时警告，检查网络质量与客户端活跃度
|
||||
- 调试技巧
|
||||
- 在应用入口处临时提升日志级别，获取更详细的启动与初始化信息
|
||||
- 使用客户端 logger.js 的调试开关，在前端侧快速验证消息流转
|
||||
- 结合浏览器开发者工具的控制台筛选功能，按级别过滤输出
|
||||
|
||||
章节来源
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
- [src/class/websockethandler.ts:413](file://src/class/websockethandler.ts#L413)
|
||||
- [client/src/logger.js:1-30](file://client/src/logger.js#L1-L30)
|
||||
|
||||
## 结论
|
||||
本项目的日志系统以轻量、集中式为核心：统一的级别与格式化逻辑，配合业务模块在关键节点输出运行态信息。当前实现以控制台输出为主，未包含文件落盘与远程上报。通过合理设置日志级别、结合 morgan 的访问日志策略，可在开发与生产环境中取得良好的可观测性与性能平衡。若需进一步增强，可在现有日志模块基础上扩展文件轮转与远程推送能力。
|
||||
|
||||
## 附录
|
||||
|
||||
### 日志级别与应用场景
|
||||
- none：完全屏蔽日志输出
|
||||
- error：致命错误，应立即修复
|
||||
- warn：潜在风险或异常流程，需关注
|
||||
- log：常规事件性信息，适合高频但非关键的运行态记录
|
||||
- info：重要状态变更与启动/停止信息
|
||||
|
||||
章节来源
|
||||
- [src/log.ts:1-7](file://src/log.ts#L1-L7)
|
||||
- [src/class/httphandler.ts:230](file://src/class/httphandler.ts#L230)
|
||||
- [src/class/websockethandler.ts:77](file://src/class/websockethandler.ts#L77)
|
||||
|
||||
### 日志输出目标与扩展
|
||||
- 当前实现
|
||||
- 仅控制台输出，无文件落盘与远程日志服务
|
||||
- 扩展建议
|
||||
- 文件落盘：在日志模块中增加文件句柄与滚动策略（按大小/时间）
|
||||
- 远程上报：在日志模块中增加 HTTP 推送或 SDK 接入（如 Loki、ELK、Sentry）
|
||||
- 与 morgan 协同：通过 logging 参数控制 HTTP 访问日志格式与级别
|
||||
|
||||
章节来源
|
||||
- [src/log.ts:30-50](file://src/log.ts#L30-L50)
|
||||
- [package.json:21](file://package.json#L21)
|
||||
- [src/index.ts:28](file://src/index.ts#L28)
|
||||
|
||||
### 日志分析与监控告警集成
|
||||
- 分析工具
|
||||
- 将控制台输出重定向至文件或管道，接入日志收集系统（如 Fluent Bit、Filebeat）
|
||||
- 使用正则提取时间戳与级别字段，构建结构化日志
|
||||
- 监控告警
|
||||
- 基于 error/warn 比例与速率阈值触发告警
|
||||
- 结合业务指标（连接数、超时率、信令成功率）进行综合评估
|
||||
|
||||
章节来源
|
||||
- [src/class/websockethandler.ts:413](file://src/class/websockethandler.ts#L413)
|
||||
- [src/class/httphandler.ts:230](file://src/class/httphandler.ts#L230)
|
||||
378
.qoder/repowiki/zh/content/服务器核心/服务器入口点.md
Normal file
378
.qoder/repowiki/zh/content/服务器核心/服务器入口点.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# 服务器入口点
|
||||
|
||||
<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)
|
||||
507
.qoder/repowiki/zh/content/服务器核心/服务器核心.md
Normal file
507
.qoder/repowiki/zh/content/服务器核心/服务器核心.md
Normal file
@@ -0,0 +1,507 @@
|
||||
# 服务器核心
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [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)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向服务器核心模块，系统化阐述以下主题：
|
||||
- 服务器入口点的设计与实现：命令行参数解析、配置加载与服务器启动流程
|
||||
- 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
|
||||
|
||||
```mermaid
|
||||
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](file://src/index.ts#L1-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
|
||||
## 核心组件
|
||||
- 入口与配置装载
|
||||
- 使用命令行参数解析器装载配置，支持端口、HTTPS、证书、信令类型、通信模式、日志级别等选项
|
||||
- 根据配置创建 Express 应用与 HTTP/HTTPS 服务器实例
|
||||
- Express 服务器装配
|
||||
- 配置日志中间件、CORS、JSON/URL 编码解析、静态资源、Swagger 文档、头像上传接口
|
||||
- 信令路由
|
||||
- HTTP 轮询：基于会话 ID 的 REST 接口，支持增量拉取
|
||||
- WebSocket：基于连接组的 1 对多路由，支持私有模式与公共模式
|
||||
- 日志系统
|
||||
- 支持多等级日志输出，可通过配置调整日志级别
|
||||
- Swagger 文档
|
||||
- 自动生成 API 文档，支持会话认证头
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:14-109](file://src/index.ts#L14-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/class/httphandler.ts:1112-1129](file://src/class/httphandler.ts#L1112-L1129)
|
||||
- [src/class/websockethandler.ts:478](file://src/class/websockethandler.ts#L478)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
## 架构总览
|
||||
服务器采用“入口模块 + Express 服务器 + 信令路由 + WebSocket 信令”的分层架构。入口模块负责参数解析与服务器启动；Express 负责 HTTP 层面的中间件、静态资源与 API；信令路由在 HTTP 层提供轮询接口，在 WebSocket 层提供实时消息分发。
|
||||
|
||||
```mermaid
|
||||
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](file://src/index.ts#L13-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 入口模块与启动流程
|
||||
- 命令行参数解析
|
||||
- 支持端口、HTTPS、证书文件、信令类型（websocket/http）、通信模式（public/private）、日志级别等
|
||||
- 环境变量可作为默认值来源
|
||||
- 服务器创建与启动
|
||||
- 根据 secure 选项创建 HTTP 或 HTTPS 服务器
|
||||
- 启动后打印访问地址（IPv4）
|
||||
- 信令类型与模式
|
||||
- 校验信令类型，不支持则回退为 websocket
|
||||
- 根据模式启动 WebSocket 信令服务器
|
||||
|
||||
```mermaid
|
||||
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 : 连接事件/消息处理就绪
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [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/index.ts:14-109](file://src/index.ts#L14-L109)
|
||||
|
||||
### HTTP 服务器与中间件配置
|
||||
- 中间件与静态资源
|
||||
- 日志中间件：支持多种日志格式（combined/dev/short/tiny/none）
|
||||
- CORS：允许任意来源
|
||||
- JSON/URL 编码解析
|
||||
- 静态资源：首页、模块资源
|
||||
- API 与路由
|
||||
- /config：返回服务器配置（是否使用 WebSocket、启动模式、日志级别）
|
||||
- /signaling：挂载信令路由
|
||||
- /api/upload/avatar：头像上传（临时文件名，服务端重命名为 userId.{ext}）
|
||||
- /uploads：头像目录静态访问
|
||||
- Swagger 文档
|
||||
- 自动扫描 HTTP 处理器注释，生成 API 文档
|
||||
|
||||
```mermaid
|
||||
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(["完成"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
章节来源
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
### 信令路由系统（HTTP 轮询）
|
||||
- 会话与连接管理
|
||||
- 会话超时：10 秒无请求自动删除
|
||||
- 连接对：私有模式下通过 connectionId 建立 host/participants 关系
|
||||
- 路由与处理器
|
||||
- 无需会话 ID 的路由：/signaling/connection-ids
|
||||
- 需要会话 ID 的路由：统一中间件校验 session-id
|
||||
- 提供连接、offer、answer、candidate 的增删改查与增量拉取
|
||||
- 增量拉取
|
||||
- fromtime 查询参数用于增量获取消息，避免重复传输
|
||||
|
||||
```mermaid
|
||||
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 响应
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [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-641](file://src/class/httphandler.ts#L398-L641)
|
||||
|
||||
章节来源
|
||||
- [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-641](file://src/class/httphandler.ts#L398-L641)
|
||||
|
||||
### 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，超时断开
|
||||
|
||||
```mermaid
|
||||
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}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/websocket.ts:15-118](file://src/websocket.ts#L15-L118)
|
||||
- [src/class/websockethandler.ts:145-206](file://src/class/websockethandler.ts#L145-L206)
|
||||
- [src/class/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
|
||||
|
||||
章节来源
|
||||
- [src/websocket.ts:15-118](file://src/websocket.ts#L15-L118)
|
||||
- [src/class/websockethandler.ts:145-206](file://src/class/websockethandler.ts#L145-L206)
|
||||
- [src/class/websockethandler.ts:214-338](file://src/class/websockethandler.ts#L214-L338)
|
||||
|
||||
### 日志系统集成与配置
|
||||
- 日志等级
|
||||
- 支持 none/error/warn/log/info 等等级
|
||||
- 可通过配置字符串解析为等级枚举
|
||||
- 输出行为
|
||||
- 根据等级决定是否输出
|
||||
- 统一时间戳与前缀格式
|
||||
- 使用场景
|
||||
- 启动信息、访问日志、错误告警、运行时事件
|
||||
|
||||
章节来源
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
|
||||
### Swagger 文档与 API 文档
|
||||
- 自动扫描
|
||||
- 扫描 HTTP 处理器与路由文件，提取注释生成 OpenAPI 文档
|
||||
- 安全方案
|
||||
- 会话认证头：session-id
|
||||
- 访问
|
||||
- /api-docs
|
||||
|
||||
章节来源
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
|
||||
## 依赖分析
|
||||
- 入口模块依赖
|
||||
- 命令行解析、HTTPS/HTTP 服务器、WebSocket 信令、日志工具、配置选项
|
||||
- 服务器装配依赖
|
||||
- Express、Morgan、CORS、Multer、Swagger UI、静态资源
|
||||
- 信令处理器依赖
|
||||
- UUID、WebSocket 处理器、日志工具
|
||||
- 文档与脚本
|
||||
- Swagger 配置、NPM 脚本、批处理脚本
|
||||
|
||||
```mermaid
|
||||
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](file://src/index.ts#L13-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
- [src/signaling.ts:1-25](file://src/signaling.ts#L1-L25)
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/class/httphandler.ts:1-1130](file://src/class/httphandler.ts#L1-L1130)
|
||||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||||
- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
|
||||
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
|
||||
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||||
|
||||
## 性能考量
|
||||
- 服务器启动与监听
|
||||
- 仅监听 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](file://src/index.ts#L55-L74)
|
||||
- [src/server.ts:44-83](file://src/server.ts#L44-L83)
|
||||
- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
|
||||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||||
|
||||
## 结论
|
||||
服务器核心模块通过清晰的分层设计实现了高性能、可扩展的信令服务。入口模块负责配置与启动，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
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:20-29](file://src/index.ts#L20-L29)
|
||||
|
||||
### HTTPS 与证书
|
||||
- 启用 HTTPS 时需提供 server.key 与 server.cert
|
||||
- 启动后打印 https:// 地址
|
||||
|
||||
章节来源
|
||||
- [src/index.ts:55-65](file://src/index.ts#L55-L65)
|
||||
|
||||
### CORS 配置
|
||||
- 允许任意来源（*）
|
||||
|
||||
章节来源
|
||||
- [src/server.ts:22](file://src/server.ts#L22)
|
||||
|
||||
### Swagger 文档访问
|
||||
- /api-docs
|
||||
|
||||
章节来源
|
||||
- [src/swagger.ts:63](file://src/swagger.ts#L63)
|
||||
|
||||
### 头像上传 API
|
||||
- POST /api/upload/avatar
|
||||
- 参数：userId（body）、avatar（file）
|
||||
- 响应：success、avatarUrl、message
|
||||
|
||||
章节来源
|
||||
- [src/server.ts:62-83](file://src/server.ts#L62-L83)
|
||||
|
||||
### 服务器启动脚本
|
||||
- package.json scripts
|
||||
- start：构建并启动
|
||||
- dev：开发模式
|
||||
- run.bat：Windows 批处理示例
|
||||
|
||||
章节来源
|
||||
- [package.json:5-12](file://package.json#L5-L12)
|
||||
- [run.bat:8](file://run.bat#L8)
|
||||
|
||||
### 服务器核心类图（代码级）
|
||||
```mermaid
|
||||
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 : "使用"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
|
||||
- [src/websocket.ts:6-118](file://src/websocket.ts#L6-L118)
|
||||
- [src/class/httphandler.ts:1112-1129](file://src/class/httphandler.ts#L1112-L1129)
|
||||
- [src/class/websockethandler.ts:478](file://src/class/websockethandler.ts#L478)
|
||||
Reference in New Issue
Block a user