【开源剪映小助手】全局配置

全局配置

目录

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

简介

本文件系统性梳理 capcut-mate 的全局配置体系，重点覆盖以下方面：

• config.py 中所有配置参数的含义、默认值、环境变量覆盖策略
• 贴纸配置文件 sticker.json 的结构与自定义方法
• 云渲染与本地部署的典型配置场景
• 文件下载大小限制配置 DOWNLOAD_FILE_SIZE_LIMIT 的使用与最佳实践
• 最佳实践与常见问题排查
• 模板目录从 default 到 default2 的迁移及其影响
• 环境变量处理改进，支持更灵活的配置管理

项目结构

capcut-mate 的配置由"运行时配置"和"静态资源配置"两部分组成：

• 运行时配置：集中于 config.py，包含路径、下载 URL、提示 URL、贴纸配置路径、模板目录、草稿保存路径、云存储配置、API Key 开关、文件下载大小限制等
• 静态资源配置：贴纸配置文件 sticker.json；模板草稿 draft_info.json；桌面客户端配置中心与下载器的交互

graph TB
A["config.py<br/>运行时配置"] --> B["DRAFT_DIR<br/>草稿保存目录"]
A --> C["TEMP_DIR<br/>临时文件目录"]
A --> D["DRAFT_URL<br/>草稿下载接口URL"]
A --> E["DOWNLOAD_URL<br/>容器内路径转外链URL"]
A --> F["TIP_URL<br/>帮助/提示URL"]
A --> G["STICKER_CONFIG_PATH<br/>贴纸配置文件路径"]
A --> H["TEMPLATE_DIR<br/>模板目录"]
A --> I["DRAFT_SAVE_PATH<br/>剪映草稿保存路径"]
A --> J["COS_*<br/>云存储配置"]
A --> K["ENABLE_APIKEY<br/>API Key开关"]
A --> L["DOWNLOAD_FILE_SIZE_LIMIT<br/>文件下载大小限制"]
M["sticker.json<br/>贴纸配置"] --> N["贴纸元数据<br/>图片/尺寸/类型"]
O["template/default/draft_info.json<br/>模板草稿(旧版)"] --> P["画布/轨道/素材结构"]
Q["template/default2/draft_info.json<br/>模板草稿(新版)"] --> R["双文件模板结构"]
Q --> S["draft_content.json<br/>内容模板"]
Q --> T["attachment_pc_common.json<br/>附件配置"]
U["draft_meta_info.json<br/>草稿元信息模板"] --> R
V["create_draft.py<br/>草稿创建逻辑"] --> Q
V --> O
W["ScriptFile<br/>双文件兼容模式"] --> R
X["template_mode.py<br/>模板导入模式"] --> W
Y["download.py<br/>下载模块"] --> L

核心组件

本节对 config.py 中的关键配置项逐条说明，含用途、默认值、环境变量覆盖策略与使用场景。

• 项目根目录 PROJECT_ROOT

  • 用途：定位项目根路径，用于拼接其他相对路径
  • 默认值：基于当前文件所在目录的绝对路径
  • 环境变量：无
  • 使用场景：作为其他路径的基础

• 草稿保存目录 DRAFT_DIR

  • 用途：存放生成的草稿文件（输出目录）
  • 默认值：PROJECT_ROOT/output/draft
  • 环境变量：无
  • 使用场景：服务端生成草稿后写入该目录

• 临时文件目录 TEMP_DIR

  • 用途：临时文件缓存与处理
  • 默认值：PROJECT_ROOT/temp
  • 环境变量：无
  • 使用场景：下载、解压、转换过程中的中间文件

• 草稿下载接口 URL DRAFT_URL

  • 用途：对外提供草稿下载的API入口
  • 默认值：capcut-mate.jcaigc.cn/openapi/cap…
  • 环境变量：DRAFT_URL
  • 使用场景：客户端/外部系统调用获取草稿

• 下载URL前缀 DOWNLOAD_URL

  • 用途：将容器内/app/路径映射为外网可访问URL
  • 默认值：capcut-mate.jcaigc.cn/
  • 环境变量：DOWNLOAD_URL
  • 使用场景：云渲染环境下，将/app/xxx 转为 https://.../xxx

• 提示URL TIP_URL

  • 用途：帮助/提示页面地址
  • 默认值：docs.jcaigc.cn/
  • 环境变量：TIP_URL
  • 使用场景：前端展示帮助链接

