修改

2026-05-16 13:24:02 +08:00
parent eae60714b4
commit 6c13817527
42 changed files with 15921 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/开发指南/开发指南.md
+++ b/.qoder/repowiki/zh/content/开发指南/开发指南.md
@@ -0,0 +1,319 @@
+# 开发指南
+
+<cite>
+**本文引用的文件**
+- [package.json](file://package.json)
+- [client/package.json](file://client/package.json)
+- [tsconfig.json](file://tsconfig.json)
+- [tsconfig.lint.json](file://tsconfig.lint.json)
+- [jest.config.js](file://jest.config.js)
+- [client/jest.config.js](file://client/jest.config.js)
+- [client/jest.setup.js](file://client/jest.setup.js)
+- [.eslintrc.cjs](file://.eslintrc.cjs)
+- [client/.eslintrc.json](file://client/.eslintrc.json)
+- [.editorconfig](file://.editorconfig)
+- [run.bat](file://run.bat)
+- [.gitignore](file://.gitignore)
+- [src/index.ts](file://src/index.ts)
+- [src/server.ts](file://src/server.ts)
+- [src/class/options.ts](file://src/class/options.ts)
+- [src/log.ts](file://src/log.ts)
+- [test/httphandler.test.ts](file://test/httphandler.test.ts)
+- [test/websockethandler.test.ts](file://test/websockethandler.test.ts)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本开发指南面向参与“视频流服务器”项目的开发者，目标是帮助你快速搭建本地开发环境、理解代码规范与编码标准、掌握调试与测试技巧、明确扩展开发流程、以及建立版本管理与发布流程的共识。项目采用 Node.js + TypeScript 构建，前端静态资源由服务端托管，支持 WebSocket 与 HTTP 两种信令模式，内置日志系统与 Swagger 文档。
+
+## 项目结构
+项目分为服务端与客户端两部分：
+- 服务端（src）：Express 应用、HTTP 路由、WebSocket 信令、日志与配置等。
+- 客户端（client）：静态页面与前端脚本，通过 /module 与 /uploads 等路由访问。
+
+```mermaid
+graph TB
+subgraph "服务端(src)"
+IDX["入口: index.ts"]
+SRV["HTTP服务: server.ts"]
+LOG["日志: log.ts"]
+OPT["选项: class/options.ts"]
+end
+subgraph "客户端(client)"
+PUB["静态资源: public/*"]
+SRC["前端源码: src/*"]
+end
+IDX --> SRV
+SRV --> PUB
+SRV --> SRC
+SRV --> LOG
+IDX --> OPT
+```
+
+图表来源
+- [src/index.ts:1-109](file://src/index.ts#L1-L109)
+- [src/server.ts:1-90](file://src/server.ts#L1-L90)
+- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+
+章节来源
+- [src/index.ts:1-109](file://src/index.ts#L1-L109)
+- [src/server.ts:1-90](file://src/server.ts#L1-L90)
+
+## 核心组件
+- 入口与启动：命令行参数解析、HTTPS/HTTP 启动、信令类型选择、日志输出。
+- HTTP 服务：CORS、JSON/URL 编码中间件、静态资源、Swagger 文档、头像上传接口。
+- 日志系统：可配置的日志级别与格式化输出。
+- 测试框架：Jest（服务端）、Jest + jsdom（客户端），覆盖 HTTP 与 WebSocket 信令逻辑。
+
+章节来源
+- [src/index.ts:1-109](file://src/index.ts#L1-L109)
+- [src/server.ts:1-90](file://src/server.ts#L1-L90)
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+- [jest.config.js:1-196](file://jest.config.js#L1-L196)
+- [client/jest.config.js:1-196](file://client/jest.config.js#L1-L196)
+
+## 架构总览
+下图展示从浏览器到服务端的典型请求链路，包括静态资源、信令与上传接口。
+
+```mermaid
+sequenceDiagram
+participant Browser as "浏览器"
+participant Express as "Express 应用(server.ts)"
+participant Signaling as "信令(HTTP/WebSocket)"
+participant FS as "文件系统(头像上传)"
+Browser->>Express : GET /
+Express-->>Browser : 返回首页(静态资源)
+Browser->>Express : GET /config
+Express-->>Browser : 返回运行配置
+Browser->>Express : GET /signaling/*
+Express->>Signaling : 转发至 HTTP 信令处理器
+Browser->>Express : POST /api/upload/avatar
+Express->>FS : 写入头像并重命名
+FS-->>Express : 返回结果
+Express-->>Browser : JSON 响应
+```
+
+图表来源
+- [src/server.ts:25-87](file://src/server.ts#L25-L87)
+- [src/index.ts:75-90](file://src/index.ts#L75-L90)
+
+章节来源
+- [src/server.ts:1-90](file://src/server.ts#L1-L90)
+- [src/index.ts:1-109](file://src/index.ts#L1-L109)
+
+## 详细组件分析
+
+### 启动与配置（index.ts）
+- 支持命令行参数：端口、HTTPS 证书、信令类型、通信模式、日志级别。
+- 自动检测本机 IPv4 地址并输出访问地址。
+- 根据信令类型启动 HTTP 轮询或 WebSocket 信令服务。
+
+```mermaid
+flowchart TD
+Start(["进程启动"]) --> ParseArgs["解析命令行参数"]
+ParseArgs --> CreateApp["创建 Express 应用"]
+CreateApp --> Mode{"是否启用 HTTPS?"}
+Mode --> |是| HTTPS["读取密钥与证书并监听"]
+Mode --> |否| HTTP["以 HTTP 监听"]
+HTTPS --> DetectIP["检测本机 IPv4 地址"]
+HTTP --> DetectIP
+DetectIP --> SigType{"信令类型"}
+SigType --> |websocket| WS["初始化 WebSocket 信令"]
+SigType --> |http| HTTPSig["初始化 HTTP 轮询信令"]
+WS --> Done(["完成"])
+HTTPSig --> Done
+```
+
+图表来源
+- [src/index.ts:14-105](file://src/index.ts#L14-L105)
+
+章节来源
+- [src/index.ts:1-109](file://src/index.ts#L1-L109)
+- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
+
+### HTTP 服务与静态资源（server.ts）
+- 中间件：CORS、JSON、URL 编码、日志（Morgan）。
+- 路由：
+  - GET /config：返回运行配置（信令类型、模式、日志级别）。
+  - /signaling：转发至信令模块。
+  - 静态资源：/ 与 /module。
+  - 上传接口：POST /api/upload/avatar，使用 Multer 存储并按用户 ID 重命名。
+  - /uploads：公开头像目录。
+
+```mermaid
+flowchart TD
+Req["请求进入"] --> CORS["CORS 允许所有来源"]
+CORS --> Body["解析 JSON/URL 编码"]
+Body --> Log{"日志级别允许?"}
+Log --> |是| Morgan["Morgan 访问日志"]
+Log --> |否| Skip["跳过日志"]
+Morgan --> Routes["分发路由"]
+Skip --> Routes
+Routes --> Config["GET /config"]
+Routes --> Signaling["GET/POST /signaling/*"]
+Routes --> Static["静态资源: / 与 /module"]
+Routes --> Upload["POST /api/upload/avatar"]
+Routes --> PublicUploads["GET /uploads/*"]
+```
+
+图表来源
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+
+章节来源
+- [src/server.ts:1-90](file://src/server.ts#L1-L90)
+
+### 日志系统（log.ts）
+- 提供多级日志：none/error/warn/log/info。
+- 可通过字符串解析日志级别。
+- 输出包含时间戳与级别前缀。
+
+章节来源
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+
+### 测试与断言（Jest）
+- 服务端测试：覆盖 HTTP 信令在 public/private 模式下的行为，含超时清理逻辑。
+- 客户端测试：Jest + jsdom 环境，通过 setup 注入 fetch、TextEncoder/Decoder、RTCPeerConnection 等缺失对象。
+
+章节来源
+- [test/httphandler.test.ts:1-510](file://test/httphandler.test.ts#L1-L510)
+- [test/websockethandler.test.ts:1-191](file://test/websockethandler.test.ts#L1-L191)
+- [client/jest.setup.js:1-35](file://client/jest.setup.js#L1-L35)
+
+## 依赖关系分析
+- 语言与构建：TypeScript、ts-node、Jest、ESLint。
+- Web 框架：Express、ws（WebSocket）、Multer（文件上传）。
+- 文档：Swagger JSdoc、Swagger UI Express。
+- 日志：Morgan。
+- 工具：Commander（命令行解析）。
+
+```mermaid
+graph LR
+Pkg["package.json 依赖"] --> TS["TypeScript 运行时"]
+Pkg --> Express["Express"]
+Pkg --> WS["ws"]
+Pkg --> Mul["Multer"]
+Pkg --> Swagger["Swagger UI Express"]
+Pkg --> Morgan["Morgan"]
+Pkg --> Cmdr["Commander"]
+Pkg --> Jest["Jest"]
+Pkg --> ESL["ESLint + TS 插件"]
+```
+
+图表来源
+- [package.json:14-46](file://package.json#L14-L46)
+
+章节来源
+- [package.json:1-60](file://package.json#L1-L60)
+
+## 性能考虑
+- 上传路径：头像上传使用磁盘存储，建议在生产环境挂载独立持久卷并限制文件大小与类型。
+- 日志级别：默认 info，可在高并发场景调低日志级别以减少 I/O。
+- 静态资源：Express 静态托管适合开发，生产建议使用 CDN 或反向代理缓存。
+- 信令：WebSocket 在高并发下优于 HTTP 轮询，建议优先使用 websocket 模式。
+
+## 故障排查指南
+- 启动失败（HTTPS 证书）：确认 server.key 与 server.cert 存在且可读；或禁用 HTTPS 并使用 HTTP。
+- 无法访问 /uploads：确保 uploads 目录存在且可读写。
+- 上传失败：检查 Multer 配置与权限，查看服务端错误日志。
+- 测试失败（jsdom 缺失 API）：确保使用客户端 jest.config 的 setup 文件已加载。
+- 超时会话未清理：检查 HTTP 信令测试中的超时轮询逻辑与清理触发点。
+
+章节来源
+- [src/server.ts:44-87](file://src/server.ts#L44-L87)
+- [client/jest.setup.js:1-35](file://client/jest.setup.js#L1-L35)
+- [test/httphandler.test.ts:194-309](file://test/httphandler.test.ts#L194-L309)
+
+## 结论
+本项目提供了清晰的服务端架构与完善的测试体系，支持 WebSocket 与 HTTP 两种信令模式，并内置日志与文档能力。遵循本文的开发与测试规范，可高效地进行功能扩展与维护。
+
+## 附录
+
+### 开发环境搭建步骤
+- 安装 Node.js 与 npm（建议使用版本管理器以避免版本冲突）。
+- 克隆仓库后，在根目录与 client 目录分别执行安装依赖命令。
+- 准备 HTTPS 证书（可选）：若启用 HTTPS，需准备 server.key 与 server.cert。
+- 使用提供的脚本启动开发服务或打包产物。
+
+章节来源
+- [package.json:5-12](file://package.json#L5-L12)
+- [client/package.json:5-8](file://client/package.json#L5-L8)
+- [run.bat:1-17](file://run.bat#L1-L17)
+
+### 代码规范与编码标准
+- 统一缩进与换行：EditorConfig 规定空格缩进、LF 换行、UTF-8 字符集。
+- TypeScript 规范：ESLint 配置启用 @typescript-eslint 推荐规则，强制分号。
+- JavaScript 规范（客户端）：ESLint 配置启用 jest 插件与推荐规则，强制分号。
+- 代码风格：遵循 EditorConfig 与 ESLint 规则，保持一致的排版与语法。
+
+章节来源
+- [.editorconfig:10-20](file://.editorconfig#L10-L20)
+- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
+- [client/.eslintrc.json:1-23](file://client/.eslintrc.json#L1-L23)
+
+### 调试技巧与开发工具
+- 本地启动：使用开发脚本启动服务，自动监听 TypeScript 源码变化。
+- 单元测试：使用 Jest 运行服务端与客户端测试，关注覆盖率与断言。
+- 信令调试：根据运行日志确认信令类型与模式，必要时降低日志级别以便观察。
+- 上传调试：通过 /uploads 访问上传后的头像，验证重命名与路径。
+
+章节来源
+- [package.json:5-12](file://package.json#L5-L12)
+- [jest.config.js:1-196](file://jest.config.js#L1-L196)
+- [client/jest.config.js:1-196](file://client/jest.config.js#L1-L196)
+- [src/server.ts:62-87](file://src/server.ts#L62-L87)
+
+### 扩展开发机制
+- 新增 HTTP 路由：在 server.ts 中添加路由与处理逻辑，注意中间件顺序与错误处理。
+- 新增 WebSocket 事件：在 WebSocket 信令模块中新增事件处理函数，并在测试中补充断言。
+- 新增测试用例：在 test 目录下新增对应测试文件，复用现有的公共断言与模拟数据。
+- 修改现有功能：遵循最小变更原则，先写测试，再实现修复或增强。
+
+章节来源
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [test/httphandler.test.ts:1-510](file://test/httphandler.test.ts#L1-L510)
+- [test/websockethandler.test.ts:1-191](file://test/websockethandler.test.ts#L1-L191)
+
+### 版本管理、分支策略与发布流程
+- 版本号：项目使用语义化版本（package.json 中 version 字段）。
+- 分支策略：建议采用 Git Flow，主分支用于稳定版本，开发分支用于迭代。
+- 发布流程：本地构建（build）、测试（test）、打包（pack），生成可执行包或容器镜像后发布。
+
+章节来源
+- [package.json:2-4](file://package.json#L2-L4)
+- [package.json:5-12](file://package.json#L5-L12)
+
+### 贡献指南与代码审查标准
+- 提交前：运行 lint 与 test，确保通过。
+- 提交流程：提交变更到功能分支，发起 Pull Request，至少一名维护者审查。
+- 代码审查要点：功能正确性、边界条件、错误处理、日志与安全、测试覆盖、性能影响。
+
+章节来源
+- [package.json:11-12](file://package.json#L11-L12)
+- [jest.config.js:1-196](file://jest.config.js#L1-L196)
+- [client/jest.config.js:1-196](file://client/jest.config.js#L1-L196)
+
+### 常见问题与最佳实践
+- 问题：浏览器跨域访问受限
+  - 解决：服务端已启用 CORS，确保请求头与路径正确。
+- 问题：WebSocket 连接失败
+  - 解决：确认信令类型为 websocket，检查服务端日志与防火墙设置。
+- 问题：头像上传失败
+  - 解决：确认上传目录存在且可写，检查文件类型与大小限制。
+- 最佳实践：在生产环境使用 HTTPS、CDN 加速静态资源、合理设置日志级别与轮询间隔。
+
+章节来源
+- [src/server.ts:22-24](file://src/server.ts#L22-L24)
+- [src/server.ts:44-87](file://src/server.ts#L44-L87)
+- [src/index.ts:55-74](file://src/index.ts#L55-L74)