# 环境配置

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