autoclip/docs/BACKEND_ARCHITECTURE.md

🏗️ 后端架构设计文档

📋 概述

自动切片工具后端采用模块化设计，支持多项目并行处理，具备完善的错误处理、配置管理和安全机制。

🏛️ 架构层次

1. 配置管理层 (Configuration Layer)

src/config.py
├── ConfigManager          # 统一配置管理器
├── Settings              # 应用设置类
├── APIConfig             # API配置
├── ProcessingConfig      # 处理参数配置
└── PathConfig           # 路径配置

功能特性:

• 环境变量支持
• 配置验证
• 向后兼容
• 多项目配置

2. 错误处理层 (Error Handling Layer)

src/utils/error_handler.py
├── AutoClipsException    # 基础异常类
├── 特定异常类            # APIError, NetworkError等
├── ErrorHandler         # 错误处理器
├── CircuitBreaker       # 熔断器
└── RetryConfig          # 重试配置

功能特性:

• 分层错误处理
• 自动重试机制
• 熔断器模式
• 错误上下文管理

3. 安全管理层 (Security Layer)

src/utils/api_key_manager.py
├── APIKeyManager        # API密钥管理器
├── 加密存储             # Fernet加密
├── 密钥轮换             # 密钥更新
└── 使用统计             # 使用情况监控

功能特性:

• 加密存储API密钥
• 密钥格式验证
• 自动过期管理
• 使用统计跟踪

4. 处理流水线层 (Pipeline Layer)

src/pipeline/
├── step1_outline.py     # 大纲提取
├── step2_timeline.py    # 时间定位
├── step3_scoring.py     # 内容评分
├── step4_title.py       # 标题生成
├── step5_clustering.py  # 主题聚类
└── step6_cutting.py     # 视频切割

功能特性:

• 模块化设计
• 独立处理步骤
• 中间结果缓存
• 错误恢复机制

5. 工具层 (Utilities Layer)

src/utils/
├── llm_client.py        # LLM客户端
├── text_processor.py    # 文本处理
├── video_processor.py   # 视频处理
└── file_manager.py      # 文件管理

功能特性:

• 统一的LLM调用接口
• 文本分块和合并
• 视频处理封装
• 文件操作抽象

🔄 数据流

处理流程

输入文件 → 配置验证 → 分块处理 → LLM调用 → 结果解析 → 文件生成 → 输出
    ↓         ↓         ↓         ↓         ↓         ↓         ↓
  验证器    配置管理   文本处理   API管理   错误处理   文件管理   元数据

错误处理流程

异常发生 → 异常分类 → 错误处理 → 重试/熔断 → 日志记录 → 用户反馈
    ↓         ↓         ↓         ↓         ↓         ↓
  捕获器    分类器    处理器    恢复器    记录器    反馈器

🛡️ 安全设计

1. API密钥管理

• 加密存储: 使用Fernet对称加密
• 密钥轮换: 支持密钥更新和轮换
• 访问控制: 基于角色的密钥访问
• 使用监控: 密钥使用统计和审计

2. 输入验证

• 文件类型验证: 限制上传文件类型
• 大小限制: 防止大文件攻击
• 内容验证: 验证文件内容完整性
• 路径安全: 防止路径遍历攻击

3. 错误信息处理

• 敏感信息过滤: 不暴露内部错误详情
• 错误分类: 区分用户错误和系统错误
• 日志脱敏: 日志中不记录敏感信息

📊 性能优化

1. 并发处理

• 异步处理: 使用asyncio支持并发
• 任务队列: 支持后台任务处理
• 资源池: 连接池和线程池管理

2. 缓存机制

• 结果缓存: 缓存LLM调用结果
• 配置缓存: 缓存配置信息
• 文件缓存: 缓存处理中间结果

3. 资源管理

• 内存优化: 流式处理大文件
• 磁盘优化: 临时文件清理
• 网络优化: 连接复用和超时控制

🔧 配置管理

环境变量

# 必需配置
DASHSCOPE_API_KEY=your_api_key_here
AUTO_CLIPS_MASTER_PASSWORD=your_master_password

# 可选配置
MODEL_NAME=qwen-plus
CHUNK_SIZE=5000
MIN_SCORE_THRESHOLD=0.7
MAX_CLIPS_PER_COLLECTION=5
LOG_LEVEL=INFO

配置文件

{
  "api_config": {
    "model_name": "qwen-plus",
    "max_tokens": 4096,
    "timeout": 30
  },
  "processing_config": {
    "chunk_size": 5000,
    "min_score_threshold": 0.7,
    "max_retries": 3
  },
  "paths": {
    "project_root": "/path/to/project",
    "uploads_dir": "/path/to/uploads",
    "temp_dir": "/path/to/temp"
  }
}

🧪 测试策略

1. 单元测试

• 配置测试: 测试配置加载和验证
• 错误处理测试: 测试异常处理和重试
• API测试: 测试LLM客户端
• 工具测试: 测试各种工具函数

2. 集成测试

• 流水线测试: 测试完整处理流程
• 文件处理测试: 测试文件上传和下载
• API集成测试: 测试与外部API的集成

3. 性能测试

• 负载测试: 测试并发处理能力
• 内存测试: 测试内存使用情况
• 网络测试: 测试网络请求性能

📈 监控和日志

1. 日志系统

# 日志配置
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('auto_clips.log'),
        logging.StreamHandler()
    ]
)

2. 性能监控

• 处理时间: 记录各步骤处理时间
• 资源使用: 监控CPU、内存、磁盘使用
• 错误率: 统计错误发生频率
• 成功率: 统计处理成功率

3. 健康检查

• 服务状态: 检查各服务是否正常
• 依赖检查: 检查外部依赖是否可用
• 资源检查: 检查系统资源是否充足

🚀 部署架构

开发环境

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Streamlit     │    │   React Dev     │    │   FastAPI Dev   │
│   (原型界面)     │    │   (开发前端)     │    │   (开发后端)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

生产环境

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Nginx         │    │   React Build   │    │   FastAPI       │
│   (反向代理)     │    │   (生产前端)     │    │   (生产后端)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   Redis Cache   │
                    │   (缓存层)       │
                    └─────────────────┘

🔄 版本控制

语义化版本

• 主版本号: 不兼容的API修改
• 次版本号: 向下兼容的功能性新增
• 修订号: 向下兼容的问题修正

迁移策略

• 向后兼容: 新版本保持对旧版本的兼容
• 渐进迁移: 支持渐进式功能迁移
• 回滚机制: 支持快速回滚到旧版本

📚 最佳实践

1. 代码规范

• PEP 8: 遵循Python代码规范
• 类型注解: 使用类型提示
• 文档字符串: 完整的函数和类文档
• 错误处理: 统一的错误处理方式

2. 安全实践

• 最小权限: 使用最小必要权限
• 输入验证: 严格验证所有输入
• 加密传输: 敏感数据加密传输
• 定期更新: 定期更新依赖包

3. 性能实践

• 异步处理: 使用异步处理提高性能
• 缓存策略: 合理使用缓存
• 资源清理: 及时清理临时资源
• 监控告警: 设置性能监控和告警

---

注意: 本文档会随着项目发展持续更新，请关注最新版本。