架构设计

引言

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

项目结构

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

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

graph TB
subgraph "后端服务"
A_main["main.py<br/>应用入口"]
A_router["src/router/v1.py<br/>路由与API"]
A_mw_prepare["src/middlewares/prepare.py<br/>准备中间件"]
A_mw_resp["src/middlewares/response.py<br/>响应中间件"]
A_service["src/service/*<br/>业务服务"]
A_config["config.py<br/>配置常量"]
A_jianying["src/pyJianYingDraft/jianying_controller.py<br/>剪映自动化"]
end
subgraph "前端桌面应用"
B_main["desktop-client/main.js<br/>Electron主进程"]
B_preload["desktop-client/preload.js<br/>预加载桥接"]
B_ipc["desktop-client/nodeapi/ipcHandlers.js<br/>IPC处理器"]
B_web["desktop-client/web/*<br/>React前端"]
B_electronSvc["desktop-client/web/src/services/electronService.js<br/>Electron服务封装"]
end
subgraph "部署与配置"
C_docker["Dockerfile<br/>镜像构建"]
C_compose["docker-compose.yaml<br/>容器编排"]
C_openapi["openapi.yaml<br/>API规范"]
end
A_main --> A_router
A_router --> A_service
A_main --> A_mw_prepare
A_main --> A_mw_resp
A_main --> A_config
A_service --> A_jianying
B_main --> B_preload
B_main --> B_ipc
B_web --> B_electronSvc
B_electronSvc --> B_ipc
A_config --> C_compose
C_docker --> A_main
C_compose --> A_main
C_openapi --> A_router

核心组件

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

架构总览

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

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

graph TB
FE["前端桌面应用<br/>Electron + React"] --> IPC["IPC桥接<br/>preload.js"]
IPC --> MAIN["主进程<br/>desktop-client/main.js"]
MAIN --> HANDLER["IPC处理器<br/>nodeapi/ipcHandlers.js"]
HANDLER --> API["后端API<br/>FastAPI"]
API --> ROUTER["路由层<br/>src/router/v1.py"]
ROUTER --> SERVICE["服务层<br/>src/service/*"]
SERVICE --> JIANYING["剪映自动化<br/>jianying_controller.py"]
API --> MW_PREP["准备中间件"]
API --> MW_RESP["响应中间件"]
API --> CFG["配置<br/>config.py"]
API --> DOCKER["容器化部署<br/>Dockerfile/docker-compose.yaml"]

详细组件分析

后端应用与中间件

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

sequenceDiagram
participant Client as "客户端"
participant App as "FastAPI应用"
participant PrepMW as "准备中间件"
participant RespMW as "响应中间件"
participant Router as "路由层"
participant Service as "服务层"
Client->>App : "HTTP请求"
App->>PrepMW : "进入准备阶段"
PrepMW-->>App : "创建目录完成"
App->>RespMW : "进入响应处理"
RespMW->>Router : "转发请求"
Router->>Service : "调用业务逻辑"
Service-->>Router : "返回业务结果"
Router-->>RespMW : "返回响应"
RespMW-->>Client : "统一格式响应"

路由与服务层

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

classDiagram
class Router_v1 {
+create_draft()
+save_draft()
+add_videos()
+add_audios()
+add_images()
+add_sticker()
+add_keyframes()
+add_captions()
+add_effects()
+add_masks()
+add_text_style()
+get_text_animations()
+get_image_animations()
+easy_create_material()
+get_draft()
+gen_video()
+gen_video_status()
+get_audio_duration()
+timelines()
+audio_timelines()
+audio_infos()
+imgs_infos()
+caption_infos()
+effect_infos()
+keyframes_infos()
+video_infos()
+search_sticker()
+get_url()
+str_list_to_objs()
+str_to_list()
+objs_to_str_list()
}
class Service {
+create_draft()
+save_draft()
+add_videos()
+add_audios()
+add_images()
+add_sticker()
+add_keyframes()
+add_captions()
+add_effects()
+add_masks()
+add_text_style()
+get_text_animations()
+get_image_animations()
+easy_create_material()
+get_draft()
+gen_video()
+gen_video_status()
+get_audio_duration()
+timelines()
+audio_timelines()
+audio_infos()
+imgs_infos()
+caption_infos()
+effect_infos()
+keyframes_infos()
+video_infos()
+search_sticker()
+get_url()
+str_list_to_objs()
+str_to_list()
+objs_to_str_list()
}
Router_v1 --> Service : "调用"

剪映自动化组件

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

stateDiagram-v2
[*] --> 主页
主页 --> 编辑页 : "点击草稿"
编辑页 --> 导出前置页 : "点击导出"
导出前置页 --> 导出开始 : "检测到导出按钮"
导出开始 --> 导出中 : "点击最终导出"
导出中 --> 导出完成 : "检测到完成按钮"
导出完成 --> 主页 : "关闭完成窗口"

前端桌面应用与 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 或模拟实现，保证浏览器环境下的兼容性

sequenceDiagram
participant UI as "React界面"
participant Preload as "预加载脚本"
participant Main as "Electron主进程"
participant Handler as "IPC处理器"
participant Backend as "后端API"
UI->>Preload : "调用electronService方法"
Preload->>Main : "ipcRenderer.invoke(...)"
Main->>Handler : "ipcMain.handle(...)"
Handler->>Backend : "HTTP请求后端API"
Backend-->>Handler : "返回响应"
Handler-->>Main : "返回结果"
Main-->>Preload : "返回结果"
Preload-->>UI : "更新界面状态"

配置与部署

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

依赖关系分析

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

graph LR
Router["路由层"] --> Service["服务层"]
Service --> Jianying["剪映自动化"]
Router --> Middlewares["中间件"]
Frontend["前端桌面应用"] --> IPC["IPC桥接"]
IPC --> MainProc["主进程"]
MainProc --> Backend["后端API"]
Backend --> Router

性能考量

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

故障排查指南

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

结论

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

附录

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

【开源剪映小助手】架构设计