AID Studio 统一任务系统实现解析:排队调度、SSE 进度推送与失败补偿机制完整指南
AID Studio 统一任务系统实现解析:排队调度、SSE 进度推送与失败补偿机制完整指南
AID Studio 是一个开源的 AI 漫剧、AI 短剧与 AI 电影创作平台,一次创作要并发提交剧本生成、图片生成、视频渲染等几十种任务。这些任务背后都由同一套统一任务系统驱动:任务先排队、按并发额度准入执行,进度经 SSE 实时推送到浏览器,失败则由多层补偿机制兜底。这篇文章用通俗的语言拆解这三块核心机制,并给出关键源码位置。
一张图看懂:任务从提交到完成要经过什么
用户在创作流程中每点击一次「生成」,后端都会落一条任务记录(通用任务 aid_extract_task 或媒体任务 aid_media_task),任务不会立即执行,而是进入排队 → 准入 → 派发 → 进度推送 → 终态/补偿的完整生命周期。
各步骤的生成任务在管理端可以集中监控,运营人员能实时看到排队中、处理中的任务分布:
排队调度:多维并发准入 + FIFO 位次
🔢 两层限流,职责分离
AID Studio 的排队核心在 TaskQueueService.java,它只做四件事:排队、并发准入、派发、名额释放,不含具体业务与计费。
- 业务任务层(全局 / 用户两维):由 TaskConcurrencyConfig.java 解析,默认全局并发 10、单用户并发 2,可在后台
aid_config(taskq_concurrent_limit_global/taskq_concurrent_limit_user)调整,还支持按用户单独覆盖,配置带 5 秒缓存即时生效。 - 媒体任务层(全局 → 用户 → 模型 → 供应商四维):由 MediaConcurrencyLimiter.java 用 Redis 原子计数 + Lua 脚本一次性判定四个维度,全部有余量才放行。模型与供应商的上限配置在各自行内
schedule_strategy_json.maxConcurrency字段中,默认全局 50、单用户 5。
📊 排队位次与优先级
排队用 Redis 有序集合(ZSet)实现,排序分值为 入队时间 - 优先级 × 权重(权重 86400000ms),既保证先进先出,又允许高优先级任务插队。任务进入 QUEUED 状态后,前端会实时收到「正在排队,当前第 N 位」的事件;若卡在并发额度上,事件里会带上受限维度(GLOBAL_LIMIT / USER_LIMIT / LOCAL_EXECUTOR_LIMIT),让用户明白到底在等什么。
三种调度模式:决定任务如何推进到终态
媒体任务提交后,调度中心 TaskDispatchService.java 会按供应商与模型策略冻结一份调度快照,并决定任务由哪种机制驱动到终态(见 DispatchMode.java):
| 模式 | 含义 | 典型场景 |
|---|---|---|
DIRECT |
同步直返,不进调度中心 | 流式文本、同步出图 |
CALLBACK_FIRST |
回调优先,先等上游回调通知,超时转轮询兜底 | 支持回调的视频/音频厂商 |
POLL_ONLY |
纯轮询,完全由调度中心按节奏查询上游 | 不支持回调的供应商 |
关键设计在 TaskDispatchServiceImpl.java:
- 策略快照冻结:轮询节奏、存活阈值在提交时冻结进任务行,之后后台改配置不影响在途任务。
- 双时钟存活判定:
upstreamAcceptTime(总时长警戒)与lastProgressTime(无进展警戒)两个时钟独立计时;上游每次回复「处理中」都会前移后者,但上游无响应时绝不调用,否则失联任务永远判不了死。 - 视频按规模抬高天花板:视频任务的存活上限按时长 × 分辨率动态抬高(只抬不压),避免用一个常量卡死所有量级的作业。
💡 调度中心由 Quartz 定时任务 MediaTask.java 每拍触发,单轮依次完成 5 件事:到期轮询、回调超时转轮询、存活异常对账、未提交僵尸收口、排队任务兜底拉起,并用 AtomicBoolean 防重入避免堆积。
SSE 进度推送:本地直推 + Redis 双通道
前端通过 GET /api/user/task/stream/{taskId} 建立 SSE 长连接(入口在 UserTaskController.java),可实时接收 progress / queued / complete / error / cancelled / partial_failed / warning 七类事件。推送链路做了双通道设计(核心在 AssetExtractSseManager.java):
- 本地直推:同一 JVM 内的
SseEmitter即时推送,零延迟; - Redis 快照保底:每次进度都会覆盖写入 Redis 快照(key:
asset:task:progress:{taskId},进行中 TTL 30 分钟、终态 5 分钟),连接侧每 1.5 秒轮询一次,跨进程也不丢进度。
几个值得借鉴的工程细节:
- 防 Nginx 缓冲:响应头设置
X-Accel-Buffering: no并先推一个注释帧强制刷出 200,否则反代可能等到连接关闭才一次性吐出事件; - 15 秒心跳:防止反向代理/防火墙掐断空闲连接;
- 毫秒级去重:每条快照带
updateMillis,本地直推与 Redis 轮询两条路径不会把同一条进度推两次; - 首包补发:前端刷新重连时,后端优先从 Redis 读最新快照立即补发;若任务已是终态,则直接补发
complete/error事件后关闭连接,无需再轮询; - 断线重连防风暴:前端 modalSseFollowReconnectPolicy.ts 用指数退避(800ms 起步、封顶 5s、最多 2 次)+ 原子占锁,避免多条连接互抢同一 taskId 形成请求风暴。
前端消费侧统一封装在 useTaskStream.ts,解析事件块并把结构化错误(错误码、是否可重试、退款状态等)交给 UI 渲染。
失败补偿机制:五道兜底保障
生成链路长、依赖上游厂商,任何一环都可能中断。AID Studio 的补偿思路是:每个失败点都有对应的定时扫描任务兜底。
| 补偿场景 | 触发条件 | 处理方式 |
|---|---|---|
| 提交阶段僵尸任务 | PENDING 且无 providerTaskId 且超兜底时限(进程重启/崩溃在提交途中遗留) |
终结为 FAILED 并退款;QUEUED 是合法排队,绝不清理 |
| 回调失联 | WAIT_CALLBACK 超过回调截止时间 |
自动转入轮询兜底(transitionExpiredCallbacks) |
| 上游存活异常 | 达到无进展 / 总时长警戒线 | 强制查询上游,只接受厂商文档明确终态,不因本地超时自动失败,避免误杀正在出片的任务 |
| 排队任务漏派发 | 完成事件丢失 / 重启后仍 QUEUED |
按 FIFO 扫描抢占并发坑位拉起(CAS 防重) |
| 计费 / 产物卡单 | 卡在 SETTLING/REFUNDING/FROZEN 超 2 分钟;SUCCEEDED 但 oss_url 为空 |
分别由 billingCompensate / ossCompensate 推进;TOKEN 差额由 extraChargeCompensate 追补 |
失败时用户看到的不是裸报错,而是结构化错误事件:经错误归一化器产出 errorCode、retryable(是否可重试)、needRecharge(是否欠费)、refundStatus(退款状态)等字段,实时推送与断线补发共用同一份组装逻辑,保证两个入口口径一致。派发失败时还会自动退回预冻结资金,避免资金挂账。
相关代码位置速查
📁 调度与限流:aid-interface/aid-interface-main/src/main/java/com/aid/media/service/(调度中心、四维限流)与 aid-interface/aid-interface-main/src/main/java/com/aid/rps/queue/(排队队列、并发配置) 📁 SSE 推送:aid-business/aid-business-main/src/main/java/com/aid/rps/controller/UserTaskController.java(SSE 端点)与 aid-interface/aid-interface-main/src/main/java/com/aid/rps/sse/AssetExtractSseManager.java(推送管理器) 📁 定时任务:aid-business/aid-business-quartz/src/main/java/com/aid/quartz/task/MediaTask.java(调度与补偿入口) 📁 前端消费:frontend/web/hooks/useTaskStream.ts 与 frontend/web/utils/modalSseFollowReconnectPolicy.ts(断线重连策略) 📖 项目概览:README.md(统一任务系统能力说明与架构图)