• 贴纸配置文件路径 STICKER_CONFIG_PATH

  • 用途：指向贴纸配置JSON文件
  • 默认值：config/sticker.json
  • 环境变量：无
  • 使用场景：搜索/加载贴纸元数据

• 模板目录 TEMPLATE_DIR

  • 用途：草稿模板根目录
  • 默认值：template
  • 环境变量：无
  • 使用场景：创建草稿时复制模板
  • ：当前使用 template/default2 作为默认模板目录

• 剪映草稿保存路径 DRAFT_SAVE_PATH

  • 用途：剪映本地草稿目录（云渲染必需）
  • 默认值：Windows路径示例（注释中给出）
  • 环境变量：无
  • 使用场景：将下载的草稿导入剪映

• 云存储配置 COS_*（腾讯云COS）

  • COS_SECRET_ID/COS_SECRET_KEY/COS_BUCKET_NAME/COS_REGION
  • 默认值：示例密钥/桶/区域（注释标明"云渲染必需配置"）
  • 环境变量：COS_SECRET_ID/COS_SECRET_KEY/COS_BUCKET_NAME/COS_REGION
  • 使用场景：上传文件并生成带签名的临时下载链接

• API Key开关 ENABLE_APIKEY

  • 用途：控制是否启用API Key鉴权
  • 默认值：true
  • 环境变量：ENABLE_APIKEY
  • 使用场景：生产环境开启鉴权

• 文件下载大小限制 DOWNLOAD_FILE_SIZE_LIMIT

  • 用途：控制文件下载的最大允许大小（字节）
  • 默认值：200MB（209,715,200 字节）
  • 环境变量：DOWNLOAD_FILE_SIZE_LIMIT
  • 使用场景：防止过大文件占用过多带宽和存储空间
  • ：支持通过环境变量动态配置，替代硬编码的200MB限制

架构总览

全局配置贯穿"生成草稿—下载—导入剪映—上传/分享"的流程，如下图所示：

sequenceDiagram
participant Client as "客户端/外部系统"
participant Service as "服务端"
participant Config as "config.py"
participant Template as "模板系统"
participant Downloader as "草稿下载器"
participant DownloadModule as "下载模块"
participant COS as "COS上传"
participant Jianying as "剪映草稿目录"
Client->>Service : 请求创建草稿
Service->>Config : 读取模板/输出目录
Service->>Template : 使用default2模板创建草稿
Template-->>Service : 返回双文件模板(draft_info.json + draft_content.json)
Service->>Service : 基于模板创建草稿并修改画布尺寸
Service-->>Client : 返回草稿URLDRAFT_URL + ?draft_id
Client->>Downloader : 下载草稿按DRAFT_URL
Downloader->>Config : 读取DRAFT_SAVE_PATH
Downloader->>DownloadModule : 调用下载函数
DownloadModule->>Config : 读取DOWNLOAD_FILE_SIZE_LIMIT
DownloadModule->>DownloadModule : 检查文件大小限制
DownloadModule->>Jianying : 导入草稿
Service->>COS : 上传产物可选
COS-->>Service : 返回带签名URLDOWNLOAD_URL前缀

详细组件分析

配置参数详解与最佳实践

• 路径类

  • DRAFT_DIR/TEMP_DIR：建议挂载到持久化卷，避免容器重启丢失
  • DRAFT_SAVE_PATH：云渲染场景必须配置为剪映可访问的路径；本地开发可用相对路径或本地共享目录
  • TEMPLATE_DIR：当前使用 template/default2 作为默认模板目录，如需自定义模板，建议在同级新增目录并调整引用

• 下载与分享类

  • DRAFT_URL：生产环境务必使用HTTPS域名，确保客户端可访问
  • DOWNLOAD_URL：与反向代理/网关一致，确保/app/被正确替换为外链前缀
  • TIP_URL：可为空，前端会根据是否为空决定是否显示帮助链接
  • DOWNLOAD_FILE_SIZE_LIMIT：建议根据实际业务需求调整，默认200MB适合大多数视频文件，大型项目可适当增大

• 云存储类（COS）

  • 建议通过环境变量注入密钥与桶信息，不要硬编码
  • 生成带签名URL时注意过期时间合理设置（默认1天），避免过短导致客户端无法下载
  • COS_REGION 与桶区域一致，避免跨区域访问失败

• API Key开关

  • 生产环境建议启用 ENABLE_APIKEY=true
  • 开发环境可临时关闭以便调试

