修改

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,347 @@
+# 环境配置
+
+<cite>
+**本文引用的文件**
+- [package.json](file://package.json)
+- [src/index.ts](file://src/index.ts)
+- [src/class/options.ts](file://src/class/options.ts)
+- [src/server.ts](file://src/server.ts)
+- [run.bat](file://run.bat)
+- [tsconfig.json](file://tsconfig.json)
+- [tsconfig.build.json](file://tsconfig.build.json)
+- [.eslintrc.cjs](file://.eslintrc.cjs)
+- [.gitignore](file://.gitignore)
+- [client/package.json](file://client/package.json)
+- [jest.config.js](file://jest.config.js)
+- [test/env_macos.postman_environment.json](file://test/env_macos.postman_environment.json)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向部署与运维人员，提供该视频 socket 服务器项目的环境配置说明，涵盖 Node.js 版本要求、操作系统兼容性、系统资源建议、开发与生产差异、环境变量与运行参数、以及常见问题排查。文档中的所有技术细节均来自仓库内现有配置文件与源码。
+
+## 项目结构
+该项目采用前后端同库的组织方式：服务端为 Node.js + Express + WebSocket，前端静态资源位于 client/public 与 client/src；构建与打包通过 TypeScript 编译器与 pkg 工具完成；测试与质量工具包括 Jest、ESLint、Swagger 文档生成等。
+
+```mermaid
+graph TB
+subgraph "服务端"
+IDX["src/index.ts<br/>入口与命令行参数解析"]
+SRV["src/server.ts<br/>Express 应用与路由"]
+OPT["src/class/options.ts<br/>运行参数接口"]
+end
+subgraph "客户端"
+PUB["client/public<br/>静态页面与资源"]
+SRC["client/src<br/>前端模块与示例"]
+end
+subgraph "构建与工具"
+PKG["package.json<br/>脚本与依赖"]
+TSC["tsconfig.json<br/>编译配置"]
+TSB["tsconfig.build.json<br/>构建扩展"]
+ESL[".eslintrc.cjs<br/>ESLint 规则"]
+JST["jest.config.js<br/>测试配置"]
+end
+IDX --> SRV
+SRV --> PUB
+SRV --> SRC
+PKG --> IDX
+PKG --> SRV
+TSC --> IDX
+TSC --> SRV
+TSB --> PKG
+ESL --> IDX
+ESL --> SRV
+JST --> PKG
+```
+
+**图示来源**
+- [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)
+- [package.json:1-60](file://package.json#L1-L60)
+- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
+- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
+- [.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)
+- [src/index.ts:1-109](file://src/index.ts#L1-L109)
+- [src/server.ts:1-90](file://src/server.ts#L1-L90)
+- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
+- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
+- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
+- [jest.config.js:1-196](file://jest.config.js#L1-L196)
+
+## 核心组件
+- 入口与参数解析：负责从命令行读取运行参数，支持端口、HTTPS 密钥证书、信令类型、通信模式、日志级别等；同时支持通过环境变量覆盖默认值。
+- Express 应用：统一处理静态资源、上传接口、Swagger 文档、CORS、JSON/URL 编码请求体等。
+- 运行参数接口：定义了安全模式、端口、密钥/证书路径、信令类型、通信模式、日志级别等字段。
+
+**章节来源**
+- [src/index.ts:14-91](file://src/index.ts#L14-L91)
+- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+
+## 架构总览
+下图展示了启动流程与关键组件交互：命令行参数解析后创建 Express 应用，按需启用 HTTPS，随后根据信令类型选择 WebSocket 或 HTTP 轮询，并输出启动日志与访问地址。
+
+```mermaid
+sequenceDiagram
+participant CLI as "命令行/环境变量"
+participant IDX as "RenderStreaming.run()"
+participant SRV as "createServer()"
+participant HTTPS as "HTTPS 服务器"
+participant HTTP as "HTTP 服务器"
+participant WS as "WebSocket 信令"
+CLI->>IDX : 解析参数(-p/-s/-k/-c/-t/-m/-l)
+IDX->>SRV : 创建 Express 应用
+alt 启用安全模式
+IDX->>HTTPS : 使用 key/cert 创建 HTTPS 服务器
+HTTPS-->>IDX : 输出 https : // 地址
+else 非安全模式
+IDX->>HTTP : 使用 Express 监听端口
+HTTP-->>IDX : 输出 http : // 地址
+end
+IDX->>WS : 按信令类型启动 WebSocket 信令
+WS-->>IDX : 信令就绪
+```
+
+**图示来源**
+- [src/index.ts:14-91](file://src/index.ts#L14-L91)
+- [src/server.ts:14-42](file://src/server.ts#L14-L42)
+
+## 详细组件分析
+
+### 命令行参数与环境变量
+- 支持的参数与默认值（优先级：命令行 > 环境变量 > 默认值）：
+  - 端口：-p/--port，默认值来自环境变量 PORT，未设置时为 80（注意：脚本 start/dev 默认 8080）
+  - 安全模式：-s/--secure，默认开启（脚本 start/dev 默认开启）
+  - 密钥文件：-k/--keyfile，默认 server.key
+  - 证书文件：-c/--certfile，默认 server.cert
+  - 信令类型：-t/--type，默认 websocket；支持 websocket/http
+  - 通信模式：-m/--mode，默认 public；支持 public/private
+  - 日志级别：-l/--logging，默认 dev；支持 combined、dev、short、tiny、none
+- 环境变量映射：
+  - PORT、SECURE、KEYFILE、CERTFILE、TYPE、MODE、LOGGING
+
+```mermaid
+flowchart TD
+Start(["启动"]) --> Parse["解析命令行参数"]
+Parse --> EnvCheck{"检查对应环境变量"}
+EnvCheck --> |存在| UseEnv["使用环境变量值"]
+EnvCheck --> |不存在| UseDefault["使用内置默认值"]
+UseEnv --> Merge["合并为最终配置"]
+UseDefault --> Merge
+Merge --> Mode{"是否指定安全模式"}
+Mode --> |是| HTTPS["启用 HTTPS 并加载 key/cert"]
+Mode --> |否| HTTP["启用 HTTP"]
+HTTPS --> Signaling["按信令类型启动"]
+HTTP --> Signaling
+Signaling --> Log["输出启动日志与访问地址"]
+Log --> End(["完成"])
+```
+
+**图示来源**
+- [src/index.ts:16-42](file://src/index.ts#L16-L42)
+- [src/index.ts:55-91](file://src/index.ts#L55-L91)
+
+**章节来源**
+- [src/index.ts:16-42](file://src/index.ts#L16-L42)
+- [src/index.ts:55-91](file://src/index.ts#L55-L91)
+
+### Express 应用与静态资源
+- CORS：允许任意来源访问
+- 请求体解析：支持 JSON 与 URL 编码
+- 静态资源：
+  - 根路径 / 映射到 client/public/index.html
+  - /module 映射到 client/src
+  - /uploads 映射到 client/public/uploads
+- 上传接口：/api/upload/avatar，使用 multer 将头像保存至 uploads/avatars，并按用户 ID 重命名
+- Swagger 文档初始化
+- /config 接口返回当前信令与模式、日志级别等配置
+
+**章节来源**
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+
+### 构建与打包配置
+- TypeScript 编译：
+  - tsconfig.json：目标 ES5，输出目录 build，包含 src 与 test
+  - tsconfig.build.json：仅包含 src，继承 tsconfig.json
+- 打包：
+  - package.json 中的 pkg 字段声明 assets 与 targets，其中 targets 包含 "node10"，表明以 Node.js 10 可执行文件为目标进行打包
+
+**章节来源**
+- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
+- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
+- [package.json:50-58](file://package.json#L50-L58)
+
+### 测试与质量工具
+- Jest：测试框架，收集覆盖率，测试匹配规则覆盖 src 与 test 下的 ts 文件
+- ESLint：基于 TypeScript 推荐规则与 jest 插件，解析 tsconfig.lint.json
+- 客户端 JS 测试：client/package.json 提供测试脚本与 eslint 配置
+
+**章节来源**
+- [jest.config.js:1-196](file://jest.config.js#L1-L196)
+- [.eslintrc.cjs:1-25](file://.eslintrc.cjs#L1-L25)
+- [client/package.json:1-19](file://client/package.json#L1-L19)
+
+## 依赖关系分析
+- 运行时依赖（节选）：express、ws、cors、multer、morgan、swagger-jsdoc、swagger-ui-express、uuid、debug 等
+- 开发依赖（节选）：jest、ts-jest、ts-node、typescript、eslint、pkg 等
+- 构建与打包：通过 tsc 与 pkg 实现，pkg targets 指向 node10
+
+```mermaid
+graph LR
+P["package.json 依赖"] --> E["express"]
+P --> W["ws"]
+P --> C["cors"]
+P --> M["multer"]
+P --> MO["morgan"]
+P --> SW["swagger-jsdoc / ui-express"]
+P --> U["uuid"]
+P --> D["debug"]
+P -.dev.-> J["jest / ts-jest / ts-node"]
+P -.dev.-> T["typescript / eslint"]
+P -.dev.-> K["pkg"]
+K --> OUT["可执行产物(目标 node10)"]
+```
+
+**图示来源**
+- [package.json:14-46](file://package.json#L14-L46)
+- [package.json:50-58](file://package.json#L50-L58)
+
+**章节来源**
+- [package.json:14-46](file://package.json#L14-L46)
+- [package.json:50-58](file://package.json#L50-L58)
+
+## 性能考虑
+- 日志级别：dev/combined/short/tiny 可按需调整，none 可减少 I/O 开销
+- 上传与静态资源：头像上传使用磁盘存储，建议确保磁盘空间充足并定期清理
+- 信令类型：WebSocket 通常比 HTTP 轮询更高效，建议在生产环境使用 websocket
+- 并发与资源：Node.js 进程的并发能力取决于 CPU 核心数与内存大小，建议为每个实例分配至少 1GB 内存并预留系统开销
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 端口占用或权限不足
+  - 症状：启动失败或端口被占用
+  - 排查：确认 -p/--port 指定端口可用；在类 Unix 系统上避免使用小于 1024 的特权端口
+- HTTPS 证书缺失
+  - 症状：启动时报错无法读取 server.key/server.cert
+  - 排查：确认 -k/--keyfile 与 -c/--certfile 指向的文件存在且可读；或关闭安全模式 -s
+- 信令类型错误
+  - 症状：日志提示信令类型不受支持并回退为 websocket
+  - 排查：确保 -t/--type 设置为 websocket 或 http
+- 静态资源 404
+  - 症状：访问 / 或 /module 返回 404
+  - 排查：确认 client/public 与 client/src 目录存在且包含所需文件
+- 上传失败
+  - 症状：/api/upload/avatar 返回错误
+  - 排查：确认 uploads/avatars 目录存在且写权限正常；检查文件名重命名逻辑
+- 环境变量未生效
+  - 症状：PORT/SECURE 等未按预期工作
+  - 排查：确认环境变量名正确且在启动前导出；命令行参数优先于环境变量
+
+**章节来源**
+- [src/index.ts:55-91](file://src/index.ts#L55-L91)
+- [src/server.ts:29-39](file://src/server.ts#L29-L39)
+- [src/server.ts:62-83](file://src/server.ts#L62-L83)
+
+## 结论
+本项目对 Node.js 的最低版本要求可参考打包目标 node10；实际运行建议使用较新的 LTS 版本以获得更好的稳定性与性能。生产环境推荐使用 WebSocket 信令、HTTPS 加密、合理设置日志级别与磁盘空间，并通过环境变量或命令行参数进行灵活配置。
+
+[本节为总结，不直接分析具体文件]
+
+## 附录
+
+### Node.js 版本要求
+- 打包目标：node10
+- 建议使用：Node.js LTS（如 18.x/20.x）
+
+**章节来源**
+- [package.json:55-57](file://package.json#L55-L57)
+
+### 操作系统兼容性
+- 服务器端：Express 与 Node.js 核心模块在 Windows、Linux、macOS 上均可运行
+- 客户端静态资源：无平台特定限制
+- 注意：Windows 批处理脚本 run.bat 用于本地快速启动
+
+**章节来源**
+- [run.bat:1-17](file://run.bat#L1-L17)
+
+### 系统资源建议
+- 内存：建议每实例至少 1GB，视并发连接与媒体负载适当增加
+- CPU：多核 CPU 更有利于并发处理
+- 磁盘：确保 uploads/avatars 目录有足够空间；静态资源目录 client/public 与 client/src 需要可读权限
+
+**章节来源**
+- [src/server.ts:44-57](file://src/server.ts#L44-L57)
+
+### 开发环境与生产环境
+- 开发环境
+  - 启动：npm run dev（使用 ts-node 直接运行 src/index.ts）
+  - 参数示例：-s -p 8080 -m private -l dev
+- 生产环境
+  - 构建：npm run build（TypeScript 编译到 build）
+  - 启动：npm run start（运行 build/index.js）
+  - 参数示例：-s -p 8080 -m private -k ./server.key -c ./server.cert -l dev
+- 打包：npm run pack（使用 pkg，目标 node10）
+
+**章节来源**
+- [package.json:5-12](file://package.json#L5-L12)
+- [run.bat:3-4](file://run.bat#L3-L4)
+
+### 环境变量与运行参数对照
+- PORT：覆盖端口默认值
+- SECURE：启用 HTTPS（布尔）
+- KEYFILE：HTTPS 秘钥文件路径
+- CERTFILE：HTTPS 证书文件路径
+- TYPE：信令类型 websocket/http
+- MODE：通信模式 public/private
+- LOGGING：日志级别 combined/dev/short/tiny/none
+
+**章节来源**
+- [src/index.ts:20-29](file://src/index.ts#L20-L29)
+
+### 信令模式与通信模式
+- 信令模式：websocket（默认）或 http（轮询）
+- 通信模式：public（默认）或 private（私有模式，用于限制访问）
+
+**章节来源**
+- [src/index.ts:26-27](file://src/index.ts#L26-L27)
+- [src/server.ts:25-25](file://src/server.ts#L25-L25)
+
+### 端口与证书路径
+- 端口：可通过 -p/--port 或环境变量 PORT 指定
+- 证书：HTTPS 模式下需提供 -k/--keyfile 与 -c/--certfile
+
+**章节来源**
+- [src/index.ts:22-25](file://src/index.ts#L22-L25)
+- [src/index.ts:56-59](file://src/index.ts#L56-L59)
+
+### Swagger 与静态资源
+- Swagger 文档：通过 initSwagger 初始化
+- 静态资源：根路径与 /module、/uploads 均已配置
+
+**章节来源**
+- [src/server.ts:41-42](file://src/server.ts#L41-L42)
+- [src/server.ts:27-28](file://src/server.ts#L27-L28)
+- [src/server.ts:86-86](file://src/server.ts#L86-L86)
+
+### Postman 环境
+- macOS 环境示例：包含 url 变量 localhost:8080
+
+**章节来源**
+- [test/env_macos.postman_environment.json:1-14](file://test/env_macos.postman_environment.json#L1-L14)