347 lines
14 KiB
Markdown
347 lines
14 KiB
Markdown
# 环境配置
|
||
|
||
<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) |