• 文件下载大小限制配置

  • DOWNLOAD_FILE_SIZE_LIMIT：以字节为单位，支持从环境变量动态配置
  • 默认值 200MB（209,715,200 字节）适用于大多数视频编辑场景
  • 可根据网络环境和存储容量进行调整，建议设置为合理的上限值
  • 超过限制时会触发 FILE_SIZE_LIMIT_EXCEEDED 错误

贴纸配置文件结构与自定义

• 结构概览

  • sticker.json 是一个数组，每个元素代表一个贴纸条目
  • 主要字段：
    • sticker.sticker_package.width_per_frame/height_per_frame：贴纸帧宽高
    • sticker.sticker_package.size：贴纸包大小
    • sticker.sticker_type：贴纸类型（数值枚举）
    • sticker.large_image.image_url：贴纸大图URL
    • sticker.track_thumbnail：轨道缩略图URL
    • sticker_id：贴纸唯一标识
    • title：贴纸标题

• 自定义方法

  • 新增贴纸：在数组末尾追加一条记录，确保 image_url 可访问
  • 修改尺寸：调整 width_per_frame/height_per_frame 以适配目标视频分辨率
  • 类型标注：根据业务需要设置 sticker_type（具体语义以实际消费方为准）
  • 图片校验：建议先在浏览器打开 image_url，确认可访问且尺寸合适

• 注意事项

  • 大量贴纸会导致加载耗时增加，建议分页或懒加载
  • track_thumbnail 与 large_image 应保持一致的视觉风格

模板草稿与元信息

模板目录迁移与结构变化

模板系统已从单文件模板迁移到双文件模板结构：

• 旧版模板 (template/default)

  • 仅包含 draft_info.json 一个文件
  • 结构相对简单，包含画布配置、轨道、素材等基础信息
  • 适用于基本的草稿创建需求

• 新版模板 (template/default2)

  • 包含多个文件的完整模板结构：
    • draft_info.json：草稿基本信息和配置
    • draft_content.json：草稿内容结构（新增）
    • draft_agency_config.json：代理配置
    • draft_meta_info.json：元信息模板
    • attachment_pc_common.json：附件通用配置（新增）
    • template.tmp：模板文件

• 双文件兼容模式

  • 草稿创建时会同时处理 draft_info.json 和 draft_content.json
  • 保存时自动同步两个文件的内容，确保数据一致性
  • 支持更复杂的草稿结构和功能

草稿元信息模板

• draft_meta_info.json 定义草稿元信息结构（如草稿ID、材料清单等）
• 用于初始化草稿目录结构
• 与新版模板的双文件结构配合使用

双文件模板的技术实现

双文件模板结构通过以下技术机制实现：

• ScriptFile 类的双文件兼容模式

  • dual_file_compatibility 属性控制是否启用双文件保存
  • 当启用时，保存一个文件会自动同步到另一个对应文件
  • 支持 draft_info.json ↔ draft_content.json 的双向同步

• 模板导入模式

  • template_mode.py 提供了完整的模板导入机制
  • 支持导入轨道、片段、素材等模板元素
  • 提供了时间范围处理、素材替换等功能

• 兼容性保证

  • 通过双文件同步确保两个模板文件内容一致
  • 向后兼容旧版单文件模板结构
  • 支持渐进式迁移从旧模板到新模板

文件下载大小限制配置

配置参数详解

• DOWNLOAD_FILE_SIZE_LIMIT
  • 用途：控制文件下载的最大允许大小（字节）
  • 默认值：200MB（209,715,200 字节）
  • 环境变量：DOWNLOAD_FILE_SIZE_LIMIT
  • 作用机制：在下载过程中实时检查已下载字节数与限制值的比较

实现机制

• 配置读取：config.py 中通过 os.getenv() 读取环境变量，未设置时使用默认值
• 下载模块集成：download.py 中将配置值赋给 DEFAULT_FILE_SIZE_LIMIT 常量
• 实时检查：下载过程中每接收一个数据块就检查是否超过限制
• 错误处理：超过限制时抛出 FILE_SIZE_LIMIT_EXCEEDED 异常

错误分类与处理

• 致命错误：FILE_SIZE_LIMIT_EXCEEDED 被分类为 fatal 错误
• 错误恢复：与其他网络错误不同，文件大小超限被视为不可恢复的配置问题
• 日志记录：详细的错误日志包含限制值和实际下载大小信息

配置示例

• 生产环境：建议设置为 500MB-1GB 以适应大型视频项目
• 开发环境：可保持默认 200MB 以节省测试资源
• 特殊场景：根据网络带宽和存储限制进行调整

