docs: 补充前后端架构说明
This commit is contained in:
hh
@@ -0,0 +1,445 @@
|
||||
# AirShelf 后端架构
|
||||
|
||||
> 适用目录：`core/backend`。
|
||||
> 最后核对：2026-07-17。
|
||||
> 本文描述当前代码结构；系统级拓扑见 [core/ARCHITECTURE.md](../ARCHITECTURE.md)。
|
||||
|
||||
## 1. 定位
|
||||
|
||||
后端是 AirShelf 的业务与数据中枢，负责：
|
||||
|
||||
- 用户、团队、成员、邀请码和权限。
|
||||
- 商品、项目、资产和五阶段生产状态。
|
||||
- AI Provider、模型配置和生成任务编排。
|
||||
- 积分预留、结算、释放和额度限制。
|
||||
- TOS 文件、素材审核、资产引用和垃圾桶生命周期。
|
||||
- Celery 异步任务、脚本 SSE、视频轮询和 FFmpeg 导出。
|
||||
- 通知中心和平台超管治理接口。
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
```text
|
||||
core/backend/
|
||||
├─ airshelf/
|
||||
│ ├─ settings/
|
||||
│ │ ├─ base.py 公共配置、数据库、Redis、Provider 环境变量
|
||||
│ │ ├─ development.py 本地开发配置
|
||||
│ │ ├─ production.py 生产安全和 WhiteNoise 配置
|
||||
│ │ └─ test.py 测试配置
|
||||
│ ├─ urls.py API 总路由
|
||||
│ ├─ celery.py Celery 应用入口
|
||||
│ ├─ wsgi.py
|
||||
│ └─ asgi.py
|
||||
├─ apps/
|
||||
│ ├─ common/
|
||||
│ ├─ accounts/
|
||||
│ ├─ products/
|
||||
│ ├─ assets/
|
||||
│ ├─ projects/
|
||||
│ ├─ ai/
|
||||
│ ├─ billing/
|
||||
│ ├─ ops/
|
||||
│ └─ adminpanel/
|
||||
├─ skills/ 脚本生成、实体提取等 AI Skill 资料
|
||||
├─ manage.py
|
||||
├─ requirements.txt
|
||||
├─ Dockerfile
|
||||
├─ docker-entrypoint.sh
|
||||
└─ README.md 本地启动与常用命令
|
||||
```
|
||||
|
||||
## 3. Django 工程入口
|
||||
|
||||
### 3.1 Settings
|
||||
|
||||
`airshelf/settings/base.py` 统一声明：
|
||||
|
||||
- Django apps 和中间件。
|
||||
- DRF 鉴权、权限、分页和过滤。
|
||||
- SQLite/MySQL 数据库切换。
|
||||
- Redis cache、Celery broker/result 和业务锁。
|
||||
- TOS、火山 ARK、火山 TTS、YunQi、TokenSSR 配置。
|
||||
- AI 功能开关和灰度团队配置。
|
||||
- 积分赠送等平台参数。
|
||||
|
||||
敏感凭证只从环境变量或部署 Secret 读取，不应写入架构文档和仓库代码。
|
||||
|
||||
### 3.2 路由
|
||||
|
||||
API 总入口：
|
||||
|
||||
```text
|
||||
/api/health/ 健康检查
|
||||
/api/auth/ 用户、团队、登录、邀请码
|
||||
/api/products/ 商品
|
||||
/api/assets/ 资产
|
||||
/api/models/ 模特库
|
||||
/api/projects/ 项目和五阶段流水线
|
||||
/api/billing/ 账户、额度和流水
|
||||
/api/ai/ AI 任务、生成、模型配置
|
||||
/api/ops/ 通知
|
||||
/api/admin/ 平台超管 API
|
||||
/django-admin/ Django Admin
|
||||
```
|
||||
|
||||
`/admin/*` 留给前端平台后台，Django 自带后台使用 `/django-admin/`。
|
||||
|
||||
### 3.3 鉴权
|
||||
|
||||
当前 DRF 支持：
|
||||
|
||||
- Token Authentication：前端主流程使用 `Authorization: Token ...`。
|
||||
- Session Authentication：Django Admin 和部分浏览器会话。
|
||||
- Basic Authentication：保留的 DRF 兼容入口。
|
||||
|
||||
当前不是 JWT 架构，不存在 refresh token 轮换链路。
|
||||
|
||||
## 4. 应用模块
|
||||
|
||||
### 4.1 `common`
|
||||
|
||||
提供基础设施型公共代码：
|
||||
|
||||
- `UUIDModel`
|
||||
- `TimeStampedModel`
|
||||
- `TeamOwnedModel`
|
||||
- `TeamScopedViewSetMixin`
|
||||
- 默认分页
|
||||
- 健康检查
|
||||
|
||||
业务 app 应复用这些基类，避免自行实现团队过滤和通用字段。
|
||||
|
||||
### 4.2 `accounts`
|
||||
|
||||
负责身份和租户：
|
||||
|
||||
- 自定义 `User`
|
||||
- `Team`
|
||||
- `TeamMember`
|
||||
- `Invitation`
|
||||
- `UserPreference`
|
||||
- `LoginSession`
|
||||
- `AdminAuditLog`
|
||||
|
||||
团队角色主要包括 owner、admin、member；平台超管通过用户字段识别，与团队角色是两个维度。
|
||||
|
||||
成员可配置日、月、累计总积分限制；团队可配置月积分限制。
|
||||
|
||||
### 4.3 `products`
|
||||
|
||||
负责生产链输入：
|
||||
|
||||
- `Product`
|
||||
- `ProductImage`
|
||||
- `ProductSellingPoint`
|
||||
|
||||
商品包含标题、品牌、类目、目标人群、规格、描述、图片和卖点，为脚本及后续资产生成提供上下文。
|
||||
|
||||
### 4.4 `assets`
|
||||
|
||||
负责业务资产和文件元数据：
|
||||
|
||||
- `Asset`
|
||||
- `AssetFile`
|
||||
- `Model`
|
||||
- `AssetReviewGroup`
|
||||
- `AssetTag` / `AssetTagging`
|
||||
- `AssetUsage`
|
||||
- `FreeAssetGroup` / `FreeAsset`
|
||||
|
||||
`Asset` 表达业务语义、归属、分类、状态和审核信息；`AssetFile` 保存 TOS 对象键、bucket、content type、文件大小、checksum、宽高、时长、预览地址等。
|
||||
|
||||
资产模块还负责：
|
||||
|
||||
- 模特立绘和三视图。
|
||||
- 人像素材审核提交与状态查询。
|
||||
- 项目资产使用关系。
|
||||
- 图片/视频资产库展示。
|
||||
- 自由创作资产归组。
|
||||
- 软删除、垃圾桶和恢复相关数据。
|
||||
|
||||
### 4.5 `projects`
|
||||
|
||||
负责视频项目和五阶段数据结构：
|
||||
|
||||
- `Project`
|
||||
- `ProjectStage`
|
||||
- `ScriptVersion` / `ScriptSegment`
|
||||
- `BaseAssetGroup`
|
||||
- `StoryboardVersion` / `StoryboardFrame`
|
||||
- `StoryboardShot` / `StoryboardShotVersion`
|
||||
- `VideoSegment` / `VideoSegmentVersion`
|
||||
- `Timeline` / `TimelineClip`
|
||||
- `SubtitleTrack`
|
||||
- `BgmTrack`
|
||||
- `ExportJob`
|
||||
|
||||
`projects` 负责业务状态和资源关系；具体 AI 外部请求应委托 `ai` 模块，积分动作应委托 `billing` 模块。
|
||||
|
||||
### 4.6 `ai`
|
||||
|
||||
负责所有模型和生成编排：
|
||||
|
||||
- `ModelProvider`
|
||||
- `ModelConfig`
|
||||
- `AITask`
|
||||
- `ImageConversation`
|
||||
- `QualityWord`
|
||||
- `PromptTemplate`
|
||||
- Provider 适配器
|
||||
- 脚本 Agent 与 Skill 装配
|
||||
- 实体提取、基础资产、三视图、生图、生视频和 TTS
|
||||
- 用户错误转换和生成通知
|
||||
|
||||
主要目录和文件：
|
||||
|
||||
```text
|
||||
apps/ai/
|
||||
├─ providers/ Provider 适配层
|
||||
├─ services.py 多生成场景编排
|
||||
├─ tasks.py Celery 任务入口
|
||||
├─ script_agent.py 脚本 Agent 和 SSE 编排
|
||||
├─ free_video.py 自由视频任务
|
||||
├─ generation_errors.py 对外错误语义
|
||||
├─ pricing.py 通用模型计价
|
||||
├─ video_pricing.py 视频计价
|
||||
└─ model_library.py 模型/模特相关生成能力
|
||||
```
|
||||
|
||||
`services.py` 是当前复杂度中心。新增场景应优先复用 Provider、任务、计费、错误转换和资产落库逻辑，避免继续堆叠重复流程。
|
||||
|
||||
### 4.7 `billing`
|
||||
|
||||
负责积分和额度：
|
||||
|
||||
- `CreditAccount`：团队余额与预留余额。
|
||||
- `CreditLedger`：充值、预留、释放、扣费、调整、退款流水。
|
||||
- `CreditReservation`：与计费型 `AITask` 关联的预留记录。
|
||||
- `BillingConfig`：积分换算、视频毛利和预留 buffer。
|
||||
- `QuotaPolicy`：团队、项目和单任务策略。
|
||||
|
||||
核心服务函数：
|
||||
|
||||
```text
|
||||
reserve_credit
|
||||
charge_reserved_credit
|
||||
release_credit
|
||||
```
|
||||
|
||||
这些函数负责事务、行锁、幂等、额度检查和流水。其他模块禁止直接改余额来模拟扣费。
|
||||
|
||||
### 4.8 `ops`
|
||||
|
||||
当前主要负责 `Notification`、消息列表和通知补齐任务。生成失败、额度变化和重要任务状态可以通过该模块形成用户消息。
|
||||
|
||||
### 4.9 `adminpanel`
|
||||
|
||||
为 React 平台超管后台提供跨团队治理 API，包括：
|
||||
|
||||
- 邀请码、团队和用户。
|
||||
- 提示词、质量词和模型配置。
|
||||
- 资产审核。
|
||||
- AI 任务查询、重试和回收。
|
||||
- 积分流水、计费配置和额度策略。
|
||||
- 项目和平台完整性检查。
|
||||
|
||||
跨团队查询必须限制为平台超管，并保留必要审计信息。
|
||||
|
||||
## 5. 核心业务链
|
||||
|
||||
### 5.1 注册与团队
|
||||
|
||||
```text
|
||||
校验邀请码
|
||||
→ 注册或加入团队
|
||||
→ 创建 TeamMember
|
||||
→ 初始化团队积分账户
|
||||
→ 返回 Token、User、Team、Role
|
||||
```
|
||||
|
||||
### 5.2 商品到项目
|
||||
|
||||
```text
|
||||
Product
|
||||
→ 创建 Project
|
||||
→ 初始化 ProjectStage
|
||||
→ 进入 script 阶段
|
||||
```
|
||||
|
||||
### 5.3 五阶段
|
||||
|
||||
```text
|
||||
script
|
||||
ScriptVersion → ScriptSegment
|
||||
|
||||
base_assets
|
||||
生成/上传商品、人物、场景 → Asset / BaseAssetGroup
|
||||
|
||||
storyboard
|
||||
StoryboardShot → 多个 ShotVersion → 采用版本
|
||||
|
||||
video
|
||||
VideoSegment → 外部视频任务 → VideoSegmentVersion
|
||||
|
||||
export
|
||||
Timeline + 字幕 + BGM + 配音 → ExportJob → 最终 Asset
|
||||
```
|
||||
|
||||
## 6. AI Provider 架构
|
||||
|
||||
### 6.1 数据配置
|
||||
|
||||
`ModelProvider` 保存供应商名称、地址、状态和元数据；`ModelConfig` 保存模型名称、能力、价格、默认状态和模型参数。
|
||||
|
||||
Provider 地址和密钥的解析顺序由服务层控制：数据库配置优先，缺失时回退到环境变量。密钥不应写入数据迁移和普通日志。
|
||||
|
||||
### 6.2 适配层
|
||||
|
||||
```text
|
||||
AIProvider Protocol
|
||||
├─ VolcanoArkProvider
|
||||
├─ OpenAICompatibleProvider
|
||||
├─ YunqiProvider
|
||||
└─ VolcanoTtsProvider
|
||||
```
|
||||
|
||||
通用 OpenAI-compatible 适配器承担 YunQi、TokenSSR 及类似网关的共性协议；Provider 特殊差异通过元数据和适配器处理。
|
||||
|
||||
### 6.3 默认模型
|
||||
|
||||
默认模型可能由数据迁移、后台配置和 Provider 状态共同决定。业务代码不应长期硬编码某个供应商为唯一默认模型；架构文档也不复制易变化的默认模型名单。
|
||||
|
||||
## 7. 任务执行模型
|
||||
|
||||
### 7.1 Celery
|
||||
|
||||
当前 Celery 任务包括：
|
||||
|
||||
- AI 任务提交与轮询。
|
||||
- 独立生图。
|
||||
- 实体提取。
|
||||
- 基础资产生成。
|
||||
- 商品、人物三视图生成。
|
||||
- 自由视频轮询。
|
||||
- 项目视频片段轮询。
|
||||
- FFmpeg 导出。
|
||||
- 通知补齐。
|
||||
|
||||
任务必须使用数据库状态作为事实来源，不能只依赖 Celery result backend。
|
||||
|
||||
### 7.2 SSE
|
||||
|
||||
脚本 Agent 使用 SSE 在单个 HTTP 流中发送分析、生成、自检、草稿、保存和完成事件。断连、异常和计费释放由脚本 Agent 编排层兜底。
|
||||
|
||||
### 7.3 审核轮询
|
||||
|
||||
素材审核提交可在 AI 资产落库后触发。目前审核状态轮询主要由项目 API 和超管 API 请求调用，不是独立 Celery 周期任务。
|
||||
|
||||
### 7.4 前端轮询
|
||||
|
||||
前端通过任务和项目 API 获取进度。前端展示进度不是最终事实，后端任务状态、外部任务标识和数据库资产才是恢复依据。
|
||||
|
||||
## 8. 计费生命周期
|
||||
|
||||
计费型任务的标准流程：
|
||||
|
||||
```text
|
||||
创建 AITask
|
||||
→ 计算报价
|
||||
→ 检查团队、成员、项目、单任务额度
|
||||
→ reserve_credit
|
||||
→ 提交任务
|
||||
→ 执行/轮询
|
||||
├─ 成功：写资产和业务版本 → charge_reserved_credit
|
||||
└─ 失败：记录错误 → release_credit
|
||||
```
|
||||
|
||||
额度层级：
|
||||
|
||||
- `Team.monthly_credit_limit`
|
||||
- `TeamMember.daily_credit_limit`
|
||||
- `TeamMember.monthly_credit_limit`
|
||||
- `TeamMember.total_credit_limit`
|
||||
- `QuotaPolicy.monthly_limit`
|
||||
- `QuotaPolicy.project_limit`
|
||||
- `QuotaPolicy.per_task_limit`
|
||||
|
||||
预留、结算和释放均需要幂等。删除仍处于 ACTIVE 的任务时，信号会尝试释放预留，避免余额永久冻结。
|
||||
|
||||
## 9. 资产与审核
|
||||
|
||||
### 9.1 文件存储
|
||||
|
||||
文件上传 TOS 后，数据库保存对象定位和元数据。对外访问使用后端生成或保存的可访问 URL，不把云存储密钥交给前端。
|
||||
|
||||
### 9.2 人像审核
|
||||
|
||||
需要审核的资产保存：
|
||||
|
||||
- `review_status`
|
||||
- `review_remote_id`
|
||||
- `review_error`
|
||||
|
||||
审核提交失败必须如实返回，不能把未提交成功的资产误标成 processing。轮询只更新发生变化的状态，避免刷新时间导致超时判断失效。
|
||||
|
||||
### 9.3 删除
|
||||
|
||||
删除需要区分：
|
||||
|
||||
- 业务记录软删除。
|
||||
- 垃圾桶展示与恢复。
|
||||
- 项目或会话引用解绑。
|
||||
- TOS 对象最终删除。
|
||||
- 任务和计费审计保留。
|
||||
|
||||
物理清理前必须检查资产引用，避免删除仍被商品、项目、模特或生成任务使用的文件。
|
||||
|
||||
## 10. 部署
|
||||
|
||||
### 10.1 API
|
||||
|
||||
后端镜像默认以 Gunicorn 启动。当前配置使用多个 worker 和线程，避免慢 AI/TOS 请求占满全部请求槽并饿死健康检查。
|
||||
|
||||
### 10.2 Worker
|
||||
|
||||
Celery Worker 复用 API 镜像，通过启动参数切换进程。当前 K8s 使用一个 Worker Deployment、并发 4，AI 和媒体任务尚未拆分独立队列。
|
||||
|
||||
### 10.3 Migration
|
||||
|
||||
`docker-entrypoint.sh` 只在 Gunicorn 启动时执行 migration 和 collectstatic。MySQL 使用 `GET_LOCK` 串行化迁移，Worker 明确跳过数据库结构变更。
|
||||
|
||||
### 10.4 FFmpeg
|
||||
|
||||
后端镜像安装 FFmpeg 和 Noto CJK 字体，用于视频拼接、字幕、BGM 和配音混合。
|
||||
|
||||
## 11. 测试与验证
|
||||
|
||||
常用验证：
|
||||
|
||||
```bash
|
||||
python manage.py check
|
||||
python manage.py makemigrations --check --dry-run
|
||||
python manage.py test
|
||||
```
|
||||
|
||||
测试环境使用独立 settings，并可让 Celery eager 执行。涉及计费、删除、任务重试和数据迁移的改动必须补回归测试。
|
||||
|
||||
## 12. 当前风险与维护边界
|
||||
|
||||
- `apps/ai/services.py` 体积较大，场景边界需要渐进拆分。
|
||||
- AI 默认模型会通过迁移和后台配置变化，文档不能写死。
|
||||
- 同步请求、SSE、Celery 和 API 轮询并存，新增流程必须明确执行模型。
|
||||
- 单 Worker Deployment 可能导致 AI 和导出资源争用。
|
||||
- 资产删除与任务删除涉及引用、计费和 TOS，不能只删除单表记录。
|
||||
- 数据迁移可能包含业务数据变换，必须保证幂等或通过迁移锁串行执行。
|
||||
|
||||
## 13. 文档同步规则
|
||||
|
||||
出现以下变化时必须更新本文：
|
||||
|
||||
- Django app、核心模型或模块职责变化。
|
||||
- API 一级路由或鉴权机制变化。
|
||||
- AI Provider 适配机制变化。
|
||||
- Celery/SSE/同步执行边界变化。
|
||||
- 计费、额度或资产删除生命周期变化。
|
||||
- 数据库、Redis、TOS、FFmpeg 或部署方式变化。
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
All backend code lives under `AirShelf/core/backend` by project decision.
|
||||
|
||||
Architecture and module boundaries: [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
|
||||
## Local bootstrap
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user