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

Docker 部署

简介

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 相关文件主要分布在以下几个关键位置：
核心应用文件
Docker 配置文件
工作流配置
dev.yml
CI/CD 流水线
Dockerfile
基础镜像构建
docker-compose.yaml
生产环境配置
docker-compose.example.yaml
示例配置模板
main.py
FastAPI 应用入口
config.py
配置管理
pyproject.toml
依赖管理
download.py
文件下载服务

核心组件

Dockerfile 分析

capcut-mate 使用了精简的 Python 3.11 slim 基础镜像作为构建基础，采用了现代化的依赖管理工具 uv：
基础镜像: python:3.11-slim
安装 uv 工具
设置工作目录 /app
创建非root用户
复制 dist 目录
安装生产依赖
设置环境变量
配置启动命令
优化特性
多阶段构建
缓存优化
安全用户

依赖管理策略

项目使用 uv 作为包管理器，相比传统的 pip 具有以下优势：

更快的安装速度
更好的依赖解析
更精确的版本锁定
支持增量安装

架构概览

capcut-mate 的 Docker 部署采用多服务架构，结合 Nginx 反向代理实现完整的功能：
存储层
外部服务
容器层
capcut-mate 容器
FastAPI 应用
草稿下载服务
文件系统
Nginx 服务器
静态文件服务
输出目录文件
剪映客户端
草稿管理
持久化卷
输出目录
时区配置
系统时间

详细组件分析

生产环境部署配置

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

多服务架构

文件系统 capcut-mate 应用 Nginx 服务器客户端文件系统 capcut-mate 应用 Nginx 服务器客户端 HTTP 请求反向代理访问输出文件返回文件内容响应数据最终响应

端口和服务配置

应用服务 (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 服务 :
- 使用静态文件服务提供输出目录访问

网络配置

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

网络拓扑

外部访问
宿主机
端口 80 -> Nginx
宿主机
端口 30000 -> 应用
capcut-mate-network
capcut-mate 容器
应用服务
linux 容器
Nginx 服务

服务通信

容器间通过服务名进行通信
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

配置加载机制

是
否
环境变量
是否存在?
使用环境变量值
使用默认配置
应用配置

草稿下载服务

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

下载流程

接收草稿URL
提取草稿ID
准备目标目录
获取文件列表
下载所有文件
更新JSON路径
触发剪映扫描
错误处理
重试机制
日志记录

文件处理特性

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

依赖关系分析

构建流程依赖

运行时依赖
构建阶段
GitHub Actions
准备代码
安装 uv
同步依赖
准备 dist 目录
构建 Docker 镜像
Python 3.11
FastAPI 框架
uvicorn ASGI 服务器
媒体处理库

依赖管理策略

项目采用分层依赖管理：

生产依赖

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

主要优势

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

最佳实践建议

生产环境: 使用 docker-compose.yaml 进行生产部署
开发环境: 使用相同的 docker-compose.yaml 进行本地开发
监控: 配置适当的日志和监控系统
备份: 定期备份输出目录和配置文件
安全: 使用只读挂载和最小权限原则
跨平台: 根据目标平台选择合适的依赖安装方式
资源管理: 根据实际需求调整 DOWNLOAD_FILE_SIZE_LIMIT 设置
网络配置: 确保自定义网络正确配置和访问
文档访问: 确保 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