架构设计

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

引言

本项目“capcut-mate”是一个面向剪映（CapCut）的自动化辅助系统，提供草稿管理、媒体素材处理、特效与字幕集成、以及视频导出能力。系统采用前后端分离策略：后端为基于 FastAPI 的 Web API，前端为 Electron 桌面应用，二者通过 IPC 和 HTTP 协议进行交互；同时系统支持容器化部署，便于在云渲染场景中运行。

项目结构

项目采用模块化分层组织：

• 后端服务层：FastAPI 应用、路由层、中间件、服务层、工具与配置
• 剪映自动化层：基于 UI 自动化库的剪映控制模块
• 前端桌面应用：Electron 主进程、预加载脚本、IPC 处理器、React 前端
• 配置与资源：OpenAPI 描述、Docker 配置、模板与贴纸配置
• 测试与工具：测试用例、ffprobe 工具

核心组件

• 应用入口与中间件
  • 应用入口负责创建 FastAPI 实例、注册路由与中间件，并启动服务。
  • 准备中间件在请求到达时创建草稿与临时目录，保证运行时文件系统就绪。
  • 统一响应中间件负责将业务响应标准化为统一格式，并集中处理异常与 422 参数校验。
• 路由与 API
  • 路由层提供 v1 版本的完整 API，覆盖草稿创建/保存、媒体添加、特效/字幕/贴纸、时间线计算、草稿查询、视频生成与状态查询等。
  • OpenAPI 规范定义了各接口的请求/响应模型与示例。
• 服务层
  • 服务层封装具体业务逻辑，调用底层工具与剪映自动化模块，返回标准化结果。
• 剪映自动化
  • 剪映控制器通过 UI 自动化库与剪映窗口交互，支持草稿查找、导出流程控制、分辨率/帧率设置、导出完成检测与文件移动等。
• 配置与部署
  • 配置文件集中管理路径、下载 URL、提示 URL、模板与 COS 存储等。
  • Dockerfile 与 docker-compose.yaml 提供容器化部署方案，支持挂载输出目录、时区与资源限制。

架构总览

系统采用前后端分离与容器化部署相结合的架构：

• 前端（Electron + React）：提供桌面应用界面，通过 IPC 与主进程通信，实现文件保存、日志、历史记录、URL 检测等功能。
• 后端（FastAPI）：提供 RESTful API，统一处理请求、中间件标准化响应、服务层编排业务逻辑。
• 自动化层：通过剪映控制器与剪映窗口交互，实现草稿导出自动化。
• 部署层：Docker 镜像与 Compose 编排，支持挂载输出目录、环境变量配置与资源限制。

详细组件分析

后端应用与中间件

• 应用入口负责：
  • 创建 FastAPI 应用并设置标题与版本
  • 注册 v1 路由与统一前缀
  • 注册准备中间件与统一响应中间件
  • 打印路由信息并启动服务
• 准备中间件：
  • 在请求到达前创建草稿目录与临时目录，确保文件系统可用
• 统一响应中间件：
  • 统一成功响应格式（code/message/data）
  • 统一异常处理（自定义异常与通用异常）
  • 特殊处理 422 参数校验错误，提取字段与消息并格式化

路由与服务层

• 路由层：
  • 提供 v1 版本的完整 API，包括草稿管理、媒体添加、特效/字幕/贴纸、时间线计算、草稿查询、视频生成与状态查询等
  • 每个路由调用服务层执行业务逻辑，并返回 Pydantic 模型定义的响应
• 服务层：
  • 通过统一的 init.py 暴露所有服务函数，便于路由层按需调用
  • 服务层内部可进一步调用工具模块与剪映自动化模块

剪映自动化组件

• 剪映控制器：
  • 通过 UI 自动化库定位剪映窗口，识别主页、编辑页与导出页状态
  • 支持草稿查找、导出按钮点击、导出设置（分辨率/帧率）、导出完成检测与文件移动
  • 提供状态机与超时控制，确保自动化流程稳定
