StemDeck任务队列架构解读为什么一次只能处理一首歌串行队列、取消与跨重启恢复设计【免费下载链接】stemdeckStemdeck is an modern stem extraction platform for musicians,producers and hobbyists, designed to isolate vocals, drums, bass, piano and guitar for practice, transcription, remixing, and creative audio workflows through a modern and interactive interface项目地址: https://gitcode.com/gh_mirrors/st/stemdeckStemDeck 是一款本地化的干声提取stem separation平台能把一首歌拆成人声、鼓、贝斯、钢琴、吉他等独立轨道供练习、扒谱与混音使用。当你一次导入多首歌时这些任务会进入一个串行导入队列任何时刻只处理一首。这篇文章将带你读懂这个设计背后的三个关键决策为什么必须串行、取消如何做到秒级生效、关闭程序后队列如何跨重启恢复并给出对应的源码位置适合想了解 StemDeck 任务队列架构的新手与开发者。一、为什么一次只能处理一首歌这不是为了省资源的性能折中而是一个正确性约束——源码里写得很直白Exactly one job runs at a time, and that is a correctness requirement rather than a tuning choice. —— app/pipeline/jobqueue.py1.1 真正的根源一个共享的 Demucs 工作进程StemDeck 用 Demucs 模型做音频分离而它并不是每个任务临时起一个分离进程而是维护了一个常驻的单一 worker 子进程app/pipeline/separate.py所有任务通过同一条 stdin把请求发给这个 worker进度信息从同一条 stderr流里解析再按任务归属回写注册表用一个全局映射把任务 ID 绑定到这个进程上registry.set_proc。如果两个任务并发跑会发生什么两个任务的请求会交错写进同一个 stdinA 任务解析到的进度条可能其实是 B 任务的输出更糟的是——你取消其中一个任务worker 进程会被整个杀掉另一个正在分离的任务也随之陪葬。所以串行不是选择而是这套单 worker 单条管道通信方式的必然要求。1.2 双保险单消费者 管道锁架构上 StemDeck 放了两道防线防线位置作用队列单消费者app/pipeline/jobqueue.py 的_worker_loop正常路径上同一时刻只有一个任务被派发管道锁app/pipeline/runner.py 的_pipeline_lock兜底任何绕过队列直接调用管道的路径例如测试、人声再拆分排队任务A → 排队任务B → 排队任务C │ ▼ ┌─────────────────┐ │ 单一消费者循环 │ ← jobqueue._worker_loop └────────┬────────┘ ▼ ┌─────────────────┐ │ _pipeline_lock │ ← 第二道保险 └────────┬────────┘ ▼ ┌─────────────────┐ │ 常驻 Demucs │ ← 唯一的分离 worker │ worker 进程 │ └─────────────────┘二、串行队列的 4 个核心设计2.1 从隐式等待到显式队列早期实现里任务用裸的asyncio.create_task启动然后在管道锁上阻塞——队列对用户完全不可见没有列表、没有固定排位、排队中的任务也无法取消。现在 app/pipeline/jobqueue.py 用一个deque显式保存等待中的任务 ID配合一个threading.Lock保证同步线程池接口与异步 worker 安全共享状态。2.2 拖拽排序为什么用锚点而不是下标排队任务支持拖拽调整顺序POST /api/queue/reorder见 app/api/queue.py。一个容易被忽视的细节是接口参数不是放到第 N 位而是放到某个任务之后。原因很现实队列在你拖拽的这几秒里可能正好完成了一首任务整条队列往前挪了一位——按下标插入可能插错位置。锚点方式更诚实如果锚点任务在拖拽期间已经离开了队列接口会回退到队尾并把最新队列顺序返回给前端重新同步而不是让客户端猜。2.3 双通道容量限制上传与链接分开计数等待中的文件上传会把源文件最大 400 MB一直留在磁盘上而链接导入等待时不占任何磁盘。所以容量按类型分开计算app/core/config.pyMAX_PENDING_UPLOAD_JOBS上传排队上限默认 20MAX_PENDING_URL_JOBS链接排队上限默认 200。这样一堆链接排队不会挤占文件上传的名额反之亦然。超限会返回 503并给出可操作的提示取消一个任务或稍候而不是一句笼统的服务繁忙。2.4 一条 SSE 流广播整条队列前端不为每个任务各开一条事件流而是整条队列共用一条/api/queue/eventsapp/api/queue.py。注释解释了原因HTTP/1.1 下浏览器对同一源的并发连接大约只有 6 个而 DAW 界面本来就占着这些连接加载 stem WAV 音频——二十条队列流会在触及服务端限制前就饿死音频加载。服务端用指纹任务 ID 序列 各任务版本号做廉价的变更检测只有真正变化时才推送一帧前端 static/js/queue.js 还有 2 秒轮询作为 SSE 断线时的兜底。三、取消机制等待、运行、以及一个危险的缝隙 ⏹️取消入口是POST /api/jobs/{id}/cancelapp/api/jobs.py按任务所处位置分三种处理3.1 还在排队立即摘除立刻释放磁盘discard(job_id) → 状态置为 cancelled → 删除任务目录排队中的上传任务可能正攥着几百 MB 的源文件所以这一步会马上把文件从磁盘清掉并释放它占用的容量名额——而不是等它排到队头才想起自己被取消了。3.2 正在运行标志位 直接终止子进程运行中的任务无法从 Python 线程内部强行打断分离调用阻塞在asyncio.to_thread里所以采用标志位 杀进程组合拳置cancel_requested标志管道在每个阶段之间检查它_check_cancel如果该任务持有 Demucs worker 进程API 线程直接 terminate 子进程——取消不必等管道线程自己发现标志位。连 ffmpeg 的转码调用都被注册过set_proc否则取消在几十分钟的转码期间会完全失灵这是 #519 修复的真实问题。3.3 危险的缝隙任务既不在队列也不在运行位有一个微妙的竞态窗口worker 把任务从队列popleft()出来、到_set_running()标记它为运行中的这一小段时间里这个任务哪儿都不在。此时取消请求会发现discard()返回 False、running_id()返回 None只能默默设置标志位后返回。如果没有兜底这个任务会永远卡在queued状态队列视图里看不到它、容量计数一直占着、上传的源文件永不释放而且——因为 queued 状态是持久化的——每次重启它都会被重新排回队列issue #520 的真实事故。解法是让唯一消费者负责收尾worker 发现自己刚拿到的任务已被请求取消时由它来完成取消app/pipeline/jobqueue.py 的_finalise_dropped_job。注释总结得很到位The worker owns the job by then and is the only thing that can close it out.四、跨重启恢复重启后队列不丢任务 StemDeck 的桌面后端是常驻进程程序可能因崩溃、OOM、断电或更新而重启。恢复逻辑全部在 app/core/registry.py 中。4.1 registry.json哪些任务值得留档持久化分两类app/core/registry.py已完成done→ 必须持久化否则重启后曲库消失可恢复queued/processing/downloading/analyzing/separating→ 同样持久化让死在半路的队列能活下来。写入采用临时文件 原子替换临时文件名每次调用都不同——两个写者管道线程、API 线程、清理循环并发写时不会互相踩文件这在 Windows 上尤其关键。4.2 重启后一个死在半路的任务有三种命运restore()启动时逐条检查可恢复任务核心判断在 _resume_or_recover磁盘上的状态处理方式stems 目录完整按完成处理——崩溃恰好发生在最后一片 stem 写完和done 落盘之间重跑只会制造重复曲库条目所以直接恢复为 donestems 不完整清掉半成品输出回到队头重跑——不清的话collect()会把上次的残留文件误当成结果resume_attempts已用尽上限 1 次明确失败提示被重启中断了两次请重新导入第三条是防死锁的关键想象一个每次跑都会把进程拖崩的任务比如 Demucs OOM 直接带走后端。如果不限制重试次数它会每次启动都被重新排队、每次又崩把整条队列永久卡死。恢复尝试计数会在重启时立刻写回磁盘——否则下次启动读到的还是旧计数限制就形同虚设。4.3 重启后队列默认暂停打开 App ≠ 自动开工恢复的任务会重新入队但队列进入paused 状态app/main.pyopening the app must not start separating on its own. A restored queue can be dozens of tracks and hours of GPU, and the user may well have opened StemDeck to do something else entirely.你上次可能排了二三十首、算下来是几个小时的 GPU 时间今天打开程序也许只是想听个歌。所以恢复的任务静静等着由你按 StartPOST /api/queue/start主动开工。而新导入的任务会自动解除暂停——用户刚点了处理按钮结果什么都没发生本身就是 bug。另外还有一层保险restore()会扫描任务目录做孤儿恢复——凡是注册表里没有、但磁盘上存在完整 stems 的目录上次进程在落盘前就死了会被重新认领进曲库而被用户删除过的任务有墓碑记录即使文件删不干净也不会死灰复燃#521 修掉的正是删掉的歌重启后复活。五、一图看懂任务的一生导入链接/上传 │ 容量检查分上传/链接两路 ▼ 注册表 排队 ──────────► registry.json 落盘 │ ├─ 排队中被取消 → 摘除 清目录 │ ▼ 单一消费者取出缝隙窗口取消标志兜底 │ ▼ _pipeline_lock → 下载/转码 → Demucs 分离 → 混音 → 节拍网格 │ 崩溃/重启 ▼ ├─ stems 完整 → 恢复为 done 状态落盘 ◄──────────────────┤ │ └─ 不完整 → 清残留、重新排队限 1 次 ▼ done → 进入曲库失败 → 隔离到 failed/ 保留诊断证据六、总结三个决策一种工程哲学 回看这套架构为什么一次只能处理一首歌的答案其实是一整条设计链串行是正确性要求单一 Demucs worker 单条 stdin/stderr 管道决定了并发必然互相干扰单消费者循环app/pipeline/jobqueue.py 管道锁app/pipeline/runner.py双保险兜住它。取消是分层契约排队任务立即摘除释放磁盘、运行任务标志位 终止子进程、缝隙窗口交给唯一消费者收尾——三个位置各自负责不留悬空状态。持久化是恢复的前提registry.json 磁盘状态判断 单次重试上限 恢复后默认暂停让崩溃后重启从丢任务变成排队重来或自动补完。想深入源码的话建议按这条路径阅读队列核心app/pipeline/jobqueue.py队列 API 与 SSEapp/api/queue.py任务生命周期与取消app/api/jobs.py注册表与恢复app/core/registry.py启动时的恢复与暂停app/main.py前端队列视图static/js/queue.js【免费下载链接】stemdeckStemdeck is an modern stem extraction platform for musicians,producers and hobbyists, designed to isolate vocals, drums, bass, piano and guitar for practice, transcription, remixing, and creative audio workflows through a modern and interactive interface项目地址: https://gitcode.com/gh_mirrors/st/stemdeck创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 StemDeck任务队列架构解读：为什么一次只能处理一首歌？串行队列、取消与跨重启恢复设计
StemDeck任务队列架构解读为什么一次只能处理一首歌串行队列、取消与跨重启恢复设计【免费下载链接】stemdeckStemdeck is an modern stem extraction platform for musicians,producers and hobbyists, designed to isolate vocals, drums, bass, piano and guitar for practice, transcription, remixing, and creative audio workflows through a modern and interactive interface项目地址: https://gitcode.com/gh_mirrors/st/stemdeckStemDeck 是一款本地化的干声提取stem separation平台能把一首歌拆成人声、鼓、贝斯、钢琴、吉他等独立轨道供练习、扒谱与混音使用。当你一次导入多首歌时这些任务会进入一个串行导入队列任何时刻只处理一首。这篇文章将带你读懂这个设计背后的三个关键决策为什么必须串行、取消如何做到秒级生效、关闭程序后队列如何跨重启恢复并给出对应的源码位置适合想了解 StemDeck 任务队列架构的新手与开发者。一、为什么一次只能处理一首歌这不是为了省资源的性能折中而是一个正确性约束——源码里写得很直白Exactly one job runs at a time, and that is a correctness requirement rather than a tuning choice. —— app/pipeline/jobqueue.py1.1 真正的根源一个共享的 Demucs 工作进程StemDeck 用 Demucs 模型做音频分离而它并不是每个任务临时起一个分离进程而是维护了一个常驻的单一 worker 子进程app/pipeline/separate.py所有任务通过同一条 stdin把请求发给这个 worker进度信息从同一条 stderr流里解析再按任务归属回写注册表用一个全局映射把任务 ID 绑定到这个进程上registry.set_proc。如果两个任务并发跑会发生什么两个任务的请求会交错写进同一个 stdinA 任务解析到的进度条可能其实是 B 任务的输出更糟的是——你取消其中一个任务worker 进程会被整个杀掉另一个正在分离的任务也随之陪葬。所以串行不是选择而是这套单 worker 单条管道通信方式的必然要求。1.2 双保险单消费者 管道锁架构上 StemDeck 放了两道防线防线位置作用队列单消费者app/pipeline/jobqueue.py 的_worker_loop正常路径上同一时刻只有一个任务被派发管道锁app/pipeline/runner.py 的_pipeline_lock兜底任何绕过队列直接调用管道的路径例如测试、人声再拆分排队任务A → 排队任务B → 排队任务C │ ▼ ┌─────────────────┐ │ 单一消费者循环 │ ← jobqueue._worker_loop └────────┬────────┘ ▼ ┌─────────────────┐ │ _pipeline_lock │ ← 第二道保险 └────────┬────────┘ ▼ ┌─────────────────┐ │ 常驻 Demucs │ ← 唯一的分离 worker │ worker 进程 │ └─────────────────┘二、串行队列的 4 个核心设计2.1 从隐式等待到显式队列早期实现里任务用裸的asyncio.create_task启动然后在管道锁上阻塞——队列对用户完全不可见没有列表、没有固定排位、排队中的任务也无法取消。现在 app/pipeline/jobqueue.py 用一个deque显式保存等待中的任务 ID配合一个threading.Lock保证同步线程池接口与异步 worker 安全共享状态。2.2 拖拽排序为什么用锚点而不是下标排队任务支持拖拽调整顺序POST /api/queue/reorder见 app/api/queue.py。一个容易被忽视的细节是接口参数不是放到第 N 位而是放到某个任务之后。原因很现实队列在你拖拽的这几秒里可能正好完成了一首任务整条队列往前挪了一位——按下标插入可能插错位置。锚点方式更诚实如果锚点任务在拖拽期间已经离开了队列接口会回退到队尾并把最新队列顺序返回给前端重新同步而不是让客户端猜。2.3 双通道容量限制上传与链接分开计数等待中的文件上传会把源文件最大 400 MB一直留在磁盘上而链接导入等待时不占任何磁盘。所以容量按类型分开计算app/core/config.pyMAX_PENDING_UPLOAD_JOBS上传排队上限默认 20MAX_PENDING_URL_JOBS链接排队上限默认 200。这样一堆链接排队不会挤占文件上传的名额反之亦然。超限会返回 503并给出可操作的提示取消一个任务或稍候而不是一句笼统的服务繁忙。2.4 一条 SSE 流广播整条队列前端不为每个任务各开一条事件流而是整条队列共用一条/api/queue/eventsapp/api/queue.py。注释解释了原因HTTP/1.1 下浏览器对同一源的并发连接大约只有 6 个而 DAW 界面本来就占着这些连接加载 stem WAV 音频——二十条队列流会在触及服务端限制前就饿死音频加载。服务端用指纹任务 ID 序列 各任务版本号做廉价的变更检测只有真正变化时才推送一帧前端 static/js/queue.js 还有 2 秒轮询作为 SSE 断线时的兜底。三、取消机制等待、运行、以及一个危险的缝隙 ⏹️取消入口是POST /api/jobs/{id}/cancelapp/api/jobs.py按任务所处位置分三种处理3.1 还在排队立即摘除立刻释放磁盘discard(job_id) → 状态置为 cancelled → 删除任务目录排队中的上传任务可能正攥着几百 MB 的源文件所以这一步会马上把文件从磁盘清掉并释放它占用的容量名额——而不是等它排到队头才想起自己被取消了。3.2 正在运行标志位 直接终止子进程运行中的任务无法从 Python 线程内部强行打断分离调用阻塞在asyncio.to_thread里所以采用标志位 杀进程组合拳置cancel_requested标志管道在每个阶段之间检查它_check_cancel如果该任务持有 Demucs worker 进程API 线程直接 terminate 子进程——取消不必等管道线程自己发现标志位。连 ffmpeg 的转码调用都被注册过set_proc否则取消在几十分钟的转码期间会完全失灵这是 #519 修复的真实问题。3.3 危险的缝隙任务既不在队列也不在运行位有一个微妙的竞态窗口worker 把任务从队列popleft()出来、到_set_running()标记它为运行中的这一小段时间里这个任务哪儿都不在。此时取消请求会发现discard()返回 False、running_id()返回 None只能默默设置标志位后返回。如果没有兜底这个任务会永远卡在queued状态队列视图里看不到它、容量计数一直占着、上传的源文件永不释放而且——因为 queued 状态是持久化的——每次重启它都会被重新排回队列issue #520 的真实事故。解法是让唯一消费者负责收尾worker 发现自己刚拿到的任务已被请求取消时由它来完成取消app/pipeline/jobqueue.py 的_finalise_dropped_job。注释总结得很到位The worker owns the job by then and is the only thing that can close it out.四、跨重启恢复重启后队列不丢任务 StemDeck 的桌面后端是常驻进程程序可能因崩溃、OOM、断电或更新而重启。恢复逻辑全部在 app/core/registry.py 中。4.1 registry.json哪些任务值得留档持久化分两类app/core/registry.py已完成done→ 必须持久化否则重启后曲库消失可恢复queued/processing/downloading/analyzing/separating→ 同样持久化让死在半路的队列能活下来。写入采用临时文件 原子替换临时文件名每次调用都不同——两个写者管道线程、API 线程、清理循环并发写时不会互相踩文件这在 Windows 上尤其关键。4.2 重启后一个死在半路的任务有三种命运restore()启动时逐条检查可恢复任务核心判断在 _resume_or_recover磁盘上的状态处理方式stems 目录完整按完成处理——崩溃恰好发生在最后一片 stem 写完和done 落盘之间重跑只会制造重复曲库条目所以直接恢复为 donestems 不完整清掉半成品输出回到队头重跑——不清的话collect()会把上次的残留文件误当成结果resume_attempts已用尽上限 1 次明确失败提示被重启中断了两次请重新导入第三条是防死锁的关键想象一个每次跑都会把进程拖崩的任务比如 Demucs OOM 直接带走后端。如果不限制重试次数它会每次启动都被重新排队、每次又崩把整条队列永久卡死。恢复尝试计数会在重启时立刻写回磁盘——否则下次启动读到的还是旧计数限制就形同虚设。4.3 重启后队列默认暂停打开 App ≠ 自动开工恢复的任务会重新入队但队列进入paused 状态app/main.pyopening the app must not start separating on its own. A restored queue can be dozens of tracks and hours of GPU, and the user may well have opened StemDeck to do something else entirely.你上次可能排了二三十首、算下来是几个小时的 GPU 时间今天打开程序也许只是想听个歌。所以恢复的任务静静等着由你按 StartPOST /api/queue/start主动开工。而新导入的任务会自动解除暂停——用户刚点了处理按钮结果什么都没发生本身就是 bug。另外还有一层保险restore()会扫描任务目录做孤儿恢复——凡是注册表里没有、但磁盘上存在完整 stems 的目录上次进程在落盘前就死了会被重新认领进曲库而被用户删除过的任务有墓碑记录即使文件删不干净也不会死灰复燃#521 修掉的正是删掉的歌重启后复活。五、一图看懂任务的一生导入链接/上传 │ 容量检查分上传/链接两路 ▼ 注册表 排队 ──────────► registry.json 落盘 │ ├─ 排队中被取消 → 摘除 清目录 │ ▼ 单一消费者取出缝隙窗口取消标志兜底 │ ▼ _pipeline_lock → 下载/转码 → Demucs 分离 → 混音 → 节拍网格 │ 崩溃/重启 ▼ ├─ stems 完整 → 恢复为 done 状态落盘 ◄──────────────────┤ │ └─ 不完整 → 清残留、重新排队限 1 次 ▼ done → 进入曲库失败 → 隔离到 failed/ 保留诊断证据六、总结三个决策一种工程哲学 回看这套架构为什么一次只能处理一首歌的答案其实是一整条设计链串行是正确性要求单一 Demucs worker 单条 stdin/stderr 管道决定了并发必然互相干扰单消费者循环app/pipeline/jobqueue.py 管道锁app/pipeline/runner.py双保险兜住它。取消是分层契约排队任务立即摘除释放磁盘、运行任务标志位 终止子进程、缝隙窗口交给唯一消费者收尾——三个位置各自负责不留悬空状态。持久化是恢复的前提registry.json 磁盘状态判断 单次重试上限 恢复后默认暂停让崩溃后重启从丢任务变成排队重来或自动补完。想深入源码的话建议按这条路径阅读队列核心app/pipeline/jobqueue.py队列 API 与 SSEapp/api/queue.py任务生命周期与取消app/api/jobs.py注册表与恢复app/core/registry.py启动时的恢复与暂停app/main.py前端队列视图static/js/queue.js【免费下载链接】stemdeckStemdeck is an modern stem extraction platform for musicians,producers and hobbyists, designed to isolate vocals, drums, bass, piano and guitar for practice, transcription, remixing, and creative audio workflows through a modern and interactive interface项目地址: https://gitcode.com/gh_mirrors/st/stemdeck创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考