mirror of
https://github.com/zhouxiaoka/autoclip.git
synced 2026-05-06 22:13:00 +08:00
8ee2d50044
- 修复WebSocketNotificationService.send_processing_progress方法参数不匹配问题 - 修复前端RealTimeStatus组件WebSocket消息处理逻辑 - 修复Celery Worker队列配置，确保任务正确路由到processing队列 - 修复Celery应用导入冲突，统一使用正确的celery_app配置 - 添加实时项目状态更新功能，前端无需手动刷新即可看到处理进度 - 完善系统启动脚本，修复PYTHONPATH未绑定变量错误 - 优化流水线处理逻辑，确保所有6个步骤正常执行 - 添加完整的项目文档和启动指南 测试结果： - WebSocket进度更新正常工作（16%, 33%, 100%） - 流水线处理完全正常（6个步骤全部成功） - 前端状态自动更新正常 - 项目状态正确同步到数据库
182 lines
6.2 KiB
Markdown
182 lines
6.2 KiB
Markdown
# AutoClip 系统架构说明
|
||
|
||
## 🏗️ 系统整体架构
|
||
|
||
AutoClip 是一个基于 Python + React 的视频自动切片和合集生成系统，采用前后端分离架构。
|
||
|
||
### **架构组件**
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ 前端 (React) │ │ 后端 (FastAPI) │ │ 文件系统 │
|
||
│ │ │ │ │ │
|
||
│ - 项目管理 │◄──►│ - API 服务 │◄──►│ - 项目文件 │
|
||
│ - 视频预览 │ │ - 业务逻辑 │ │ - 输出文件 │
|
||
│ - 状态监控 │ │ - 数据处理 │ │ - 元数据 │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
│
|
||
┌─────────────────┐
|
||
│ 数据库 (SQLite) │
|
||
│ │
|
||
│ - 项目信息 │
|
||
│ - 切片元数据 │
|
||
│ - 合集元数据 │
|
||
│ - 任务状态 │
|
||
└─────────────────┘
|
||
```
|
||
|
||
## 📁 数据存储架构
|
||
|
||
### **1. 数据库层 (SQLite)**
|
||
|
||
**核心表结构：**
|
||
- `projects`: 项目基本信息
|
||
- `clips`: 切片元数据
|
||
- `collections`: 合集元数据
|
||
- `tasks`: 处理任务状态
|
||
- `bilibili_accounts`: B站账号信息
|
||
- `upload_records`: 文件上传记录
|
||
|
||
**数据关系：**
|
||
```
|
||
projects (1) ──► (N) clips
|
||
projects (1) ──► (N) collections
|
||
projects (1) ──► (N) tasks
|
||
```
|
||
|
||
### **2. 文件系统层**
|
||
|
||
**目录结构：**
|
||
```
|
||
data/
|
||
├── projects/ # 项目原始文件
|
||
│ └── {project_id}/ # 每个项目一个目录
|
||
│ ├── raw/ # 原始视频文件
|
||
│ ├── step1_outline/ # 大纲生成结果
|
||
│ ├── step2_timeline/ # 时间轴分析
|
||
│ ├── step3_scoring/ # 内容评分
|
||
│ ├── step4_title/ # 标题生成
|
||
│ ├── step5_clustering/ # 内容聚类
|
||
│ └── step6_video/ # 视频生成
|
||
│ ├── clips_metadata.json # 切片元数据
|
||
│ └── collections_metadata.json # 合集元数据
|
||
├── output/ # 最终输出文件
|
||
│ ├── clips/ # 切片视频文件
|
||
│ │ └── {project_id}/ # 按项目组织
|
||
│ ├── collections/ # 合集视频文件
|
||
│ │ └── {project_id}/ # 按项目组织
|
||
│ └── metadata/ # 全局元数据
|
||
├── temp/ # 临时文件
|
||
├── cache/ # 缓存文件
|
||
├── uploads/ # 上传文件
|
||
└── backups/ # 数据库备份
|
||
```
|
||
|
||
## 🔄 数据流程
|
||
|
||
### **1. 项目创建流程**
|
||
|
||
```
|
||
用户上传视频 → 创建项目记录 → 存储原始文件 → 开始处理流程
|
||
↓
|
||
数据库: projects 表新增记录
|
||
文件系统: data/projects/{project_id}/raw/ 存储视频
|
||
```
|
||
|
||
### **2. 视频处理流程**
|
||
|
||
```
|
||
原始视频 → 字幕提取 → 内容分析 → 切片生成 → 合集生成 → 最终输出
|
||
↓ ↓ ↓ ↓ ↓ ↓
|
||
step1_outline → step2_timeline → step3_scoring → step4_title → step5_clustering → step6_video
|
||
```
|
||
|
||
### **3. 数据同步流程**
|
||
|
||
```
|
||
文件系统处理完成 → 元数据生成 → 同步到数据库 → 前端显示
|
||
↓ ↓ ↓ ↓
|
||
clips_metadata.json → 解析元数据 → 写入clips表 → API返回
|
||
collections_metadata.json → 解析元数据 → 写入collections表 → API返回
|
||
```
|
||
|
||
## 🔧 关键技术实现
|
||
|
||
### **1. 数据同步机制**
|
||
|
||
- **自动同步**: 处理完成后自动同步元数据到数据库
|
||
- **手动同步**: 提供同步脚本处理历史数据
|
||
- **增量同步**: 只同步新增或修改的数据
|
||
|
||
### **2. 路径管理**
|
||
|
||
- **统一路径管理器**: `backend/core/unified_paths.py`
|
||
- **动态路径检测**: 自动检测最佳输出路径
|
||
- **路径验证**: 定期检查路径配置一致性
|
||
|
||
### **3. 状态管理**
|
||
|
||
- **项目状态**: pending → processing → completed
|
||
- **任务状态**: pending → running → completed/failed
|
||
- **实时更新**: WebSocket + 轮询机制
|
||
|
||
## 🚨 常见问题和解决方案
|
||
|
||
### **1. 数据不一致问题**
|
||
|
||
**现象**: 文件系统有数据，但数据库中没有
|
||
**原因**: 数据同步失败或未执行
|
||
**解决**: 运行 `scripts/sync_complete_metadata.py`
|
||
|
||
### **2. 路径混乱问题**
|
||
|
||
**现象**: 文件分散在多个目录
|
||
**原因**: 硬编码路径与配置路径冲突
|
||
**解决**: 使用统一路径管理器
|
||
|
||
### **3. 前端显示异常**
|
||
|
||
**现象**: 后端API正常，前端显示异常
|
||
**原因**: 前端缓存或状态管理问题
|
||
**解决**: 清除浏览器缓存，重启前端服务
|
||
|
||
## 📋 维护和监控
|
||
|
||
### **1. 定期检查**
|
||
|
||
- **数据一致性**: 检查文件系统与数据库的一致性
|
||
- **路径配置**: 验证路径配置的正确性
|
||
- **存储空间**: 监控磁盘空间使用情况
|
||
|
||
### **2. 备份策略**
|
||
|
||
- **数据库备份**: 定期备份 SQLite 数据库
|
||
- **文件备份**: 重要项目文件的备份
|
||
- **配置备份**: 系统配置文件的备份
|
||
|
||
### **3. 日志监控**
|
||
|
||
- **应用日志**: 监控应用运行状态
|
||
- **错误日志**: 及时发现问题
|
||
- **性能日志**: 监控系统性能
|
||
|
||
## 🚀 最佳实践
|
||
|
||
### **1. 数据管理**
|
||
|
||
- 定期运行数据同步脚本
|
||
- 及时清理临时文件和缓存
|
||
- 保持文件系统结构清晰
|
||
|
||
### **2. 开发流程**
|
||
|
||
- 新功能开发前先清理测试数据
|
||
- 使用统一的路径配置
|
||
- 及时更新文档和注释
|
||
|
||
### **3. 部署维护**
|
||
|
||
- 生产环境定期备份数据
|
||
- 监控系统资源使用情况
|
||
- 及时更新依赖和修复安全漏洞
|