root/video_socket-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
video_socket-server/.qoder/repowiki/zh/content/快速开始.md
stary 6c13817527 修改
2026-05-16 13:24:02 +08:00

17 KiB
Raw Permalink Blame History

快速开始

**本文引用的文件** - [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)

目录

  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 示例页面。

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

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

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 : 传输信令消息

图表来源

章节来源

详细组件分析

服务端启动与参数解析

  • 支持的命令行参数：
    • -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 输出当前模式日志
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(["服务就绪"])

图表来源

章节来源

Express 服务器与路由

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

章节来源

客户端示例概览

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

章节来源

双向通信示例工作流

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

图表来源

章节来源

接收端示例工作流

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

图表来源

章节来源

多人播放示例工作流

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

图表来源

章节来源

依赖分析

  • 服务端依赖（部分）：Express、ws（WebSocket）、cors、multer、morgan、swagger-ui-express 等
  • 开发依赖（部分）：TypeScript、ts-node、Jest、ESLint、pkg 等
  • 客户端依赖（部分）：Jest、ESLint、node-fetch 等
  • 构建与打包：TypeScript 编译、Jest 测试、pkg 打包
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 代码检查"]

图表来源

章节来源

性能考虑

  • 信令协议选择：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 字段

章节来源

结论

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

附录

环境要求

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

章节来源

依赖安装步骤

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

章节来源

构建与打包

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

章节来源

启动服务器

  • 开发模式：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）

章节来源

运行内置客户端示例

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

章节来源

实际命令行示例与预期输出

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

章节来源

Reference in New Issue View Git Blame Copy Permalink