docs/v1.0/requirements/backend/01-architecture-overview.md

架构概述

文档版本：v1.0
最后更新：2025-01-27

---

目录

1. 系统特点
2. 架构设计原则
3. 整体架构图
4. 核心模块

---

系统特点

Jointo是一个 AI 驱动的视频创作平台，具有以下核心特点：

1. AI 驱动

• 大量使用 AI 生成功能（图片、视频、音效、字幕、配音）
• 支持多种 AI 模型和服务提供商
• 异步处理 AI 任务，支持进度查询

2. 文件密集

• 需要处理大量图片、视频、音频文件
• 支持多种文件格式（图片、视频、音频、文档）
• 使用对象存储管理文件资源

3. 异步任务

• AI 生成和视频导出都是耗时操作
• 使用任务队列（Celery）处理异步任务
• 支持任务重试、优先级、进度追踪

4. 协作支持

• 支持多人协同编辑项目
• 基于角色的权限管理（owner、editor、viewer）
• 实时通知和状态同步

5. 实时性要求

• 部分功能需要实时反馈（WebSocket）
• 缓存热点数据提升响应速度
• 优化数据库查询性能

---

架构设计原则

1. 微服务化

• 核心服务解耦，便于扩展
• 每个服务职责单一，易于维护
• 支持独立部署和升级

2. 异步优先

• 耗时操作异步处理，避免阻塞
• 使用消息队列解耦服务
• 支持任务重试和错误处理

3. 可扩展性

• 支持水平扩展（增加服务器节点）
• 数据库读写分离
• 使用缓存减轻数据库压力

4. 高可用性

• 关键服务冗余部署
• 数据库主从复制
• 自动故障转移

5. 安全性

• 完善的认证授权机制（JWT）
• 基于角色的访问控制（RBAC）
• 数据加密和安全传输（HTTPS）

---

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                        前端 (React)                          │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTPS
┌───────────────────────────▼─────────────────────────────────┐
│                    API Gateway / Nginx                       │
│              (负载均衡、SSL终止、路由)                        │
└───────────────┬───────────────────────────┬─────────────────┘
                │                           │
    ┌───────────▼──────────┐    ┌───────────▼──────────┐
    │   API 服务 (FastAPI) │    │   WebSocket 服务      │
    │   - RESTful API      │    │   - 实时协作          │
    │   - 认证授权         │    │   - 实时通知          │
    └───────────┬──────────┘    └──────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              业务逻辑层 (Services)                     │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │项目管理  │ │分镜管理  │ │资源管理  │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │视频管理  │ │AI服务    │ │导出服务  │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └───────────┬───────────────────────────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              数据访问层 (Repositories)                 │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │PostgreSQL │ │  Redis   │ │ SQLModel │            │
    │  │(主数据库) │ │ (缓存)   │ │  (ORM)   │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └────────────────────────────────────────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              异步任务层 (Celery)                       │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │  Celery  │ │ RabbitMQ │ │  Worker  │            │
    │  │ (任务队列)│ │ (消息队列)│ │ (任务执行)│            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └───────────┬───────────────────────────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              外部服务层                                │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │对象存储   │ │ AI API   │ │ 视频处理 │            │
    │  │(MinIO/   │ │(AIHubMix)│ │(FFmpeg)  │            │
    │  │ S3)      │ │          │ │          │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └────────────────────────────────────────────────────────┘

---

核心模块

1. API 服务层

• 职责：接收 HTTP 请求，路由分发，参数验证
• 技术：FastAPI
• 特点：高性能、自动生成文档、类型安全

2. 业务逻辑层

• 职责：实现业务规则，协调数据访问和外部服务
• 模块：
  • 项目管理服务
  • 分镜管理服务
  • 剧本管理服务
  • 资源管理服务
  • AI 生成服务
  • 视频导出服务

3. 数据访问层

• 职责：数据库操作、缓存管理、查询优化
• 技术：SQLAlchemy ORM、Redis
• 特点：统一数据访问接口，支持事务

4. 异步任务层

• 职责：处理耗时任务（AI 生成、视频导出）
• 技术：Celery + RabbitMQ
• 特点：支持重试、优先级、定时任务

5. 外部服务层

• 对象存储：MinIO / AWS S3（文件管理）
• AI 服务：OpenAI、Stable Diffusion（内容生成）
• 视频处理：FFmpeg（视频合成、转码）

---

数据流示例

用户创建项目流程

1. 前端发送 POST /api/v1/projects 请求
   ↓
2. API 层验证请求参数（Pydantic）
   ↓
3. 业务逻辑层（ProjectService）
   - 检查用户权限
   - 创建项目记录
   ↓
4. 数据访问层（ProjectRepository）
   - 写入 PostgreSQL
   - 更新 Redis 缓存
   ↓
5. 返回项目信息给前端

AI 生成图片流程

1. 前端发送 POST /api/v1/ai/generate-image 请求
   ↓
2. API 层验证参数
   ↓
3. 业务逻辑层（AIService）
   - 创建 AI 任务记录
   - 提交异步任务到 Celery
   ↓
4. 返回任务 ID 给前端
   ↓
5. Celery Worker 执行任务
   - 调用 AI API（Stable Diffusion）
   - 上传生成的图片到对象存储
   - 更新任务状态
   ↓
6. 前端轮询任务状态，获取结果

---

相关文档

• 技术栈选型
• 系统架构设计
• 数据库设计

---

文档版本：v1.0
最后更新：2025-01-27