一个主页的视频怎么批量下载？自研采集任务队列的一次设计复盘

一个主页的视频怎么批量下载？自研采集任务队列的一次设计复盘

有人问我：能不能把一个博主的参考视频全存下来做拆解？我说简单，手动下呗。两个小时后我存完了 43 条，却不记得任何一条讲了什么——只记得手腕在重复"点、等、点、等"。我不服气，把当时能找到的工具挨个试了一遍，最长的那条链路，我点了 60 多次下载按钮。

做完这件事我坐在那里发了会儿呆：一个真人对着页面一小时的工作量，机器本该十分钟跑完，中间那 50 分钟的差距，全是"人肉调度器"在替软件打工。做工具的人最怕的就是这个——于是接下来的两周，我把"整主页批量下载"重做成了一条采集任务队列。这篇文章是一次完整的设计复盘：需求怎么拆、状态机怎么定、并发怎么被教做人、边界在哪里。

⚠️合规前提：本文讨论的采集只针对公开可见内容，目的仅限个人学习与自有素材备份，全程遵守各平台服务条款与频控规则，不涉及存储、传播或商用他人版权作品。

📑 文章目录

• 一. 需求拆解：单条、整主页、合集，是三个产品 🧩
• 二. 为什么手动点不动：登录态、翻页与风控 🧱
• 三. 任务队列设计：排队-解析-下载-重试的状态机 🚦
• 四. 进度可视化：为什么每条任务都要能单独重试 👀
• 五. 自动入库：下载完成只是开始 📦
• 六. 踩过的坑：并发被限流、分页参数突变 🕳️
• 七. 边界与合规：只做公开内容，仅供个人学习 ⚖️
• 常见问题 FAQ
• 八. 写在最后 📝
• 参考文献

一. 需求拆解：单条、整主页、合集，是三个产品 🧩

“主页视频批量下载"听起来是一个功能，拆开其实是三种形态，工程含义完全不同：单条是"一次解析一次下载”；整主页是"先枚举、再展开任务"；合集（创作者把视频归成的专题列表）介于两者之间，但它的分页机制最不稳定。做设计前先把这三件事分开建模，是这次复盘的第一个结论。

需求确认后，剩下所有设计都围绕一个词：排队。

二. 为什么手动点不动：登录态、翻页与风控 🧱

手动点 60 次下载，累的不是手，是三个机器本来能消化、但人肉处理不了的环节。

**登录态。**人在浏览器里是登录状态，脚本不是。这里我做过一次权衡：要不要引导用户把账号授权给工具去模拟登录？结论是不做。批量采集的正当场景是公开内容与自有素材备份，不该依赖他人账号的私密会话；工具只处理匿名状态下的公开分页，账号相关操作留给用户自己。少碰一点凭证，就少一分信任成本。

**翻页。**刷过抖音或快手主页的人都知道，列表是无限滚动的，一次只加载二十来条，剩下的靠滚动触发。手动下载的本质，是人肉当翻页器。队列化的做法是把"枚举"和"下载"拆成两个阶段：先沿公开分页把视频 ID 清单完整拉下来，再逐条展开成下载任务。

**风控节流。**人点按钮的频率是随机、缓慢、带停顿的；脚本是恒定频率的，一眼假。所以工程上我们不追求"最快"，只追求"最像一个有节制的人在浏览"：请求间隔加随机抖动，量大自然慢。

思考：💡 慢一点没关系，反正挂机跑？
🤔 不止是体验问题。节流是这套系统里少数"合规与稳定性双赢"的设计：把频率压到人工浏览的量级，既降低被风控标记的概率，也让失败率显著下降。后来限流事故证明，这条是整套设计里最值得守住的纪律。

三. 任务队列设计：排队-解析-下载-重试的状态机 🚦

队列的骨架是一张状态机。六态：queued（排队）→parsing（解析）→downloading（下载）→done（完成），外加retrying（退避待重试）与failed（终态，可人工重试）。

领取槽位 解析出播放地址 流式落盘 [queued] ──────────────▶ [parsing] ────────────▶ [downloading] ────────────┐ ▲ │ 解析失败 │ 网络中断 │ 全部字节到齐 │ ▼ ▼ ▼ │ ┌──────────────────────────────────────┐ [done] │ │ [retrying] 指数退避+抖动 │ │ 元数据落库 │ └──────────────────────────────────────┘ ▼ │ │ 重试次数 < N → 回到 parsing/downloading (自动入库，见第五节) │ 人工重试（任意终态可回）│ 达到上限 ▼ └───────────────────────────────▶ [failed] ◀── 确定性失败（内容非公开/地址已失效）

