351 lines
13 KiB
Markdown
351 lines
13 KiB
Markdown
# 容器化部署
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向视频流服务器项目，提供从本地开发到容器化部署的完整指南，覆盖以下主题：
|
||
- Docker 镜像构建：Dockerfile 配置与多阶段构建优化
|
||
- Docker Compose：服务定义、端口映射、卷挂载、环境变量
|
||
- 容器网络：端口暴露、内部通信、外部访问
|
||
- Kubernetes 部署：Deployment、Service、Ingress 资源定义
|
||
- 安全配置：证书、密钥、只读根文件系统、非 root 用户
|
||
- 资源限制与健康检查
|
||
- 监控与日志最佳实践
|
||
|
||
## 项目结构
|
||
该仓库为基于 Node.js + Express + WebSocket 的视频信令与静态资源服务，核心运行方式如下：
|
||
- 使用命令行参数控制端口、HTTPS、信令协议类型、通信模式、日志级别等
|
||
- 默认监听端口可在脚本中查看，支持 HTTP 或 HTTPS
|
||
- 提供静态页面与上传接口，集成 Swagger 文档
|
||
- 通过 HTTP 轮询或 WebSocket 提供 WebRTC 信令
|
||
|
||
```mermaid
|
||
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](file://src/server.ts#L14-L89)
|
||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||
- [src/websocket.ts:15-39](file://src/websocket.ts#L15-L39)
|
||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||
- [package.json:5-12](file://package.json#L5-L12)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
|
||
- [run.bat:1-6](file://run.bat#L1-L6)
|
||
|
||
**章节来源**
|
||
- [package.json:5-12](file://package.json#L5-L12)
|
||
- [src/index.ts:20-40](file://src/index.ts#L20-L40)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
- [run.bat:1-6](file://run.bat#L1-L6)
|
||
|
||
## 核心组件
|
||
- 应用入口与参数解析：负责读取命令行参数与环境变量，初始化 Express 应用与 HTTPS/HTTP 服务器
|
||
- Express 服务器：配置 CORS、日志、静态资源、上传接口、Swagger 文档
|
||
- WebSocket 信令：基于 ws 的信令通道，支持连接管理、offer/answer/candidate 广播等
|
||
- 信令路由：HTTP REST 接口，按会话隔离，支持轮询与 WebSocket 两种模式
|
||
- 配置项接口：统一承载端口、HTTPS、信令类型、通信模式、日志级别等
|
||
|
||
**章节来源**
|
||
- [src/index.ts:13-106](file://src/index.ts#L13-L106)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/websocket.ts:6-117](file://src/websocket.ts#L6-L117)
|
||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||
- [src/class/options.ts:1-9](file://src/class/options.ts#L1-L9)
|
||
|
||
## 架构总览
|
||
容器化部署建议采用“单容器一进程”原则，将应用打包为镜像并在容器内运行。网络层面需明确：
|
||
- 端口暴露：HTTP/HTTPS 端口对外暴露
|
||
- 内部通信：WebSocket 与 HTTP 信令在同一进程内处理
|
||
- 外部访问：通过反向代理或 Ingress 统一入口
|
||
|
||
```mermaid
|
||
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、信令类型、通信模式、日志级别
|
||
|
||
```mermaid
|
||
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(["完成"])
|
||
```
|
||
|
||
[此图为流程图示意，不直接对应具体源码文件，故不提供图表来源]
|
||
|
||
**章节来源**
|
||
- [package.json:5-12](file://package.json#L5-L12)
|
||
- [tsconfig.json:1-13](file://tsconfig.json#L1-L13)
|
||
- [tsconfig.build.json:1-5](file://tsconfig.build.json#L1-L5)
|
||
- [src/index.ts:20-40](file://src/index.ts#L20-L40)
|
||
|
||
### Docker Compose 配置要点
|
||
- 服务定义：单服务运行应用进程
|
||
- 端口映射：将宿主 80/443 映射到容器端口
|
||
- 卷挂载：
|
||
- 静态资源目录：client/public
|
||
- 上传目录：client/public/uploads（确保写权限）
|
||
- 环境变量：通过环境变量传递端口、HTTPS 开关、证书路径、信令类型、通信模式、日志级别
|
||
- 依赖与健康检查：可选添加健康检查探针，探测 /config 或 /signaling
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
[此图为概念性交互示意，不直接对应具体源码文件，故不提供图表来源]
|
||
|
||
**章节来源**
|
||
- [src/server.ts:25-86](file://src/server.ts#L25-L86)
|
||
- [src/websocket.ts:15-39](file://src/websocket.ts#L15-L39)
|
||
- [src/index.ts:20-40](file://src/index.ts#L20-L40)
|
||
|
||
### 容器网络配置
|
||
- 端口暴露：根据 HTTPS 开关暴露 80（HTTP）或 443（HTTPS），默认监听端口可在启动参数中调整
|
||
- 内部通信：WebSocket 与 HTTP 信令在同一进程内，无需额外网络组件
|
||
- 外部访问：建议通过反向代理或 Ingress 提供 TLS 终止与域名路由
|
||
|
||
```mermaid
|
||
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 信令"]
|
||
```
|
||
|
||
[此图为流程图示意，不直接对应具体源码文件，故不提供图表来源]
|
||
|
||
**章节来源**
|
||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||
- [src/server.ts:25-86](file://src/server.ts#L25-L86)
|
||
|
||
### Kubernetes 部署配置
|
||
- Deployment：单副本或按需副本数，设置资源请求与限制
|
||
- Service：ClusterIP/LoadBalancer，暴露 80/443
|
||
- Ingress：TLS 终止、路径路由至 Service
|
||
- Secret：存放 server.key 与 server.cert
|
||
- ConfigMap：存放运行参数（如端口、信令类型、通信模式、日志级别）
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "Kubernetes"
|
||
I["Ingress"]
|
||
S["Service"]
|
||
D["Deployment"]
|
||
P["Pod"]
|
||
end
|
||
I --> S
|
||
S --> D
|
||
D --> P
|
||
```
|
||
|
||
[此图为概念性部署示意，不直接对应具体源码文件，故不提供图表来源]
|
||
|
||
**章节来源**
|
||
- [src/index.ts:20-40](file://src/index.ts#L20-L40)
|
||
- [src/server.ts:25-86](file://src/server.ts#L25-L86)
|
||
|
||
### 容器安全配置
|
||
- 证书与密钥：
|
||
- 将 server.key 与 server.cert 以 Secret 方式挂载，避免硬编码
|
||
- 应用通过环境变量或挂载路径读取证书
|
||
- 最小权限：
|
||
- 使用非 root 用户运行
|
||
- 根文件系统只读，仅对上传目录进行写入
|
||
- 网络策略：限制入站流量，仅开放必要端口
|
||
- 配置注入：通过 ConfigMap/环境变量注入运行参数
|
||
|
||
**章节来源**
|
||
- [src/index.ts:55-65](file://src/index.ts#L55-L65)
|
||
- [server.cert:1-22](file://server.cert#L1-L22)
|
||
- [src/server.ts:44-57](file://src/server.ts#L44-L57)
|
||
|
||
### 资源限制与健康检查
|
||
- 资源限制：为 CPU 与内存设置 requests/limits，避免资源争抢
|
||
- 健康检查：
|
||
- HTTP 探针：探测 /config 或 /signaling，确认服务可用
|
||
- TCP 探针：若仅需端口存活，可使用 TCPSocket
|
||
- 重启策略：根据业务需求设置 restartPolicy
|
||
|
||
**章节来源**
|
||
- [src/server.ts:25-26](file://src/server.ts#L25-L26)
|
||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||
|
||
### 监控与日志收集
|
||
- 日志：
|
||
- 使用 morgan 输出访问日志，支持多种格式
|
||
- 将日志输出到 stdout/stderr，便于容器平台采集
|
||
- 指标：
|
||
- 可扩展 Prometheus 指标导出（如连接数、消息速率）
|
||
- 链路追踪：
|
||
- 结合 OpenTelemetry 或平台内置追踪能力
|
||
|
||
**章节来源**
|
||
- [src/server.ts:18-20](file://src/server.ts#L18-L20)
|
||
- [src/index.ts:62-72](file://src/index.ts#L62-L72)
|
||
|
||
## 依赖关系分析
|
||
- 应用入口依赖服务器创建与 WebSocket 信令
|
||
- Express 服务器依赖信令路由与静态资源
|
||
- 信令路由依赖 HTTP 处理器
|
||
- 配置项接口贯穿各组件，作为统一输入
|
||
|
||
```mermaid
|
||
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](file://src/index.ts#L52-L91)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||
- [src/websocket.ts:15-39](file://src/websocket.ts#L15-L39)
|
||
- [src/class/options.ts:1-9](file://src/class/options.ts#L1-L9)
|
||
|
||
**章节来源**
|
||
- [src/index.ts:52-91](file://src/index.ts#L52-L91)
|
||
- [src/server.ts:14-89](file://src/server.ts#L14-L89)
|
||
- [src/signaling.ts:4-24](file://src/signaling.ts#L4-L24)
|
||
- [src/websocket.ts:15-39](file://src/websocket.ts#L15-L39)
|
||
- [src/class/options.ts:1-9](file://src/class/options.ts#L1-L9)
|
||
|
||
## 性能考虑
|
||
- 多阶段构建减少镜像体积，缩短拉取时间
|
||
- 仅复制构建产物与运行时依赖，避免 node_modules 进入最终镜像
|
||
- 合理设置资源限制，避免 OOM
|
||
- WebSocket 与 HTTP 共用同一进程，降低进程间通信开销
|
||
- 静态资源与上传目录分离，便于缓存与持久化
|
||
|
||
[本节为通用指导，不直接分析具体文件，故不提供章节来源]
|
||
|
||
## 故障排查指南
|
||
- 端口占用：确认容器端口未被占用，或调整映射端口
|
||
- HTTPS 证书：检查 server.key 与 server.cert 是否正确挂载与读取
|
||
- CORS 问题：确认前端域名与跨域配置
|
||
- 上传失败：检查上传目录权限与磁盘空间
|
||
- 信令异常：验证会话 ID 与 WebSocket 连接状态
|
||
|
||
**章节来源**
|
||
- [src/index.ts:55-65](file://src/index.ts#L55-L65)
|
||
- [src/server.ts:44-86](file://src/server.ts#L44-L86)
|
||
- [src/websocket.ts:27-38](file://src/websocket.ts#L27-L38)
|
||
|
||
## 结论
|
||
通过多阶段构建与最小化运行时镜像，结合 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
|
||
|
||
**章节来源**
|
||
- [src/index.ts:20-40](file://src/index.ts#L20-L40)
|
||
- [package.json:9](file://package.json#L9)
|
||
|
||
### API 与信令概览
|
||
- 配置接口：返回当前信令类型、通信模式与日志级别
|
||
- 上传接口：支持头像上传并重命名为用户 ID
|
||
- 信令接口：按会话隔离，支持连接管理与 WebRTC 信令交换
|
||
|
||
**章节来源**
|
||
- [src/server.ts:25-86](file://src/server.ts#L25-L86)
|
||
- [src/服务端接口与WebSocket消息类型.md:7-33](file://src/服务端接口与WebSocket消息类型.md#L7-L33)
|
||
- [src/服务端接口与WebSocket消息类型.md:37-83](file://src/服务端接口与WebSocket消息类型.md#L37-L83)
|
||
- [src/服务端接口与WebSocket消息类型.md:139-234](file://src/服务端接口与WebSocket消息类型.md#L139-L234) |