Files
video_socket-server/.qoder/repowiki/zh/content/服务器核心/服务器核心.md
2026-05-16 13:24:02 +08:00

507 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 服务器核心
<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
- 信令路由HTTPsrc/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
- WebRTCoffer/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/--typewebsocket 或 http
- 通信模式:-m/--modepublic 或 private
- 日志级别:-l/--loggingcombined/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
- 参数userIdbody、avatarfile
- 响应success、avatarUrl、message
章节来源
- [src/server.ts:62-83](file://src/server.ts#L62-L83)
### 服务器启动脚本
- package.json scripts
- start构建并启动
- dev开发模式
- run.batWindows 批处理示例
章节来源
- [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)