# Docker 部署
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [文件下载大小限制功能](#文件下载大小限制功能)
8. [跨平台兼容性改进](#跨平台兼容性改进)
9. [性能考虑](#性能考虑)
10. [故障排除指南](#故障排除指南)
11. [结论](#结论)
12. [附录](#附录)

## 简介

capcut-mate 是一个基于 Python FastAPI 的视频编辑辅助工具，提供了丰富的视频处理和草稿管理功能。本文档详细介绍如何使用 Docker 对该应用进行容器化部署，包括多阶段构建策略、镜像优化技巧、服务编排配置以及生产环境的最佳实践。

该应用支持多种视频处理功能，包括音频添加、字幕生成、特效应用、贴纸添加等，同时提供了草稿下载和管理能力。通过 Docker 容器化部署，可以实现环境隔离、资源控制和快速扩展。

**重要更新**：项目现已实现跨平台兼容性改进，Windows 特定依赖（pywin32、uiautomation）已移至可选依赖组[windows]，解决了 Docker 容器打包失败问题。现在可以在非 Windows 平台安装和运行，同时保留 Windows 平台的完整功能。

**新增功能**：系统现已集成文件下载大小限制功能，通过 DOWNLOAD_FILE_SIZE_LIMIT 环境变量控制文件下载的最大大小，默认值为 200MB（209,715,200 字节），有效防止大文件下载对系统资源造成压力。

：TIP_URL 环境变量已更新为指向官方文档站点 `https://docs.jcaigc.cn`，为用户提供更好的帮助文档访问体验。

## 项目结构

capcut-mate 项目的 Docker 相关文件主要分布在以下几个关键位置：

```mermaid
graph TB
subgraph "Docker 配置文件"
A[Dockerfile] --> B[基础镜像构建]
C[docker-compose.yaml] --> D[生产环境配置]
E[docker-compose.example.yaml] --> F[示例配置模板]
end
subgraph "核心应用文件"
G[main.py] --> H[FastAPI 应用入口]
I[config.py] --> J[配置管理]
K[pyproject.toml] --> L[依赖管理]
M[download.py] --> N[文件下载服务]
end
subgraph "工作流配置"
O[dev.yml] --> P[CI/CD 流水线]
end
A --> G
C --> G
E --> G
M --> N
```


## 核心组件

### Dockerfile 分析

capcut-mate 使用了精简的 Python 3.11 slim 基础镜像作为构建基础，采用了现代化的依赖管理工具 uv：

```mermaid
flowchart TD
A[基础镜像: python:3.11-slim] --> B[安装 uv 工具]
B --> C[设置工作目录 /app]
C --> D[创建非root用户]
D --> E[复制 dist 目录]
E --> F[安装生产依赖]
F --> G[设置环境变量]
G --> H[配置启动命令]
I[优化特性] --> J[多阶段构建]
J --> K[缓存优化]
K --> L[安全用户]
```


### 依赖管理策略

项目使用 uv 作为包管理器，相比传统的 pip 具有以下优势：
- 更快的安装速度
- 更好的依赖解析
- 更精确的版本锁定
- 支持增量安装


## 架构概览

capcut-mate 的 Docker 部署采用多服务架构，结合 Nginx 反向代理实现完整的功能：

```mermaid
graph TB
subgraph "容器层"
A[capcut-mate 容器] --> B[FastAPI 应用]
B --> C[草稿下载服务]
C --> D[文件系统]
E[Nginx 服务器] --> F[静态文件服务]
F --> G[输出目录文件]
end
subgraph "外部服务"
H[剪映客户端] --> I[草稿管理]
end
subgraph "存储层"
J[持久化卷] --> K[输出目录]
L[时区配置] --> M[系统时间]
end
A -.-> E
A -.-> H
A -.-> J
E -.-> J
```


## 详细组件分析

### 生产环境部署配置

生产环境使用 docker-compose.yaml 进行部署，现已合并了 Nginx 反向代理服务：

#### 多服务架构
```mermaid
sequenceDiagram
participant Client as 客户端
participant Nginx as Nginx 服务器
participant App as capcut-mate 应用
participant FS as 文件系统
Client->>Nginx : HTTP 请求
Nginx->>App : 反向代理
App->>FS : 访问输出文件
FS-->>App : 返回文件内容
App-->>Nginx : 响应数据
Nginx-->>Client : 最终响应
```


#### 端口和服务配置
- **应用服务 (capcut-mate)**:
  - 端口映射: 30000:30000 (应用端口)
  - 网络配置: 使用自定义网络 `capcut-mate-network`
  - 资源限制: 内存 2GB，CPU 2 个核心，OOM 保护
- **Nginx 服务 (linux)**:
  - 端口映射: 80:80 (HTTP 服务)
  - 网络配置: 使用相同网络 `capcut-mate-network`
  - 资源限制: 内存 2GB，CPU 2.0 个核心，OOM 保护

#### 数据持久化配置
- **应用服务**:
  - 输出目录挂载: `./output:/app/output`
  - 时区同步: 挂载 `/etc/localtime` 和 `/etc/timezone`
- **Nginx 服务**:
  - 输出目录挂载: `./output:/app/www/output`

#### 环境变量配置
- **应用服务**:
  - DRAFT_URL: http://127.0.0.1/openapi/capcut-mate/v1/get_draft
  - DOWNLOAD_URL: http://127.0.0.1/
  - TIP_URL: https://docs.jcaigc.cn（**已更新**）
  - DOWNLOAD_FILE_SIZE_LIMIT: 209,715,200 字节（200MB）
- **Nginx 服务**:
  - 使用静态文件服务提供输出目录访问


### 网络配置

项目使用自定义桥接网络实现容器间通信：

#### 网络拓扑
```mermaid
graph TB
subgraph "capcut-mate-network"
A[capcut-mate 容器] --> B[应用服务]
C[linux 容器] --> D[Nginx 服务]
end
subgraph "外部访问"
E[宿主机] --> F[端口 80 -> Nginx]
G[宿主机] --> H[端口 30000 -> 应用]
end
A -.-> C
C -.-> A
```


#### 服务通信
- 容器间通过服务名进行通信
- capcut-mate 服务监听 30000 端口
- Nginx 服务监听 80 端口
- 两个服务共享同一个自定义网络


### 应用配置管理

应用通过环境变量进行配置管理，支持动态配置：

#### 关键配置项
| 配置项 | 默认值 | 用途 | 环境变量 |
|--------|--------|------|----------|
| 草稿下载URL | http://127.0.0.1/openapi/capcut-mate/v1/get_draft | 草稿下载接口 | DRAFT_URL |
| 下载URL前缀 | http://127.0.0.1/ | 文件URL生成 | DOWNLOAD_URL |
| 提示URL | https://docs.jcaigc.cn（**已更新**） | 帮助文档链接 | TIP_URL |
| 文件下载大小限制 | 200MB (209,715,200字节) | 文件大小限制 | DOWNLOAD_FILE_SIZE_LIMIT |

#### 配置加载机制
```mermaid
flowchart LR
A[环境变量] --> B{是否存在?}
B --> |是| C[使用环境变量值]
B --> |否| D[使用默认配置]
C --> E[应用配置]
D --> E
```


### 草稿下载服务

应用集成了强大的草稿下载功能，支持多种媒体类型的处理：

#### 下载流程
```mermaid
flowchart TD
A[接收草稿URL] --> B[提取草稿ID]
B --> C[准备目标目录]
C --> D[获取文件列表]
D --> E[下载所有文件]
E --> F[更新JSON路径]
F --> G[触发剪映扫描]
H[错误处理] --> I[重试机制]
I --> J[日志记录]
```


#### 文件处理特性
- **原子写入**: 使用 O_EXCL 标志确保文件写入的原子性
- **路径转换**: 自动将远程路径转换为本地路径
- **重试机制**: 网络请求失败时自动重试
- **进度监控**: 详细的下载进度和状态记录


## 依赖关系分析

### 构建流程依赖

```mermaid
graph TB
subgraph "构建阶段"
A[GitHub Actions] --> B[准备代码]
B --> C[安装 uv]
C --> D[同步依赖]
D --> E[准备 dist 目录]
E --> F[构建 Docker 镜像]
end
subgraph "运行时依赖"
G[Python 3.11] --> H[FastAPI 框架]
H --> I[uvicorn ASGI 服务器]
I --> J[媒体处理库]
end
F --> G
```


### 依赖管理策略

项目采用分层依赖管理：

#### 生产依赖
- **Web 框架**: FastAPI (高性能异步 Web 框架)
- **ASGI 服务器**: Uvicorn (标准 ASGI 服务器)
- **媒体处理**: PyMediaInfo (多媒体信息提取)
- **网络请求**: Requests (HTTP 客户端库)

#### 可选依赖（跨平台兼容性改进）
- **Windows 支持**: pywin32 (Windows API 访问) - 可选依赖组 [windows]
- **自动化**: UIAutomation (UI 自动化测试) - 可选依赖组 [windows]
- **云存储**: COS Python SDK (腾讯云对象存储)

**重要更新**：Windows 特定依赖已移至可选依赖组 [windows]，允许在非 Windows 平台正常安装和运行应用。


## 文件下载大小限制功能

### 功能概述

系统现已集成文件下载大小限制功能，通过 DOWNLOAD_FILE_SIZE_LIMIT 环境变量控制文件下载的最大大小，默认值为 200MB（209,715,200 字节）。这一功能有效防止大文件下载对系统资源造成压力，提升系统的稳定性和安全性。

### 配置实现

#### 环境变量配置
```yaml
# 生产环境配置
- DOWNLOAD_FILE_SIZE_LIMIT=209715200  # 200MB

# 本地开发配置
- DOWNLOAD_FILE_SIZE_LIMIT=209715200  # 200MB
```

#### 应用层配置
```python
# config.py 中的配置
DOWNLOAD_FILE_SIZE_LIMIT = int(os.getenv("DOWNLOAD_FILE_SIZE_LIMIT", str(200 * 1024 * 1024)))

# download.py 中的使用
DEFAULT_FILE_SIZE_LIMIT = config.DOWNLOAD_FILE_SIZE_LIMIT
```

#### 下载过程中的限制检查
```python
# 在下载过程中实时检查文件大小
if downloaded_size > limit:
    raise CustomException(
        CustomError.FILE_SIZE_LIMIT_EXCEEDED,
        detail=f"{limit / 1024 / 1024:.2f} MB"
    )
```

### 功能特性

#### 实时监控
- **实时大小检查**: 下载过程中持续监控文件大小
- **精确限制**: 基于字节的精确大小限制
- **异常处理**: 超限时抛出 FILE_SIZE_LIMIT_EXCEEDED 异常

#### 灵活配置
- **环境变量驱动**: 支持通过环境变量动态调整限制
- **默认值设置**: 提供合理的默认值（200MB）
- **单位换算**: 支持不同单位的配置（字节、KB、MB）

#### 错误处理
- **清晰的错误信息**: 显示具体的限制值和当前状态
- **优雅降级**: 超限时停止下载并返回错误
- **日志记录**: 详细记录限制检查过程


## 跨平台兼容性改进

### Windows 依赖分离

项目已实现重要的跨平台兼容性改进：

#### 可选依赖组 [windows]
```toml
[project.optional-dependencies]
windows = [
    "pywin32>=311; sys_platform == 'win32'",
    "uiautomation>=2.0.29; sys_platform == 'win32'",
]
```

#### 运行时平台检测
```python
# 平台检查和依赖导入
if sys.platform != "win32":
    raise ImportError("JianyingController is only available on Windows platform")
```

#### 功能完整性保障
- **非 Windows 平台**: 可以正常安装和运行，但剪映自动化功能不可用
- **Windows 平台**: 完整功能，包括剪映自动化导出
- **可选安装**: Windows 用户可通过 `pip install capcut-mate[windows]` 获取完整功能


## 性能考虑

### 容器资源优化

#### 内存和 CPU 限制
- **内存限制**: 2GB，防止内存泄漏导致系统不稳定
- **CPU 限制**: 2 个核心，确保系统资源合理分配
- **OOM 保护**: 调整 oom_score_adj=-500，降低被 OOM Killer 杀死的风险

#### 启动参数优化
- **工作进程**: --workers 4，利用多核 CPU 并行处理
- **缓冲控制**: PYTHONUNBUFFERED=1，确保日志实时输出
- **路径优化**: 自动添加 /app/.venv/bin 到 PATH

### 网络性能优化

#### 端口配置
- **应用端口**: 30000/TCP，避免与系统常用端口冲突
- **反向代理**: Nginx 提供静态文件服务和负载均衡

#### 文件访问优化
- **直接挂载**: 输出目录直接挂载到宿主机，避免容器内文件复制
- **只读挂载**: 时区文件使用 ro 模式，提高安全性

### 文件下载优化

#### 大小限制优化
- **资源保护**: 通过 DOWNLOAD_FILE_SIZE_LIMIT 防止大文件占用过多资源
- **性能提升**: 合理的默认值（200MB）平衡了功能需求和系统性能
- **灵活调整**: 支持根据实际需求调整限制值

## 故障排除指南

### 常见问题诊断

#### 端口冲突
**症状**: 容器启动失败，显示端口占用
**解决方案**:
```bash
# 检查端口占用
netstat -ano | findstr 30000
netstat -ano | findstr 80

# 修改 docker-compose.yaml 中的端口映射
ports:
  - "30001:30000"  # 应用端口
  - "8080:80"      # Nginx 端口
```

#### 权限问题
**症状**: 文件写入失败，权限不足
**解决方案**:
```bash
# 检查挂载目录权限
ls -la ./output

# 确保目录可写
chmod 755 ./output
```

#### 网络连接问题
**症状**: 草稿下载超时或失败
**解决方案**:
```bash
# 检查网络连通性
curl -I http://127.0.0.1/openapi/capcut-mate/v1/get_draft

# 验证服务状态
docker-compose ps

# 检查防火墙设置
ufw status
```

#### 文件大小限制问题
**症状**: 下载大文件时报错 "FILE_SIZE_LIMIT_EXCEEDED"
**解决方案**:
```bash
# 调整 DOWNLOAD_FILE_SIZE_LIMIT 环境变量
# 例如：设置为 500MB
DOWNLOAD_FILE_SIZE_LIMIT=524288000

# 或者禁用限制（不推荐）
DOWNLOAD_FILE_SIZE_LIMIT=0
```

#### TIP_URL 访问问题
**症状**: 帮助文档无法访问
**解决方案**:
```bash
# 检查 TIP_URL 配置
# 默认值: https://docs.jcaigc.cn

# 在 docker-compose.yaml 中验证配置
environment:
  - TIP_URL=https://docs.jcaigc.cn
```

### 跨平台兼容性问题

#### Windows 依赖缺失
**症状**: 在非 Windows 平台运行时出现 ImportError
**解决方案**:
```bash
# 非 Windows 平台正常运行（无剪映自动化功能）
pip install capcut-mate

# Windows 平台完整安装
pip install capcut-mate[windows]
```

### 日志分析

#### 容器日志
```bash
# 查看容器日志
docker-compose logs -f capcut-mate
docker-compose logs -f linux

# 查看最近的日志条目
docker-compose logs --tail 100 capcut-mate

# 实时查看日志
docker-compose logs -f --since "5m" capcut-mate
```

#### 应用日志
应用会在启动时打印所有注册的路由信息，便于调试 API 接口：

```python
# 示例日志输出
Route: GET,POST PUT,DELETE /openapi/capcut-mate/v1/add_audios -> add_audios
Route: GET,POST PUT,DELETE /openapi/capcut-mate/v1/add_captions -> add_captions
```

#### 文件下载限制日志
当触发文件大小限制时，系统会记录详细的错误信息：

```python
# 文件大小限制错误示例
CustomError.FILE_SIZE_LIMIT_EXCEEDED: 200.00 MB
```


## 结论

capcut-mate 的 Docker 容器化部署提供了完整、可靠的视频处理服务解决方案。通过合理的镜像构建策略、资源配置和网络设计，实现了高性能、高可用的应用部署。

### 主要优势

1. **环境一致性**: Docker 确保开发、测试和生产环境的一致性
2. **资源控制**: 通过内存和 CPU 限制，防止资源滥用
3. **快速部署**: 多服务架构简化了部署流程
4. **数据持久化**: 通过卷挂载确保数据安全和持久性
5. **扩展性**: 支持水平扩展和负载均衡
6. **跨平台兼容**: 现已支持非 Windows 平台运行
7. **资源保护**: 新增的文件下载大小限制功能有效防止资源滥用
8. **反向代理**: Nginx 提供静态文件服务和负载均衡
9. **官方文档支持**: TIP_URL 已更新为官方文档站点，提供更好的用户体验

### 最佳实践建议

1. **生产环境**: 使用 docker-compose.yaml 进行生产部署
2. **开发环境**: 使用相同的 docker-compose.yaml 进行本地开发
3. **监控**: 配置适当的日志和监控系统
4. **备份**: 定期备份输出目录和配置文件
5. **安全**: 使用只读挂载和最小权限原则
6. **跨平台**: 根据目标平台选择合适的依赖安装方式
7. **资源管理**: 根据实际需求调整 DOWNLOAD_FILE_SIZE_LIMIT 设置
8. **网络配置**: 确保自定义网络正确配置和访问
9. **文档访问**: 确保 TIP_URL 配置正确，便于用户获取帮助

## 附录

### 部署命令参考

#### 生产环境部署
```bash
# 拉取最新镜像
docker pull gogoshine/capcut-mate:latest

# 启动生产环境
docker-compose up -d

# 查看运行状态
docker-compose ps
```

#### 本地开发部署
```bash
# 启动本地开发环境
docker-compose up -d

# 查看服务状态
docker-compose ps

# 停止服务
docker-compose down
```

#### 快速部署（推荐）
：基于 README.md 的优化，推荐使用一键部署命令：

```bash
# 克隆项目并一键部署
git clone https://github.com/Hommy-master/capcut-mate.git
cd capcut-mate
docker-compose pull && docker-compose up -d

# 部署后访问 API 文档
# http://localhost:30000/docs
```

### 配置文件模板

#### 环境变量配置
```yaml
environment:
  # 草稿下载URL（本地开发模式）
  DRAFT_URL: http://127.0.0.1/openapi/capcut-mate/v1/get_draft
  # 文件下载URL前缀（本地开发模式）
  DOWNLOAD_URL: http://127.0.0.1/
  # 帮助文档URL（**已更新**）
  TIP_URL: https://docs.jcaigc.cn
  # 文件下载大小限制（字节），默认200MB（209715200）
  DOWNLOAD_FILE_SIZE_LIMIT: 209715200
```

#### 存储配置
```yaml
volumes:
  # 生产环境
  - ./output:/app/output
  # 本地开发
  - ./output:/app/www/output
  # 时区配置
  - /etc/localtime:/etc/localtime:ro
  - /etc/timezone:/etc/timezone:ro
```

### 跨平台安装指南

#### 非 Windows 平台
```bash
# 基础安装（无剪映自动化功能）
pip install capcut-mate

# 或使用 Docker
docker run -d -p 30000:30000 gogoshine/capcut-mate:latest
```

#### Windows 平台
```bash
# 完整安装（包含剪映自动化功能）
pip install capcut-mate[windows]

# 或使用 Docker（Windows 专用）
docker run -d -p 30000:30000 gogoshine/capcut-mate-windows:latest
```

### 文件下载大小限制配置示例

#### 调整限制值
```yaml
# 500MB 限制
- DOWNLOAD_FILE_SIZE_LIMIT: 524288000

# 1GB 限制
- DOWNLOAD_FILE_SIZE_LIMIT: 1073741824

# 禁用限制（不推荐）
- DOWNLOAD_FILE_SIZE_LIMIT: 0
```

#### 单位换算参考
- 1MB = 1,048,576 字节
- 200MB = 209,715,200 字节
- 500MB = 524,288,000 字节
- 1GB = 1,073,741,824 字节

### TIP_URL 配置说明

：TIP_URL 环境变量已更新为官方文档站点：

- **默认值**: `https://docs.jcaigc.cn`
- **用途**: 为用户提供帮助文档和使用指南
- **配置位置**:
  - 应用层: `config.py` 中的 `TIP_URL = os.getenv("TIP_URL", "https://docs.jcaigc.cn/")`
  - Docker 配置: `docker-compose.yaml` 和 `docker-compose.example.yaml` 中的环境变量
- **访问方式**: 用户可以通过应用界面访问帮助文档链接

### 附件
- 接口文档： docs.jcaigc.cn
- 效果案例： www.jcaigc.cn/workflow
- 开源仓库： capcut-mate


capcut-mate 是一个基于 Python FastAPI 的视频编辑辅助工具，提供了丰富的视频处理和草稿管理功能。本文档详细介绍如何使用 Docker 对该应用进行容器化部署，包括多阶段构建策略、镜像优化技巧、服务编排配置以及生产环境的最佳实践。

【开源剪映小助手】Docker 部署

云计算

音视频

开发工具

Capcut-mate是基于Python FastAPI的视频编辑辅助工具，支持Docker容器化部署，提供音频添加、字幕生成等丰富功能。新增跨平台兼容性改进和文件下载大小限制功能，优化性能与稳定性。包含Nginx反向代理和多阶段构建策略，适合生产环境部署。

日志分析

负载均衡

包管理器

文件系统

数据安全

对象存储

媒体处理

服务器

防火墙

云存储

Windows

容器

Docker

路由

JSON

2026采购季 | AI焕新·智启新局

4核4G3M云服务器 新用户低至38元/年！

对象存储COS新用户低至1元！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【开源剪映小助手】Docker 部署-腾讯云开发者社区-腾讯云

【开源剪映小助手】Docker 部署

【开源剪映小助手】Docker 部署

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