# AirShelf 后端架构 > 适用目录：`core/backend`。 > 最后核对：2026-07-18。 > 本文描述当前代码结构；系统级拓扑见 [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 或部署方式变化。