生产环境部署
目录
简介
本指南面向 capcut-mate 本地开发环境部署与使用，提供简单易懂的部署步骤和配置说明。文档基于仓库现有的开发模式进行整理，重点介绍如何在本地快速启动和使用该视频编辑自动化工具。
项目结构
capcut-mate 是一个基于 Python/FastAPI 的本地开发工具，提供 CapCut 草稿管理、视频生成、素材处理等能力。项目采用简洁的单机部署模式，通过 Docker 容器化部署，支持本地开发和测试使用。
graph TB
A["应用入口<br/>main.py"] --> B["路由注册<br/>router/v1.py"]
A --> C["中间件<br/>middlewares/*"]
A --> D["服务层<br/>service/*"]
D --> E["工具模块<br/>utils/*"]
E --> F["日志<br/>logger.py"]
E --> G["下载器<br/>draft_downloader.py"]
E --> H["任务管理器<br/>video_task_manager.py"]
E --> I["COS 上传<br/>cos.py"]
E --> J["媒体工具<br/>media.py"]
E --> K["辅助工具<br/>helper.py"]
A --> L["配置<br/>config.py"]
M["容器编排<br/>docker-compose.yaml"] --> N["镜像构建<br/>Dockerfile"]
核心组件
- 应用入口与路由：FastAPI 应用创建、路由注册、中间件注册、Uvicorn 启动。
- 中间件：请求前准备（目录创建）、统一响应与异常处理。
- 下载器：草稿文件列表获取、多文件下载、路径修复、robocopy 触发剪映扫描。
- 任务管理器：异步队列、并发控制、导出流程、COS 上传、计费扣点。
- 日志：结构化日志格式、流式输出、uvicorn 适配。
- 配置：环境变量驱动的 URL、COS、API Key 开关等。
架构总览
capcut-mate 采用简化的单机部署架构，适用于本地开发和测试场景。应用容器直接暴露 API 端口，支持本地文件系统存储和基本的素材处理功能。
graph TB
subgraph "本地开发环境"
APP["FastAPI 应用容器"]
DL["草稿下载器"]
TM["视频任务管理器"]
LOG["日志输出"]
FS["本地文件系统<br/>/app/output"]
end
APP --> DL
APP --> TM
APP --> LOG
TM --> FS
详细组件分析
应用入口与启动
- 应用通过 FastAPI 创建，注册路由与中间件，启动 Uvicorn。
- 开发建议：固定端口暴露、禁用调试日志、设置 workers 数量。
sequenceDiagram
participant Entrypoint as "main.py"
participant Uvicorn as "Uvicorn"
participant Router as "路由(v1)"
participant MW as "中间件"
Entrypoint->>Uvicorn : "启动服务(host=0.0.0.0, port=30000)"
Uvicorn->>Entrypoint : "加载应用"
Entrypoint->>Router : "include_router(prefix=/openapi/capcut-mate)"
Entrypoint->>MW : "注册中间件(Prepare/Response)"
Uvicorn-->>Entrypoint : "服务就绪"
中间件设计
- 请求前准备中间件：确保草稿与临时目录存在。
- 统一响应中间件：标准化成功/失败响应、422 参数校验、异常捕获与翻译。
flowchart TD
Start(["请求进入"]) --> Prep["准备中间件<br/>创建目录"]
Prep --> Next["调用下游处理器"]
Next --> Resp["响应中间件"]
Resp --> IsJSON{"JSON 响应?"}
IsJSON --> |是| Wrap["封装统一格式"]
IsJSON --> |否| Pass["透传响应"]
Resp --> Err{"异常?"}
Err --> |是| Handle["捕获异常并返回标准错误"]
Err --> |否| Done["完成"]
Wrap --> Done
Pass --> Done
Handle --> Done
日志与错误处理
- 日志格式包含时间、级别、模块、相对路径与行号，uvicorn 与业务日志分离。
- 统一异常体系：业务异常与通用异常均转化为标准响应结构。
classDiagram
class Logger {
+dictConfig()
+getLogger()
}
class Exceptions {
+CustomError
+CustomException
}
Logger <.. Exceptions : "配合使用"
配置与环境变量
- 关键配置项：草稿下载 URL、下载 URL、贴纸配置、模板目录、COS 凭据、API Key 开关。
- 建议：敏感信息通过环境变量注入，避免硬编码。
依赖关系分析
- 应用依赖：FastAPI、uvicorn、requests、qcloud_cos、uiautomation（Windows）。
- 容器镜像：基于 python:3.11-slim，使用 uv 安装依赖，暴露 30000 端口。
- 编排：docker-compose 映射端口、挂载输出目录、设置资源限制与重启策略。
graph LR
IMG["Python 3.11 Slim"] --> APP["capcut-mate 应用"]
APP --> REQ["requests"]
APP --> COS["qcloud_cos"]
APP --> UIA["uiautomation(Windows)"]
DC["docker-compose"] --> IMG
DC --> VOL["/app/output 挂载"]
性能考虑
- 并发与锁：任务管理器使用 processing_lock 与 export_video_lock 控制导出并发，避免剪映同时导出导致不稳定。
- I/O 与磁盘：robocopy 触发扫描，确保剪映及时识别新增素材；输出目录挂载到宿主机，减少容器内文件系统开销。
- 资源限制：容器设置内存上限与 CPU 份额，OOM 调整降低被杀风险。
- 依赖安装：使用 uv 与只读缓存目录，提升安装速度与一致性。
故障排查指南
- 常见问题定位
- 下载失败：检查草稿 URL、网络连通性、422 参数校验、日志错误。
- 导出失败：确认 Windows 环境、剪映已打开且处于目录页、磁盘空间充足。
- COS 上传失败：核对 SecretId/SecretKey/Bucket/Region、签名 URL 生成与过期时间。
- 日志查看：关注 uvicorn.access、uvicorn.error 与业务日志，定位异常堆栈。
- 响应格式：统一错误响应包含 code 与 message，便于前端与监控系统解析。
结论
capcut-mate 的本地开发部署应围绕"简单、易用、可靠"展开：通过 Docker 容器化确保环境一致性；通过合理的资源配置满足开发需求；通过统一的日志与错误处理提升可观测性；通过任务队列与导出锁控制关键临界区。该简化部署模式适合个人开发者和小型团队的本地开发与测试使用。
附录
服务器配置要求（开发环境）
- 操作系统：Windows 10/11 或 Linux（推荐 Ubuntu 20.04+）。
- CPU：至少 4 核，建议 6 核以上。
- 内存：建议 8GB 以上，容器设置 2G 内存上限。
- 存储：SSD 至少 50GB 可用空间，输出目录挂载独立卷。
- 网络：开放 30000 端口，允许访问公网草稿源。
网络安全设置（开发环境）
- 开发环境默认使用 localhost:30000，无需复杂的安全配置。
- 如需外部访问，建议使用 VPN 或内网穿透工具。
- API Key 校验可选启用，便于本地测试。
负载均衡与反向代理（开发环境）
- 开发环境无需负载均衡，单机部署即可满足需求。
- 如需多实例部署，可使用 Docker Swarm 或 Kubernetes。
SSL 证书配置（开发环境）
- 开发环境使用 HTTP 协议，无需 SSL 证书。
- 如需 HTTPS，可使用自签名证书或 Let's Encrypt。
数据库连接池与缓存（开发环境）
- 开发环境无需数据库连接池。
- 使用内置 LRU 缓存（草稿对象缓存）即可满足需求。
日志轮转设置（开发环境）
- 使用标准输出日志，便于 Docker 容器管理。
- 建议使用 Docker 日志驱动进行日志轮转。
监控指标与告警（开发环境）
- 开发环境无需复杂监控系统。
- 建议使用 Docker Stats 或简单的进程监控。
运维自动化脚本（开发环境）
- 使用 Docker Compose 进行一键部署。
- 支持 GitHub Actions 进行 CI/CD 流水线。
备份与灾难恢复（开发环境）
- 开发环境数据量较小，可定期备份输出目录。
- 建议使用 Git 或版本控制系统管理配置文件。
附录
- 接口文档： docs.jcaigc.cn
- 效果案例： www.jcaigc.cn/workflow
- 开源仓库： capcut-mate
