【开源剪映小助手】开发环境搭建

用户59913033478
2 阅读4分钟

开发环境搭建

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

capcut-mate 是一个基于 Python 和 Electron 的 CapCut 视频编辑助手项目。该项目提供了云端渲染服务，支持 Windows 和 macOS 平台的桌面客户端应用。项目采用 FastAPI 构建 RESTful API 服务，并通过 Docker 进行容器化部署。

项目结构

项目采用模块化架构设计，主要包含以下核心组件：

graph TB
subgraph "后端服务"
A[FastAPI 应用<br/>main.py]
B[路由模块<br/>src/router]
C[业务逻辑<br/>src/service]
D[数据模型<br/>src/schemas]
E[中间件<br/>src/middlewares]
end
subgraph "桌面客户端"
F[Electron 主进程<br/>desktop-client/main.js]
G[React 前端<br/>desktop-client/web]
H[构建配置<br/>desktop-client/scripts]
end
subgraph "基础设施"
I[Docker 容器<br/>Dockerfile]
J[Compose 编排<br/>docker-compose.yaml]
K[CI/CD 流水线<br/>.github/workflows]
end
A --> B
B --> C
C --> D
F --> G
I --> A
J --> I

核心组件

系统要求

项目对运行环境有明确的要求：

Python 环境

  • Python 版本：3.11 或更高版本
  • 包管理：uv (版本 0.8.11)
  • 依赖管理：基于 pyproject.toml 和 uv.lock

Node.js 环境

  • Node.js 版本：22.x
  • 包管理：npm
  • 依赖：Electron 31.7.6

操作系统兼容性

  • Windows：支持 Windows 10/11
  • macOS：支持 macOS 10.13+ (Intel x64) 和 macOS 11.0+ (Apple Silicon ARM64)
  • Linux：基于 Alpine Linux 3.11

硬件要求

  • 内存：至少 2GB RAM
  • 存储：至少 500MB 可用空间
  • CPU：多核处理器 (推荐 2+ 核心)

依赖组件

项目依赖的关键组件包括：

graph LR
subgraph "Python 依赖"
A[FastAPI >=0.100.0]
B[Uvicorn >=0.35.0]
C[Requests >=2.32.5]
D[PyWin32 >=311]
E[uiautomation >=2.0.29]
F[PyMediaInfo >=7.0.1]
G[COS Python SDK >=1.9.38]
H[Email Validator >=2.2.0]
end
subgraph "Node.js 依赖"
I[Electron 31.7.6]
J[Axios ^1.11.0]
K[React ^19.2.0]
L[Bootstrap ^5.3.8]
M[Vite ^7.2.6]
end
A --> I
B --> J

架构概览

项目采用分层架构设计，后端服务与桌面客户端分离：

sequenceDiagram
participant Client as "桌面客户端"
participant API as "FastAPI 服务"
participant Jianying as "剪映控制"
participant COS as "腾讯云存储"
Client->>API : HTTP 请求
API->>API : 验证请求
API->>Jianying : 控制剪映窗口
Jianying-->>API : 导出状态
API->>COS : 上传草稿
COS-->>API : 上传结果
API-->>Client : 响应数据

详细组件分析

后端服务配置

FastAPI 应用初始化

后端服务使用 FastAPI 构建，包含完整的路由注册和中间件配置：

classDiagram
class FastAPIApp {
+title : "CapCut Mate API"
+version : "1.0"
+include_router()
+add_middleware()
+logger.info()
}
class Middleware {
+PrepareMiddleware
+ResponseMiddleware
}
class Router {
+v1_router
+prefix : "/openapi/capcut-mate"
+tags : ["capcut-mate"]
}
FastAPIApp --> Middleware
FastAPIApp --> Router
环境配置管理

项目使用环境变量进行配置管理，支持多种部署场景：

环境变量默认值用途必需
DRAFT_URLcapcut-mate.jcaigc.cn/openapi/cap…草稿下载地址否
DOWNLOAD_URLcapcut-mate.jcaigc.cn/文件下载 URL否
TIP_URLdocs.jcaigc.cn/提示信息地址否
COS_SECRET_IDAKIDiGckgR1PaYIp8EAxXu3zmNlw460mQ1Rg腾讯云密钥ID否
COS_SECRET_KEY8LRZcdeUBjCctxoSs21nMhpnfKm24uX0腾讯云密钥否
COS_BUCKET_NAMEcapcut-mate-1367161383存储桶名称否
COS_REGIONap-shanghai存储桶区域否
ENABLE_APIKEYtrueAPI密钥启用否

Docker 容器化部署

Dockerfile 配置

容器使用 Python 3.11 slim 基础镜像，优化了启动时间和资源占用：

flowchart TD
A["基础镜像: python:3.11-slim"] --> B["安装 uv 包管理器"]
B --> C["创建工作目录 /app"]
C --> D["创建非 root 用户"]
D --> E["复制应用文件"]
E --> F["安装依赖 (uv sync)"]
F --> G["设置环境变量"]
G --> H["暴露端口 30000"]
H --> I["启动命令 uv run main.py"]
Compose 编排配置

Docker Compose 支持多种部署场景：

