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

用户59913033478
1 阅读12分钟

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 相关文件主要分布在以下几个关键位置：

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：

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 反向代理实现完整的功能：

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 反向代理服务：

多服务架构
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
环境变量配置

网络配置

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

网络拓扑
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 端口
  • 两个服务共享同一个自定义网络

应用配置管理

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

关键配置项
配置项默认值用途环境变量
草稿下载URLhttp://127.0.0.1/openapi/capcut-mate/v1/get_draft草稿下载接口DRAFT_URL
下载URL前缀http://127.0.0.1/文件URL生成DOWNLOAD_URL
提示URLdocs.jcaigc.cn（**已更新**）帮助文档链接TIP_URL
文件下载大小限制200MB (209,715,200字节)文件大小限制DOWNLOAD_FILE_SIZE_LIMIT
配置加载机制
flowchart LR
A[环境变量] --> B{是否存在?}
B --> |是| C[使用环境变量值]
B --> |否| D[使用默认配置]
C --> E[应用配置]
D --> E

草稿下载服务

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

下载流程
flowchart TD
A[接收草稿URL] --> B[提取草稿ID]
B --> C[准备目标目录]
C --> D[获取文件列表]
D --> E[下载所有文件]
E --> F[更新JSON路径]
F --> G[触发剪映扫描]
H[错误处理] --> I[重试机制]
I --> J[日志记录]
文件处理特性
  • 原子写入: 使用 O_EXCL 标志确保文件写入的原子性
  • 路径转换: 自动将远程路径转换为本地路径
  • 重试机制: 网络请求失败时自动重试
  • 进度监控: 详细的下载进度和状态记录

依赖关系分析

构建流程依赖

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 字节）。这一功能有效防止大文件下载对系统资源造成压力，提升系统的稳定性和安全性。

配置实现

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

# 本地开发配置
- DOWNLOAD_FILE_SIZE_LIMIT=209715200  # 200MB
应用层配置
# 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
下载过程中的限制检查
# 在下载过程中实时检查文件大小
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]
[project.optional-dependencies]
windows = [
    "pywin32>=311; sys_platform == 'win32'",
    "uiautomation>=2.0.29; sys_platform == 'win32'",
]
运行时平台检测
# 平台检查和依赖导入
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）平衡了功能需求和系统性能
  • 灵活调整: 支持根据实际需求调整限制值

故障排除指南

常见问题诊断

端口冲突

症状: 容器启动失败，显示端口占用 解决方案:

# 检查端口占用
netstat -ano | findstr 30000
netstat -ano | findstr 80

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

症状: 文件写入失败，权限不足 解决方案:

# 检查挂载目录权限
ls -la ./output

# 确保目录可写
chmod 755 ./output
网络连接问题

症状: 草稿下载超时或失败 解决方案:

# 检查网络连通性
curl -I http://127.0.0.1/openapi/capcut-mate/v1/get_draft

# 验证服务状态
docker-compose ps

# 检查防火墙设置
ufw status
文件大小限制问题

症状: 下载大文件时报错 "FILE_SIZE_LIMIT_EXCEEDED" 解决方案:

# 调整 DOWNLOAD_FILE_SIZE_LIMIT 环境变量
# 例如：设置为 500MB
DOWNLOAD_FILE_SIZE_LIMIT=524288000

# 或者禁用限制（不推荐）
DOWNLOAD_FILE_SIZE_LIMIT=0
TIP_URL 访问问题

症状: 帮助文档无法访问 解决方案:

# 检查 TIP_URL 配置
# 默认值: https://docs.jcaigc.cn

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

跨平台兼容性问题

Windows 依赖缺失

症状: 在非 Windows 平台运行时出现 ImportError 解决方案:

# 非 Windows 平台正常运行（无剪映自动化功能）
pip install capcut-mate

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

日志分析

容器日志
# 查看容器日志
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 接口：

# 示例日志输出
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
文件下载限制日志

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

# 文件大小限制错误示例
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 配置正确，便于用户获取帮助

附录

部署命令参考

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

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

# 查看运行状态
docker-compose ps
本地开发部署
# 启动本地开发环境
docker-compose up -d

# 查看服务状态
docker-compose ps

# 停止服务
docker-compose down
快速部署（推荐）

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

# 克隆项目并一键部署
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

配置文件模板

环境变量配置
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
存储配置
volumes:
  # 生产环境
  - ./output:/app/output
  # 本地开发
  - ./output:/app/www/output
  # 时区配置
  - /etc/localtime:/etc/localtime:ro
  - /etc/timezone:/etc/timezone:ro

跨平台安装指南

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

# 或使用 Docker
docker run -d -p 30000:30000 gogoshine/capcut-mate:latest
Windows 平台
# 完整安装（包含剪映自动化功能）
pip install capcut-mate[windows]

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

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

调整限制值
# 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 中的环境变量
  • 访问方式: 用户可以通过应用界面访问帮助文档链接

附件

avatar
文章
阅读
粉丝