mb-rrvideo-server 1.0.2 → 1.0.3

package/DOCKER.md

@@ -1,20 +1,211 @@
-# Docker 部署指南
+# Docker 部署完整指南
 
-mb-rrvideo-server 视频转码服务 Docker 镜像，开箱即用。
+本文档面向 Docker 新手，提供从零开始的完整部署指南。
 
-## 快速开始
+## 重要说明
 
-### 1. 准备配置文件
+**项目命名：**
+- **npm 包名**：`mb-rrvideo-server`（转码服务的 npm 包）
+- **Docker 镜像名**：`mb-rrvideo-converter`（完整的转码系统镜像）
+- **容器名**：`rrvideo-server`（运行中的容器）
 
-在部署目录创建 `config.json`：
+**为什么镜像名不同？**
+- `mb-rrvideo-server` 是 npm 包，只包含转码服务代码
+- `mb-rrvideo-converter` 是 Docker 镜像，包含完整的转码系统（Node.js + mb-rrvideo + mb-rrvideo-server + Playwright）
+- 使用不同的名称避免混淆
 
+**快速参考：**
 ```bash
-mkdir -p rrvideo-deploy
-cd rrvideo-deploy
+# 下载 npm 包
+npm pack mb-rrvideo-server
+
+# 构建 Docker 镜像
+docker build -t mb-rrvideo-converter:latest .
+
+# 查看镜像
+docker images mb-rrvideo-converter
+
+# 运行容器
+docker-compose up -d
+
+# 容器名称
+docker ps | grep rrvideo-server
+```
+
+## 目录
+
+- [什么是 Docker](#什么是-docker)
+- [前置准备](#前置准备)
+- [文件说明](#文件说明)
+- [方式一：使用 npm 包快速部署](#方式一使用-npm-包快速部署推荐)
+- [方式二：从源码构建镜像](#方式二从源码构建镜像)
+- [方式三：镜像迁移到其他服务器](#方式三镜像迁移到其他服务器)
+- [常用命令](#常用命令)
+- [故障排除](#故障排除)
+- [镜像优化说明](#镜像优化说明)
+
+---
+
+## 什么是 Docker
+
+Docker 是一个容器化平台，可以把应用和所有依赖打包成一个"镜像"，然后在任何服务器上运行。
+
+**核心概念：**
+- **镜像（Image）**：类似"安装包"，包含应用和所有依赖
+- **容器（Container）**：镜像运行后的实例，类似"运行中的程序"
+- **Dockerfile**：构建镜像的"配方"，定义如何打包应用
+- **docker-compose.yml**：配置文件，定义如何运行容器（端口、目录挂载等）
+
+**为什么需要两个文件？**
+- `Dockerfile`：用于**构建镜像**（打包应用）
+- `docker-compose.yml`：用于**运行容器**（启动应用）
+
+---
+
+## 前置准备
+
+### 1. 安装 Docker
+
+**CentOS/RHEL：**
+```bash
+# 安装 Docker
+sudo yum install -y yum-utils
+sudo yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
+sudo yum install -y docker-ce docker-ce-cli containerd.io
+
+# 启动 Docker
+sudo systemctl start docker
+sudo systemctl enable docker
+
+# 验证安装
+docker --version
+```
+
+**Ubuntu/Debian：**
+```bash
+# 安装 Docker
+curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
+
+# 启动 Docker
+sudo systemctl start docker
+sudo systemctl enable docker
+
+# 验证安装
+docker --version
+```
+
+### 2. 安装 Docker Compose
+
+```bash
+# 下载 Docker Compose
+sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+
+# 添加执行权限
+sudo chmod +x /usr/local/bin/docker-compose
+
+# 验证安装
+docker-compose --version
+```
+
+### 3. 配置 Docker 国内镜像加速（可选但推荐）
+
+```bash
+# 创建配置目录
+sudo mkdir -p /etc/docker
+
+# 配置镜像加速
+sudo tee /etc/docker/daemon.json <<-'EOF'
+{
+  "registry-mirrors": [
+    "https://docker.mirrors.ustc.edu.cn",
+    "https://hub-mirror.c.163.com",
+    "https://mirror.ccs.tencentyun.com"
+  ]
+}
+EOF
+
+# 重启 Docker
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+```
+
+---
+
+## 文件说明
+
+### Dockerfile
+用于构建镜像，包含：
+- **Node.js 22** 环境
+- **mb-rrvideo**（转码工具，全局安装）
+- **mb-rrvideo-server**（转码服务，全局安装）
+- **Playwright Chromium**（浏览器，mb-rrvideo 依赖）
+- **PM2**（进程管理）
+- 所有系统依赖
+
+**验证 mb-rrvideo 是否安装：**
+```bash
+# 进入容器
+docker-compose exec rrvideo-server bash
+
+# 检查 mb-rrvideo
+rrvideos --version
+# 输出：mb-rrvideo version x.x.x
+
+# 检查 mb-rrvideo-server
+rrvideo-server --version
+# 或者
+pm2 status
 ```
 
-创建 `config.json`（参考 config.example.json）：
+### docker-compose.yml
+用于运行容器，配置：
+- 端口映射（24203）
+- 目录挂载（config、logs、temp、Video）
+- 环境变量
+- 资源限制
 
+### config.json
+服务配置文件，包含：
+- 服务器端口
+- 存储配置（本地/MinIO）
+- 转码参数
+- 日志配置
+
+---
+
+## 方式一：使用 npm 包快速部署（推荐）
+
+这种方式最简单，适合快速部署。
+
+### 步骤 1：下载文件
+
+```bash
+# 创建部署目录
+mkdir -p ~/rrvideo-deploy
+cd ~/rrvideo-deploy
+
+# 从 npm 下载文件
+npm pack mb-rrvideo-server
+tar -xzf mb-rrvideo-server-*.tgz
+cd package
+
+# 或者直接下载
+wget https://registry.npmjs.org/mb-rrvideo-server/-/mb-rrvideo-server-1.0.2.tgz
+tar -xzf mb-rrvideo-server-1.0.2.tgz
+cd package
+```
+
+### 步骤 2：准备配置文件
+
+```bash
+# 复制配置模板
+cp config.example.json config.json
+
+# 编辑配置（根据实际情况修改）
+vi config.json
+```
+
+**配置示例（本地存储）：**
 ```json
 {
   "server": {
@@ -45,20 +236,213 @@ cd rrvideo-deploy
 }
 ```
 
-### 2. 下载 docker-compose.yml
+### 步骤 3：构建镜像
 
 ```bash
-wget https://raw.githubusercontent.com/your-repo/mb-rrvideo-server/main/docker-compose.yml
+# 构建镜像（需要 10-20 分钟，取决于网络速度）
+docker build -t mb-rrvideo-converter:latest .
+
+# 查看镜像
+docker images mb-rrvideo-converter
+```
+
+**输出示例：**
+```
+REPOSITORY             TAG       IMAGE ID       CREATED         SIZE
+mb-rrvideo-converter   latest    abc123def456   2 minutes ago   1.5GB
 ```
 
-或手动创建 `docker-compose.yml`：
+### 步骤 4：启动服务
 
-```yaml
+```bash
+# 使用 docker-compose 启动
+docker-compose up -d
+
+# 查看容器状态
+docker-compose ps
+```
+
+**输出示例：**
+```
+NAME              IMAGE                      STATUS         PORTS
+rrvideo-server    mb-rrvideo-converter:latest   Up 10 seconds  0.0.0.0:24203->24203/tcp
+```
+
+### 步骤 5：验证服务
+
+```bash
+# 健康检查
+curl http://localhost:24203/health
+
+# 查看日志
+docker-compose logs -f
+
+# 验证 mb-rrvideo 是否正常
+docker-compose exec rrvideo-server rrvideos --version
+
+# 验证 Playwright 浏览器
+docker-compose exec rrvideo-server npx playwright --version
+```
+
+**成功输出：**
+```json
+{"result_code":0,"message":"rrvideo-server is running"}
+```
+
+```bash
+# mb-rrvideo 版本信息
+mb-rrvideo version 1.x.x
+
+# Playwright 版本信息
+Version 1.x.x
+```
+
+### 步骤 6：测试转码功能（可选）
+
+```bash
+# 进入容器
+docker-compose exec rrvideo-server bash
+
+# 测试 mb-rrvideo 转码（需要准备一个 rrweb 录屏 JSON 文件）
+# 示例：
+cat > /tmp/test.json << 'EOF'
+{
+  "events": [...]
+}
+EOF
+
+# 执行转码
+rrvideos convert /tmp/test.json -o /tmp/test.mp4
+
+# 检查输出
+ls -lh /tmp/test.mp4
+```
+
+如果能成功生成视频文件，说明 mb-rrvideo 工作正常。
+
+---
+
+## 方式二：从源码构建镜像
+
+适合需要修改代码或自定义配置的场景。
+
+### 步骤 1：克隆仓库
+
+```bash
+# 克隆代码
+git clone https://github.com/your-repo/mb-rrvideo-server.git
+cd mb-rrvideo-server
+
+# 或者从 npm 下载
+npm pack mb-rrvideo-server
+tar -xzf mb-rrvideo-server-*.tgz
+cd package
+```
+
+### 步骤 2：准备配置
+
+```bash
+cp config.example.json config.json
+vi config.json
+```
+
+### 步骤 3：构建镜像
+
+```bash
+# 构建镜像
+docker build -t mb-rrvideo-converter:1.0.2 .
+
+# 同时打上 latest 标签
+docker tag mb-rrvideo-converter:1.0.2 mb-rrvideo-converter:latest
+```
+
+### 步骤 4：启动服务
+
+```bash
+docker-compose up -d
+```
+
+---
+
+## 方式三：镜像迁移到其他服务器
+
+当你在一台服务器上构建好镜像后，可以迁移到其他服务器使用。
+
+### 方法 A：导出/导入镜像文件（适合内网）
+
+#### 在源服务器上：
+
+```bash
+# 1. 导出镜像为 tar 文件
+docker save mb-rrvideo-converter:latest -o mb-rrvideo-converter.tar
+
+# 2. 查看文件大小
+ls -lh mb-rrvideo-converter.tar
+# 输出：-rw------- 1 root root 1.5G Feb  6 18:00 mb-rrvideo-converter.tar
+
+# 3. 传输到目标服务器（选择一种方式）
+
+# 方式1：使用 scp
+scp mb-rrvideo-converter.tar user@target-server:/tmp/
+
+# 方式2：使用 rsync（支持断点续传）
+rsync -avz --progress mb-rrvideo-converter.tar user@target-server:/tmp/
+
+# 方式3：使用 U 盘或移动硬盘
+# 直接复制文件到移动设备
+```
+
+#### 在目标服务器上：
+
+```bash
+# 1. 导入镜像
+docker load -i /tmp/mb-rrvideo-converter.tar
+
+# 2. 验证镜像
+docker images mb-rrvideo-converter
+
+# 3. 准备部署目录
+mkdir -p ~/rrvideo-deploy
+cd ~/rrvideo-deploy
+
+# 4. 创建配置文件
+cat > config.json << 'EOF'
+{
+  "server": {
+    "port": 24203,
+    "host": "0.0.0.0"
+  },
+  "storage": {
+    "type": "local",
+    "local": {
+      "video_dir": "/app/Video",
+      "temp_dir": "/app/temp"
+    }
+  },
+  "rrvideo": {
+    "speed": 1,
+    "skipInactive": true,
+    "mouseTail": false
+  },
+  "convert": {
+    "delete_after_upload": true,
+    "max_concurrent_tasks": 3
+  },
+  "log": {
+    "level": "INFO",
+    "flush_interval": 2000,
+    "buffer_max_size": 500
+  }
+}
+EOF
+
+# 5. 创建 docker-compose.yml
+cat > docker-compose.yml << 'EOF'
 version: '3.8'
 
 services:
   rrvideo-server:
-    image: mb-rrvideo-server:latest
+    image: mb-rrvideo-converter:latest
     container_name: rrvideo-server
     restart: unless-stopped
     
@@ -75,96 +459,138 @@ services:
     environment:
       - TZ=Asia/Shanghai
       - NODE_ENV=production
+EOF
+
+# 6. 启动服务
+docker-compose up -d
+
+# 7. 验证服务
+curl http://localhost:24203/health
 ```
 
-### 3. 启动服务
+### 方法 B：使用私有镜像仓库（适合多服务器部署）
 
-```bash
-# 使用预构建镜像
-docker-compose up -d
+#### 步骤 1：搭建私有仓库（在一台服务器上）
 
-# 或从源码构建
-docker-compose build
-docker-compose up -d
+```bash
+# 启动 Docker Registry
+docker run -d \
+  -p 5000:5000 \
+  --restart=always \
+  --name registry \
+  -v /data/registry:/var/lib/registry \
+  registry:2
+
+# 验证仓库
+curl http://localhost:5000/v2/_catalog
 ```
 
-### 4. 查看日志
+#### 步骤 2：推送镜像到私有仓库
 
 ```bash
-# 查看容器日志
-docker-compose logs -f
+# 在源服务器上
 
-# 查看应用日志
-tail -f logs/server/$(date +%Y-%m-%d)/*.log
+# 1. 标记镜像（假设私有仓库地址是 192.168.1.100:5000）
+docker tag mb-rrvideo-converter:latest 192.168.1.100:5000/mb-rrvideo-converter:latest
+
+# 2. 配置 Docker 允许 HTTP 仓库（如果使用 HTTP）
+sudo tee /etc/docker/daemon.json <<-'EOF'
+{
+  "insecure-registries": ["192.168.1.100:5000"]
+}
+EOF
+
+sudo systemctl restart docker
+
+# 3. 推送镜像
+docker push 192.168.1.100:5000/mb-rrvideo-converter:latest
 ```
 
-### 5. 健康检查
+#### 步骤 3：在目标服务器拉取镜像
 
 ```bash
-curl http://localhost:24203/health
-```
+# 在目标服务器上
 
-## 从源码构建镜像
+# 1. 配置 Docker 允许 HTTP 仓库
+sudo tee /etc/docker/daemon.json <<-'EOF'
+{
+  "insecure-registries": ["192.168.1.100:5000"]
+}
+EOF
 
-### 1. 克隆仓库
+sudo systemctl restart docker
 
-```bash
-git clone <repository>
-cd mb-rrvideo-server
+# 2. 拉取镜像
+docker pull 192.168.1.100:5000/mb-rrvideo-converter:latest
+
+# 3. 重新标记为本地镜像（可选）
+docker tag 192.168.1.100:5000/mb-rrvideo-converter:latest mb-rrvideo-converter:latest
+
+# 4. 部署（同方法 A 的步骤 3-7）
 ```
 
-### 2. 构建镜像
+### 方法 C：使用公有镜像仓库（Docker Hub / 阿里云）
+
+#### 使用 Docker Hub：
 
 ```bash
-docker build -t mb-rrvideo-server:latest .
-```
+# 在源服务器上
+
+# 1. 登录 Docker Hub
+docker login
 
-### 3. 推送到私有仓库（可选）
+# 2. 标记镜像（your-username 是你的 Docker Hub 用户名）
+docker tag mb-rrvideo-converter:latest your-username/mb-rrvideo-converter:latest
+
+# 3. 推送镜像
+docker push your-username/mb-rrvideo-converter:latest
+```
 
 ```bash
-# 标记镜像
-docker tag mb-rrvideo-server:latest your-registry.com/mb-rrvideo-server:latest
+# 在目标服务器上
+
+# 1. 拉取镜像
+docker pull your-username/mb-rrvideo-converter:latest
 
-# 推送镜像
-docker push your-registry.com/mb-rrvideo-server:latest
+# 2. 重新标记
+docker tag your-username/mb-rrvideo-converter:latest mb-rrvideo-converter:latest
+
+# 3. 部署
 ```
 
-## 使用 Docker Run（不使用 docker-compose）
+#### 使用阿里云容器镜像服务：
 
 ```bash
-docker run -d \
-  --name rrvideo-server \
-  --restart unless-stopped \
-  -p 24203:24203 \
-  -v $(pwd)/config.json:/app/config/config.json:ro \
-  -v $(pwd)/logs:/app/logs \
-  -v $(pwd)/temp:/app/temp \
-  -v $(pwd)/Video:/app/Video \
-  -v $(pwd)/tasks:/app/tasks \
-  -e TZ=Asia/Shanghai \
-  -e NODE_ENV=production \
-  mb-rrvideo-server:latest
-```
+# 在源服务器上
 
-## 目录结构
+# 1. 登录阿里云镜像仓库
+docker login --username=your-aliyun-account registry.cn-hangzhou.aliyuncs.com
 
-部署后的目录结构：
+# 2. 标记镜像
+docker tag mb-rrvideo-converter:latest registry.cn-hangzhou.aliyuncs.com/your-namespace/mb-rrvideo-converter:latest
 
+# 3. 推送镜像
+docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/mb-rrvideo-converter:latest
 ```
-rrvideo-deploy/
-├── config.json          # 配置文件（必须）
-├── docker-compose.yml   # Docker Compose 配置
-├── logs/                # 日志目录（自动创建）
-│   ├── convert/         # 转码日志
-│   ├── merge/           # 合并日志
-│   └── server/          # 服务器日志
-├── temp/                # 临时文件（自动创建）
-├── Video/               # 视频输出（自动创建）
-└── tasks/               # 任务数据（自动创建）
+
+```bash
+# 在目标服务器上
+
+# 1. 拉取镜像
+docker pull registry.cn-hangzhou.aliyuncs.com/your-namespace/mb-rrvideo-converter:latest
+
+# 2. 重新标记
+docker tag registry.cn-hangzhou.aliyuncs.com/your-namespace/mb-rrvideo-converter:latest mb-rrvideo-converter:latest
+
+# 3. 部署
 ```
 
+---
+
 ## 常用命令
 
+### 容器管理
+
 ```bash
 # 启动服务
 docker-compose up -d
@@ -175,124 +601,237 @@ docker-compose stop
 # 重启服务
 docker-compose restart
 
-# 查看状态
+# 删除容器（不删除数据）
+docker-compose down
+
+# 删除容器和数据卷
+docker-compose down -v
+
+# 查看容器状态
 docker-compose ps
 
-# 查看日志
+# 查看容器详细信息
+docker inspect rrvideo-server
+```
+
+### 日志查看
+
+```bash
+# 查看实时日志
 docker-compose logs -f
 
+# 查看最近 100 行日志
+docker-compose logs --tail=100
+
+# 查看应用日志
+tail -f logs/server/$(date +%Y-%m-%d)/*.log
+tail -f logs/convert/$(date +%Y-%m-%d)/*.log
+```
+
+### 进入容器调试
+
+```bash
 # 进入容器
 docker-compose exec rrvideo-server bash
 
-# 查看 PM2 状态
+# 在容器内执行命令
 docker-compose exec rrvideo-server pm2 status
-
-# 查看 PM2 日志
 docker-compose exec rrvideo-server pm2 logs
+docker-compose exec rrvideo-server rrvideos --version
+docker-compose exec rrvideo-server node --version
+```
 
-# 更新镜像
-docker-compose pull
-docker-compose up -d
-
-# 清理容器
-docker-compose down
+### 镜像管理
 
-# 清理容器和数据卷
-docker-compose down -v
-```
+```bash
+# 查看所有镜像
+docker images
 
-## 配置说明
+# 删除镜像
+docker rmi mb-rrvideo-converter:latest
 
-### 端口映射
+# 清理未使用的镜像
+docker image prune -a
 
-默认映射 `24203:24203`，如需修改宿主机端口：
+# 查看镜像详细信息
+docker inspect mb-rrvideo-converter:latest
 
-```yaml
-ports:
-  - "8080:24203"  # 宿主机8080 -> 容器24203
+# 查看镜像构建历史
+docker history mb-rrvideo-converter:latest
 ```
 
-### 资源限制
+### 资源监控
 
-在 docker-compose.yml 中配置：
+```bash
+# 查看容器资源使用
+docker stats rrvideo-server
 
-```yaml
-deploy:
-  resources:
-    limits:
-      cpus: '4'
-      memory: 4G
-    reservations:
-      cpus: '2'
-      memory: 2G
+# 查看容器进程
+docker top rrvideo-server
+
+# 查看磁盘使用
+docker system df
 ```
 
-### 使用 MinIO 存储
+---
 
-修改 `config.json`：
+## 故障排除
 
-```json
-{
-  "storage": {
-    "type": "minio",
-    "minio": {
-      "endpoint": "minio.example.com",
-      "port": 9000,
-      "useSSL": true,
-      "accessKey": "your-access-key",
-      "secretKey": "your-secret-key",
-      "bucket": "videos",
-      "public_host": "https://cdn.example.com"
-    }
-  }
-}
+### 问题 1：服务无法启动
+
+**症状：**
+```bash
+docker-compose ps
+# 显示 Exit 1 或 Restarting
 ```
 
-## 故障排除
+**排查步骤：**
 
-### 服务无法启动
+1. 查看日志：
+```bash
+docker-compose logs
+```
 
-1. 检查配置文件是否存在：
+2. 检查配置文件：
 ```bash
-ls -la config.json
+cat config.json
+# 确保 JSON 格式正确
 ```
 
-2. 检查配置文件格式：
+3. 检查端口占用：
 ```bash
-cat config.json | jq .
+netstat -tlnp | grep 24203
+# 如果端口被占用，修改 docker-compose.yml 中的端口映射
 ```
 
-3. 查看容器日志：
+4. 检查目录权限：
 ```bash
-docker-compose logs
+ls -la logs/ temp/ Video/
+# 确保目录可写
 ```
 
-### 转码失败
+### 问题 2：转码失败
+
+**症状：**
+日志显示转码错误
+
+**排查步骤：**
 
 1. 检查 mb-rrvideo 是否正常：
 ```bash
 docker-compose exec rrvideo-server rrvideos --version
 ```
 
-2. 查看转码日志：
+2. 检查 Playwright 浏览器：
+```bash
+docker-compose exec rrvideo-server npx playwright install --dry-run chromium
+```
+
+3. 查看转码日志：
 ```bash
 tail -f logs/convert/$(date +%Y-%m-%d)/*.log
 ```
 
-### 内存不足
+4. 检查内存：
+```bash
+docker stats rrvideo-server
+# 如果内存不足，增加 docker-compose.yml 中的内存限制
+```
+
+### 问题 3：镜像构建失败
+
+**症状：**
+```bash
+docker build -t mb-rrvideo-converter:latest .
+# 报错或卡住
+```
+
+**解决方案：**
+
+1. 检查网络连接：
+```bash
+ping registry.npmmirror.com
+ping mirrors.aliyun.com
+```
+
+2. 配置 Docker 代理（如果在国外服务器）：
+```bash
+sudo mkdir -p /etc/systemd/system/docker.service.d
+sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<-'EOF'
+[Service]
+Environment="HTTP_PROXY=http://proxy.example.com:8080"
+Environment="HTTPS_PROXY=http://proxy.example.com:8080"
+Environment="NO_PROXY=localhost,127.0.0.1"
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+```
+
+3. 清理构建缓存：
+```bash
+docker builder prune -a
+```
+
+4. 重新构建：
+```bash
+docker build --no-cache -t mb-rrvideo-converter:latest .
+```
 
-增加容器内存限制：
+### 问题 4：容器内存不足
 
+**症状：**
+转码时容器被 OOM Kill
+
+**解决方案：**
+
+修改 `docker-compose.yml`：
 ```yaml
 deploy:
   resources:
     limits:
-      memory: 8G
+      memory: 8G  # 增加到 8GB
+    reservations:
+      memory: 4G
+```
+
+然后重启：
+```bash
+docker-compose down
+docker-compose up -d
+```
+
+### 问题 5：磁盘空间不足
+
+**症状：**
+```bash
+docker system df
+# 显示磁盘使用率很高
+```
+
+**解决方案：**
+
+1. 清理未使用的容器：
+```bash
+docker container prune
+```
+
+2. 清理未使用的镜像：
+```bash
+docker image prune -a
+```
+
+3. 清理构建缓存：
+```bash
+docker builder prune -a
 ```
 
-### 磁盘空间不足
+4. 清理数据卷：
+```bash
+docker volume prune
+```
 
-1. 启用自动删除：
+5. 启用自动删除转码后的文件：
 ```json
 {
   "convert": {
@@ -301,74 +840,205 @@ deploy:
 }
 ```
 
-2. 定期清理临时文件：
+---
+
+## 镜像优化说明
+
+### 镜像包含的完整组件
+
+Docker 镜像是**开箱即用**的，包含转码所需的所有组件：
+
+1. **Node.js 22**（运行环境）
+2. **PM2**（进程管理器，自动重启）
+3. **mb-rrvideo**（转码工具，全局安装）
+   - 命令：`rrvideos`
+   - 功能：将 rrweb 录屏数据转换为视频
+   - 自带 FFmpeg（无需额外安装）
+4. **mb-rrvideo-server**（转码服务，全局安装）
+   - 命令：`rrvideo-server`
+   - 功能：HTTP 服务，接收转码请求
+5. **Playwright Chromium**（浏览器）
+   - 功能：渲染 rrweb 录屏数据
+   - 大小：约 400MB
+6. **系统依赖**
+   - 字体库（支持中文）
+   - 图形库（Chromium 依赖）
+
+**验证所有组件：**
 ```bash
-docker-compose exec rrvideo-server rm -rf /app/temp/*
+docker-compose exec rrvideo-server bash
+
+# 检查 Node.js
+node --version
+
+# 检查 PM2
+pm2 --version
+
+# 检查 mb-rrvideo（转码工具）
+rrvideos --version
+
+# 检查 mb-rrvideo-server（转码服务）
+which rrvideo-server
+
+# 检查 Playwright
+npx playwright --version
+
+# 检查 FFmpeg（mb-rrvideo 自带）
+rrvideos --help | grep ffmpeg
 ```
 
-## 生产环境建议
+### 为什么镜像这么大？
+
+镜像大小约 **1.5GB**，主要组成：
+- **Node.js 22 基础镜像**：约 200MB
+- **系统依赖**：约 100MB
+- **Playwright Chromium**：约 400MB（转码必需）
+- **npm 包**：约 50MB
+- **其他**：约 750MB
 
-1. **使用持久化存储**：将 Video 目录挂载到独立磁盘
-2. **配置日志轮转**：避免日志文件过大
-3. **监控资源使用**：使用 Prometheus + Grafana
-4. **备份配置文件**：定期备份 config.json
-5. **使用私有镜像仓库**：提高部署速度和安全性
+### Playwright Chromium 是什么？
 
-## 更新服务
+mb-rrvideo 使用 Playwright 来渲染 rrweb 录屏数据，需要一个真实的浏览器环境。Chromium 是必需的，无法移除。
 
-### 更新到最新版本
+### 如何减小镜像大小？
 
+**方法 1：使用镜像压缩**
 ```bash
-# 拉取最新镜像
-docker-compose pull
+# 导出时压缩
+docker save mb-rrvideo-converter:latest | gzip > mb-rrvideo-converter.tar.gz
 
-# 重启服务
-docker-compose up -d
+# 压缩后约 600MB
+ls -lh mb-rrvideo-converter.tar.gz
+
+# 导入
+gunzip -c mb-rrvideo-converter.tar.gz | docker load
+```
+
+**方法 2：使用私有镜像仓库**
+
+搭建私有仓库后，只需传输一次镜像，后续所有服务器都可以快速拉取。
+
+**方法 3：分层构建（高级）**
+
+如果你有多个类似项目，可以创建一个基础镜像包含 Node.js + Playwright，然后在此基础上构建应用镜像。
+
+### 构建时间优化
+
+**首次构建**：10-20 分钟（取决于网络）
+**后续构建**：2-5 分钟（利用缓存）
+
+**加速技巧：**
+1. 使用国内镜像源（Dockerfile 已配置）
+2. 使用 Docker 镜像加速（见前置准备）
+3. 使用构建缓存：
+```bash
+# 不要使用 --no-cache，让 Docker 利用缓存
+docker build -t mb-rrvideo-converter:latest .
 ```
 
-### 回滚到旧版本
+### 网络传输优化
 
+**方法 1：使用压缩**
 ```bash
-# 修改 docker-compose.yml 中的镜像版本
-image: mb-rrvideo-server:1.0.1
+# 导出并压缩
+docker save mb-rrvideo-converter:latest | gzip > mb-rrvideo-converter.tar.gz
 
-# 重启服务
-docker-compose up -d
+# 传输（约 600MB）
+scp mb-rrvideo-converter.tar.gz user@target:/tmp/
+
+# 解压并导入
+gunzip -c mb-rrvideo-converter.tar.gz | docker load
 ```
 
-## 多实例部署
+**方法 2：使用 rsync 断点续传**
+```bash
+# 支持断点续传，网络不稳定时很有用
+rsync -avz --progress mb-rrvideo-converter.tar user@target:/tmp/
+```
 
-如需部署多个实例（负载均衡）：
+**方法 3：使用内网镜像仓库**
 
-```yaml
-version: '3.8'
+在内网搭建私有仓库，传输速度可达 100MB/s+。
 
-services:
-  rrvideo-server-1:
-    image: mb-rrvideo-server:latest
-    container_name: rrvideo-server-1
-    ports:
-      - "24203:24203"
-    volumes:
-      - ./config.json:/app/config/config.json:ro
-      - ./logs-1:/app/logs
-      - ./temp-1:/app/temp
-      - ./Video:/app/Video
-  
-  rrvideo-server-2:
-    image: mb-rrvideo-server:latest
-    container_name: rrvideo-server-2
-    ports:
-      - "24204:24203"
-    volumes:
-      - ./config.json:/app/config/config.json:ro
-      - ./logs-2:/app/logs
-      - ./temp-2:/app/temp
-      - ./Video:/app/Video
+---
+
+## 生产环境建议
+
+### 1. 资源配置
+
+**最低配置：**
+- CPU: 2 核
+- 内存: 4GB
+- 磁盘: 50GB
+
+**推荐配置：**
+- CPU: 4 核
+- 内存: 8GB
+- 磁盘: 100GB SSD
+
+### 2. 目录规划
+
+```bash
+/data/rrvideo/
+├── config.json          # 配置文件
+├── docker-compose.yml   # 容器配置
+├── logs/                # 日志（建议定期清理）
+├── temp/                # 临时文件（自动清理）
+├── Video/               # 视频输出（建议挂载独立磁盘）
+└── tasks/               # 任务数据
+```
+
+### 3. 日志管理
+
+```bash
+# 定期清理日志（添加到 crontab）
+0 2 * * * find /data/rrvideo/logs -name "*.log" -mtime +7 -delete
+```
+
+### 4. 监控告警
+
+使用 Prometheus + Grafana 监控容器资源：
+```bash
+# 安装 cAdvisor
+docker run -d \
+  --name=cadvisor \
+  --volume=/:/rootfs:ro \
+  --volume=/var/run:/var/run:ro \
+  --volume=/sys:/sys:ro \
+  --volume=/var/lib/docker/:/var/lib/docker:ro \
+  --publish=8080:8080 \
+  google/cadvisor:latest
+```
+
+### 5. 备份策略
+
+```bash
+# 备份配置文件
+cp config.json config.json.bak.$(date +%Y%m%d)
+
+# 备份镜像
+docker save mb-rrvideo-converter:latest -o mb-rrvideo-server-backup.tar
 ```
 
-## 技术支持
+---
+
+## 更多资源
+
+- **npm 包**: https://www.npmjs.com/package/mb-rrvideo-server
+- **使用文档**: README.md
+- **更新日志**: CHANGELOG.md
+- **问题反馈**: GitHub Issues
+
+---
+
+## 总结
+
+本文档涵盖了从零开始部署 mb-rrvideo-server 的所有内容：
+
+1. ✅ Docker 基础概念和安装
+2. ✅ 三种部署方式（npm 包、源码、镜像迁移）
+3. ✅ 镜像迁移的三种方法（文件传输、私有仓库、公有仓库）
+4. ✅ 常用命令和故障排除
+5. ✅ 镜像优化和生产环境建议
 
-- GitHub Issues: <repository-url>
-- 文档: README.md
-- 更新日志: CHANGELOG.md
+如有问题，请查看故障排除章节或提交 Issue。

package/Dockerfile

@@ -13,7 +13,14 @@ ENV TZ=Asia/Shanghai \
     PLAYWRIGHT_BROWSERS_PATH=/root/.cache/ms-playwright
 
 # ============================================
-# 第一步：安装系统依赖
+# 第一步：配置国内镜像源（加速构建）
+# ============================================
+# 使用阿里云 Debian 镜像源
+RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources && \
+    sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+
+# ============================================
+# 第二步：安装系统依赖
 # ============================================
 RUN apt-get update && apt-get install -y \
     # 基础工具
@@ -44,26 +51,47 @@ RUN apt-get update && apt-get install -y \
     && rm -rf /var/lib/apt/lists/*
 
 # ============================================
-# 第二步：配置 npm 国内镜像源（加速安装）
+# 第三步：配置 npm 国内镜像源（加速安装）
 # ============================================
 RUN npm config set registry https://registry.npmmirror.com
 
 # ============================================
-# 第三步：全局安装 Node.js 包
+# 第四步：全局安装 PM2
+# ============================================
+RUN npm install -g pm2 && npm cache clean --force
+
+# ============================================
+# 第五步：安装本地依赖包 (mb-rrvideo)
+# 方案：直接使用源码在容器内编译安装
+# 前置条件：构建前由 server-run.sh 脚本将 ../mb-rrvideo 复制到 ./_deps/mb-rrvideo
+# ============================================
+COPY _deps/mb-rrvideo /tmp/mb-rrvideo
+RUN cd /tmp/mb-rrvideo && \
+    # 安装依赖（包含 devDependencies 以便执行 build）
+    npm install && \
+    # 编译 TypeScript
+    npm run build && \
+    # 全局安装
+    npm install -g . && \
+    # 清理源码和缓存
+    cd / && rm -rf /tmp/mb-rrvideo && npm cache clean --force
+
+# ============================================
+# 第六步：复制项目源码并安装
 # ============================================
-RUN npm install -g \
-    pm2 \
-    mb-rrvideo \
-    mb-rrvideo-server \
-    && npm cache clean --force
+WORKDIR /app
+COPY . /app
+
+# 安装当前项目依赖并链接命令
+RUN npm install -g . && npm cache clean --force
 
 # ============================================
-# 第四步：安装 Playwright 浏览器（Chromium）
+# 第七步：安装 Playwright 浏览器（Chromium）
 # ============================================
 RUN npx playwright install chromium
 
 # ============================================
-# 第五步：创建应用目录
+# 第八步：创建应用目录
 # ============================================
 RUN mkdir -p /app/config \
     && mkdir -p /app/logs \
@@ -72,27 +100,22 @@ RUN mkdir -p /app/config \
     && mkdir -p /app/tasks
 
 # ============================================
-# 第六步：复制 PM2 配置文件
+# 第九步：复制 PM2 配置文件
 # ============================================
 COPY ecosystem.docker.config.js /app/ecosystem.config.js
 
 # ============================================
-# 第七步：设置工作目录
-# ============================================
-WORKDIR /app
-
-# ============================================
-# 第八步：暴露端口
+# 第十步：暴露端口
 # ============================================
 EXPOSE 24203
 
 # ============================================
-# 第九步：健康检查
+# 第十一步：健康检查
 # ============================================
 HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
     CMD curl -f http://localhost:24203/health || exit 1
 
 # ============================================
-# 第十步：启动服务
+# 第十二步：启动服务
 # ============================================
 CMD ["pm2-runtime", "start", "ecosystem.config.js"]

package/README.md

@@ -31,19 +31,33 @@ npm install
 ```
 
 ### 4. Docker 部署（推荐生产环境）
+
+Docker 镜像**开箱即用**，包含所有依赖（Node.js + mb-rrvideo + mb-rrvideo-server + Playwright）。
+
 ```bash
+# 下载 npm 包
+npm pack mb-rrvideo-server
+tar -xzf mb-rrvideo-server-*.tgz
+cd package
+
 # 准备配置文件
 cp config.example.json config.json
 # 编辑 config.json
 
+# 构建镜像（镜像名：mb-rrvideo-converter）
+docker build -t mb-rrvideo-converter:latest .
+
 # 启动服务
 docker-compose up -d
 
+# 验证 mb-rrvideo 是否正常
+docker-compose exec rrvideo-server rrvideos --version
+
 # 查看日志
 docker-compose logs -f
 ```
 
-详细的 Docker 部署指南请查看 [DOCKER.md](DOCKER.md)
+详细的 Docker 部署指南（包括镜像迁移、故障排除等）请查看 [DOCKER.md](https://www.npmjs.com/package/mb-rrvideo-server?activeTab=code)
 
 ## 配置
 

package/docker-compose.yml

@@ -3,7 +3,7 @@ version: '3.8'
 services:
   rrvideo-server:
     build: .
-    image: mb-rrvideo-server:latest
+    image: mb-rrvideo-converter:latest
     container_name: rrvideo-server
     restart: unless-stopped
     

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mb-rrvideo-server",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "视频转码服务 - 接收可回溯机请求，执行转码/合并，上传MinIO/本地存储",
   "main": "src/index.js",
   "bin": {