12 KiB
12 KiB
部署指南
**本文引用的文件** - [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)目录
简介
本指南面向生产环境部署“视频流服务器”应用，覆盖以下主题：
- 生产环境配置要求：Node.js 版本、系统资源、网络与安全参数
- 容器化部署：Docker 方案（含镜像构建与运行）
- 编排部署：Kubernetes 部署清单模板与要点
- 反向代理：Nginx 与 Apache 的典型配置思路
- SSL/TLS 证书：申请与配置流程
- 性能优化：内存管理、并发处理、资源限制
- 监控与日志：日志级别与输出策略
- 故障排除与维护：常见问题定位与修复
- 自动化与 CI/CD：打包、运行与部署脚本建议
项目结构
该仓库为基于 TypeScript 的 Express 服务器，提供 WebSocket 信令与静态资源服务，并内置 Swagger 文档与头像上传接口。
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"]
图表来源
章节来源
核心组件
- 启动与配置
- 命令行参数解析与默认值：端口、HTTPS 开关、密钥/证书路径、信令类型、通信模式、HTTP 访问日志级别
- 环境变量覆盖：PORT、SECURE、KEYFILE、CERTFILE、TYPE、MODE、LOGGING
- HTTP(S) 服务器
- 支持 HTTP 与 HTTPS；HTTPS 由外部证书文件加载
- 动态输出监听地址列表（IPv4）
- Express 应用
- CORS 允许跨域
- JSON/URL 编码请求体解析
- 静态资源托管与根页面路由
- Swagger 文档初始化
- 头像上传接口（Multer 存储到 uploads/avatars）
- 日志系统
- 日志级别枚举与动态设置
- 控制台输出格式化时间戳与级别前缀
章节来源
架构总览
下图展示从客户端到服务器的典型交互路径，包括 HTTP(S) 访问、静态资源、信令与上传流程。
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
图表来源
详细组件分析
启动与配置组件
- 命令行与环境变量映射
- 端口：支持 -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）
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 : 打印启动信息
图表来源
章节来源
HTTP 服务器与静态资源
- 路由与中间件
- CORS 允许所有来源
- JSON/URL 编码请求体解析
- 静态资源：根目录与 /module
- 根路径返回 index.html（若存在）
- Swagger 文档
- 初始化并暴露文档端点
- 头像上传
- Multer 存储到 uploads/avatars
- 接口返回重命名后的访问路径
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 未找到"]
图表来源
章节来源
日志系统
- 日志级别：none/error/warn/log/info
- 动态设置：通过命令行 -l/--logging 或环境变量 LOGGING
- 输出格式：带 ISO 时间戳与级别前缀
章节来源
依赖关系分析
- 运行时依赖
- express、ws、cors、multer、morgan、swagger-ui-express 等
- 开发与构建
- TypeScript、Jest、ESLint、ts-node、pkg 等
- 包装与分发
- pkg 将构建产物与静态资源打包为可执行文件
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["可执行二进制"]
图表来源
章节来源
性能考虑
- 内存管理
- 使用 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
章节来源
结论
本指南提供了从配置、部署到运维的完整路径。生产环境建议：
- 使用反向代理统一接入与证书终止
- 以容器化与编排方式提升弹性与可观测性
- 严格控制日志级别与输出，配合监控告警
- 对上传与媒体数据进行容量与安全评估
附录
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 步骤
章节来源