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

# 容器化部署

<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)