graph TB
subgraph "容器配置"
A["capcut-mate 服务"]
B["端口映射: 30000:30000"]
C["内存限制: 2GB"]
D["CPU 限制: 2 核心"]
end
subgraph "卷挂载"
E["/opt/1panel/.../output:/app/output"]
F["/etc/localtime:/etc/localtime"]
G["/etc/timezone:/etc/timezone"]
end
subgraph "环境变量"
H["DRAFT_URL=草稿下载地址"]
I["DOWNLOAD_URL=下载URL"]
J["TIP_URL=提示URL"]
end
A --> E
A --> F
A --> G
A --> H
A --> I
A --> J

桌面客户端架构

Electron 应用结构

桌面客户端采用 React + Vite 技术栈，支持多平台构建：

graph LR
subgraph "主进程"
A[main.js]
B[Electron 主进程]
C[IPC 通信]
end
subgraph "渲染进程"
D[React 应用]
E[Vite 开发服务器]
F[组件系统]
end
subgraph "构建配置"
G[electron-builder.config.js]
H[electron-builder-green.config.js]
I[打包脚本]
end
A --> D
B --> C
D --> F
G --> I
H --> I
多平台构建支持

项目支持三种构建模式：

平台架构构建目标安装包类型
Windowsx64NSIS 安装程序exe
macOSARM64DMG 安装包dmg
macOSx64DMG 安装包dmg

依赖关系分析

Python 依赖树

项目的核心 Python 依赖关系如下：

graph TD
A["capcut-mate 1.0.0"] --> B["FastAPI >=0.100.0"]
A --> C["Uvicorn[standard] >=0.35.0"]
A --> D["Requests >=2.32.5"]
A --> E["PyWin32 >=311"]
A --> F["uiautomation >=2.0.29"]
A --> G["PyMediaInfo >=7.0.1"]
A --> H["COS Python SDK >=1.9.38"]
A --> I["Email Validator >=2.2.0"]
B --> J["Starlette"]
B --> K["Pydantic"]
C --> L["httptools"]
C --> M["uvloop"]
D --> N["certifi"]
D --> O["charset-normalizer"]

Node.js 依赖分析

桌面客户端的前端依赖采用现代化技术栈：

graph LR
subgraph "前端框架"
  A["React ^19.2.0"]
  B["React DOM ^19.2.0"]
  C["React Router DOM ^7.10.1"]
end
subgraph "UI 组件"
  D["Bootstrap ^5.3.8"]
  E["React Bootstrap ^2.10.10"]
  F["React Bootstrap Icons ^1.11.6"]
end
subgraph "开发工具"
  G["Vite ^7.2.6"]
  H["@vitejs/plugin-react ^5.1.1"]
  I["Cross-env ^10.1.0"]
end
subgraph "运行时"
  J["Axios ^1.11.0"]
  K["UUID ^8.3.2"]
  L["Log4js ^6.9.1"]
end

性能考虑

容器性能优化

Docker 容器针对性能进行了多项优化：

  1. 镜像大小优化

    • 使用 Alpine Linux 3.11 slim 基础镜像
    • 最小化安装不必要的系统包
    • 使用只读文件系统

  2. 资源限制

    • 内存限制：2GB
    • CPU 限制：2 核心
    • 禁用 OOM Killer

  3. 启动优化

    • 使用 uv 作为包管理器
    • 预编译的二进制依赖
    • 缓存优化

开发环境性能

开发环境建议配置：

  • 内存：至少 4GB RAM
  • CPU：4 核心以上
  • 存储：SSD 硬盘
  • 网络：稳定的互联网连接

故障排除指南

常见环境问题

Python 环境问题

问题：Python 版本不兼容

  • 症状：安装依赖时报错
  • 解决方案：升级到 Python 3.11+

问题：uv 安装失败

  • 症状：无法安装 uv 包管理器
  • 解决方案：检查网络连接，使用代理或离线安装
Docker 容器问题

问题：容器启动失败

  • 症状：容器立即退出
  • 解决方案：检查日志输出，验证环境变量配置

问题：端口冲突

  • 症状：端口 30000 被占用
  • 解决方案：修改 docker-compose.yaml 中的端口映射
桌面客户端问题

问题：Electron 构建失败

  • 症状：npm ci 失败
  • 解决方案：清理 node_modules，重新安装依赖

问题：跨平台构建问题

  • 症状：macOS 构建失败
  • 解决方案：检查代码签名配置，更新 entitlements 文件

调试工具设置

后端调试
# 启用详细日志
uv run main.py --log-level debug

# 使用调试模式启动
uvicorn main:app --reload --log-level debug
前端调试
# 开发模式启动
npm run web:dev

# 生产模式构建
npm run web:build

结论

capcut-mate 项目提供了完整的开发环境搭建方案，支持多种部署方式和平台。通过合理的环境配置、依赖管理和容器化部署，开发者可以快速建立可用的开发环境。

关键要点：

  • 明确的系统要求和兼容性说明
  • 完善的 Docker 容器化部署方案
  • 支持多平台的桌面客户端应用
  • 清晰的 CI/CD 流水线配置
  • 详细的故障排除指南

建议开发者根据具体需求选择合适的部署方式，并按照本文档的指导完成环境搭建。

avatar
文章
阅读
粉丝