316 lines
12 KiB
Markdown
316 lines
12 KiB
Markdown
# 贡献指南
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [package.json](file://package.json)
|
||
- [tsconfig.json](file://tsconfig.json)
|
||
- [.eslintrc.cjs](file://.eslintrc.cjs)
|
||
- [jest.config.js](file://jest.config.js)
|
||
- [src/index.ts](file://src/index.ts)
|
||
- [src/server.ts](file://src/server.ts)
|
||
- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
|
||
- [src/class/httphandler.ts](file://src/class/httphandler.ts)
|
||
- [.gitignore](file://.gitignore)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本贡献指南面向希望参与“视频流服务器”项目的开发者，提供从 Fork、Clone、分支与提交、Pull Request 到代码审查、Issue 提交、版本发布与变更日志维护、社区行为准则与协作规范的全流程说明。同时给出新贡献者的入门建议与资源链接，帮助快速上手。
|
||
|
||
## 项目结构
|
||
该项目采用前后端一体化的 Node/Express + TypeScript 后端，内置静态前端资源与测试框架，支持 WebSocket 与 HTTP 两种信令模式，具备会话管理、WebRTC 信令转发、文件上传与 Swagger 文档能力。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "后端"
|
||
IDX["入口: src/index.ts"]
|
||
SRV["服务器: src/server.ts"]
|
||
WS["WebSocket处理器: src/class/websockethandler.ts"]
|
||
HTTP["HTTP处理器: src/class/httphandler.ts"]
|
||
end
|
||
subgraph "前端"
|
||
PUB["静态资源: client/public/**/*"]
|
||
SRC["前端模块: client/src/**/*"]
|
||
end
|
||
subgraph "工具与配置"
|
||
PKG["包脚本: package.json"]
|
||
TSC["编译配置: tsconfig.json"]
|
||
ESL["代码规范: .eslintrc.cjs"]
|
||
JST["测试配置: jest.config.js"]
|
||
GIT["忽略规则: .gitignore"]
|
||
end
|
||
IDX --> SRV
|
||
SRV --> WS
|
||
SRV --> HTTP
|
||
SRV --> PUB
|
||
SRV --> SRC
|
||
PKG --> TSC
|
||
PKG --> ESL
|
||
PKG --> JST
|
||
PKG --> GIT
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
|
||
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)
|
||
- [package.json:1-60](file://package.json#L1-L60)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
|
||
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
|
||
- [.gitignore:1-187](file://.gitignore#L1-L187)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
|
||
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
|
||
- [package.json:1-60](file://package.json#L1-L60)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
|
||
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
|
||
- [.gitignore:1-187](file://.gitignore#L1-L187)
|
||
|
||
## 核心组件
|
||
- 入口与启动
|
||
- 通过命令行参数解析与 HTTPS/HTTP 服务启动，支持 WebSocket 或 HTTP 信令模式，以及公共/私有通信模式。
|
||
- 服务器与路由
|
||
- Express 应用挂载 CORS、日志中间件、静态资源、Swagger 文档、上传接口与信令路由。
|
||
- WebSocket 信令
|
||
- 实现 1 对多（主持人/参与者）模式下的 offer/answer/candidate 转发、广播、心跳检测与断线清理。
|
||
- HTTP 信令
|
||
- 基于轮询的信令 API，提供会话创建、连接管理、offer/answer/candidate 获取与断线记录。
|
||
- 测试与规范
|
||
- Jest 测试配置与覆盖率收集；ESLint TypeScript 规则；TypeScript 编译配置。
|
||
|
||
**章节来源**
|
||
- [src/index.ts:1-109](file://src/index.ts#L1-L109)
|
||
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)
|
||
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
|
||
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
|
||
## 架构总览
|
||
后端以 Express 为核心，根据信令类型选择 WebSocket 或 HTTP 处理器；静态资源与前端模块通过 Express 提供；测试与规范工具贯穿开发流程。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Client["浏览器/客户端"] --> Mode{"信令模式"}
|
||
Mode --> |WebSocket| WS["WebSocket处理器<br/>websockethandler.ts"]
|
||
Mode --> |HTTP| HTTP["HTTP处理器<br/>httphandler.ts"]
|
||
WS --> Server["Express服务器<br/>server.ts"]
|
||
HTTP --> Server
|
||
Server --> Static["静态资源<br/>client/public/**/*"]
|
||
Server --> Front["前端模块<br/>client/src/**/*"]
|
||
Server --> Swagger["Swagger文档"]
|
||
Server --> Upload["头像上传API"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/server.ts:1-90](file://src/server.ts#L1-L90)
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)
|
||
|
||
## 详细组件分析
|
||
|
||
### WebSocket 信令处理流程
|
||
WebSocket 处理器支持公共/私有模式，实现连接、断开、offer/answer/candidate 转发与广播、心跳检测与断线清理。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant S as "WebSocket处理器"
|
||
participant G as "连接组"
|
||
participant H as "主持人"
|
||
participant P as "参与者"
|
||
C->>S : "connect(connectionId)"
|
||
S->>G : "创建/加入连接组"
|
||
S-->>C : "connect(角色, participantId)"
|
||
C->>S : "offer/answer/candidate"
|
||
alt 私有模式
|
||
S->>H : "主持人接收转发"
|
||
S->>P : "参与者接收转发"
|
||
else 公共模式
|
||
S->>G : "广播到其他客户端"
|
||
end
|
||
C->>S : "disconnect"
|
||
S->>G : "清理连接组并通知"
|
||
S-->>C : "disconnect"
|
||
```
|
||
|
||
**图表来源**
|
||
- [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/class/websockethandler.ts:448-473](file://src/class/websockethandler.ts#L448-L473)
|
||
|
||
**章节来源**
|
||
- [src/class/websockethandler.ts:1-479](file://src/class/websockethandler.ts#L1-L479)
|
||
|
||
### HTTP 信令处理流程
|
||
HTTP 处理器提供会话与连接管理、offer/answer/candidate 获取、断线记录与全量信令拉取。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Handler as "HTTP处理器"
|
||
participant Store as "内存存储"
|
||
participant Other as "其他会话/连接"
|
||
Client->>Handler : "PUT /signaling (创建会话)"
|
||
Handler->>Store : "初始化会话映射"
|
||
Handler-->>Client : "{ sessionId }"
|
||
Client->>Handler : "PUT /signaling/connection (创建连接)"
|
||
Handler->>Store : "登记连接ID与配对"
|
||
Handler-->>Client : "{ connectionId, polite }"
|
||
Client->>Handler : "GET /signaling/offer?fromtime"
|
||
Handler->>Store : "按模式过滤并返回offer列表"
|
||
Client->>Handler : "GET /signaling (全量信令)"
|
||
Handler->>Store : "聚合连接/断线/offer/answer/candidate"
|
||
Handler-->>Client : "{ messages, datetime }"
|
||
Client->>Handler : "DELETE /signaling/connection"
|
||
Handler->>Store : "清理连接与配对"
|
||
```
|
||
|
||
**图表来源**
|
||
- [src/class/httphandler.ts:664-783](file://src/class/httphandler.ts#L664-L783)
|
||
- [src/class/httphandler.ts:492-641](file://src/class/httphandler.ts#L492-L641)
|
||
|
||
**章节来源**
|
||
- [src/class/httphandler.ts:1-800](file://src/class/httphandler.ts#L1-L800)
|
||
|
||
### 代码规范与测试
|
||
- ESLint 规则启用 TypeScript 推荐规则与 Jest 推荐规则，强制分号与多余分号检查。
|
||
- Jest 配置启用覆盖率收集、TS 转换、Node 环境与测试匹配规则。
|
||
- TypeScript 编译配置输出至 build 目录，源码位于 src，测试位于 test。
|
||
|
||
**章节来源**
|
||
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
|
||
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
|
||
## 依赖关系分析
|
||
- 后端运行时依赖：Express、WS、CORS、Morgan、Multer、Swagger。
|
||
- 开发依赖：Jest、TS-Jest、ESLint、TypeScript、pkg 等。
|
||
- 构建与打包：通过 TypeScript 编译与 pkg 配置，打包静态资源与前端模块。
|
||
|
||
```mermaid
|
||
graph LR
|
||
PKG["package.json"] --> DEPS["运行时依赖"]
|
||
PKG --> DEVDEPS["开发依赖"]
|
||
PKG --> BIN["构建与打包配置"]
|
||
BIN --> TSC["tsconfig.json"]
|
||
BIN --> ESL["eslint配置"]
|
||
BIN --> JST["jest配置"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [package.json:1-60](file://package.json#L1-L60)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
|
||
- [jest.config.js:1-196](file://jest.config.js#L1-L196)
|
||
|
||
**章节来源**
|
||
- [package.json:1-60](file://package.json#L1-L60)
|
||
|
||
## 性能考量
|
||
- WebSocket 心跳与超时：处理器内置心跳检测与超时断开逻辑，避免僵尸连接占用资源。
|
||
- HTTP 轮询：提供 fromtime 参数过滤增量消息，降低带宽与计算压力。
|
||
- 日志与中间件：morgan 日志级别可配置，建议在生产环境调整为合适级别。
|
||
- 静态资源：静态目录与前端模块统一托管，确保缓存与压缩策略一致。
|
||
|
||
**章节来源**
|
||
- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
|
||
- [src/server.ts:17-20](file://src/server.ts#L17-L20)
|
||
|
||
## 故障排查指南
|
||
- 启动失败
|
||
- 检查证书文件路径与权限（HTTPS 模式），确认端口占用与网络接口。
|
||
- 信令异常
|
||
- 确认信令模式（WebSocket/HTTP）与通信模式（public/private）配置一致。
|
||
- 查看日志输出定位连接组状态与消息转发问题。
|
||
- 测试失败
|
||
- 使用 Jest 覆盖率报告定位未覆盖路径，修正测试用例与模拟。
|
||
- 规范检查
|
||
- 运行 ESLint 并修复规则冲突，确保提交前通过静态检查。
|
||
|
||
**章节来源**
|
||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||
- [src/server.ts:25-42](file://src/server.ts#L25-L42)
|
||
- [jest.config.js:19-26](file://jest.config.js#L19-L26)
|
||
- [.eslintrc.cjs:18-23](file://.eslintrc.cjs#L18-L23)
|
||
|
||
## 结论
|
||
本指南提供了从开发环境准备到贡献流程、代码审查、Issue 规范、版本发布与变更日志维护、社区协作的完整实践路径。建议贡献者在提交前完成本地测试与规范检查，并遵循分支命名与提交信息格式，确保高质量交付。
|
||
|
||
## 附录
|
||
|
||
### 代码贡献流程
|
||
- Fork 仓库
|
||
- 在代码托管平台执行 Fork 操作，获得个人副本。
|
||
- Clone 与安装
|
||
- 克隆到本地，安装依赖并运行开发脚本。
|
||
- 分支与提交
|
||
- 基于主分支创建特性分支，遵循分支命名规范与提交信息格式。
|
||
- Pull Request
|
||
- 提交 PR，填写模板信息，等待审查与合并。
|
||
|
||
**章节来源**
|
||
- [package.json:5-12](file://package.json#L5-L12)
|
||
|
||
### 分支命名规范与提交信息格式
|
||
- 分支命名
|
||
- feat/xxx：新增功能
|
||
- fix/xxx：缺陷修复
|
||
- docs/xxx：文档更新
|
||
- refactor/xxx：重构
|
||
- test/xxx：测试相关
|
||
- 提交信息格式
|
||
- 类型(scope): 描述
|
||
- 例如：feat(server): 支持自定义日志级别
|
||
|
||
### 代码审查标准与流程
|
||
- 审查清单
|
||
- 功能正确性与边界条件
|
||
- 性能影响与资源占用
|
||
- 日志与错误处理
|
||
- 单元测试覆盖率
|
||
- 规范检查通过
|
||
- 审查流程
|
||
- 提交 PR → 指派审查者 → 评论与修改 → 合并
|
||
|
||
### Issue 提交规范
|
||
- Bug 报告
|
||
- 环境信息、复现步骤、期望/实际结果、日志片段
|
||
- 功能请求
|
||
- 背景、需求描述、影响范围、优先级建议
|
||
|
||
### 版本发布与变更日志维护
|
||
- 版本号
|
||
- 遵循语义化版本：主版本.次版本.修订
|
||
- 变更日志
|
||
- 按版本记录新增、修复、变更与废弃项，标注影响与迁移指引
|
||
|
||
### 社区行为准则与协作规范
|
||
- 尊重与包容：保持友善与专业
|
||
- 明确沟通：使用清晰、简洁的语言
|
||
- 合规贡献：遵守开源许可证与安全政策
|
||
|
||
### 新贡献者入门指导与资源链接
|
||
- 环境准备
|
||
- Node.js、TypeScript、Git 基础
|
||
- 本地运行
|
||
- 使用开发脚本启动服务，访问静态页面与 Swagger 文档
|
||
- 学习资源
|
||
- Express、WebSocket、WebRTC 信令基础
|
||
- Jest 与 ESLint 使用指南 |