环境变量与部署配置

• docker-compose.yaml（生产）

  • 显式设置了 DRAFT_URL、DOWNLOAD_URL、TIP_URL 等环境变量
  • 设置 DOWNLOAD_FILE_SIZE_LIMIT=209715200（200MB）
  • 建议将输出目录挂载到宿主机持久化存储

• docker-compose.example.yaml（示例）

  • 使用 capcut-mate.jcaigc.cn 作为生产环境URL
  • 设置 DOWNLOAD_FILE_SIZE_LIMIT=209715200（200MB）
  • 提供了完整的环境变量配置示例

• 环境变量覆盖优先级

  • config.py 中使用 os.getenv(key, default) 读取，若未设置则采用默认值
  • docker compose 的 environment 字段会覆盖容器内默认值

桌面客户端配置中心与下载器

• 配置中心（Web）

  • 支持选择剪映草稿保存路径（targetDirectory）
  • 选择后写入本地配置文件，后续下载器使用该路径

• 下载器（Node/Electron）

  • 读取配置中心设置的 targetDirectory
  • 校验目录权限，必要时弹窗提示
  • 下载草稿并导入剪映

草稿创建流程与模板使用

模板迁移后的创建流程

草稿创建逻辑已适配新的双文件模板结构：

flowchart TD
A["创建草稿请求"] --> B["生成草稿ID"]
B --> C["定位模板目录"]
C --> D["复制模板文件到草稿目录"]
D --> E["加载draft_info.json为模板"]
E --> F["启用双文件兼容模式"]
F --> G["修改画布尺寸配置"]
G --> H["保存草稿文件"]
H --> I["添加主轨道"]
I --> J["返回草稿URL"]

关键变更点

• 模板路径：从 template/default 迁移到 template/default2
• 文件结构：从单一 draft_info.json 扩展到双文件结构
• 兼容性：新增双文件兼容模式，确保两个模板文件内容同步
• 功能增强：支持更复杂的草稿结构和配置选项

依赖关系分析

• 配置依赖链

  • 草稿下载器依赖 DRAFT_URL 与 DRAFT_SAVE_PATH
  • 下载模块依赖 DOWNLOAD_FILE_SIZE_LIMIT 进行大小检查
  • COS上传依赖 COS_* 与 DOWNLOAD_URL
  • 贴纸搜索依赖 STICKER_CONFIG_PATH
  • 草稿创建依赖 TEMPLATE_DIR 与 DRAFT_DIR
  • ：草稿创建现在依赖双文件模板结构

• 外部依赖

  • 腾讯云 COS SDK（CosS3Client）
  • 反向代理/网关（提供 DOWNLOAD_URL 前缀）

graph LR
CFG["config.py"] --> DL["草稿下载器"]
CFG --> DM["下载模块"]
CFG --> COS["COS上传"]
CFG --> STK["贴纸配置"]
CFG --> TPL["模板目录(default2)"]
DM --> LIMIT["DOWNLOAD_FILE_SIZE_LIMIT"]
DL --> OUT["DRAFT_DIR/DRAFT_SAVE_PATH"]
COS --> URL["DOWNLOAD_URL"]
STK --> SEARCH["贴纸搜索"]
TPL --> CREATE["草稿创建(双文件兼容)"]
SCRIPT["ScriptFile"] --> COMPAT["双文件兼容模式"]
CREATE --> SCRIPT

性能考量

• 贴纸加载
  • 大型 sticker.json 会增加解析与传输开销，建议分页或按需加载
• 下载与导入
  • 草稿文件较多时，下载与解压可能占用IO，建议将 DRAFT_DIR/TEMP_DIR 挂载到高性能磁盘
  • ：双文件模板结构增加了文件数量，但通过兼容模式优化了同步性能
  • ：DOWNLOAD_FILE_SIZE_LIMIT 可以防止过大的文件占用过多带宽和存储资源
• COS上传
  • 生成签名URL时尽量复用，避免频繁调用SDK
  • 控制过期时间，避免过短导致客户端反复刷新URL
• 模板迁移
  • 新版本模板文件更多，但通过批量复制优化了创建速度
  • 双文件兼容模式确保了数据一致性，无额外性能开销
• 文件大小限制
  • 合理设置 DOWNLOAD_FILE_SIZE_LIMIT 可以避免网络拥塞和存储压力
  • 对于大型视频项目，建议适当增大限制值以适应实际需求

故障排查指南

