YumCut Daemon 架构完整指南:作业队列、并发控制与 FFmpeg 7.1.1 渲染配置

原创2026-10-24 16:07:272,001 阅读

YumCut Daemon 架构完整指南:作业队列、并发控制与 FFmpeg 7.1.1 渲染配置

YumCut 是一款免费开源的 AI 视频生成器,能把一句提示词自动变成可直接发布的竖版短视频,适用于 TikTok、Reels 和 YouTube Shorts。它的核心渲染引擎是 YumCut Daemon——一个本地守护进程,负责作业队列调度、并发控制与 FFmpeg 视频合成。本文带你用通俗易懂的方式读懂它的架构设计,并给出 FFmpeg 7.1.1 的完整渲染配置步骤。

YumCut 带水印的竖版视频生成效果演示

一、Daemon 是什么?🎬

可以把整个系统想象成一条自动化视频生产线:

  • Web 应用(API 层):接收用户请求,维护项目状态,相当于"工厂调度中心"
  • Daemon(渲染守护进程):真正干活的"工人",通过轮询 API 领取作业,本地执行脚本生成、配音、字幕、图片、视频合成等流水线,再把产物上传回存储服务
  • Storage(存储服务):持久化音频、图片、视频等媒体文件

一个项目会经历多个流水线阶段(脚本 → 音频 → 转写 → 元数据 → 字幕 → 图片 → 视频分镜 → 主视频合成),由 scripts/daemon/helpers/executor.ts 中的 executeJob 按项目状态分发到对应阶段处理器。

YumCut Daemon 渲染管线使用的场景画面示例

二、作业队列机制:从创建到认领

2.1 轮询式调度器(Scheduler)

Daemon 的主入口是 scripts/daemon/index.ts。它不做长连接,而是每隔 DAEMON_INTERVAL_MS(默认 1000ms)执行一次 tick():

  1. 防重入:若上一次 tick 还没结束(tickInProgress 为 true),本轮直接跳过,避免任务叠加
  2. 计算容量:capacity = maxConcurrency - inFlight.size,没有容量则跳过
  3. 拉取候选项目:调用 /api/daemon/projects/eligible 获取符合状态的项目
  4. 幂等建单:ensureJobsForProjects 为每个项目创建 queued 状态的作业,已存在则跳过
  5. 认领作业:claimNextJobs 按队列顺序逐个认领,直到达到容量上限

相关实现在 scripts/daemon/helpers/jobs.ts。

2.2 服务端事务锁定:防止多 Daemon 抢活

当部署了多个 Daemon 实例时,谁抢到作业?答案在 src/app/api/daemon/jobs/ 的 claim 路由里:服务端在单个数据库事务中用 updateMany 做原子更新,条件包括——

  • 作业当前必须是 queued 状态
  • 项目未被其他 Daemon 锁定(currentDaemonId 为空或就是自己)
  • 项目没有其他 running 作业(同一项目串行处理)

认领成功后,作业状态变为 running 并写入 daemonId,同时项目被打上 currentDaemonId 和 currentDaemonLockedAt 锁。这套字段由迁移 prisma/migrations/20251211173000_daemon_assignment_locking/ 引入,还附带了一张 Daemon 注册表用于标识每个实例。

作业生命周期为 queued → running → done / failed(另有 paused),状态回写通过 setJobStatus,带一次快速重试以容忍网络抖动。

三、并发控制与超时保护 ⚙️

3.1 在途任务计数

Daemon 用一个 inFlight Map 跟踪正在处理的项目。每个任务的执行流程:

  • 启动时登记 projectId、开始时间和 jobId
  • 任务完成(done/failed)后在 finally 中清理,释放并发额度
  • 同一项目不会重复启动(inFlight.has(job.projectId) 检查)

默认 DAEMON_MAX_CONCURRENCY=2,即同时最多渲染 2 个项目,避免打满 CPU 与内存。

3.2 看门狗超时 + 陈旧作业清理

  • 看门狗:每个任务启动时挂一个 setTimeout 计时器,超过 DAEMON_TASK_TIMEOUT_SECONDS(默认 3600 秒)仍未结束,就把项目置为 Error、作业标记为 failed,原因 task-timeout
  • 清理脚本:由于心跳机制已移除,改用 scripts/daemon/cleanup-stale-jobs.ts 定期扫描卡死作业。它调用 /api/daemon/jobs/sweep-stale 接口,默认清理超过 15 分钟(CLEANUP_TTL_MINUTES)的 running 作业,支持 CLEANUP_DRY_RUN=true 预演

