AutoClip AI 视频切片项目快速上手指南从环境搭建到前后端联调【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址: https://gitcode.com/GitHub_Trending/autoc/autoclip本文是 AutoClipAI 智能视频切片与高光提取系统的快速开始指南覆盖开发环境搭建、后端 FastAPI 与前端 React 的启动联调、新增路由/模型/服务的二次开发范式、数据库迁移、测试与 Docker 部署等完整流程。读者按本文操作可以在一台机器上从零跑通「长视频 → 自动切片 → 智能合集」的核心链路并掌握向该项目贡献代码的基本方法。项目简介与重构目标AutoClip 是一个基于 AI 的视频自动切片工具能够将长视频自动切分为多个精彩片段并进一步聚合生成智能合集。当前仓库正在进行一次面向现代化后端架构的重构重构目标集中在三个方面数据持久化引入 SQLite SQLAlchemy 管理数据替代原先的临时内存状态服务模块化重构 FastAPI 应用实现服务模块化管理业务逻辑从路由层下沉到独立的services层任务调度打通前后端的任务调度系统借助 Celery Redis 实现异步处理与实时进度反馈。从源码可以印证这三项目标均已落地数据库引擎与会话管理集中在 backend/core/database.py所有模型统一继承 backend/models/base.py 中的Base/BaseModelFastAPI 应用通过 backend/app_factory.py 的create_app()工厂函数创建路由统一注册在 backend/api/v1/init.pyCelery 任务队列与任务路由配置位于 backend/core/celery_app.py。项目结构总览仓库顶层目录结构如下autoclip/ ├── backend/ # 后端服务 │ ├── app/ # FastAPI应用 │ ├── api/ # API路由v1 版本路由 │ ├── core/ # 核心模块配置、数据库、Celery │ ├── models/ # 数据模型SQLAlchemy ORM │ ├── services/ # 业务服务 │ ├── tasks/ # Celery 任务队列 │ ├── pipeline/ # 切片处理流水线大纲→时间线→评分→视频 │ ├── prompt/ # 各内容类型的 AI 提示词 │ └── utils/ # 工具函数 ├── frontend/ # 前端应用React TypeScript Vite ├── shared/ # 共享代码 ├── docs/ # 文档 ├── data/ # 数据文件数据库、上传、输出 └── scripts/ # 启动/构建脚本需要说明的是实际仓库的backend下还细分出了pipeline/六步切片流水线、prompt/业务、知识科普、娱乐、演讲等分类提示词与utils/下载、FFmpeg、字幕、缩略图等工具等目录比文档初版的结构图更完整frontend/src/内则按components/、pages/、services/、stores/组织 React 代码。开发环境准备必需工具工具版本要求说明Python3.10推荐 3.11yt-dlp 等核心依赖已不支持 3.9Node.js16推荐 18前端构建与开发服务器Redis6.0推荐 7.0Celery 的 broker 与结果后端FFmpeg最新稳定版视频切片、转码的核心依赖Git任意较新版本版本管理从 requirements.txt 可以看到后端依赖采用精确锁定版本fastapi0.141.1、sqlalchemy2.0.52、celery[redis]5.6.3、yt-dlp2026.8.19等保证 CI、Docker 镜像与桌面端打包安装的是同一套依赖避免「本机可用、发布后损坏」的问题。安装步骤克隆项目并进入目录git clone repository-url cd autoclip后端环境设置基于 Poetrycd backend # 安装Poetry (如果未安装) curl -sSL https://install.python-poetry.org | python3 - # 安装依赖 poetry install # 激活虚拟环境 poetry shell备选方案当前仓库同时维护了requirements.txt与pyproject.toml。按 pyproject.toml 的说明运行依赖以 requirements.txt 为准桌面端 / Docker / CI 都用它开发者也可以改用pip install -r requirements.txt pip install -e .的方式安装——后者还会在环境中注册autoclip与autoclip-mcp两个命令行入口。前端环境设置cd frontend npm install前端依赖可见 frontend/package.jsonReact 18 TypeScript 5 Vite 5UI 组件库为 Ant Design 5状态管理使用 Zustand视频播放使用 react-player拖拽排序使用 react-beautiful-dnd。启动 Redis# macOS brew install redis brew services start redis # Ubuntu sudo apt-get install redis-server sudo systemctl start redis快速启动前后端联调1. 启动后端服务cd backend poetry run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000后端入口是 backend/main.py它调用create_app(modeweb)创建应用实例启动时startup事件会自动完成数据库建表、加载 API 密钥等初始化工作。应用工厂中注册了全局异常处理器、CORS 中间件与/health、/api/health等健康检查端点详见 backend/app_factory.py。2. 启动前端服务cd frontend npm run dev3. 访问应用前端界面http://localhost:3000后端 APIhttp://localhost:8000API 文档Swagger UIhttp://localhost:8000/docsReDoc 文档http://localhost:8000/redoc后端/docs与/redoc由 FastAPI 自动生成可在浏览器中直接交互调试全部 API 端点。补充Celery Worker 的启动任务调度系统依赖 Celery Worker 消费队列。仓库 README 特别强调启动 Worker必须带-Q指定队列因为任务按 backend/core/celery_app.py 中的task_routes路由到了专用队列celery -A backend.core.celery_app worker --loglevelinfo -Q celery,processing,video,notification,upload如果不带-QWorker 只消费默认的celery队列流水线任务会一直堆积在processing队列中无人执行。定时任务每日凌晨 2 点清理过期任务、每 5 分钟健康检查由 beat 调度器触发celery -A backend.core.celery_app beat --loglevelinfo后端开发指南后端采用「路由层api→ 服务层services→ 数据层models/repositories」的分层结构。新功能开发遵循以下三步范式。添加新的 API 路由在backend/api/v1/下创建新的路由文件在 backend/api/v1/init.py 中导入并注册路由在backend/services/下实现对应的服务逻辑。示例# backend/api/v1/example.py from fastapi import APIRouter, Depends from sqlalchemy.orm import Session from backend.core.database import get_db from backend.services.example_service import ExampleService router APIRouter() router.get(/example) async def get_example(db: Session Depends(get_db)): service ExampleService(db) return service.get_examples()路由的依赖注入get_db定义在 backend/core/database.py它从SessionLocal会话工厂创建会话请求结束后自动关闭。实际仓库中已注册的路由包括 projects、clips、collections、tasks、processing、bilibili、youtube、speech-recognition、subtitle-editor、upload、progress、pipeline、settings、upload-queue、account-health 等十余个模块新增路由后可仿照这些模块在api_router中统一注册。添加新的数据模型在backend/models/下创建新的模型文件继承Base类或带通用字段与时间戳的BaseModel并添加必要的字段运行数据库迁移。# backend/models/example.py from sqlalchemy import Column, String, DateTime from backend.models.base import Base, TimestampMixin class Example(Base, TimestampMixin): __tablename__ examples id Column(String(36), primary_keyTrue, indexTrue) name Column(String(255), nullableFalse) description Column(String(500))实际项目中模型基类 backend/models/base.py 提供了三件套TimestampMixin自动维护created_at/updated_at、BaseModel继承自Base并追加 UUID 主键id、to_dict()/update_from_dict()工具方法、generate_uuid()主键生成器。以项目模型 backend/models/project.py 为参照可以看到Project使用ProjectStatus/ProjectType枚举定义状态与类型并通过relationship与 Clip、Collection、Task 建立关联是新增模型时最直接的参考范本。添加新的服务在backend/services/下创建新的服务文件实现业务逻辑依赖注入Session添加错误处理和日志记录。# backend/services/example_service.py from sqlalchemy.orm import Session from backend.models.example import Example from backend.schemas.example import ExampleCreate class ExampleService: def __init__(self, db: Session): self.db db def create_example(self, example_data: ExampleCreate) - Example: example Example(**example_data.dict()) self.db.add(example) self.db.commit() self.db.refresh(example) return example注意当前项目 Pydantic 已升级到 v2见 requirements.txt 中pydantic2.13.5新增 schema 时建议使用 Pydantic v2 风格model_dump()替代dict()、model_validate()替代parse_obj()并参考 backend/schemas/ 下已有的 project/clip/collection/task/bilibili 等 schema 写法。前端开发指南添加新的页面在frontend/src/pages/下创建新的页面组件在路由配置中添加新页面在导航菜单中添加链接。// frontend/src/pages/ExamplePage.tsx import React from react; import { Card, Table } from antd; const ExamplePage: React.FC () { return ( Card title示例页面 Table / /Card ); }; export default ExamplePage;当前仓库的页面组件包括 HomePage.tsx、ProjectDetailPage.tsx、ProcessingPage.tsx、SettingsPage.tsx、UploadStatusPage.tsx 等组件化封装则集中在 frontend/src/components/。添加新的 API 调用在frontend/src/services/下添加 API 方法在组件中使用 API 调用添加错误处理和加载状态。// frontend/src/services/api.ts export const exampleApi { getExamples: async (): PromiseExample[] { const response await apiService.get(/examples); return response.data; }, createExample: async (data: ExampleCreate): PromiseExample { const response await apiService.post(/examples, data); return response.data; } };前端的 API 客户端基座位于 frontend/src/services/api.ts环境配置与请求工具分别位于 frontend/src/utils/apiConfig.ts 与 frontend/src/utils/apiUtils.ts新增接口时可复用其中的 axios 实例与错误处理逻辑。测试指南# 运行后端测试 cd backend poetry run pytest # 运行前端测试 cd frontend npm test # 运行端到端测试需要先启动所有服务 npm run test:e2e仓库在 backend/tests/ 下提供了丰富的后端测试用例pytest 配置见 backend/pytest.ini覆盖路径工具、本地预设、错误处理、失败流水线、处理框架、发布导出、仓库仓储层、任务提交、字幕处理器等多个模块可作为新增代码时编写测试的参照。数据库操作项目使用 SQLAlchemy 2.0 作为 ORM默认使用 SQLite文件库可平滑升级到 PostgreSQL。数据库引擎配置详见 backend/core/database.py其中包含若干重要的工程细节文件型 SQLite 采用默认连接池而非:memory:用的StaticPool并开启 WAL 日志模式与 30 秒 busy timeout避免多线程场景下 Session 共用一条连接导致的ObjectDeletedError、任务凭空消失等问题。cd backend # 创建迁移根据模型变更自动生成 alembic revision --autogenerate -m 描述变更 # 应用迁移 alembic upgrade head # 回滚一个版本 alembic downgrade -1 # 查看迁移历史 alembic history此外还可以直接运行python backend/init_db.py或python -m backend.core.database完成建表与连接测试。环境变量配置从 env.example 可以看到项目支持的全部环境变量其中核心几组如下# 数据库与 Redis DATABASE_URLsqlite:///./data/autoclip.db REDIS_URLredis://localhost:6379/0 # AI 模型DashScope / 通义千问默认为 qwen-plus LLM_PROVIDERdashscope API_DASHSCOPE_API_KEYyour_dashscope_api_key API_MODEL_NAMEqwen-plus API_MAX_TOKENS4096 API_TIMEOUT30 # 处理参数 PROCESSING_CHUNK_SIZE5000 PROCESSING_MIN_SCORE_THRESHOLD0.7 PROCESSING_MAX_CLIPS_PER_COLLECTION5 PROCESSING_MAX_RETRIES3 # 日志与运行环境 LOG_LEVELINFO LOG_FORMAT%(asctime)s - %(name)s - %(levelname)s - %(message)s LOG_FILEbackend.log ENVIRONMENTdevelopment DEBUGtrue这些变量的解析统一收敛在 backend/core/config.py 的 pydantic-settingsSettings类中自动读取.env文件忽略未声明键并通过get_model_config()、get_processing_config()、get_logging_config()等函数向各模块分发。除 DashScope 外项目还支持 OpenAI 兼容接口、Gemini、硅基流动以及 Ollama / LM Studio 本地模型详见 docs/MULTI_LLM_PROVIDER_GUIDE.md。常用命令速查开发命令# 启动后端开发服务器支持热重载 poetry run uvicorn app.main:app --reload # 启动前端开发服务器 npm run dev # 构建前端产物 npm run build # 运行测试 poetry run pytest npm test数据库命令# 创建迁移 alembic revision --autogenerate -m 描述 # 应用迁移 alembic upgrade head # 查看迁移历史 alembic history部署命令# 构建Docker镜像 docker build -t autoclip . # 运行Docker容器映射 8000 端口 docker run -p 8000:8000 autoclip仓库还提供了更方便的一键脚本见 README.md./docker-start.shDocker 一键启动、./start_autoclip.sh本地一键启动含完整检查和监控、./quick_start.sh快速启动、./status_autoclip.sh/./docker-status.sh状态检查、./stop_autoclip.sh/./docker-stop.sh停止服务以及 Dockerfile 与 docker-compose.yml / docker-compose.dev.yml。常见问题排查1. 数据库连接失败问题无法连接到数据库。解决方案检查数据库文件是否存在默认路径data/autoclip.db确认数据库文件权限设置检查DATABASE_URL连接字符串是否指向正确路径。深度排查可运行python -m backend.core.database直接测试连接并初始化数据库若为文件型 SQLite确认磁盘有写入权限。2. Redis 连接失败问题Celery 无法连接到 Redis。解决方案确认 Redis 服务正在运行redis-cli ping应返回PONG检查REDIS_URL连接配置默认redis://localhost:6379/0确认 Redis 端口未被占用。3. 前端构建失败问题npm run build失败。解决方案清除node_modules并重新安装检查 TypeScript 类型错误可运行npm run typecheck确认所有依赖都已安装。4. API 调用失败问题前端无法调用后端 API。解决方案确认后端服务正在运行访问 http://localhost:8000/health 检查检查 CORS 配置backend/app_factory.py 中的CORSMiddleware生产环境需将allow_origins收敛为具体域名验证 API 端点路径对照 Swagger UI http://localhost:8000/docs 中实际注册的路径。获取帮助与下一步文档资源项目维护了完善的技术文档体系与本文相关的有 docs/PROJECT_MANAGEMENT.md项目管理、docs/BACKEND_ARCHITECTURE.md后端架构、docs/SYSTEM_ARCHITECTURE.md系统架构、docs/CLI_AND_MCP.mdCLI 与 MCP、docs/DEVELOPER_GUIDE.md开发者指南、docs/DOCKER.mdDocker 部署、docs/QUICK_REFERENCE.md快速参考。问题反馈可在仓库创建 Issue、联系项目维护者或查看项目 Wiki。下一步行动清单熟悉项目结构阅读 README.md 与backend/、frontend/下代码设置开发环境按本文步骤配置 Python、Node、Redis、FFmpeg 环境运行示例启动前后端服务通过 Web 界面新建项目、下载/上传视频并触发处理流程开始开发从backend/api/v1/、backend/services/、frontend/src/pages/中挑选工作项开始提交代码遵循项目的代码规范后端 PEP 8、前端 ESLint TypeScript提交信息使用约定式提交格式。文档版本1.0 创建日期2024年12月 最后更新2024年12月说明本文基于docs/QUICK_START_GUIDE.md整理编写并结合当前仓库源码入口、配置、数据库、Celery、路由注册、环境变量示例、依赖清单等补充了可验证的实现细节与进阶指引文档中的外链技术文档FastAPI / SQLAlchemy / Celery / React 官方文档可在对应官网查阅。【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址: https://gitcode.com/GitHub_Trending/autoc/autoclip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AutoClip AI 视频切片项目快速上手指南：从环境搭建到前后端联调
AutoClip AI 视频切片项目快速上手指南从环境搭建到前后端联调【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址: https://gitcode.com/GitHub_Trending/autoc/autoclip本文是 AutoClipAI 智能视频切片与高光提取系统的快速开始指南覆盖开发环境搭建、后端 FastAPI 与前端 React 的启动联调、新增路由/模型/服务的二次开发范式、数据库迁移、测试与 Docker 部署等完整流程。读者按本文操作可以在一台机器上从零跑通「长视频 → 自动切片 → 智能合集」的核心链路并掌握向该项目贡献代码的基本方法。项目简介与重构目标AutoClip 是一个基于 AI 的视频自动切片工具能够将长视频自动切分为多个精彩片段并进一步聚合生成智能合集。当前仓库正在进行一次面向现代化后端架构的重构重构目标集中在三个方面数据持久化引入 SQLite SQLAlchemy 管理数据替代原先的临时内存状态服务模块化重构 FastAPI 应用实现服务模块化管理业务逻辑从路由层下沉到独立的services层任务调度打通前后端的任务调度系统借助 Celery Redis 实现异步处理与实时进度反馈。从源码可以印证这三项目标均已落地数据库引擎与会话管理集中在 backend/core/database.py所有模型统一继承 backend/models/base.py 中的Base/BaseModelFastAPI 应用通过 backend/app_factory.py 的create_app()工厂函数创建路由统一注册在 backend/api/v1/init.pyCelery 任务队列与任务路由配置位于 backend/core/celery_app.py。项目结构总览仓库顶层目录结构如下autoclip/ ├── backend/ # 后端服务 │ ├── app/ # FastAPI应用 │ ├── api/ # API路由v1 版本路由 │ ├── core/ # 核心模块配置、数据库、Celery │ ├── models/ # 数据模型SQLAlchemy ORM │ ├── services/ # 业务服务 │ ├── tasks/ # Celery 任务队列 │ ├── pipeline/ # 切片处理流水线大纲→时间线→评分→视频 │ ├── prompt/ # 各内容类型的 AI 提示词 │ └── utils/ # 工具函数 ├── frontend/ # 前端应用React TypeScript Vite ├── shared/ # 共享代码 ├── docs/ # 文档 ├── data/ # 数据文件数据库、上传、输出 └── scripts/ # 启动/构建脚本需要说明的是实际仓库的backend下还细分出了pipeline/六步切片流水线、prompt/业务、知识科普、娱乐、演讲等分类提示词与utils/下载、FFmpeg、字幕、缩略图等工具等目录比文档初版的结构图更完整frontend/src/内则按components/、pages/、services/、stores/组织 React 代码。开发环境准备必需工具工具版本要求说明Python3.10推荐 3.11yt-dlp 等核心依赖已不支持 3.9Node.js16推荐 18前端构建与开发服务器Redis6.0推荐 7.0Celery 的 broker 与结果后端FFmpeg最新稳定版视频切片、转码的核心依赖Git任意较新版本版本管理从 requirements.txt 可以看到后端依赖采用精确锁定版本fastapi0.141.1、sqlalchemy2.0.52、celery[redis]5.6.3、yt-dlp2026.8.19等保证 CI、Docker 镜像与桌面端打包安装的是同一套依赖避免「本机可用、发布后损坏」的问题。安装步骤克隆项目并进入目录git clone repository-url cd autoclip后端环境设置基于 Poetrycd backend # 安装Poetry (如果未安装) curl -sSL https://install.python-poetry.org | python3 - # 安装依赖 poetry install # 激活虚拟环境 poetry shell备选方案当前仓库同时维护了requirements.txt与pyproject.toml。按 pyproject.toml 的说明运行依赖以 requirements.txt 为准桌面端 / Docker / CI 都用它开发者也可以改用pip install -r requirements.txt pip install -e .的方式安装——后者还会在环境中注册autoclip与autoclip-mcp两个命令行入口。前端环境设置cd frontend npm install前端依赖可见 frontend/package.jsonReact 18 TypeScript 5 Vite 5UI 组件库为 Ant Design 5状态管理使用 Zustand视频播放使用 react-player拖拽排序使用 react-beautiful-dnd。启动 Redis# macOS brew install redis brew services start redis # Ubuntu sudo apt-get install redis-server sudo systemctl start redis快速启动前后端联调1. 启动后端服务cd backend poetry run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000后端入口是 backend/main.py它调用create_app(modeweb)创建应用实例启动时startup事件会自动完成数据库建表、加载 API 密钥等初始化工作。应用工厂中注册了全局异常处理器、CORS 中间件与/health、/api/health等健康检查端点详见 backend/app_factory.py。2. 启动前端服务cd frontend npm run dev3. 访问应用前端界面http://localhost:3000后端 APIhttp://localhost:8000API 文档Swagger UIhttp://localhost:8000/docsReDoc 文档http://localhost:8000/redoc后端/docs与/redoc由 FastAPI 自动生成可在浏览器中直接交互调试全部 API 端点。补充Celery Worker 的启动任务调度系统依赖 Celery Worker 消费队列。仓库 README 特别强调启动 Worker必须带-Q指定队列因为任务按 backend/core/celery_app.py 中的task_routes路由到了专用队列celery -A backend.core.celery_app worker --loglevelinfo -Q celery,processing,video,notification,upload如果不带-QWorker 只消费默认的celery队列流水线任务会一直堆积在processing队列中无人执行。定时任务每日凌晨 2 点清理过期任务、每 5 分钟健康检查由 beat 调度器触发celery -A backend.core.celery_app beat --loglevelinfo后端开发指南后端采用「路由层api→ 服务层services→ 数据层models/repositories」的分层结构。新功能开发遵循以下三步范式。添加新的 API 路由在backend/api/v1/下创建新的路由文件在 backend/api/v1/init.py 中导入并注册路由在backend/services/下实现对应的服务逻辑。示例# backend/api/v1/example.py from fastapi import APIRouter, Depends from sqlalchemy.orm import Session from backend.core.database import get_db from backend.services.example_service import ExampleService router APIRouter() router.get(/example) async def get_example(db: Session Depends(get_db)): service ExampleService(db) return service.get_examples()路由的依赖注入get_db定义在 backend/core/database.py它从SessionLocal会话工厂创建会话请求结束后自动关闭。实际仓库中已注册的路由包括 projects、clips、collections、tasks、processing、bilibili、youtube、speech-recognition、subtitle-editor、upload、progress、pipeline、settings、upload-queue、account-health 等十余个模块新增路由后可仿照这些模块在api_router中统一注册。添加新的数据模型在backend/models/下创建新的模型文件继承Base类或带通用字段与时间戳的BaseModel并添加必要的字段运行数据库迁移。# backend/models/example.py from sqlalchemy import Column, String, DateTime from backend.models.base import Base, TimestampMixin class Example(Base, TimestampMixin): __tablename__ examples id Column(String(36), primary_keyTrue, indexTrue) name Column(String(255), nullableFalse) description Column(String(500))实际项目中模型基类 backend/models/base.py 提供了三件套TimestampMixin自动维护created_at/updated_at、BaseModel继承自Base并追加 UUID 主键id、to_dict()/update_from_dict()工具方法、generate_uuid()主键生成器。以项目模型 backend/models/project.py 为参照可以看到Project使用ProjectStatus/ProjectType枚举定义状态与类型并通过relationship与 Clip、Collection、Task 建立关联是新增模型时最直接的参考范本。添加新的服务在backend/services/下创建新的服务文件实现业务逻辑依赖注入Session添加错误处理和日志记录。# backend/services/example_service.py from sqlalchemy.orm import Session from backend.models.example import Example from backend.schemas.example import ExampleCreate class ExampleService: def __init__(self, db: Session): self.db db def create_example(self, example_data: ExampleCreate) - Example: example Example(**example_data.dict()) self.db.add(example) self.db.commit() self.db.refresh(example) return example注意当前项目 Pydantic 已升级到 v2见 requirements.txt 中pydantic2.13.5新增 schema 时建议使用 Pydantic v2 风格model_dump()替代dict()、model_validate()替代parse_obj()并参考 backend/schemas/ 下已有的 project/clip/collection/task/bilibili 等 schema 写法。前端开发指南添加新的页面在frontend/src/pages/下创建新的页面组件在路由配置中添加新页面在导航菜单中添加链接。// frontend/src/pages/ExamplePage.tsx import React from react; import { Card, Table } from antd; const ExamplePage: React.FC () { return ( Card title示例页面 Table / /Card ); }; export default ExamplePage;当前仓库的页面组件包括 HomePage.tsx、ProjectDetailPage.tsx、ProcessingPage.tsx、SettingsPage.tsx、UploadStatusPage.tsx 等组件化封装则集中在 frontend/src/components/。添加新的 API 调用在frontend/src/services/下添加 API 方法在组件中使用 API 调用添加错误处理和加载状态。// frontend/src/services/api.ts export const exampleApi { getExamples: async (): PromiseExample[] { const response await apiService.get(/examples); return response.data; }, createExample: async (data: ExampleCreate): PromiseExample { const response await apiService.post(/examples, data); return response.data; } };前端的 API 客户端基座位于 frontend/src/services/api.ts环境配置与请求工具分别位于 frontend/src/utils/apiConfig.ts 与 frontend/src/utils/apiUtils.ts新增接口时可复用其中的 axios 实例与错误处理逻辑。测试指南# 运行后端测试 cd backend poetry run pytest # 运行前端测试 cd frontend npm test # 运行端到端测试需要先启动所有服务 npm run test:e2e仓库在 backend/tests/ 下提供了丰富的后端测试用例pytest 配置见 backend/pytest.ini覆盖路径工具、本地预设、错误处理、失败流水线、处理框架、发布导出、仓库仓储层、任务提交、字幕处理器等多个模块可作为新增代码时编写测试的参照。数据库操作项目使用 SQLAlchemy 2.0 作为 ORM默认使用 SQLite文件库可平滑升级到 PostgreSQL。数据库引擎配置详见 backend/core/database.py其中包含若干重要的工程细节文件型 SQLite 采用默认连接池而非:memory:用的StaticPool并开启 WAL 日志模式与 30 秒 busy timeout避免多线程场景下 Session 共用一条连接导致的ObjectDeletedError、任务凭空消失等问题。cd backend # 创建迁移根据模型变更自动生成 alembic revision --autogenerate -m 描述变更 # 应用迁移 alembic upgrade head # 回滚一个版本 alembic downgrade -1 # 查看迁移历史 alembic history此外还可以直接运行python backend/init_db.py或python -m backend.core.database完成建表与连接测试。环境变量配置从 env.example 可以看到项目支持的全部环境变量其中核心几组如下# 数据库与 Redis DATABASE_URLsqlite:///./data/autoclip.db REDIS_URLredis://localhost:6379/0 # AI 模型DashScope / 通义千问默认为 qwen-plus LLM_PROVIDERdashscope API_DASHSCOPE_API_KEYyour_dashscope_api_key API_MODEL_NAMEqwen-plus API_MAX_TOKENS4096 API_TIMEOUT30 # 处理参数 PROCESSING_CHUNK_SIZE5000 PROCESSING_MIN_SCORE_THRESHOLD0.7 PROCESSING_MAX_CLIPS_PER_COLLECTION5 PROCESSING_MAX_RETRIES3 # 日志与运行环境 LOG_LEVELINFO LOG_FORMAT%(asctime)s - %(name)s - %(levelname)s - %(message)s LOG_FILEbackend.log ENVIRONMENTdevelopment DEBUGtrue这些变量的解析统一收敛在 backend/core/config.py 的 pydantic-settingsSettings类中自动读取.env文件忽略未声明键并通过get_model_config()、get_processing_config()、get_logging_config()等函数向各模块分发。除 DashScope 外项目还支持 OpenAI 兼容接口、Gemini、硅基流动以及 Ollama / LM Studio 本地模型详见 docs/MULTI_LLM_PROVIDER_GUIDE.md。常用命令速查开发命令# 启动后端开发服务器支持热重载 poetry run uvicorn app.main:app --reload # 启动前端开发服务器 npm run dev # 构建前端产物 npm run build # 运行测试 poetry run pytest npm test数据库命令# 创建迁移 alembic revision --autogenerate -m 描述 # 应用迁移 alembic upgrade head # 查看迁移历史 alembic history部署命令# 构建Docker镜像 docker build -t autoclip . # 运行Docker容器映射 8000 端口 docker run -p 8000:8000 autoclip仓库还提供了更方便的一键脚本见 README.md./docker-start.shDocker 一键启动、./start_autoclip.sh本地一键启动含完整检查和监控、./quick_start.sh快速启动、./status_autoclip.sh/./docker-status.sh状态检查、./stop_autoclip.sh/./docker-stop.sh停止服务以及 Dockerfile 与 docker-compose.yml / docker-compose.dev.yml。常见问题排查1. 数据库连接失败问题无法连接到数据库。解决方案检查数据库文件是否存在默认路径data/autoclip.db确认数据库文件权限设置检查DATABASE_URL连接字符串是否指向正确路径。深度排查可运行python -m backend.core.database直接测试连接并初始化数据库若为文件型 SQLite确认磁盘有写入权限。2. Redis 连接失败问题Celery 无法连接到 Redis。解决方案确认 Redis 服务正在运行redis-cli ping应返回PONG检查REDIS_URL连接配置默认redis://localhost:6379/0确认 Redis 端口未被占用。3. 前端构建失败问题npm run build失败。解决方案清除node_modules并重新安装检查 TypeScript 类型错误可运行npm run typecheck确认所有依赖都已安装。4. API 调用失败问题前端无法调用后端 API。解决方案确认后端服务正在运行访问 http://localhost:8000/health 检查检查 CORS 配置backend/app_factory.py 中的CORSMiddleware生产环境需将allow_origins收敛为具体域名验证 API 端点路径对照 Swagger UI http://localhost:8000/docs 中实际注册的路径。获取帮助与下一步文档资源项目维护了完善的技术文档体系与本文相关的有 docs/PROJECT_MANAGEMENT.md项目管理、docs/BACKEND_ARCHITECTURE.md后端架构、docs/SYSTEM_ARCHITECTURE.md系统架构、docs/CLI_AND_MCP.mdCLI 与 MCP、docs/DEVELOPER_GUIDE.md开发者指南、docs/DOCKER.mdDocker 部署、docs/QUICK_REFERENCE.md快速参考。问题反馈可在仓库创建 Issue、联系项目维护者或查看项目 Wiki。下一步行动清单熟悉项目结构阅读 README.md 与backend/、frontend/下代码设置开发环境按本文步骤配置 Python、Node、Redis、FFmpeg 环境运行示例启动前后端服务通过 Web 界面新建项目、下载/上传视频并触发处理流程开始开发从backend/api/v1/、backend/services/、frontend/src/pages/中挑选工作项开始提交代码遵循项目的代码规范后端 PEP 8、前端 ESLint TypeScript提交信息使用约定式提交格式。文档版本1.0 创建日期2024年12月 最后更新2024年12月说明本文基于docs/QUICK_START_GUIDE.md整理编写并结合当前仓库源码入口、配置、数据库、Celery、路由注册、环境变量示例、依赖清单等补充了可验证的实现细节与进阶指引文档中的外链技术文档FastAPI / SQLAlchemy / Celery / React 官方文档可在对应官网查阅。【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址: https://gitcode.com/GitHub_Trending/autoc/autoclip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考