root/video_socket-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9c05c6a9d9aed053c77d9d9b6e9dfda720d8d022
video_socket-server/.qoder/repowiki/zh/content/部署指南/环境配置.md
stary 6c13817527 修改
2026-05-16 13:24:02 +08:00

14 KiB
Raw Blame History

环境配置

**本文引用的文件** - [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)

目录

  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 文档生成等。

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

图示来源

章节来源

核心组件

  • 入口与参数解析：负责从命令行读取运行参数，支持端口、HTTPS 密钥证书、信令类型、通信模式、日志级别等；同时支持通过环境变量覆盖默认值。
  • Express 应用：统一处理静态资源、上传接口、Swagger 文档、CORS、JSON/URL 编码请求体等。
  • 运行参数接口：定义了安全模式、端口、密钥/证书路径、信令类型、通信模式、日志级别等字段。

章节来源

架构总览

下图展示了启动流程与关键组件交互：命令行参数解析后创建 Express 应用，按需启用 HTTPS，随后根据信令类型选择 WebSocket 或 HTTP 轮询，并输出启动日志与访问地址。

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 : 信令就绪

图示来源

详细组件分析

命令行参数与环境变量

  • 支持的参数与默认值（优先级：命令行 > 环境变量 > 默认值）：
    • 端口：-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
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(["完成"])

图示来源

章节来源

Express 应用与静态资源

  • CORS：允许任意来源访问
  • 请求体解析：支持 JSON 与 URL 编码
  • 静态资源：
    • 根路径 / 映射到 client/public/index.html
    • /module 映射到 client/src
    • /uploads 映射到 client/public/uploads
  • 上传接口：/api/upload/avatar，使用 multer 将头像保存至 uploads/avatars，并按用户 ID 重命名
  • Swagger 文档初始化
  • /config 接口返回当前信令与模式、日志级别等配置

章节来源

构建与打包配置

  • TypeScript 编译：
    • tsconfig.json：目标 ES5，输出目录 build，包含 src 与 test
    • tsconfig.build.json：仅包含 src，继承 tsconfig.json
  • 打包：
    • package.json 中的 pkg 字段声明 assets 与 targets，其中 targets 包含 "node10"，表明以 Node.js 10 可执行文件为目标进行打包

章节来源

测试与质量工具

  • Jest：测试框架，收集覆盖率，测试匹配规则覆盖 src 与 test 下的 ts 文件
  • ESLint：基于 TypeScript 推荐规则与 jest 插件，解析 tsconfig.lint.json
  • 客户端 JS 测试：client/package.json 提供测试脚本与 eslint 配置

章节来源

依赖关系分析

  • 运行时依赖（节选）：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
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)"]

图示来源

章节来源

性能考虑

  • 日志级别：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 等未按预期工作
    • 排查：确认环境变量名正确且在启动前导出；命令行参数优先于环境变量

章节来源

结论

本项目对 Node.js 的最低版本要求可参考打包目标 node10；实际运行建议使用较新的 LTS 版本以获得更好的稳定性与性能。生产环境推荐使用 WebSocket 信令、HTTPS 加密、合理设置日志级别与磁盘空间，并通过环境变量或命令行参数进行灵活配置。

[本节为总结，不直接分析具体文件]

附录

Node.js 版本要求

  • 打包目标：node10
  • 建议使用：Node.js LTS（如 18.x/20.x）

章节来源

操作系统兼容性

  • 服务器端：Express 与 Node.js 核心模块在 Windows、Linux、macOS 上均可运行
  • 客户端静态资源：无平台特定限制
  • 注意：Windows 批处理脚本 run.bat 用于本地快速启动

章节来源

系统资源建议

  • 内存：建议每实例至少 1GB，视并发连接与媒体负载适当增加
  • CPU：多核 CPU 更有利于并发处理
  • 磁盘：确保 uploads/avatars 目录有足够空间；静态资源目录 client/public 与 client/src 需要可读权限

章节来源

开发环境与生产环境

  • 开发环境
    • 启动：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）

章节来源

环境变量与运行参数对照

  • PORT：覆盖端口默认值
  • SECURE：启用 HTTPS（布尔）
  • KEYFILE：HTTPS 秘钥文件路径
  • CERTFILE：HTTPS 证书文件路径
  • TYPE：信令类型 websocket/http
  • MODE：通信模式 public/private
  • LOGGING：日志级别 combined/dev/short/tiny/none

章节来源

信令模式与通信模式

  • 信令模式：websocket（默认）或 http（轮询）
  • 通信模式：public（默认）或 private（私有模式，用于限制访问）

章节来源

端口与证书路径

  • 端口：可通过 -p/--port 或环境变量 PORT 指定
  • 证书：HTTPS 模式下需提供 -k/--keyfile 与 -c/--certfile

章节来源

Swagger 与静态资源

  • Swagger 文档：通过 initSwagger 初始化
  • 静态资源：根路径与 /module、/uploads 均已配置

章节来源

Postman 环境

  • macOS 环境示例：包含 url 变量 localhost:8080

章节来源

Reference in New Issue View Git Blame Copy Permalink