video_socket-server/.qoder/repowiki/zh/content/部署指南/部署指南.md

# 部署指南

<cite>
**本文引用的文件**
- [package.json](file://package.json)
- [src/index.ts](file://src/index.ts)
- [src/server.ts](file://src/server.ts)
- [src/class/options.ts](file://src/class/options.ts)
- [src/log.ts](file://src/log.ts)
- [run.bat](file://run.bat)
- [tsconfig.json](file://tsconfig.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向生产环境部署“视频流服务器”应用，覆盖以下主题：
- 生产环境配置要求：Node.js 版本、系统资源、网络与安全参数
- 容器化部署：Docker 方案（含镜像构建与运行）
- 编排部署：Kubernetes 部署清单模板与要点
- 反向代理：Nginx 与 Apache 的典型配置思路
- SSL/TLS 证书：申请与配置流程
- 性能优化：内存管理、并发处理、资源限制
- 监控与日志：日志级别与输出策略
- 故障排除与维护：常见问题定位与修复
- 自动化与 CI/CD：打包、运行与部署脚本建议

## 项目结构
该仓库为基于 TypeScript 的 Express 服务器，提供 WebSocket 信令与静态资源服务，并内置 Swagger 文档与头像上传接口。

```mermaid
graph TB
A["入口脚本<br/>src/index.ts"] --> B["HTTP(S) 服务器<br/>Express 应用"]
B --> C["静态资源<br/>client/public"]
B --> D["信令路由<br/>/signaling"]
B --> E["Swagger 文档<br/>/swagger*"]
B --> F["头像上传接口<br/>/api/upload/avatar"]
A --> G["日志模块<br/>src/log.ts"]
A --> H["选项解析<br/>src/class/options.ts"]
```

图表来源
- [src/index.ts:13-106](file://src/index.ts#L13-L106)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)

章节来源
- [src/index.ts:13-106](file://src/index.ts#L13-L106)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
- [package.json:1-60](file://package.json#L1-L60)

## 核心组件
- 启动与配置
  - 命令行参数解析与默认值：端口、HTTPS 开关、密钥/证书路径、信令类型、通信模式、HTTP 访问日志级别
  - 环境变量覆盖：PORT、SECURE、KEYFILE、CERTFILE、TYPE、MODE、LOGGING
- HTTP(S) 服务器
  - 支持 HTTP 与 HTTPS；HTTPS 由外部证书文件加载
  - 动态输出监听地址列表（IPv4）
- Express 应用
  - CORS 允许跨域
  - JSON/URL 编码请求体解析
  - 静态资源托管与根页面路由
  - Swagger 文档初始化
  - 头像上传接口（Multer 存储到 uploads/avatars）
- 日志系统
  - 日志级别枚举与动态设置
  - 控制台输出格式化时间戳与级别前缀

章节来源
- [src/index.ts:20-44](file://src/index.ts#L20-L44)
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)

## 架构总览
下图展示从客户端到服务器的典型交互路径，包括 HTTP(S) 访问、静态资源、信令与上传流程。

```mermaid
graph TB
subgraph "客户端"
U["浏览器/前端"]
end
subgraph "反向代理层"
RP["Nginx/Apache"]
end
subgraph "应用服务器"
S["Express 应用"]
WS["WebSocket 信令"]
FS["静态资源<br/>client/public"]
SW["Swagger 文档"]
UP["头像上传接口"]
end
subgraph "证书"
CERT["server.key / server.cert"]
end
U --> RP
RP --> S
S --> FS
S --> SW
S --> UP
S --> WS
S -. 使用证书 .-> CERT
```

图表来源
- [src/index.ts:55-65](file://src/index.ts#L55-L65)
- [src/server.ts:25-28](file://src/server.ts#L25-L28)
- [src/server.ts:44-83](file://src/server.ts#L44-L83)

## 详细组件分析

### 启动与配置组件
- 命令行与环境变量映射
  - 端口：支持 -p/--port 与 PORT
  - HTTPS：-s/--secure 与 SECURE；需配合 -k/--keyfile 与 -c/--certfile 或 KEYFILE/CERTFILE
  - 信令类型：-t/--type 支持 websocket/http，默认 websocket
  - 模式：-m/--mode 支持 public/private，默认 public
  - 日志：-l/--logging 支持 combined/dev/short/tiny/none，默认 dev
- 服务器启动
  - HTTPS 时读取密钥与证书文件
  - 输出监听地址与协议（http/https）

```mermaid
sequenceDiagram
participant CLI as "命令行/环境变量"
participant IDX as "src/index.ts"
participant APP as "Express 应用"
participant HTTPS as "HTTPS 服务器"
CLI->>IDX : 解析参数与默认值
IDX->>APP : 创建 Express 应用
IDX->>HTTPS : 加载 server.key/server.cert
HTTPS-->>IDX : 绑定端口并输出监听地址
IDX-->>CLI : 打印启动信息
```

图表来源
- [src/index.ts:20-44](file://src/index.ts#L20-L44)
- [src/index.ts:55-74](file://src/index.ts#L55-L74)

章节来源
- [src/index.ts:20-44](file://src/index.ts#L20-L44)
- [src/index.ts:55-74](file://src/index.ts#L55-L74)
- [src/class/options.ts:1-10](file://src/class/options.ts#L1-L10)

### HTTP 服务器与静态资源
- 路由与中间件
  - CORS 允许所有来源
  - JSON/URL 编码请求体解析
  - 静态资源：根目录与 /module
  - 根路径返回 index.html（若存在）
- Swagger 文档
  - 初始化并暴露文档端点
- 头像上传
  - Multer 存储到 uploads/avatars
  - 接口返回重命名后的访问路径

```mermaid
flowchart TD
Start(["请求进入"]) --> CORS["CORS 中间件"]
CORS --> Body["JSON/URL 编码解析"]
Body --> Routes{"匹配路由"}
Routes --> |"/" 或 "/index.html"| StaticIndex["返回静态首页"]
Routes --> |"/module/*"| StaticModule["返回模块源码"]
Routes --> |"/signaling"| Signaling["信令路由"]
Routes --> |"/swagger*"| Swagger["Swagger 文档"]
Routes --> |"/api/upload/avatar"| Upload["头像上传处理"]
Routes --> |"/uploads/*"| StaticUploads["返回上传文件"]
Routes --> |其他| NotFound["404 未找到"]
```

图表来源
- [src/server.ts:14-89](file://src/server.ts#L14-L89)

章节来源
- [src/server.ts:14-89](file://src/server.ts#L14-L89)

### 日志系统
- 日志级别：none/error/warn/log/info
- 动态设置：通过命令行 -l/--logging 或环境变量 LOGGING
- 输出格式：带 ISO 时间戳与级别前缀

章节来源
- [src/log.ts:1-51](file://src/log.ts#L1-L51)
- [src/index.ts:28](file://src/index.ts#L28)

## 依赖关系分析
- 运行时依赖
  - express、ws、cors、multer、morgan、swagger-ui-express 等
- 开发与构建
  - TypeScript、Jest、ESLint、ts-node、pkg 等
- 包装与分发
  - pkg 将构建产物与静态资源打包为可执行文件

```mermaid
graph LR
P["package.json"] --> TSC["TypeScript 编译"]
P --> JEST["Jest 测试"]
P --> ESL["ESLint 规则"]
P --> TS["ts-node 开发"]
P --> PKG["pkg 打包"]
TSC --> BUILD["build 目录产物"]
PKG --> BIN["可执行二进制"]
```

图表来源
- [package.json:14-46](file://package.json#L14-L46)
- [package.json:50-58](file://package.json#L50-L58)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)

章节来源
- [package.json:14-46](file://package.json#L14-L46)
- [package.json:50-58](file://package.json#L50-L58)
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)

## 性能考虑
- 内存管理
  - 使用 Node.js 的垃圾回收与进程退出策略，避免内存泄漏
  - 对大文件上传（如头像）采用流式处理与合理缓存大小
- 并发处理
  - Express 默认并发能力受 Node.js 事件循环影响；高并发场景建议前置反向代理或使用集群模式
  - WebSocket 信令应结合连接数与消息频率进行限流与心跳检测
- 资源限制
  - 设置合理的 ulimit、文件句柄上限与 Node.js 堆内存上限
  - 在容器中配置 CPU/内存资源配额与重启策略
- I/O 与静态资源
  - 将静态资源交由反向代理缓存与压缩（gzip/br），减轻应用压力
- 日志与监控
  - 使用 morgan 输出访问日志，结合日志切割与归档
  - 结合系统监控（CPU/内存/磁盘/网络）与应用指标（QPS/响应时间/错误率）

## 故障排除指南
- 启动失败（证书相关）
  - 确认 server.key 与 server.cert 文件存在且可读
  - 检查 -s/--secure 是否启用，以及 -k/-c 或 KEYFILE/CERTFILE 是否正确
- 端口占用
  - 更换 -p/--port 或释放占用端口；确认防火墙放行
- CORS 与跨域
  - 当前实现允许所有来源；生产环境建议限定来源
- 上传失败
  - 检查 uploads/avatars 目录权限与磁盘空间
  - 确认 Multer 存储配置与文件大小限制
- 日志级别过低
  - 提升 -l/--logging 或设置 LOGGING=dev/info 等
- 信令类型不支持
  - 仅支持 websocket 与 http；非预期值会被修正为 websocket

章节来源
- [src/index.ts:55-65](file://src/index.ts#L55-L65)
- [src/server.ts:44-83](file://src/server.ts#L44-L83)
- [src/log.ts:15-24](file://src/log.ts#L15-L24)

## 结论
本指南提供了从配置、部署到运维的完整路径。生产环境建议：
- 使用反向代理统一接入与证书终止
- 以容器化与编排方式提升弹性与可观测性
- 严格控制日志级别与输出，配合监控告警
- 对上传与媒体数据进行容量与安全评估

## 附录

### A. 生产环境配置要求
- Node.js 版本
  - 建议使用长期支持版本（LTS），确保与依赖兼容
- 系统资源
  - CPU：根据并发连接与媒体处理需求评估
  - 内存：预留足够堆内存与静态资源缓存
  - 磁盘：为 uploads/avatars 与日志保留充足空间
- 网络
  - 开放端口：HTTP(80)/HTTPS(443) 与 WebSocket 端口
  - 防火墙与安全组放行
  - 反向代理层启用 TLS 终止与压缩

### B. Docker 容器化部署
- 构建镜像
  - 使用多阶段构建，先安装依赖、再编译、最后复制运行时产物
  - 将 client/public 与构建产物纳入镜像
- 运行容器
  - 映射端口：80/443 至宿主机
  - 挂载证书卷：server.key 与 server.cert
  - 挂载上传目录：确保持久化
  - 设置环境变量覆盖默认配置（如 PORT、MODE、LOGGING）

### C. Kubernetes 部署配置
- Deployment
  - 设置副本数、就绪探针与存活探针
  - 资源请求与限制
- Service
  - ClusterIP/LoadBalancer/Ingress 选择
- ConfigMap
  - 非敏感配置项（如日志级别）
- Secret
  - 证书与敏感参数（如密钥文件）
- Ingress
  - TLS 配置与路径转发规则

### D. 反向代理设置
- Nginx
  - HTTPS 终止：配置 server 与 ssl_certificate/ssl_certificate_key
  - 负载均衡：upstream 与健康检查
  - 静态资源缓存与压缩
  - WebSocket 反向代理：升级头部透传
- Apache
  - mod_ssl 终止 HTTPS
  - mod_proxy_http 与 mod_proxy_wstunnel 代理 HTTP 与 WebSocket
  - 启用压缩与缓存

### E. SSL/TLS 证书
- 申请
  - Let’s Encrypt（免费）、商业 CA 或企业内 CA
- 配置
  - 将证书与私钥放置于安全位置
  - 在启动参数中指定 -k/--keyfile 与 -c/--certfile
  - 或通过环境变量 KEYFILE/CERTFILE 指定

### F. 监控与日志
- 日志
  - 使用 morgan 输出访问日志，按天切割
  - 结合日志聚合（如 ELK/Fluentd）与告警
- 指标
  - 连接数、吞吐量、错误率、响应时间
  - 媒体帧率、丢包率等业务指标

### G. 自动化部署与 CI/CD
- 构建
  - 使用 npm ci、tsc 与 pkg 生成可执行文件
- 测试
  - Jest 单元测试与 Postman 集成测试
- 部署
  - Docker 镜像推送至镜像仓库
  - Kubernetes 应用部署与滚动更新
- 脚本
  - run.bat 示例展示了构建与启动流程，可参考扩展为 CI/CD 步骤

章节来源
- [run.bat:1-17](file://run.bat#L1-L17)
- [package.json:5-12](file://package.json#L5-L12)