# 配置与部署

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [跨平台部署配置](#跨平台部署配置)
7. [CI/CD与自动化部署](#cicd与自动化部署)
8. [依赖关系分析](#依赖关系分析)
9. [性能考虑](#性能考虑)
10. [故障排查指南](#故障排查指南)
11. [结论](#结论)
12. [附录](#附录)

## 简介
本文件面向运维与开发人员，系统性梳理 capcut-mate 的全局配置、环境变量、运行时参数与部署流程，覆盖本地与容器化部署、云渲染环境准备、腾讯云 COS 对象存储集成以及监控告警建议。文档同时给出生产环境最佳实践、性能优化与安全配置要点，帮助快速、稳定地上线与维护该服务。

本版本新增了基于最新Docker配置文件的环境变量优化说明，反映了TIP_URL配置的改进和README.md中部署流程的简化。

## 项目结构
capcut-mate 采用 Python + FastAPI 构建的服务，配合模板与贴纸资源，支持草稿生成与云端导出。关键目录与文件如下：
- 配置与常量：config.py
- 应用入口：main.py
- 容器化：Dockerfile、docker-compose.yaml、docker-compose.example.yaml
- 依赖声明：pyproject.toml、uv.lock
- 跨平台支持：src/pyJianYingDraft/__init__.py、src/utils/video_task_manager.py
- 云存储与计费：src/utils/cos.py、src/utils/points.py
- 贴纸与模板：config/sticker.json、template/default/*.json、template/default2/*.json
- 文档与示例：README.md、README.zh.md

```mermaid
graph TB
A["应用入口 main.py"] --> B["路由注册 src/router/*"]
A --> C["中间件 src/middlewares/*"]
A --> D["工具模块 src/utils/*"]
D --> E["COS上传 src/utils/cos.py"]
D --> F["积分校验/扣减 src/utils/points.py"]
D --> G["视频任务管理 src/utils/video_task_manager.py"]
H["跨平台支持 src/pyJianYingDraft/__init__.py"] --> G
I["配置常量 config.py"] --> A
J["依赖声明 pyproject.toml/uv.lock"] --> A
K["贴纸配置 config/sticker.json"] --> D
L["模板草稿 template/default/*.json"] --> D
M["模板草稿 template/default2/*.json"] --> D
N["部署配置 docker-compose.yaml"] --> O["容器编排"]
O --> P["Docker镜像"]
Q["文档示例 README.md"] --> R["一键部署流程"]
```


## 核心组件
- 全局配置与环境变量
 - 路径与下载相关：DRAFT_DIR、TEMP_DIR、DRAFT_URL、DOWNLOAD_URL、TIP_URL、STICKER_CONFIG_PATH、TEMPLATE_DIR
 - 云渲染必需：DRAFT_SAVE_PATH（剪映草稿保存路径）
 - COS 对象存储：COS_SECRET_ID、COS_SECRET_KEY、COS_BUCKET_NAME、COS_REGION
 - API Key 校验：ENABLE_APIKEY（默认启用）
- 应用入口与路由
 - FastAPI 应用初始化、路由注册、中间件注册、日志打印
- 容器化与编排
 - Dockerfile：基础镜像、uv 安装、工作目录、暴露端口、环境变量、启动命令
 - docker-compose.yaml：生产环境编排（挂载输出目录、时区、环境变量、资源限制、重启策略）
 - docker-compose.example.yaml：示例环境编排（生产环境参考配置）
- 跨平台支持
 - Windows平台：完整功能，包括UI自动化和剪映控制
 - Linux平台：基础功能，UI自动化相关功能不可用


## 架构总览
下图展示 capcut-mate 在容器中的运行架构，以及与外部系统的交互（COS、nginx、剪映导出）：

```mermaid
graph TB
subgraph "容器内"
 Svc["FastAPI 服务 main.py"]
 Utils["工具模块 cos.py / points.py / video_task_manager.py"]
 Cfg["配置常量 config.py"]
 Tpl["模板与贴纸 template/* / config/sticker.json"]
 CrossPlat["跨平台支持 pyJianYingDraft"]
end

subgraph "外部系统"
 COS["腾讯云 COS"]
 Nginx["静态资源服务 nginx"]
 Jianying["剪映导出流程"]
end

Svc --> Utils
Utils --> COS
Svc --> Tpl
Svc --> Cfg
Svc --> CrossPlat
CrossPlat --> Jianying
Svc <--> Nginx
```


## 详细组件分析

### 全局配置与环境变量
- 路径与下载
 - DRAFT_DIR、TEMP_DIR：草稿与临时文件目录
 - DRAFT_URL：草稿下载地址（默认指向线上域名）
 - DOWNLOAD_URL：将容器内路径/app/替换为该 URL，用于生成可访问的下载链接
 - TIP_URL：草稿提示页面URL，用于引导用户了解如何使用草稿功能
 - STICKER_CONFIG_PATH、TEMPLATE_DIR：贴纸与模板资源路径
- 云渲染必需
 - DRAFT_SAVE_PATH：剪映草稿保存路径（云渲染场景必配）
- COS 对象存储
 - COS_SECRET_ID、COS_SECRET_KEY、COS_BUCKET_NAME、COS_REGION：COS 客户端初始化所需凭据与桶信息
- API Key 校验
 - ENABLE_APIKEY：默认启用，用于开启基于 API Key 的鉴权与积分扣减

TIP_URL环境变量现在在生产环境和示例环境中都有明确的配置，确保用户能够正确访问草稿使用指南。


### 应用入口与中间件
- 应用初始化
 - 创建 FastAPI 实例，注册路由前缀与标签
 - 注册 PrepareMiddleware 与 ResponseMiddleware，打印路由清单
- 启动方式
 - 本地直接运行 uvicorn，监听 0.0.0.0:30000


### 容器化与编排
- Dockerfile
 - 基于 python:3.11-slim，安装 uv 并同步依赖
 - 工作目录 /app，拷贝 dist 与工具二进制
 - 暴露端口 30000，设置环境变量（PATH、HOME、UV_CACHE_DIR），以 uv run 启动
- docker-compose.yaml（生产）
 - 映射输出目录到宿主机，挂载时区
 - 设置 DRAFT_URL、DOWNLOAD_URL、TIP_URL 环境变量
 - 限制内存与 CPU，调整 OOM 优先级，重启策略 unless-stopped
- docker-compose.example.yaml（示例）
 - 提供生产环境参考配置，包含完整的环境变量设置
 - 适用于生产环境部署的完整示例

生产环境和示例环境都包含了TIP_URL的配置，确保在不同部署场景下都能正确显示草稿使用指南。


### 云存储与计费集成
- COS 上传
 - 初始化 CosConfig 与 CosS3Client
 - 上传文件至按"日期/小时/原文件名"组织的键
 - 生成带签名的临时下载 URL，默认有效期 1 天
- 积分校验与扣减
 - 通过远程 API 校验 apiKey 有效性
 - 成功后进行积分扣减，失败抛出自定义异常

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "FastAPI 接口"
participant COS as "COS 上传"
participant Points as "积分服务"
Client->>API : "提交任务请求"
API->>Points : "校验/扣减积分"
Points-->>API : "返回结果"
API->>COS : "上传产物到 COS"
COS-->>API : "返回上传结果"
API-->>Client : "返回带签名下载链接"
```


### 模板与贴纸资源
- 贴纸配置
 - config/sticker.json：包含大量贴纸元数据（图片、尺寸、类型等）
- 草稿模板
 - template/default/draft_info.json：基础画布与轨道配置
 - template/default2/draft_info.json：更丰富的素材与渲染配置


## 跨平台部署配置

### Windows平台部署
Windows平台提供完整功能，包括UI自动化和剪映控制：

#### 本地安装
```bash
# 使用uv安装（推荐）
uv sync

# 或者使用pip安装
pip install -e .[windows]
```

#### Docker部署（Windows）
```dockerfile
FROM python:3.11-windowsservercore-ltsc2022

WORKDIR /app
COPY . .

# 安装完整依赖
RUN pip install -e .[windows]

EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### Linux平台部署
Linux平台提供基础功能，UI自动化相关功能不可用：

#### 本地安装
```bash
# 使用uv安装（推荐）
uv sync

# 或者使用pip安装
pip install -e .
```

#### Docker部署（Linux）
```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .

# 安装基础依赖
RUN pip install -e .

EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### 功能差异对比
| 功能 | Windows平台 | Linux平台 |
|------|-------------|-----------|
| API服务功能 | ✅ 完整支持 | ✅ 完整支持 |
| 草稿管理 | ✅ 支持 | ✅ 支持 |
| 素材处理 | ✅ 支持 | ✅ 支持 |
| 视频自动导出 | ✅ 支持 | ❌ 不支持 |
| UI界面操作 | ✅ 支持 | ❌ 不支持 |
| 剪映应用控制 | ✅ 支持 | ❌ 不支持 |


## CI/CD与自动化部署

### GitHub Actions工作流
项目使用GitHub Actions进行自动化构建和部署：

#### Docker镜像构建（dev.yml）
- 使用 `astral-sh/setup-uv@v2` 安装uv环境
- 采用 `uv sync` 只安装基础依赖，避免平台特定依赖冲突
- 构建并推送Docker镜像到Docker Hub

#### 桌面客户端多平台构建（desktop-client-dev.yml）
- 支持Windows、macOS (ARM64/Intel) 多平台构建
- 使用Electron 22和Node.js 22
- 自动构建安装包和绿色安装包

```mermaid
flowchart TD
A["代码推送"] --> B["GitHub Actions触发"]
B --> C["安装uv环境"]
C --> D["安装基础依赖 (uv sync)"]
D --> E["准备生产环境文件"]
E --> F["构建Docker镜像"]
F --> G["推送Docker Hub"]
H["PR触发"] --> I["跳过登录和推送"]
```


### 依赖管理策略
项目采用uv作为包管理器，具有以下优势：
- 更快的依赖解析和安装速度
- 更好的缓存机制
- 支持锁定文件（uv.lock）
- 跨平台兼容性更好


## 依赖关系分析
- 运行时依赖
 - FastAPI、uvicorn、cos-python-sdk-v5、pymediainfo、requests 等
 - Windows特定依赖：pywin32、uiautomation（通过可选依赖提供）
- 组件耦合
 - main.py 依赖路由、中间件与控制器；工具模块依赖配置常量；COS 与积分模块独立但被业务流程调用
 - 跨平台模块通过条件导入实现平台差异化

```mermaid
graph LR
Main["main.py"] --> Router["路由模块"]
Main --> MW["中间件"]
Main --> Utils["工具模块"]
Utils --> Cfg["config.py"]
Utils --> COS["cos.py"]
Utils --> Points["points.py"]
Utils --> VTM["video_task_manager.py"]
VTM --> PYJD["pyJianYingDraft"]
PYJD --> WinDep["Windows依赖 (可选)"]
Cfg --> COS
Cfg --> Points
```


## 性能考虑
- 容器资源限制
 - 生产环境建议根据并发与媒体处理负载设置合理的 mem_limit、memswap_limit 与 cpus
 - OOM 优先级可适度调整，避免关键进程被系统回收
- 并发与线程
 - CMD 中 workers 数量可根据 CPU 核心数与 I/O 密集度调整
- I/O 与缓存
 - 输出目录与临时目录挂载到高性能磁盘，避免频繁跨卷拷贝
 - 使用 UV_CACHE_DIR 缓存依赖，提升容器启动速度
- 网络与存储
 - COS 上传尽量选择就近地域，减少网络抖动对导出时延的影响
- 跨平台性能
 - Windows平台的UI自动化功能比Linux平台性能更好
 - Linux平台适合纯API服务场景，避免UI相关开销

## 故障排查指南
- 启动与端口
 - 确认容器已暴露 30000 端口且未被占用
 - 查看容器日志，定位中间件与路由注册阶段的异常
- 路由与鉴权
 - 若启用 API Key 校验，请确认 ENABLE_APIKEY 与上游积分服务连通
 - 校验失败通常会触发自定义异常，检查积分服务返回码
- COS 上传
 - 检查 COS 凭据是否正确、桶是否存在、地域是否匹配
 - 上传失败会记录错误日志并抛出自定义异常
- 剪映导出
 - 云渲染场景需确保 DRAFT_SAVE_PATH 正确指向剪映草稿目录
 - 如出现导出窗口无法激活，检查系统自动化依赖与权限
 - Linux平台无法使用自动导出功能，需要手动导出
- 跨平台问题
 - Windows平台缺少pywin32或uiautomation时，系统会优雅降级
 - 确保使用正确的安装方式：`pip install -e .[windows]` 或 `pip install -e .`
- 环境变量问题
 - TIP_URL未正确配置会导致草稿创建时无法显示使用指南
 - 确保在docker-compose中正确设置了TIP_URL环境变量


## 结论
通过统一的配置常量、清晰的容器化编排、完善的云存储/计费集成以及跨平台支持，capcut-mate 能够在本地与生产环境中稳定运行。最新的CI/CD流程采用uv包管理器和平台无关的依赖安装策略，大大提升了部署效率和稳定性。最新的环境变量配置优化确保了TIP_URL在不同部署场景下的正确设置，为用户提供更好的使用体验。建议在生产中结合资源限制、网络优化与监控告警，持续迭代性能与可靠性。

## 附录

### A. 全局配置项与环境变量对照表
- 路径与下载
 - DRAFT_DIR：草稿目录
 - TEMP_DIR：临时目录
 - DRAFT_URL：草稿下载地址
 - DOWNLOAD_URL：容器内路径转外链的基础 URL
 - TIP_URL：草稿提示页URL
 - STICKER_CONFIG_PATH：贴纸配置文件路径
 - TEMPLATE_DIR：模板目录路径
- 云渲染必需
 - DRAFT_SAVE_PATH：剪映草稿保存路径
- COS 对象存储
 - COS_SECRET_ID、COS_SECRET_KEY、COS_BUCKET_NAME、COS_REGION
- API Key 校验
 - ENABLE_APIKEY：默认启用

新增TIP_URL配置项，用于提供草稿使用指南的访问链接。


### B. 环境变量与编排示例
- 生产编排（docker-compose.yaml）
 - 端口映射：30000:30000
 - 挂载输出目录与系统时区
 - 环境变量：DRAFT_URL、DOWNLOAD_URL、TIP_URL
 - 资源限制：mem_limit、memswap_limit、cpus
 - OOM 优先级：oom_score_adj
 - 重启策略：unless-stopped
- 示例编排（docker-compose.example.yaml）
 - 提供生产环境完整配置示例
 - 包含所有必要环境变量的设置
 - 适用于生产环境部署参考

两个编排文件都包含了TIP_URL环境变量的配置，确保在不同部署场景下都能正确显示草稿使用指南。


### C. 云渲染环境搭建与监控告警建议
- 云渲染环境搭建
 - 安装并运行剪映专业版，确保可导出草稿
 - 配置 DRAFT_SAVE_PATH 指向剪映草稿目录
 - 配置 ENABLE_APIKEY 为 true，接入积分服务
- COS 对象存储集成
 - 配置 COS_SECRET_ID、COS_SECRET_KEY、COS_BUCKET_NAME、COS_REGION
 - 上传产物后生成带签名的临时下载链接
- 监控告警
 - 建议对以下指标进行监控：容器 CPU/内存使用率、COS 上传成功率与耗时、积分服务可用性、导出任务时延
 - 告警阈值应结合业务峰值与 SLA 设定


### D. 跨平台部署最佳实践
- Windows平台
 - 使用 `pip install -e .[windows]` 安装完整依赖
 - 确保系统具备UI自动化能力
 - 适合需要自动导出功能的场景
- Linux平台
 - 使用 `pip install -e .` 安装基础依赖
 - 适合纯API服务场景
 - 无法使用自动导出功能
- Docker部署
 - Windows Docker镜像：`python:3.11-windowsservercore-ltsc2022`
 - Linux Docker镜像：`python:3.11-slim`
 - 确保选择与目标平台匹配的镜像


### E. CI/CD自动化部署流程
- 依赖安装策略
 - 使用 `uv sync` 只安装基础依赖，避免平台特定依赖冲突
 - 通过可选依赖提供Windows特定功能
- 多平台构建
 - GitHub Actions支持Windows、macOS (ARM64/Intel) 多平台
 - 自动构建安装包和绿色安装包
- Docker镜像管理
 - 自动提取镜像标签并推送Docker Hub
 - 支持分支、标签、SHA等多种标签策略


### F. 一键部署流程优化
基于README.md中的部署说明优化

项目提供了简化的部署流程，支持一键部署：

#### 快速部署（推荐）
```bash
git clone https://github.com/Hommy-master/capcut-mate.git
cd capcut-mate
docker-compose pull && docker-compose up -d
```

部署完成后，访问 http://localhost:30000/docs 查看API文档。


### G. TIP_URL环境变量配置详解
基于最新配置文件的环境变量分析

TIP_URL环境变量用于提供草稿使用指南的访问链接，在以下场景中发挥作用：

- 草稿创建接口返回的响应中包含tip_url字段
- 用户在创建草稿时可以访问相关的使用指南
- 支持自定义草稿使用指南的URL

配置方式：
- 默认值：`https://docs.jcaigc.cn/`
- 生产环境：可在docker-compose中自定义设置
- 示例配置：`- TIP_URL=https://docs.jcaigc.cn`

本文件面向运维与开发人员，系统性梳理 capcut-mate 的全局配置、环境变量、运行时参数与部署流程，覆盖本地与容器化部署、云渲染环境准备、腾讯云 COS 对象存储集成以及监控告警建议。文档同时给出生产环境最佳实践、性能优化与安全配置要点，帮助快速、稳定地上线与维护该服务。

【开源剪映小助手】配置与部署

后端

音视频

运维

CapCut-Mate配置部署指南：Python+FastAPI构建的视频处理服务，支持草稿生成与云端导出。提供Windows/Linux跨平台部署方案，集成腾讯云COS存储与APIKey鉴权。包含Docker容器化配置、CI/CD自动化流程及生产环境最佳实践，优化TIP_URL配置提升用户体验。

对象存储

包管理器

容器编排

媒体处理

云存储

中间件

云渲染

Windows

Docker

容器

路由

Python

Linux

对象存储COS新用户低至1元！


2026采购季 | AI焕新·智启新局

crtr

message-queue-catalog

domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【开源剪映小助手】配置与部署-腾讯云开发者社区-腾讯云

【开源剪映小助手】配置与部署

【开源剪映小助手】配置与部署

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