# 服务器核心

<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)