wehub-resource-sync
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. 部署维护**
|
|
|
|
- 生产环境定期备份数据
|
|
- 监控系统资源使用情况
|
|
- 及时更新依赖和修复安全漏洞
|