1. 从一次批量抓取崩溃说起为什么单线程下载在抖音场景下必然翻车做过内容归档的人大概都有过这种体验脚本跑得好好的前几十条视频顺利落盘突然某一条卡住不动整个队列跟着僵死或者跑到一半网络抖了一下重试逻辑没写好直接把已经下载好的文件覆盖成半截损坏的碎片。我最早写抖音内容抓取工具的时候就是用一个最朴素的循环加requests.get结果在一次三百多条的目标清单里成功率只有六成出头剩下的要么超时、要么拿到的是被限流后的空响应。这个问题的根源不在于代码写得丑而在于抖音的内容获取链路本身就是一个高不确定性环境。它涉及签名参数动态生成、请求头校验、CDN 分片、跳转重定向、以及服务端对异常频率的软性限制。任何一环出问题单线程串行流程都会把整条链路拖死。所以后来我彻底重构了这套工作流核心思路就是标题里说的3层容错架构——把容错从事后补救变成分层内建。这篇内容适合两类人看一类是正在用 douyin-downloader 或者类似工具做内容归档、素材收集的运营和技术同学另一类是想理解一个高可用抓取工作流到底该怎么设计的开发者。我会把三层容错的设计动机、每一层的具体实现逻辑、参数怎么调、踩过哪些坑全部摊开讲清楚。你不需要有很深的分布式背景只要写过基本的 Python 请求代码就能跟着复现。先说结论三层容错分别解决的是单请求级别的失败、单任务级别的失败、以及整批工作流级别的失败。这三层的边界如果划不清楚就会出现重试把限流触发得更狠或者任务级失败被当成请求级失败反复重试这类典型问题。下面逐层拆。2. 第一层容错单请求的重试、退避与请求指纹管理2.1 为什么简单的 retry 装饰器在这里不够用很多人第一反应是套一个tenacity或者自己写个for i in range(3)的重试。这在普通 API 场景下没问题但在抖音内容获取里会踩两个坑。第一个坑是重试的请求长得一模一样。如果你的请求头、签名参数、时间戳在重试时完全不变服务端很容易识别出这是同一个失败请求的重复投递直接给你更严格的限制。正确的做法是每次重试都重新生成请求指纹——包括更新签名、刷新时间戳、必要时轮换 User-Agent 池。第二个坑是固定间隔重试。失败后立刻重试等于在服务端已经注意到你的时候继续加压。我实测下来指数退避配合抖动jitter的效果最好基础间隔从 1 秒起步每次乘以 1.8 左右再加一个 ±30% 的随机抖动避免多个任务在同一时刻集体重试形成脉冲。import time import random def backoff_delay(attempt, base1.0, factor1.8, max_delay30.0): delay min(base * (factor ** attempt), max_delay) jitter delay * random.uniform(-0.3, 0.3) return max(0.5, delay jitter)这段逻辑看起来简单但max_delay和factor这两个参数是要根据你的并发规模调的。并发越高factor 应该越大否则退避还没生效请求已经又堆上去了。2.2 请求指纹的三个可变维度我把请求指纹拆成三个可以独立轮换的维度这样重试时不会整体变化导致签名失效也不会完全不变导致被识别。维度是否每次重试都变说明时间戳与签名必须变签名依赖时间戳时间戳不变签名就是废的User-Agent按轮换池随机准备 5-8 个主流移动端 UA重试时换一个请求间隔指数退避不改变请求内容只改变节奏这里有个细节签名参数里的时间戳和请求头里的时间戳必须一致否则服务端校验会直接拒绝。我早期就犯过这个错重试时只更新了 URL 里的签名时间戳忘了同步 header结果所有重试全部 403排查了半天才定位到。2.3 超时设置连接超时和读取超时要分开requests的timeout参数如果只给一个值会同时作用于连接和读取。但在抖音场景下连接通常很快慢的是读取尤其是视频流分片。我建议分开设置timeout (5, 20) # 连接5秒读取20秒连接超时给短一点快速失败快速重试读取超时给长一点避免大文件下载中途被误判为失败。这个参数我调过好几轮连接 5 秒、读取 20 秒是成功率比较稳的组合。如果你的网络环境波动大读取可以放宽到 30 秒但不要无限等否则任务级容错就没法及时介入了。提示重试次数不要设太高。单请求层面我一般设 3 次超过 3 次还失败说明问题不在这一层应该交给任务级容错去处理而不是在这里死磕。3. 第二层容错任务级的状态机与断点续传3.1 把每个内容抓取当成一个独立任务第一层解决的是一次请求失败怎么办但如果某个内容本身已经不可访问比如被删除、被设为私密你重试一百次也没用。这时候就需要第二层任务级容错。我的做法是把每个目标内容抽象成一个任务对象带一个明确的状态机PENDING - FETCHING - DOWNLOADING - VERIFYING - DONE \- FAILED_RETRYABLE \- FAILED_PERMANENT关键区别在于FAILED_RETRYABLE和FAILED_PERMANENT。前者是网络抖动、临时限流这类可以再试的后者是内容不存在、权限不足这类重试无意义的。如果不做这个区分整批任务会被少数永久失败的任务拖住反复消耗重试配额。判断逻辑我总结了几条经验规则HTTP 404 / 内容已删除标记直接判永久失败不重试HTTP 403 / 429判可重试但退避时间要拉长连接超时 / 读取超时判可重试返回内容为空但状态码 200需要进一步校验可能是被软性拦截最后这条特别容易被忽略。有些时候服务端返回 200但 body 是空的或者是一个提示页如果你不校验内容就直接落盘会得到一堆垃圾文件。3.2 断点续传分片下载与临时文件管理视频文件通常不小下载到一半失败如果从头再来既浪费时间又增加请求压力。所以任务级容错必须包含断点续传。实现上我用的是分片下载加临时文件记录import os def download_with_resume(url, filepath, chunk_size1024*1024): tmp_path filepath .part downloaded os.path.getsize(tmp_path) if os.path.exists(tmp_path) else 0 headers {Range: fbytes{downloaded}-} if downloaded else {} # 发起请求追加写入 tmp_path # 完成后 os.rename(tmp_path, filepath)这里有几个实操要点。第一.part临时文件在任务成功后才重命名为正式文件这样即使中途崩溃也不会污染已完成的内容库。第二Range 请求不是所有 CDN 都支持如果服务端返回 200 而不是 206说明不支持断点续传这时候要清空临时文件重新完整下载否则会拼接出错。第三临时文件要定期清理我一般设置 24 小时未更新的.part文件自动删除避免磁盘被僵尸文件占满。3.3 任务队列的并发控制任务级容错还涉及并发数的问题。并发太低效率上不去并发太高容易触发限流。我的经验值是同时活跃的下载任务控制在 4-8 个具体取决于你的网络出口和目标内容的分布。更重要的是并发控制要和第一层的退避联动。如果某个时间段内失败率突然升高应该动态降低并发而不是维持原并发继续硬冲。我加了一个简单的自适应逻辑连续 5 个任务失败并发数减半连续 20 个任务成功并发数逐步恢复。class AdaptiveConcurrency: def __init__(self, initial6, min_conc1, max_conc10): self.current initial self.min_conc min_conc self.max_conc max_conc self.consecutive_fail 0 self.consecutive_success 0 def on_failure(self): self.consecutive_fail 1 self.consecutive_success 0 if self.consecutive_fail 5: self.current max(self.min_conc, self.current // 2) self.consecutive_fail 0 def on_success(self): self.consecutive_success 1 self.consecutive_fail 0 if self.consecutive_success 20: self.current min(self.max_conc, self.current 1) self.consecutive_success 0这套逻辑不复杂但效果很明显。我实测下来加了自适应并发之后整批任务的成功率从 78% 提升到了 94% 左右而且没有出现被明显限流的情况。4. 第三层容错工作流级别的检查点与幂等恢复4.1 为什么需要工作流级别的容错前两层解决的是单个请求和单个任务的问题。但如果你要处理的是几百上千条内容跑一次可能要几个小时中间可能因为各种原因中断——进程被杀、机器重启、网络整体故障。这时候如果没有工作流级别的容错你只能从头再来前面下载好的内容要么重复下载要么被覆盖。第三层容错的核心是检查点checkpoint加幂等恢复。简单说就是定期把哪些任务已完成、哪些还在进行、哪些失败了这个状态持久化下来重启后从检查点继续而不是从头开始。4.2 检查点的存储选型检查点存哪里这个选择有讲究。我对比过几种方案方案优点缺点适用场景JSON 文件简单、无依赖并发写入有风险、大清单性能差小批量、单进程SQLite单文件、支持事务、查询方便高并发写入需要加锁中小批量、推荐Redis高性能、支持原子操作需要额外服务、持久化配置复杂大批量、多进程我最终选了 SQLite因为它在单机、中等批量、需要事务保证这个场景下是最平衡的。每条任务一行记录状态更新用UPDATE ... WHERE status PENDING这种带条件的更新天然保证幂等——即使同一任务被处理两次第二次的条件更新不会生效。CREATE TABLE tasks ( id TEXT PRIMARY KEY, url TEXT NOT NULL, status TEXT DEFAULT PENDING, retry_count INTEGER DEFAULT 0, filepath TEXT, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 幂等领取任务 UPDATE tasks SET status FETCHING, updated_at CURRENT_TIMESTAMP WHERE id ? AND status IN (PENDING, FAILED_RETRYABLE);这个WHERE status IN (...)就是幂等的关键。不管多少个进程同时来领这个任务只有一个能成功把状态改掉其他的影响行数为 0直接跳过。4.3 崩溃恢复时的状态清理重启后有一类特殊状态需要处理FETCHING和DOWNLOADING。这些是进行中的状态但进程已经死了实际上没有人在处理它们。如果不清理这些任务会永远卡住。我的做法是启动时扫描所有进行中状态的任务把它们重置为可重试状态同时检查对应的.part临时文件是否存在存在就保留用于断点续传不存在就从头开始。def recover_interrupted_tasks(conn): conn.execute( UPDATE tasks SET status FAILED_RETRYABLE WHERE status IN (FETCHING, DOWNLOADING) ) conn.commit()这一步看起来简单但非常关键。我见过不少工具就是因为没有这个恢复逻辑一旦崩溃就有一批任务永远卡在中间状态既不算完成也不算失败整批任务的统计都对不上。4.4 完成校验怎么确认一个任务真的完成了第三层容错还有一个容易被忽视的点完成校验。任务状态标成 DONE 不代表文件真的没问题。我加了三重校验文件存在且大小大于一个最小阈值比如 100KB排除空文件文件头字节符合视频格式特征MP4 的 ftyp box文件大小与响应头里的 Content-Length 一致如果服务端提供了的话只有三重都通过才把状态改成 DONE。任何一重失败降级为可重试状态并删除损坏文件。这个校验逻辑帮我拦下了不少看起来下载成功实际是坏文件的情况尤其是网络不稳定的时候。5. 三层容错如何协同一次完整工作流的执行链路5.1 从任务领取到落盘的全过程把三层串起来看一次完整的内容获取是这样的工作流启动从 SQLite 里领取一批 PENDING 任务交给任务调度器。调度器根据当前自适应并发数把任务分发给工作线程。每个工作线程执行任务时内部的请求走第一层容错——失败重试、指数退避、指纹轮换。如果单请求重试 3 次仍失败任务标记为可重试或永久失败交回任务层。任务层根据失败类型决定是否重新入队。整个过程中检查点定期写入 SQLite崩溃后可恢复。这个链路里三层的职责边界非常清晰第一层只管这一次请求不关心任务整体第二层只管这一个任务不关心整批进度第三层只管整批工作流不关心单个请求细节边界清晰的好处是任何一层出问题都不会污染其他层。比如第一层重试次数用完了它不会自己去改任务状态而是抛给第二层处理第二层判定永久失败后也不会去动检查点交给第三层统一记录。5.2 参数联动三层之间的配置怎么配合三层容错的参数不是孤立的需要联动调整。我整理了一张对照表参数所属层推荐值联动关系单请求重试次数第一层3越高第二层压力越小但单任务耗时越长退避基础间隔第一层1s与并发数反相关并发高则间隔大任务最大重试次数第二层5应大于单请求重试次数否则任务层没意义自适应并发上限第二层8-10与网络出口质量相关检查点写入间隔第三层每 10 个任务太频繁影响性能太稀疏丢失进度多这张表是我调了很多轮之后稳定下来的配置。新手最容易犯的错是把任务最大重试次数设得比单请求重试次数还小导致任务层根本没机会介入所有失败都在第一层被消耗掉了。5.3 日志与可观测性出问题时怎么定位是哪一层三层架构如果没有好的日志出问题时会很难定位。我的做法是给每层打不同前缀的日志[REQ]开头的是第一层请求日志记录每次请求的 URL、状态码、耗时、重试次数[TASK]开头的是第二层任务日志记录任务 ID、状态流转、失败原因分类[FLOW]开头的是第三层工作流日志记录检查点写入、恢复、整批统计这样出问题时先看[FLOW]确认整体进度再看[TASK]找到具体失败的任务最后看[REQ]定位到具体是哪次请求出的问题。排查链路非常清晰。注意日志里不要记录完整的签名参数和敏感 header只记录必要的诊断信息。这既是安全考虑也能避免日志文件膨胀过快。6. 实测数据与踩坑复盘这套架构到底值不值6.1 重构前后的效率对比我用同一批 500 条目标内容做了对比测试环境是普通家用宽带单机运行。指标单线程朴素版三层容错版总耗时约 4 小时 20 分约 1 小时 10 分成功率61%96%需人工介入是否崩溃后可恢复否是重复下载量高接近零耗时降低主要来自并发和断点续传成功率提升主要来自分层重试和永久失败识别。最让我满意的是崩溃后可恢复这一项——以前跑长任务必须守着现在可以放心让它自己跑。6.2 踩过的三个典型坑坑一重试时没更新签名导致重试全部失败。这个前面提过根源是没理解签名和时间戳的绑定关系。修复方法是在每次重试前重新走一遍签名生成逻辑而不是复用第一次的请求对象。坑二断点续传时服务端返回 200 而非 206导致文件拼接损坏。有些 CDN 对 Range 请求的响应不规范返回完整内容而不是分片。如果不检查状态码就直接追加写入文件会变成前半段 完整内容的畸形结构。修复方法是严格检查响应状态码非 206 就清空临时文件重新下载。坑三检查点写入太频繁SQLite 被写锁拖慢。我一开始每完成一个任务就写一次检查点结果在并发 8 的情况下SQLite 的写锁成了瓶颈。后来改成批量写入每 10 个任务或每 30 秒写一次性能立刻恢复正常。6.3 什么情况下这套架构可能过度设计说实话如果你只是偶尔下载十几条内容这套三层架构确实有点重。杀鸡用牛刀。但如果你的场景符合以下任意一条这套架构就是值得的单批任务超过 100 条需要长时间无人值守运行对成功率有要求不能接受大量人工补漏需要定期重复执行形成稳定的内容归档流程我个人的判断标准是只要你会因为一次失败而需要手动重跑就应该考虑上容错架构。因为手动重跑的时间成本远高于前期多写的那几百行代码。7. 把这套思路迁移到其他抓取场景三层容错的本质不是抖音特有的它是一套通用的高可用抓取工作流设计模式。任何面对高不确定性外部服务 大批量任务 需要无人值守的场景都可以套用。迁移的时候需要替换的主要是第一层的请求指纹逻辑和第二层的失败分类规则。比如换成其他内容平台签名算法不同、限流特征不同但重试要换指纹失败要分类这两个原则是不变的。第三层的检查点和幂等恢复几乎是通用的直接复用即可。我在另一个电商订单抓取的项目里就复用了这套架构只改了第一层的请求构造和第二层的失败判定第三层原封不动两天就搭起来了。这也是我为什么建议把三层边界划清楚——边界清晰复用成本才低。最后分享一个我在实际使用中的小习惯每次跑大批量任务之前先用 10 条内容做一次冒烟测试确认三层容错都正常工作再放开全量。这个习惯帮我避免了好几次跑了三小时才发现配置写错的尴尬。冒烟测试的成本是几分钟但省下的可能是几个小时。
