391 lines
17 KiB
Markdown
391 lines
17 KiB
Markdown
# 快速开始
|
||
|
||
<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) |