• 草稿下载失败

  • 检查 DRAFT_URL 是否可达，是否携带正确的 draft_id 参数
  • 确认 DRAFT_SAVE_PATH 存在且具备读写权限
  • 查看下载器日志，关注网络异常与文件写入错误

• 文件大小限制相关问题

  • 检查 DOWNLOAD_FILE_SIZE_LIMIT 配置是否过小
  • 确认下载的文件大小是否超过了限制值
  • 查看错误日志中的 FILE_SIZE_LIMIT_EXCEEDED 信息
  • 调整环境变量 DOWNLOAD_FILE_SIZE_LIMIT 的值

• 无法导入剪映

  • 确认 DRAFT_SAVE_PATH 指向剪映可访问的路径
  • 检查草稿目录结构是否完整（draft_info.json/draft_content.json）

• COS上传失败

  • 校验 COS_SECRET_ID/COS_SECRET_KEY/COS_BUCKET_NAME/COS_REGION 是否正确
  • 确认桶区域与 COS_REGION 一致
  • 查看签名URL是否过期

• 贴纸搜索异常

  • 确认 STICKER_CONFIG_PATH 指向有效JSON文件
  • 检查 image_url 是否可访问，尺寸是否合理

• 模板相关问题

  • 检查 TEMPLATE_DIR 是否指向正确的 template/default2 目录
  • 确认模板文件完整性，特别是 draft_content.json 和 attachment_pc_common.json
  • 验证双文件兼容模式是否正常工作，两个模板文件内容是否同步

结论

capcut-mate 的全局配置以 config.py 为核心，结合 docker-compose 的环境变量覆盖，形成"可定制、可扩展、可运维"的配置体系。通过合理设置路径、下载URL、云存储参数与API Key开关，可在本地与云端稳定运行。贴纸配置与模板草稿进一步提升了内容生态的灵活性。

重要更新：模板系统已成功从 single-file 模式迁移到 dual-file 模式，提供了更强大的草稿创建能力。新的双文件结构（draft_info.json + draft_content.json）支持更复杂的草稿配置，同时通过双文件兼容模式确保了向后兼容性和数据一致性。

新增功能：DOWNLOAD_FILE_SIZE_LIMIT 配置为系统增加了灵活的文件大小控制能力。通过环境变量可动态调整下载限制，既保证了系统的稳定性，又满足了不同场景的需求。建议根据实际业务场景合理设置该参数，以平衡性能、存储和用户体验。

新增改进：环境变量处理机制得到显著改进，所有核心配置参数都可以通过环境变量进行动态配置。这使得部署更加灵活，支持不同的环境（开发、测试、生产）使用不同的配置值，而无需修改代码。

建议在生产环境中严格管理敏感配置（COS密钥、API Key），并结合持久化卷与合理的过期策略提升可靠性与性能。对于模板系统的维护，建议定期备份模板文件，并在升级时验证双文件结构的完整性。同时，根据实际使用情况调整 DOWNLOAD_FILE_SIZE_LIMIT 参数，确保系统能够处理预期的文件大小。

附录

• 常见配置场景示例
  • 本地开发：使用 docker-compose.example.yaml，DRAFT_URL/ DOWNLOAD_URL 指向 capcut-mate.jcaigc.cn，DRAFT_SAVE_PATH 指向本地剪映草稿目录，DOWNLOAD_FILE_SIZE_LIMIT=209715200（200MB）
  • 生产部署：使用 docker-compose.yaml，DRAFT_URL/ DOWNLOAD_URL 指向 HTTPS 域名，COS_* 通过环境变量注入，ENABLE_APIKEY=true，DOWNLOAD_FILE_SIZE_LIMIT=524288000（500MB）
  • 自定义贴纸：在 sticker.json 中新增条目，确保 image_url 可访问且尺寸合适
  • 文件大小限制：根据项目需求调整 DOWNLOAD_FILE_SIZE_LIMIT，如大型视频项目可设置为 1GB 或更高
  • 模板自定义：在 template/default2 目录下修改现有模板文件，或创建新的模板目录并更新 TEMPLATE_DIR 配置
  • 双文件模板使用：通过设置 script.dual_file_compatibility = True 启用双文件兼容模式，确保 draft_info.json 和 draft_content.json 同步更新
  • 环境变量配置：所有配置参数都可以通过对应的环境变量进行覆盖，如 DRAFT_URL、DOWNLOAD_URL、COS_SECRET_ID 等
• 接口文档： docs.jcaigc.cn
• 效果案例： www.jcaigc.cn/workflow
• 开源仓库： capcut-mate