# 快速开始

<cite>
**本文引用的文件**
- [package.json](file://package.json)
- [tsconfig.json](file://tsconfig.json)
- [src/index.ts](file://src/index.ts)
- [src/server.ts](file://src/server.ts)
- [src/class/options.ts](file://src/class/options.ts)
- [run.bat](file://run.bat)
- [client/public/index.html](file://client/public/index.html)
- [client/public/bidirectional/index.html](file://client/public/bidirectional/index.html)
- [client/public/bidirectional/js/main.js](file://client/public/bidirectional/js/main.js)
- [client/public/receiver/index.html](file://client/public/receiver/index.html)
- [client/public/receiver/js/main.js](file://client/public/receiver/js/main.js)
- [client/public/multiplay/index.html](file://client/public/multiplay/index.html)
- [client/public/multiplay/js/main.js](file://client/public/multiplay/js/main.js)
- [client/package.json](file://client/package.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本快速开始指南面向首次部署与运行 Video Socket Server 的用户，涵盖以下内容：
- 环境要求：Node.js 版本、操作系统兼容性与依赖工具
- 安装与构建：全局安装 TypeScript 与开发工具，构建后端与打包
- 启动服务器：命令行参数详解（端口、模式、SSL 证书等）
- 运行内置客户端示例：双向通信、视频接收、多客户端播放
- 常见问题与故障排除：证书缺失、端口占用、浏览器限制等
- 实际命令行示例与预期输出

## 项目结构
该仓库采用“前后端同源”的组织方式：服务端为基于 Express 的 Node.js 应用，前端示例位于 client/public 与 client/src，通过静态资源与 API 提供完整的 WebRTC 示例页面。

```mermaid
graph TB
subgraph "服务端"
A["Express 应用<br/>src/server.ts"]
B["入口与参数解析<br/>src/index.ts"]
C["选项类型定义<br/>src/class/options.ts"]
end
subgraph "客户端示例"
D["首页与导航<br/>client/public/index.html"]
E["双向通信示例<br/>client/public/bidirectional/index.html"]
F["接收端示例<br/>client/public/receiver/index.html"]
G["多人播放示例<br/>client/public/multiplay/index.html"]
end
B --> A
A --> D
D --> E
D --> F
D --> G
```

图表来源
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
- [client/public/index.html:1-78](file://client/public/index.html#L1-L78)
- [client/public/bidirectional/index.html:1-84](file://client/public/bidirectional/index.html#L1-L84)
- [client/public/receiver/index.html:1-54](file://client/public/receiver/index.html#L1-L54)
- [client/public/multiplay/index.html:1-54](file://client/public/multiplay/index.html#L1-L54)

章节来源
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
- [client/public/index.html:1-78](file://client/public/index.html#L1-L78)

## 核心组件
- 服务端入口与参数解析：负责读取命令行参数、创建 HTTP/HTTPS 服务器、初始化 WebSocket 或 HTTP 信令，并打印启动日志。
- Express 服务器：提供静态资源托管、/signaling 接口、/config 接口、Swagger 文档、头像上传 API 等。
- 客户端示例：包含双向通信、接收端、多人播放等示例页面，均通过模块化 JS 与服务端交互。

章节来源
- [src/index.ts:13-109](file://src/index.ts#L13-L109)
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)

## 架构总览
下图展示从浏览器到服务端的整体交互路径：浏览器加载示例页面，通过 /config 获取信令协议与模式，随后根据模式与协议选择 WebSocket 或 HTTP 信令通道进行连接；服务端根据模式（public/private）与协议（websocket/http）决定行为。

```mermaid
sequenceDiagram
participant Browser as "浏览器"
participant Static as "静态资源服务<br/>/ (Express)"
participant Config as "/config 接口"
participant Signaling as "/signaling 接口"
participant WS as "WebSocket 信令"
Browser->>Static : 访问根路径 /
Static-->>Browser : 返回 client/public/index.html
Browser->>Config : GET /config
Config-->>Browser : 返回 useWebSocket/startupMode/logging
Browser->>Signaling : 发起信令请求HTTP 或 WebSocket
Signaling-->>Browser : 返回信令数据
Browser->>WS : 建立 WebSocket 连接可选
WS-->>Browser : 传输信令消息
```

图表来源
- [src/server.ts:25-27](file://src/server.ts#L25-L27)
- [src/server.ts:26](file://src/server.ts#L26)
- [src/index.ts:75-88](file://src/index.ts#L75-L88)

章节来源
- [src/server.ts:14-90](file://src/server.ts#L14-L90)
- [src/index.ts:13-109](file://src/index.ts#L13-L109)

## 详细组件分析

### 服务端启动与参数解析
- 支持的命令行参数：
  - -p, --port：监听端口，默认来自环境变量或 80
  - -s, --secure：启用 HTTPS（需要 server.key 与 server.cert）
  - -k, --keyfile：HTTPS 私钥文件路径
  - -c, --certfile：HTTPS 证书文件路径
  - -t, --type：信令协议类型，websocket 或 http
  - -m, --mode：通信模式，public 或 private
  - -l, --logging：HTTP 日志格式，combined、dev、short、tiny 或 none
- 启动流程要点：
  - 若启用 HTTPS，则读取指定密钥与证书文件并监听对应端口
  - 打印可用 IP 地址与协议（http/https）
  - 根据 type 决定使用 WebSocket 或 HTTP 信令
  - 根据 mode 输出当前模式日志

```mermaid
flowchart TD
Start(["进程启动"]) --> ParseArgs["解析命令行参数"]
ParseArgs --> CreateServer{"是否启用 HTTPS？"}
CreateServer --> |是| LoadCert["读取密钥与证书"]
LoadCert --> ListenHTTPS["监听 HTTPS 端口"]
CreateServer --> |否| ListenHTTP["监听 HTTP 端口"]
ListenHTTPS --> DecideType{"信令类型？"}
ListenHTTP --> DecideType
DecideType --> |websocket| InitWS["初始化 WebSocket 信令"]
DecideType --> |http| InitHTTP["初始化 HTTP 信令"]
InitWS --> LogMode["输出模式日志"]
InitHTTP --> LogMode
LogMode --> End(["服务就绪"])
```

图表来源
- [src/index.ts:14-44](file://src/index.ts#L14-L44)
- [src/index.ts:55-91](file://src/index.ts#L55-L91)

章节来源
- [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 服务器与路由
- 静态资源：托管 client/public 与 client/src 下的文件
- 路由：
  - GET /config：返回 useWebSocket、startupMode、logging
  - /signaling：转发至信令模块
  - GET /：返回首页 index.html（若存在）
  - POST /api/upload/avatar：头像上传并按用户 ID 重命名
  - /uploads：头像上传后的静态访问
- Swagger 文档：初始化并暴露接口文档

章节来源
- [src/server.ts:14-90](file://src/server.ts#L14-L90)

### 客户端示例概览
- 首页（client/public/index.html）：列出示例入口（接收端、双向通信、多人播放），并展示服务器配置信息
- 双向通信（bidirectional）：支持本地/远端视频预览、编解码器偏好设置、统计信息展示
- 接收端（receiver）：点击播放后建立连接，接收视频流并支持输入通道
- 多人播放（multiplay）：在接收端基础上增加多玩家标签通道

章节来源
- [client/public/index.html:1-78](file://client/public/index.html#L1-L78)
- [client/public/bidirectional/index.html:1-84](file://client/public/bidirectional/index.html#L1-L84)
- [client/public/receiver/index.html:1-54](file://client/public/receiver/index.html#L1-L54)
- [client/public/multiplay/index.html:1-54](file://client/public/multiplay/index.html#L1-L54)

### 双向通信示例工作流
```mermaid
sequenceDiagram
participant U as "用户"
participant UI as "示例页面<br/>bidirectional/index.html"
participant JS as "JS 主逻辑<br/>bidirectional/js/main.js"
participant RS as "RenderStreaming"
participant Sign as "信令"
participant Peer as "对端浏览器"
U->>UI : 选择设备/分辨率并点击“启动视频”
UI->>JS : 触发 startVideo()
JS->>RS : startLocalVideo()
U->>UI : 点击“设置连接”
UI->>JS : 触发 setUp()
JS->>Sign : 选择 WebSocket 或 HTTP 信令
JS->>RS : start() + createConnection()
RS-->>JS : onConnect 回调
JS->>RS : addTransceiver(本地轨道)
JS->>Peer : 发送 Offer/ICE 候选
Peer-->>JS : 返回 Answer/ICE 候选
JS->>UI : 显示远端轨道
U->>UI : 点击“挂断”
UI->>JS : 触发 hangUp()
JS->>RS : deleteConnection() + stop()
```

图表来源
- [client/public/bidirectional/js/main.js:112-184](file://client/public/bidirectional/js/main.js#L112-L184)
- [client/public/bidirectional/js/main.js:220-241](file://client/public/bidirectional/js/main.js#L220-L241)

章节来源
- [client/public/bidirectional/js/main.js:1-383](file://client/public/bidirectional/js/main.js#L1-L383)

### 接收端示例工作流
```mermaid
sequenceDiagram
participant U as "用户"
participant UI as "示例页面<br/>receiver/index.html"
participant JS as "JS 主逻辑<br/>receiver/js/main.js"
participant RS as "RenderStreaming"
participant Sign as "信令"
U->>UI : 点击“播放”按钮
UI->>JS : onClickPlayButton()
JS->>RS : start() + createConnection()
RS-->>JS : onConnect 回调
JS->>RS : createDataChannel("input")
JS->>UI : 创建 VideoPlayer 并添加远端轨道
U->>UI : 关闭页面/断开
UI->>JS : beforeunload
JS->>RS : stop()
```

图表来源
- [client/public/receiver/js/main.js:67-88](file://client/public/receiver/js/main.js#L67-L88)
- [client/public/receiver/js/main.js:96-108](file://client/public/receiver/js/main.js#L96-L108)

章节来源
- [client/public/receiver/js/main.js:1-186](file://client/public/receiver/js/main.js#L1-L186)

### 多人播放示例工作流
```mermaid
sequenceDiagram
participant U as "用户"
participant UI as "示例页面<br/>multiplay/index.html"
participant JS as "JS 主逻辑<br/>multiplay/js/main.js"
participant RS as "RenderStreaming"
participant Sign as "信令"
U->>UI : 点击“播放”按钮
UI->>JS : onClickPlayButton()
JS->>RS : start() + createConnection()
RS-->>JS : onConnect 回调
JS->>RS : createDataChannel("input")
JS->>RS : createDataChannel("multiplay")
JS->>JS : onOpenMultiplayChannel() 发送标签变更消息
JS->>UI : 创建 VideoPlayer 并添加远端轨道
U->>UI : 关闭页面/断开
UI->>JS : beforeunload
JS->>RS : stop()
```

图表来源
- [client/public/multiplay/js/main.js:74-95](file://client/public/multiplay/js/main.js#L74-L95)
- [client/public/multiplay/js/main.js:105-110](file://client/public/multiplay/js/main.js#L105-L110)

章节来源
- [client/public/multiplay/js/main.js:1-204](file://client/public/multiplay/js/main.js#L1-L204)

## 依赖分析
- 服务端依赖（部分）：Express、ws（WebSocket）、cors、multer、morgan、swagger-ui-express 等
- 开发依赖（部分）：TypeScript、ts-node、Jest、ESLint、pkg 等
- 客户端依赖（部分）：Jest、ESLint、node-fetch 等
- 构建与打包：TypeScript 编译、Jest 测试、pkg 打包

```mermaid
graph LR
P["package.json<br/>服务端脚本与依赖"] --> TS["TypeScript 编译<br/>tsconfig.json"]
P --> NPM["NPM 脚本<br/>build/test/dev/start"]
P --> DevDeps["开发依赖<br/>ts-node/jest/eslint/pkg"]
P --> Deps["运行时依赖<br/>express/ws/cors/multer/morgan/swagger"]
CP["client/package.json<br/>客户端脚本与依赖"] --> JestC["Jest 测试"]
CP --> ESLintC["ESLint 代码检查"]
```

图表来源
- [package.json:14-46](file://package.json#L14-L46)
- [tsconfig.json:1-13](file://tsconfig.json#L1-13)
- [client/package.json:1-19](file://client/package.json#L1-L19)

章节来源
- [package.json:1-60](file://package.json#L1-L60)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
- [client/package.json:1-19](file://client/package.json#L1-L19)

## 性能考虑
- 信令协议选择：WebSocket 通常具有更低延迟与更少轮询开销，适合实时场景；HTTP 轮询在受限网络环境下更稳定但会增加带宽与 CPU 开销。
- 日志级别：合理选择 -l 参数以平衡可观测性与性能（none 最低开销）。
- 编解码器偏好：在支持的浏览器上设置编解码器偏好可提升质量与效率，避免不必要的冗余编解码器。
- 多人播放：多人场景下建议使用公共模式（public）并控制并发连接数量，避免带宽与 CPU 压力过大。

## 故障排除指南
- 无法启动 HTTPS：
  - 确认 server.key 与 server.cert 文件存在且路径正确
  - 使用 -k 与 -c 指定密钥与证书文件
- 端口被占用：
  - 更换 -p 指定的端口，或释放占用端口
- 浏览器报错“不支持编解码器偏好”：
  - 当前浏览器不支持 setCodecPreferences，示例会提示不支持；升级浏览器或移除偏好设置
- 模式不匹配：
  - 双向通信示例仅在 Private 模式有效；接收端与多人播放示例仅在 Public 模式有效
- 无法访问示例页面：
  - 确认已执行构建（npm run build），并使用 npm run start 启动服务
- 上传头像失败：
  - 检查 uploads 目录权限与磁盘空间；确认请求包含 avatar 字段

章节来源
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
- [src/server.ts:62-83](file://src/server.ts#L62-L83)
- [client/public/bidirectional/js/main.js:99-105](file://client/public/bidirectional/js/main.js#L99-L105)
- [client/public/receiver/js/main.js:48-54](file://client/public/receiver/js/main.js#L48-L54)
- [client/public/multiplay/js/main.js:55-61](file://client/public/multiplay/js/main.js#L55-L61)

## 结论
通过本指南，您可以在本地完成 Video Socket Server 的环境准备、依赖安装、构建与启动，并成功运行内置的客户端示例。请根据实际网络与浏览器环境调整信令协议、模式与日志级别，以获得最佳体验。

## 附录

### 环境要求
- Node.js：用于运行服务端与客户端示例
- TypeScript：用于编译与开发（版本由 package.json 中 devDependencies 指定）
- 操作系统：跨平台（Windows/macOS/Linux），需满足 Node.js 与浏览器兼容性

章节来源
- [package.json:28-46](file://package.json#L28-L46)

### 依赖安装步骤
- 全局安装 TypeScript 与 ts-node（如需直接运行 TypeScript 源码）
- 在项目根目录执行安装：npm install
- 在 client 目录执行安装：cd client && npm install

章节来源
- [package.json:28-46](file://package.json#L28-L46)
- [client/package.json:1-19](file://client/package.json#L1-L19)

### 构建与打包
- 构建：npm run build（TypeScript 编译至 build 目录）
- 打包：npm run pack（使用 pkg 打包）

章节来源
- [package.json:5, 6, 12:5-12](file://package.json#L5-L12)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)

### 启动服务器
- 开发模式：npm run dev（热启动，直接运行 src/index.ts）
- 生产模式：npm run start（先构建再启动，使用 build/index.js）
- Windows 批处理：双击 run.bat（自动构建并启动）

常用命令行参数说明（节选）：
- -p, --port：监听端口（默认来自环境变量或 80）
- -s, --secure：启用 HTTPS（需要 server.key 与 server.cert）
- -k, --keyfile：HTTPS 私钥文件路径
- -c, --certfile：HTTPS 证书文件路径
- -t, --type：信令协议类型（websocket 或 http）
- -m, --mode：通信模式（public 或 private）
- -l, --logging：HTTP 日志格式（combined、dev、short、tiny 或 none）

章节来源
- [src/index.ts:20-29](file://src/index.ts#L20-L29)
- [package.json:9-10](file://package.json#L9-L10)
- [run.bat:8](file://run.bat#L8)

### 运行内置客户端示例
- 双向通信：打开 bidirectional/index.html，选择设备与分辨率，点击“启动视频”，再点击“设置连接”，即可进行双向视频通话
- 视频接收：打开 receiver/index.html，点击“播放”，建立连接后接收视频流
- 多人播放：打开 multiplay/index.html，点击“播放”，建立连接后接收视频流并支持多玩家标签通道

章节来源
- [client/public/bidirectional/index.html:1-84](file://client/public/bidirectional/index.html#L1-L84)
- [client/public/receiver/index.html:1-54](file://client/public/receiver/index.html#L1-L54)
- [client/public/multiplay/index.html:1-54](file://client/public/multiplay/index.html#L1-L54)

### 实际命令行示例与预期输出
- 构建与启动（Windows）：双击 run.bat，预期输出包含 http/https 地址与模式日志
- 开发启动：npm run dev，预期输出包含端口与协议信息
- 生产启动：npm run start，预期输出包含端口与协议信息

章节来源
- [run.bat:1-6](file://run.bat#L1-L6)
- [package.json:9-10](file://package.json#L9-L10)
- [src/index.ts:67-73](file://src/index.ts#L67-L73)