13 KiB
13 KiB
容器化部署
**本文引用的文件** - [package.json](file://package.json) - [tsconfig.json](file://tsconfig.json) - [tsconfig.build.json](file://tsconfig.build.json) - [src/index.ts](file://src/index.ts) - [src/server.ts](file://src/server.ts) - [src/signaling.ts](file://src/signaling.ts) - [src/websocket.ts](file://src/websocket.ts) - [src/class/options.ts](file://src/class/options.ts) - [src/服务端接口与WebSocket消息类型.md](file://src/服务端接口与WebSocket消息类型.md) - [.gitignore](file://.gitignore) - [run.bat](file://run.bat) - [server.cert](file://server.cert)目录
简介
本文件面向视频流服务器项目，提供从本地开发到容器化部署的完整指南，覆盖以下主题：
- Docker 镜像构建：Dockerfile 配置与多阶段构建优化
- Docker Compose：服务定义、端口映射、卷挂载、环境变量
- 容器网络：端口暴露、内部通信、外部访问
- Kubernetes 部署：Deployment、Service、Ingress 资源定义
- 安全配置：证书、密钥、只读根文件系统、非 root 用户
- 资源限制与健康检查
- 监控与日志最佳实践
项目结构
该仓库为基于 Node.js + Express + WebSocket 的视频信令与静态资源服务，核心运行方式如下：
- 使用命令行参数控制端口、HTTPS、信令协议类型、通信模式、日志级别等
- 默认监听端口可在脚本中查看，支持 HTTP 或 HTTPS
- 提供静态页面与上传接口，集成 Swagger 文档
- 通过 HTTP 轮询或 WebSocket 提供 WebRTC 信令
graph TB
subgraph "应用进程"
A["Express 应用<br/>src/server.ts"]
B["HTTP/HTTPS 服务器<br/>src/index.ts"]
C["WebSocket 信令<br/>src/websocket.ts"]
D["信令路由<br/>src/signaling.ts"]
end
subgraph "静态资源"
E["客户端页面<br/>client/public"]
F["前端模块<br/>client/src"]
end
subgraph "配置与脚本"
G["启动脚本<br/>package.json scripts"]
H["编译配置<br/>tsconfig.json/tsconfig.build.json"]
I["运行批处理<br/>run.bat"]
end
B --> A
A --> D
A --> E
A --> F
B --> C
G --> B
H --> G
I --> G
图表来源
- src/server.ts:14-89
- src/index.ts:52-91
- src/websocket.ts:15-39
- src/signaling.ts:4-24
- package.json:5-12
- tsconfig.json:1-13
- tsconfig.build.json:1-5
- run.bat:1-6
章节来源
核心组件
- 应用入口与参数解析：负责读取命令行参数与环境变量，初始化 Express 应用与 HTTPS/HTTP 服务器
- Express 服务器：配置 CORS、日志、静态资源、上传接口、Swagger 文档
- WebSocket 信令：基于 ws 的信令通道，支持连接管理、offer/answer/candidate 广播等
- 信令路由：HTTP REST 接口，按会话隔离，支持轮询与 WebSocket 两种模式
- 配置项接口：统一承载端口、HTTPS、信令类型、通信模式、日志级别等
章节来源
- src/index.ts:13-106
- src/server.ts:14-89
- src/websocket.ts:6-117
- src/signaling.ts:4-24
- src/class/options.ts:1-9
架构总览
容器化部署建议采用“单容器一进程”原则，将应用打包为镜像并在容器内运行。网络层面需明确：
- 端口暴露：HTTP/HTTPS 端口对外暴露
- 内部通信：WebSocket 与 HTTP 信令在同一进程内处理
- 外部访问：通过反向代理或 Ingress 统一入口
graph TB
subgraph "宿主机"
L["负载均衡/反向代理<br/>Nginx/Ingress"]
end
subgraph "容器"
S["应用进程<br/>Node.js + Express + WebSocket"]
P["端口映射<br/>80/443 -> 容器端口"]
V["卷挂载<br/>静态资源/上传目录"]
end
L --> P
P --> S
V -.-> S
[此图为概念性架构示意，不直接对应具体源码文件，故不提供图表来源]
详细组件分析
Docker 镜像构建
- 基础镜像选择：建议使用官方 Node.js LTS 镜像作为基础层
- 多阶段构建：
- 第一阶段：安装依赖并编译 TypeScript 源码
- 第二阶段：仅复制构建产物与必要运行时依赖，减小镜像体积
- 工作目录与用户：
- 设置非 root 用户与只读根文件系统，提升安全性
- 启动命令：
- 使用 package.json 中的 start 脚本，结合环境变量控制端口、HTTPS、信令类型、通信模式、日志级别
flowchart TD
Start(["开始"]) --> Stage1["阶段1：安装依赖与编译<br/>Node LTS + npm ci + tsc"]
Stage1 --> Stage2["阶段2：复制构建产物<br/>最小化运行时镜像"]
Stage2 --> Config["配置运行用户与权限<br/>非root + 只读根"]
Config --> Expose["暴露端口<br/>80/443"]
Expose --> Entrypoint["设置入口命令<br/>npm start"]
Entrypoint --> End(["完成"])
[此图为流程图示意，不直接对应具体源码文件，故不提供图表来源]
章节来源
Docker Compose 配置要点
- 服务定义：单服务运行应用进程
- 端口映射：将宿主 80/443 映射到容器端口
- 卷挂载：
- 静态资源目录：client/public
- 上传目录：client/public/uploads（确保写权限）
- 环境变量：通过环境变量传递端口、HTTPS 开关、证书路径、信令类型、通信模式、日志级别
- 依赖与健康检查：可选添加健康检查探针，探测 /config 或 /signaling
sequenceDiagram
participant U as "用户"
participant C as "Compose 服务"
participant N as "Node 应用"
participant WS as "WebSocket 信令"
U->>C : 访问 / 或 /signaling
C->>N : 请求转发
N-->>C : 返回静态页面/接口响应
U->>WS : 建立 WebSocket 连接
WS-->>U : 信令数据offer/answer/candidate
[此图为概念性交互示意，不直接对应具体源码文件，故不提供图表来源]
章节来源
容器网络配置
- 端口暴露：根据 HTTPS 开关暴露 80（HTTP）或 443（HTTPS），默认监听端口可在启动参数中调整
- 内部通信：WebSocket 与 HTTP 信令在同一进程内，无需额外网络组件
- 外部访问：建议通过反向代理或 Ingress 提供 TLS 终止与域名路由
flowchart TD
A["外部请求"] --> B{"是否启用 HTTPS?"}
B --> |是| C["443/TCP 映射"]
B --> |否| D["80/TCP 映射"]
C --> E["应用进程监听端口"]
D --> E
E --> F["HTTP 轮询 /signaling"]
E --> G["WebSocket /ws 信令"]
[此图为流程图示意，不直接对应具体源码文件，故不提供图表来源]
章节来源
Kubernetes 部署配置
- Deployment：单副本或按需副本数，设置资源请求与限制
- Service：ClusterIP/LoadBalancer，暴露 80/443
- Ingress：TLS 终止、路径路由至 Service
- Secret：存放 server.key 与 server.cert
- ConfigMap：存放运行参数（如端口、信令类型、通信模式、日志级别）
graph TB
subgraph "Kubernetes"
I["Ingress"]
S["Service"]
D["Deployment"]
P["Pod"]
end
I --> S
S --> D
D --> P
[此图为概念性部署示意，不直接对应具体源码文件，故不提供图表来源]
章节来源
容器安全配置
- 证书与密钥：
- 将 server.key 与 server.cert 以 Secret 方式挂载，避免硬编码
- 应用通过环境变量或挂载路径读取证书
- 最小权限：
- 使用非 root 用户运行
- 根文件系统只读，仅对上传目录进行写入
- 网络策略：限制入站流量，仅开放必要端口
- 配置注入：通过 ConfigMap/环境变量注入运行参数
章节来源
资源限制与健康检查
- 资源限制：为 CPU 与内存设置 requests/limits，避免资源争抢
- 健康检查：
- HTTP 探针：探测 /config 或 /signaling，确认服务可用
- TCP 探针：若仅需端口存活，可使用 TCPSocket
- 重启策略：根据业务需求设置 restartPolicy
章节来源
监控与日志收集
- 日志：
- 使用 morgan 输出访问日志，支持多种格式
- 将日志输出到 stdout/stderr，便于容器平台采集
- 指标：
- 可扩展 Prometheus 指标导出（如连接数、消息速率）
- 链路追踪：
- 结合 OpenTelemetry 或平台内置追踪能力
章节来源
依赖关系分析
- 应用入口依赖服务器创建与 WebSocket 信令
- Express 服务器依赖信令路由与静态资源
- 信令路由依赖 HTTP 处理器
- 配置项接口贯穿各组件，作为统一输入
graph LR
IDX["src/index.ts"] --> SRV["src/server.ts"]
SRV --> SIG["src/signaling.ts"]
IDX --> WS["src/websocket.ts"]
SRV --> OPT["src/class/options.ts"]
图表来源
- src/index.ts:52-91
- src/server.ts:14-89
- src/signaling.ts:4-24
- src/websocket.ts:15-39
- src/class/options.ts:1-9
章节来源
- src/index.ts:52-91
- src/server.ts:14-89
- src/signaling.ts:4-24
- src/websocket.ts:15-39
- src/class/options.ts:1-9
性能考虑
- 多阶段构建减少镜像体积，缩短拉取时间
- 仅复制构建产物与运行时依赖，避免 node_modules 进入最终镜像
- 合理设置资源限制，避免 OOM
- WebSocket 与 HTTP 共用同一进程，降低进程间通信开销
- 静态资源与上传目录分离，便于缓存与持久化
[本节为通用指导，不直接分析具体文件，故不提供章节来源]
故障排查指南
- 端口占用：确认容器端口未被占用，或调整映射端口
- HTTPS 证书：检查 server.key 与 server.cert 是否正确挂载与读取
- CORS 问题：确认前端域名与跨域配置
- 上传失败：检查上传目录权限与磁盘空间
- 信令异常：验证会话 ID 与 WebSocket 连接状态
章节来源
结论
通过多阶段构建与最小化运行时镜像，结合 Compose/Kubernetes 的标准化编排，可实现稳定、安全、可观测的容器化部署。配合证书管理、资源限制与健康检查，可满足生产环境的高可用与高安全要求。
[本节为总结性内容，不直接分析具体文件，故不提供章节来源]
附录
关键运行参数与环境变量
- 端口：-p/--port，默认值来自环境变量 PORT
- HTTPS：-s/--secure，证书与密钥路径由 -k/--keyfile 与 -c/--certfile 指定
- 信令类型：-t/--type，支持 websocket/http
- 通信模式：-m/--mode，public/private
- 日志级别：-l/--logging，支持 combined/dev/short/tiny/none
章节来源
API 与信令概览
- 配置接口：返回当前信令类型、通信模式与日志级别
- 上传接口：支持头像上传并重命名为用户 ID
- 信令接口：按会话隔离，支持连接管理与 WebRTC 信令交换
章节来源