# 状态机骨架：状态迁移只能由调度器驱动，UI、计费、入库都只是状态的投影ALLOWED={QUEUED:{PARSING,FAILED},DOWNLOADING:{DONE,RETRYING},RETRYING:{PARSING,DOWNLOADING,FAILED},DONE:{ARCHIVED},# 自动入库是 done 的延伸态FAILED:{QUEUED},# 只能人工触发回队，永不自动迁移# ...}deftransition(task,event):target=classify(task,event)# 限流/超时=暂时失败；404/非公开=确定性失败iftargetnotinALLOWED[task.state]:raiseIllegalTransition(task)# 脏迁移直接拒绝，坏不了账本task.state=target audit_log.append(task.id,target)# 每次迁移落本地日志：崩溃恢复 + 扣费证据链

两个设计决策事后看最关键：其一，延迟解析——播放地址有时效签名，任务在队列里排久了会 403，所以解析动作推迟到领取槽位的那一刻做；其二，classify 先于 retry——重试的前提是分得清"暂时"和"彻底"，否则就是把用户往限流枪口上再推一把。

四. 进度可视化：为什么每条任务都要能单独重试 👀

队列跑起来之后，用户对"确定性"的需求远大于对"速度"的需求。批量任务天然参差：两百条里有 195 条顺利完成、5 条卡在解析——如果界面只有一个总进度圈转，用户只能全部重跑，而这恰恰是风险最高的操作。

所以列表里每一条任务都是独立个体：各自的实时进度、各自的失败原因文案（"被限流，稍后自动重试"和"内容不可见，需你确认"是两种语气）、各自的重试按钮。配合按次付费的下载失败不扣次数规则，重试对用户是零成本的，对系统则是把"判断失败"的权力还给用户。

思考：💡 失败原因要不要把技术细节全摊开？
🤔 摊一半。原始错误码用户看不懂，纯安慰话术又不可信。我们的折中是"人话结论 + 可展开详情"：第一行永远是"下一步该做什么"，详情留给愿意深究的人。

五. 自动入库：下载完成只是开始 📦

done不是终点。一条存完就躺在"下载"文件夹里改名为video(23).mp4的素材，和没下载没有区别。所以状态机里 done 后面还有一个archived：字节落盘后立即写元数据（来源平台、原链接、发布日期、时长），按平台/类型建索引，去重校验，进本地素材库。

这一步背后是一句我们内部反复说的话：下载是动作，素材库才是资产。

影栈是面向创作者的素材库产品——短视频素材资产管理平台。它把抖音、B站、小红书、快手等平台获取的图文、视频、音频素材统一管理起来：智能集合筛选、项目工作区、素材对比同步播放、一键拖入剪辑软件，让创作者的每一次收藏都变成可复用的资产。

这条采集队列与素材库已经做进了影栈桌面客户端（macOS / Win10/11，客户端页：https://yc.codexaiplus.com/client ），目前公测预约中、安装包尚未公开，公测期功能免费；素材文件始终保存在用户本地目录，库丢了可以重建，文件永远是你自己的。

六. 踩过的坑：并发被限流、分页参数突变 🕳️

坑一：并发开太大，被平台教做人。第一版我理直气壮开了 6 个并发下载，觉得这是对技术的尊重。跑 80 条任务，前 30 条生龙活虎，之后整条链路的请求开始成批 403——不是单任务失败，是枚举接口也开始返回空列表。那一刻我才明白：风控不针对某个请求，针对的是这个来源的整体行为速率。修复方案没有魔法：信号量把同时在途的任务压到 2，退避加抖动，宁可慢，不可炸。