3.3 优雅退出

收到 SIGINT / SIGTERM 时,Daemon 会停止调度循环,并给在途任务最多 1 秒的缓冲时间后再退出,保证状态尽量完整落库。

四、FFmpeg 7.1.1 渲染配置 🔧

4.1 为什么强制要求 7.1.1?

YumCut 的视频合成依赖多层画面合并(视频层 + 字幕 + 水印 + 叠加层),旧版 FFmpeg 的 merge-layer 处理存在缺陷,会导致合成失败。因此 Daemon 在启动时就会校验版本(见 scripts/daemon/helpers/ffmpeg.ts):

  • 执行 ffmpeg -version 并解析版本号,低于 7.1.1 立即退出并报错
  • 找不到 ffmpeg 或无法解析版本同样拒绝启动
  • 测试环境可用 DAEMON_SKIP_FFMPEG_CHECK=1 跳过检查(生产不推荐)

4.2 Ubuntu 下安装 FFmpeg 7.1.1 最快配置方法

完整的逐步指引见 docs/daemon-ffmpeg.md(适用于 Ubuntu 22.04 / 24.04 / 24.10),核心四步:

# 1. 移除系统自带版本(可选但更干净)
sudo apt remove ffmpeg && sudo apt autoremove

# 2. 添加维护 7.x 的 PPA 源
sudo add-apt-repository ppa:ubuntuhandbook1/ffmpeg7
sudo apt update

# 3. 安装
sudo apt install ffmpeg

# 4. 验证版本(应显示 ffmpeg version 7.1.1-…)
ffmpeg -version

💡 如果 Ubuntu Pro 拉取了 ESM 构建而非 PPA 版本,可用 sudo apt install -t "o=LP-PPA-ubuntuhandbook1-ffmpeg7" ffmpeg 强制指定来源。

五、配置文件速查表 📋

Daemon 的所有配置都放在 .daemon.env(可参考 daemon.env.example),由 scripts/daemon/helpers/config.ts 用 Zod 严格校验,缺失必填项会直接拒绝启动。

参数 默认值 说明
DAEMON_ID 必填 实例静态标识,用于监控与作业锁定
DAEMON_API_BASE_URL / DAEMON_STORAGE_BASE_URL 必填 API 与存储服务地址
DAEMON_API_PASSWORD 必填 与 API 层共享的认证密钥
DAEMON_INTERVAL_MS 1000 调度轮询间隔(毫秒)
DAEMON_MAX_CONCURRENCY 2 最大并行渲染项目数
DAEMON_TASK_TIMEOUT_SECONDS 3600 单任务看门狗超时(秒)
DAEMON_REQUEST_TIMEOUT_MS 15000 访问 API 的 HTTP 超时
DAEMON_SCRIPT_WORKSPACE 等 必填 脚本 / 字幕 / 角色 / 项目产物工作区路径
DAEMON_SCRIPT_MODE normal 脚本与图片生成速度档(fast / normal)

想观察调度器细节?设置 DAEMON_VERBOSE_SCHEDULER=1,每次 tick 都会打印容量、候选数、认领数等快照日志。

六、启动 Daemon 并验证 ✅

  1. 复制 daemon.env.example 为 .daemon.env,按部署环境填写
  2. 安装好 FFmpeg 7.1.1 并确认 ffmpeg -version 输出
  3. 运行 npm run daemon 启动

启动日志会依次显示:Daemon performing startup checks(版本与资产检查)→ Daemon startup checks passed → 打印完整运行配置 → Daemon starting。之后调度器立即执行第一次 tick,开始领取队列中的作业。

YumCut 批量生成的 AI 短视频成片效果九宫格

七、总结

YumCut Daemon 用一套朴素但健壮的设计扛住了批量渲染场景:轮询调度 + 幂等建单 + 事务锁定解决了多实例抢活问题;inFlight 计数 + 看门狗超时 + stale 清理脚本构成了完整的并发保护闭环;启动期 FFmpeg 7.1.1 强校验则从源头杜绝了渲染失败。理解这三块,你就能自如地部署、扩容和调优自己的 AI 短视频渲染集群了。🚀

登录后查看全文
app.yumcut.com