# 12_任务队列_错误重试_稳定性设计 ## 1. 文档目标 本文档定义系统 B 的任务队列、状态机、幂等、重试、错误码、恢复机制和并发控制。 ## 2. 为什么必须队列化 系统 B 的生成链路长且耗时： ```text 照片检测 人物档案 方案生成 预览图 正式图 图片质检 TTS 字幕 视频合成 最终质检 人工审核 ``` 如果同步执行，容易导致： - 请求超时 - 用户重复点击 - 服务阻塞 - 失败无法恢复 - 成本无法追踪 ## 3. 队列划分 ```text photo_check_queue：照片检测 text_queue：方案、文案、Prompt image_queue：预览图、正式图 video_queue：AI 图生视频 voice_queue：TTS audio_queue：BGM 处理 ffmpeg_queue：视频合成 qc_queue：质量检测 cleanup_queue：文件清理 notification_queue：通知 ``` ## 4. 任务状态 ```text pending：等待执行 running：执行中 success：成功 failed：失败 retrying：重试中 cancelled：取消 manual_required：需要人工处理 ``` ## 5. 任务字段 每个任务必须有： ```text task_id project_id task_type provider_id status input_json input_hash output_asset_id provider_request_id retry_count max_retry cost_estimate cost_actual error_code error_message created_at started_at finished_at ``` ## 6. 幂等设计 幂等 key： ```text project_id + task_type + input_hash ``` 规则： - 如果已有成功任务，直接返回成功结果。 - 如果已有运行任务，返回当前任务状态。 - 如果已有失败任务，按重试规则处理。 - 同一请求不能重复创建多个高成本任务。 ## 7. 项目级锁 某些任务必须串行： - 创作方案生成 - 视频合成 - 最终交付 使用 Redis lock： ```text lock:project:{project_id}:workflow ``` 避免并发触发导致状态混乱。 ## 8. 重试策略 默认： ```text max_retry = 3 backoff = exponential ``` 例如： ```text 第 1 次失败：30 秒后重试 第 2 次失败：2 分钟后重试 第 3 次失败：5 分钟后重试 ``` 不可重试错误： - 用户照片不合格 - 余额不足 - 授权未确认 - 内容审核不通过 - 套餐限制冲突 可重试错误： - Provider 超时 - 网络错误 - 速率限制 - 临时服务异常 - FFmpeg 临时失败 ## 9. 失败转人工 满足任一条件转人工： - 同一任务连续失败超过 max_retry - 图片质检连续失败 - 人像一致性评分过低 - 视频合成失败 - 审核 warning - 高端定制项目 状态： ```text manual_required ``` ## 10. 并发限制 ### 用户级 ```text 每个用户最多同时 1 个正式生成项目 ``` ### 项目级 ```text 每个项目最多同时 N 个图片任务 视频合成任务只能 1 个 ``` ### Provider 级 ```text 按 Provider 设置 QPS 和并发数 ``` ## 11. 队列优先级 优先级建议： 1. 高端定制项目 2. 已支付正式生成 3. 预览生成 4. 免费预览 5. 清理任务 ## 12. 错误码设计 | 错误码 | 含义 | |---|---| | TASK_TIMEOUT | 任务超时 | | PROVIDER_TIMEOUT | Provider 超时 | | PROVIDER_RATE_LIMIT | Provider 限流 | | PROVIDER_ERROR | Provider 错误 | | INPUT_INVALID | 输入参数错误 | | PHOTO_QUALITY_FAIL | 照片质量不合格 | | PAYMENT_REQUIRED | 需要支付 | | QUOTA_NOT_ENOUGH | 额度不足 | | MODERATION_REJECTED | 审核不通过 | | FFMPEG_FAILED | 视频合成失败 | | STORAGE_FAILED | 存储失败 | | UNKNOWN_ERROR | 未知错误 | ## 13. 任务恢复 服务重启后： 1. 扫描 running 超时任务。 2. 判断是否有 Provider request_id。 3. 查询 Provider 状态，能恢复则恢复。 4. 无法恢复则标记 failed 并按规则重试。 ## 14. 状态一致性 项目状态由 WorkflowService 统一更新。不要让 Worker 随意改最终状态。 Worker 只上报： ```text task success/failed output asset progress error ``` WorkflowService 根据任务完成情况推进项目状态。 ## 15. 防重复点击 前端：按钮 loading，防抖。 后端：幂等 key + 状态校验。 例如： - 已在 preview_generating，不允许再次 generate-preview。 - 已 payment_paid，不允许重复创建同一套餐订单。 ## 16. 任务超时设置 建议： ```text photo_check：2 分钟 text_generate：3 分钟 image_generate：10 分钟 video_generate：30 分钟 voice_generate：5 分钟 ffmpeg_render：30 分钟 final_qc：10 分钟 ``` ## 17. 告警 触发告警： - 失败任务数超过阈值 - 某 Provider 连续失败 - 队列积压过多 - 视频合成失败率过高 - 单项目成本异常 - 磁盘/MinIO 容量不足 ## 18. 日志要求 每个任务记录： - 输入摘要 - 输出摘要 - Provider - 成本 - 耗时 - 错误 - 重试次数 敏感数据脱敏保存。 ## 19. V3 真人动态视频队列增量 新增队列： ```text identity_anchor_queue：身份锚点生成 face_consistency_queue：本人相似度检查 motion_portrait_queue：动态写真轻动效 real_video_clip_queue：真人动态视频片段 video_clip_qc_queue：视频片段质检 lipsync_queue：口型同步 ``` 隔离原则： - `real_video_clip_queue` 必须独立限流，避免高成本视频任务堵住图片和普通合成。 - `lipsync_queue` 独立限流，失败不影响基础旁白字幕交付。 - `face_consistency_queue` 可优先级较高，因为它决定是否能继续生成。 V3 超时建议： ```text identity_anchor_generate：10 分钟 face_consistency_check：3 分钟 motion_portrait_generate：20 分钟 real_video_clip_generate：60 分钟 video_clip_qc：10 分钟 lipsync_generate：45 分钟 ``` V3 错误码： ```text IDENTITY_ANCHOR_NOT_CONFIRMED FACE_CONSISTENCY_LOW REAL_VIDEO_PROVIDER_DISABLED REAL_VIDEO_CONFIRMATION_REQUIRED REAL_VIDEO_COST_LIMIT_EXCEEDED REAL_VIDEO_CLIP_FAILED VIDEO_CLIP_QC_FAILED LIPSYNC_FAILED MINOR_MANUAL_REVIEW_REQUIRED ``` 真实视频任务失败时： 1. 记录 Provider 错误。 2. 标记片段 failed 或 needs_retry。 3. 不回落 mock 假成功。 4. 不重复扣用户额度。 5. 用户端显示失败原因和重试入口。