MAX_INFLIGHT=2# 实测下来的"最温柔"并发，再高就开始被标记slot=asyncio.Semaphore(MAX_INFLIGHT)asyncdefrun(task):asyncwithslot:# 并发闸：同一时刻最多两个任务在下载forattemptinrange(task.MAX_RETRY):try:awaitstream_to_disk(task)# 流式写盘，长视频内存占用恒定returntransition(task,DONE)except(RateLimited,Timeout):# 暂时性失败：指数退避 + 随机抖动awaitasyncio.sleep(min(BASE*2**attempt,CAP)+random()*JITTER)transition(task,RETRYING)except(Gone,NotPublic):# 确定性失败：立刻终态，绝不重试骚扰returntransition(task,FAILED)returntransition(task,FAILED)# 达到上限 → 交还人工决策

坑二：合集分页参数突变。某天起，快手某类合集的枚举开始大量重复入库，查下来是分页游标结构变了，旧参数被接口宽容地"忽略"，于是每一页都返回第一页。教训：枚举阶段必须以视频 ID 去重为准绳，而不是信任分页参数本身；并且"快照式"先固定清单再建任务，防止枚举中途列表变化导致错位。

思考：💡 被限流了，为什么不换个伪装头硬冲？
🤔 因为那是把工具往灰产的方向推。被限流说明当前行为已经越过了平台认为舒适的边界，正确响应是减速、退避、把失败诚实地告诉用户，而不是军备竞赛。我们宁可接受"今天这 5 条没下成"，也不透支"这个工具明天还能不能用"。

七. 边界与合规：只做公开内容，仅供个人学习 ⚖️

最后是把贯穿全文的边界写成白纸黑字，这也是产品设计的一部分，不是免责声明的点缀：

• 只处理公开内容：需要登录可见、粉丝专属、会员专属、已删除或权限变更的视频，枚举阶段就不会进入任务清单，确定性失败直接终态；
• 用途限定：仅供个人学习与自有素材备份（比如存自己账号的历史作品），不鼓励任何形式的搬运、二次分发与商用；
• 频率自律：并发与节流策略本身就是一种态度——我们对平台的姿势是"安静路过的访客"，不是"强攻"；
• 本地为王：素材存在用户自己的磁盘上，我们不做服务端中转存储，数据不离开用户的设备。

做采集类功能，边界画得越清楚，产品能走的路越长。

常见问题 FAQ

Q1：一个主页的视频能全部批量下载下来吗？
不能保证"全部"。只有匿名状态下公开可见、且分页接口能枚举到的内容会进任务队列；被作者删除、设为权限可见、或平台限制公开展示条目的，拿不到也不该拿。

Q2：合集下载和整主页批量有什么区别？
主页是"账号维度"的枚举，合集是"专题维度"的枚举，一个账号可以有多个合集。两者共用同一条任务队列，区别只在枚举来源；合集的分页游标更容易变化（见第六节踩坑）。

Q3：采集抖音、快手会不会很容易触发风控？
取决于行为速率。任务队列默认低并发、带随机抖动、失败指数退避，把请求节奏压到接近人工浏览的量级；被限流的任务会自动转入重试等待，不会持续骚扰平台。

Q4：某条任务失败了，会白扣次数吗？
不会。按次付费的规则里写死了"下载失败不扣次数"，计费动作后置到任务到达完成状态之后，失败任务可以随时单独重试。

八. 写在最后 📝

写完这套队列，我偶尔还会想起那 60 多次点击。做工具的人有种很朴素的执念：看见重复动作就难受，看见"人肉调度器"就手痒，非要把人从机械劳动里换出去不可。但这个项目教给我的另一件事是克制——技术的边界不在"能不能"，在"该不该"：只做公开内容，只服务个人学习与自有备份，慢一点、安静一点。把力气花在秩序上，而不是花在越界上，这大概就是我们理解的"把收藏变成资产"。

关于影栈：影栈桌面客户端正在迭代文中这套采集队列与本地素材库，macOS / Win10/11，公测预约中（安装包未公开），公测期功能免费，官网 https://yc.codexaiplus.com/client 。每一次收藏，都算数。

参考文献

[1] Node.js 官方文档. “Stream.” nodejs.org. https://nodejs.org/api/stream.html

[2] Bull 项目. “A job queue for Node.js backed by Redis.” GitHub. https://github.com/OptimalBits/bull

[3] yt-dlp 项目. “A feature-rich command-line audio/video downloader.” GitHub. https://github.com/yt-dlp/yt-dlp

[4] AWS Architecture Blog. “Exponential Backoff and Jitter.” aws.amazon.com. https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/