• 设计要点：
  • 状态枚举与状态机：导出分辨率、帧率枚举；应用状态与子状态
  • 控件查找器：基于描述与类名的匹配器，提升控件定位稳定性
  • 错误处理：针对未找到控件、超时等异常进行统一处理

前端桌面应用与 IPC

• 主进程：
  • 创建 BrowserWindow，加载开发/生产模式下的 React 应用
  • 初始化 IPC 处理器，暴露文件保存、日志、历史记录、URL 检测等接口
• 预加载脚本：
  • 通过 contextBridge 暴露安全 API 至渲染进程，封装 IPC 调用
• IPC 处理器：
  • 实现 save-file、get-download-log、clear-download-log、on-file-operation-log、show-message-box、get-config-data、update-draft-path、open-external-url、check-url-access、get-history-record 等
• Electron 服务封装：
  • 根据是否在 Electron 环境选择真实 API 或模拟实现，保证浏览器环境下的兼容性

配置与部署

• 配置文件：
  • 定义项目根目录、草稿目录、临时目录、下载 URL、提示 URL、贴纸配置路径、模板目录、剪映草稿保存路径、COS 存储配置、API Key 启用开关等
• Docker 镜像：
  • 基于 Python slim 镜像，使用 uv 安装依赖，暴露 30000 端口，设置环境变量与缓存目录
• Compose 编排：
  • 暴露 30000 端口，挂载输出目录与时区，设置内存/CPU 限制与 OOM 优先级，支持自动重启

依赖关系分析

• 组件耦合与内聚
  • 路由层与服务层高内聚，通过 Pydantic 模型解耦请求/响应结构
  • 中间件与路由层低耦合，通过 FastAPI 生命周期管理
  • 剪映自动化模块与服务层松耦合，通过函数调用与异常传播
• 外部依赖与集成点
  • 剪映自动化依赖 UI 自动化库与操作系统窗口句柄
  • 前端通过 IPC 与主进程通信，主进程与后端 API 交互
  • 容器化部署依赖 Docker 与 Compose，支持挂载与环境变量注入

性能考量

• 中间件顺序与开销
  • 准备中间件在请求早期创建目录，避免后续 IO 报错，减少重试成本
  • 统一响应中间件对 JSON 响应进行格式化，建议在高并发场景下关注序列化开销
• 容器资源限制
  • Compose 中设置内存上限与 CPU 份额，结合 OOM 优先级调整，有助于在多任务场景下稳定运行
• 剪映自动化
  • 自动化流程包含多次窗口查找与点击，建议在批量导出时增加重试与超时控制，避免长时间阻塞

故障排查指南

• 常见问题与定位
  • 422 参数校验失败：统一响应中间件会解析 FastAPI 的验证错误并格式化为统一错误响应，检查请求体字段与类型
  • 服务器内部错误：统一响应中间件捕获通用异常并返回标准错误格式，查看日志定位具体异常
  • 剪映窗口未找到：检查剪映是否已安装、版本是否受支持、窗口标题是否匹配
  • IPC 通信异常：确认预加载脚本正确暴露 API，主进程已注册相应 handle，渲染进程通过 electronService 调用
• 日志与监控
  • 后端日志：中间件与服务层均记录关键事件与错误
  • 前端日志：主进程与渲染进程均可输出日志，便于定位 IPC 与网络问题

结论

capcut-mate 项目通过清晰的分层架构与前后端分离策略，实现了对剪映的自动化控制与 API 服务。后端以 FastAPI 为核心，配合中间件与服务层，提供稳定可靠的接口；前端通过 Electron 与 IPC 实现桌面应用体验；容器化部署简化了运维与扩展。该架构具备良好的可维护性与扩展性，适合在云渲染与本地场景中灵活部署。

附录

• API 规范参考：OpenAPI 描述文件定义了完整的接口契约与示例，便于客户端对接与测试
• 前端工程配置：Electron 与 Vite 的组合提供了高效的开发与打包体验

文档信息

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