Python批量下载调度框架:断点续传、哈希校验与有界并发实践
做流媒体资源批量下载,最难的不是单个文件怎么下,而是把一堆文件稳定、不重复、不断点地拉下来。我之前在自建素材库和离线数据集的时候,经常遇到下载一半断掉、重新开始、重复下载、把磁盘IO和网络连接打到崩溃的问题,后来干脆自己设计了一个基于Python的批量任务调度框架,核心就三件事:断点续传、哈希校验、有界并发。这篇文章把整个设计思路和落地代码做一个完整复盘,适合那些需要批量获取公开媒体资源、自建媒体库、做离线数据备份,或者想学习如何用asyncio写一个正经任务框架的同学参考。
先说结论:这套框架不需要引入Celery、RabbitMQ这类重型中间件,在单机场景下用Python自带的asyncio就能把并发控制、任务调度、断点续传和完整性校验全部做干净。整个项目大概三百行核心代码,能支撑上千个下载任务的批量执行,跑挂了也能接着跑,不会因为一次断电把所有进度清零。
1. 项目概述与设计动因
1.1 需求背景与核心痛点
我最初的需求其实很简单:要把一批公开的音频资源(大约200个文件,总大小接近30GB)从远端服务器拉到本地,用于语音识别模型的训练数据准备。任务本身不复杂,但真开始做的时候发现一系列让人抓狂的问题。
最典型的一个场景:下载到第47个文件,进度95%,网络闪断,任务失败。重新跑一遍脚本?对不起,前面46个文件已经下载好了,脚本从头来过,要么跳过已经存在的文件,要么删掉重下。跳过会导致文件不完整,删掉重下浪费时间。更麻烦的是,这些资源文件没有统一的ETag约定,有的服务器支持断点续传,有的不支持,有的还带着代理缓存,返回的头信息五花八门。
我当时需要的是一个能长期稳定跑的东西:
- 批量导入下载任务,支持从文本文件、CSV甚至数据库里读URL。
- 每个任务独立管理状态,下载失败之后自动重试,不会拖垮整个队列。
- 已下载的部分文件要能断点续传,不能因为一次断网就全部重来。
- 下载完成后要做文件完整性校验,避免拿到一个损坏的媒体文件。
- 同时并发量要可控,不能一下开几百个连接把服务器或者本地网络搞挂。
这就是这个任务调度框架的起点。
1.2 设计原则与架构选型
在设计架构之前我对比了几种方案。
第一反应是直接用wget加curl循环跑。这个方案最直观,但状态管理很弱,失败重试策略不好写,并发控制要么靠xargs -P,要么自己写Shell脚本,一旦任务中断,整个状态就丢了。而且wget的-c虽然支持断点续传,但只对单文件有效,批量场景下的调度逻辑还是得自己写。
第二反应是上Celery加Redis。这套组合功能很全,分布式调度、任务持久化、重试机制都有。但问题是,我只有一个节点,任务类型就是简单的HTTP下载,引入Celery相当于杀鸡用牛刀,还要额外维护Broker和Worker进程。我仔细算了一下,光是为了跑批量下载,额外多出来的运维成本完全没必要。
第三,就是我现在采用的方案:asyncio + aiohttp + 自研状态机。
为什么选异步?因为下载任务是典型的IO密集型任务,瓶颈在网络和磁盘,不是CPU。用多线程当然也能做,但线程切换开销、共享变量的锁管理、线程池上限控制,这些写起来远不如协程自然。asyncio配合Semaphore可以轻量地限制并发度,而且Python 3.7之后的asyncio.run()封装非常友好,调试起来也直观。
架构上我把整个系统分成三层:
- 调度层:负责任务队列管理、任务状态流转、重试策略、并发控制。
- 下载层:基于aiohttp封装断点续传逻辑,负责HTTP Range请求、分块写入临时文件。
- 校验层:负责下载完成后的哈希计算与结果比对,校验失败自动触发重新下载。
这三层各司其职,互不干扰。每层都提供独立的日志输出,出了问题翻日志就能定位。
2. 核心机制拆解
2.1 断点续传:从Range Request到文件续写
断点续传的原理听起来很简单,实现的时候有几道坎。
HTTP协议里,客户端在请求头带上Range: bytes=<start>-<end>,服务器如果支持Range,会返回206 Partial Content,并在Content-Range头里带上传送的具体区间。如果不支持,会返回200 OK并且直接传整个文件。这是最基本的机制。
但实际应用中有几个关键点:
第一,本地文件怎么写才安全?
最稳妥的做法是下载时先写入临时文件,比如xxx.mp4.part。每次记录已下载字节数,下次断点续传时打开.part文件,seek到末尾,再从断点位置发起Range请求。这里要注意,seek之前必须确认文件的实际大小和记录的进度一致,否则文件大小对不上,继续写入会直接破坏数据结构。
我见过很多人直接往目标文件里写,下载到一半进程崩了,留下一个残缺的.mp4文件。后期校验哈希失败,但是你已经分不清这个文件是完整下载后校验失败,还是下载过程中就断了。
第二,怎么识别服务器是否支持续传?
判断依据是响应的状态码。206就是支持,200就是不支持或者说服务器选择忽略Range头。如果服务器不支持,策略上只能从零重新下载。
这里有个细节,很多代码只判断状态码,却不考虑重定向。aiohttp默认会跟随重定向,但重定向之后的响应状态码可能已经变了。我用allow_redirects=False先拿一轮响应,如果遇到301/302再手动处理Location,保证拿到的Range响应是原始服务器的返回。
第三,断点续传和普通“重传”的区别。
普通重传是重新发起整个文件的下载请求,断点续传是只请求缺失部分。对于大文件,这个差距是数量级的。一个1GB的文件已经下载了990MB,断点续传只需要再传10MB,而重传需要1GB。
顺带提一句,经常有人把下载续传和上传断点续传搞混。上传场景下一般用Content-Range头来分段推送,下载场景则是用Range头来分段获取,两者的协议语义完全不同。如果搜网上的代码,注意区分“断点续传和完整上传的区别”,下载框架里用的始终是Range。
2.2 哈希校验:完整性验证的最后一环
下载完成不等于文件可用。网络传输过程中数据可能损坏,服务器端文件可能本身就是坏的,甚至本地磁盘写入过程中可能遇到坏道。所以必须有一种机制来验证文件完整性,最常见的做法就是哈希校验。
我用的哈希算法是SHA-256。虽然MD5计算更快,但在2025年这个阶段,MD5已经被认为不安全,用在完整性校验场景虽然问题不大,但既然现代CPU计算SHA-256的速度也足够快,就没必要给自己留隐患。
哈希校验的算法本身没有太多花样,关键在怎么算。
- 分块读取:不能一次性把整个文件读进内存,几百MB的文件会直接把内存打爆。我每次读
8 * 1024 * 1024字节(8MB),丢进hashlib.sha256()的update()方法里。 - 二进制模式打开:文本模式下Windows系统会做换行符转换,导致算出的哈希和服务器上的完全不同。必须用
rb模式。 - 哈希值对比:两个哈希都转成十六进制字符串后比较,避免二进制比较时踩到字节序的坑。
校验通过的任务标记为completed,校验失败的任务重新进入下载队列,并且要带上重试次数。超过最大重试次数之后标记为failed,等待人工处理。
这里有一个容易被忽视的点:下载完成之后不要立刻删掉.part文件。哈希校验失败重试的时候,.part文件还能作为断点续传的基础。一旦删掉,整个文件从零开始,非常浪费。
2.3 有界并发:如何在速度和资源占用之间找平衡
“并发”这个词在Python里有很多实现方式,但资源是有限的。我现在说的“有界并发”,本质上是控制同时打开的网络连接数和占用的内存资源。
如果完全不限并发,直接把200个任务全部扔进asyncio事件循环,几百个协程同时向外发送请求,本地文件描述符会被耗尽,路由器可能扛不住几千个TCP连接,目标服务器也可能直接封IP。我遇到过本地OSError: Too many open files崩溃,原因就是并发连接数超过了系统文件描述符限制。
解决办法是用asyncio.Semaphore。
信号量本质上是一个计数器。初始化为N,每个协程要执行下载操作前先acquire(),计数器减1;下载结束后release(),计数器加1。当计数器为0的时候,新的协程会阻塞,直到有其他协程释放位置。这样就能保证同时激活的下载任务不超过N个。
这里要特别说明,信号量控制的是“正在下载的任务数”,不是“任务总数”。任务可以全量入列,但真正同时跑的就是信号量允许的N个。排队等着的协程并不会占用文件描述符,只是挂在事件循环上等待。
并发数N怎么定?我的经验是:
- 如果目标是公共资源站,N取4到8,太激进的并发容易触发反爬策略或者限流。
- 如果目标是自己的服务器,N可以取16到32,同时还要考虑带宽上限。
有一个估算公式:并发数 ≈ 期望总带宽 / 单连接平均带宽。比如期望占用500Mbps带宽,单连接平均能跑到50Mbps,那并发数取10左右比较合理。实际项目中我会先跑5个任务测速,再根据测速结果推算并发数。
3. 实操落地:一个可复用的调度框架
3.1 环境准备与目录设计
先交代环境。我用的是Python 3.10版本,依赖只有两个:
标准库用到的模块有:asyncio、hashlib、json、os、time、pathlib、dataclasses、logging。
项目目录结构:
tasks.json是整个框架的“记忆中枢”。每次任务状态变化都会立即写盘,这样即使进程被强杀,重启后也能从磁盘恢复现场。定时写盘或者只在下一次状态变化时写盘,这两种方案我都试过,最终选了“每次状态变化立即写盘”,因为任务状态变化频率不高,写盘开销可以忽略。
3.2 任务模型与状态持久化
任务模型我用dataclass定义:
这里我把任务状态定义成一个明确的状态机:
PENDING:任务刚加载进队列,还没开始下载。DOWNLOADING:正在下载或者等待断点续传。VERIFYING:下载已完成,正在计算哈希。COMPLETED:哈希校验通过,任务正式完成。FAILED:重试次数用尽,任务失败,等待人工介入。
状态转移路径是PENDING -> DOWNLOADING -> VERIFYING -> COMPLETED,任何一步失败都能回到DOWNLOADING进行重试,重试超过max_retries后标记为FAILED。
任务持久化其实就是一个save_tasks()函数,把整个任务列表写成JSON:
有个写文件的小经验:先写临时文件再原子替换,避免写一半程序崩溃导致tasks.json损坏。改进版本:
os.replace是原子操作,要么旧文件还在,要么新文件完整生效,不存在中间态。
3.3 断点续传下载器的实现
下载器是整个框架里最核心的部分。直接上代码:
几个关键细节:
iter_chunked比原来的resp.content.read()更适合大文件传输,它按指定大小分块,不会无限占用内存。- 临时文件判空逻辑很关键:如果系统里残留了一个损坏的
.part文件,但数据库记录的downloaded_bytes是0,这时直接seek到0等于没断点,所以要从头开始覆盖写。 - 写文件用二进制模式,
ab和wb两种模式根据状态码切换。 site-packages里旧版aiohttp的Timeout用法曾经是ClientTimeout(total=60),现在新版有细微差别,但aiohttp.ClientTimeout(total=60)仍然可用。
3.4 哈希校验与校验失败处理
校验模块设计得比较独立:
校验失败的逻辑是这样的:
这里有个值得展开的点:校验失败之后要不要删.part文件?我的做法是删。因为如果哈希不匹配,你根本不知道是文件哪个字节出了问题,继续在旧数据上做断点续传,后续下载回来的新数据会拼在一个损坏的基座上,最后校验大概率还是失败。清零重建虽然浪费一点带宽,但至少结果可信。
如果项目对带宽极度敏感,其实可以做一个“按块校验”的变体,把文件切成固定大小的块,每块单独记录SHA256值。下载时只重传错误块。但这会让框架复杂度上一个量级,当前需求下不值得。
3.5 调度器主体与信号量并发控制
调度器的核心是一个事件循环,不断从任务队列里拿PENDING任务,交给信号量控制的协程执行:
注意我在校验阶段用了asyncio.to_thread()。SHA-256计算是CPU密集型操作,如果在主事件循环里直接执行,会让整个调度器卡住——所有正在下载的任务都会暂停,直到哈希计算完成。用to_thread把哈希计算丢到独立线程,异步主循环就能继续保持其他下载任务运转。
并发控制的核心就这一段:
Semaphore(max_concurrency)在_process_one开始时才获取,所以同一个时间窗口内,正在执行_process_one的协程数最多为max_concurrency,其余的协程都在worker()入口处排队等待。
有人会问:“那asyncio.gather创建了所有协程,岂不是每个任务都会建立aiohttp会话?”不会。session是在_process_one内创建的,协程排队期间并没有执行到session创建。所以资源占用是可控的。
为了让调度器在崩溃后恢复任务,入口可以在run()之前加一段恢复逻辑:
这个逻辑很重要。进程崩溃时,很可能某个任务正卡在DOWNLOADING状态,重启后如果不重置,任务永远不会再被消费。
4. 常见问题与排查技巧实录
4.1 断点续传失效的三种典型场景
场景一:服务端不支持Range请求
有些静态资源服务器,尤其是一些古董CDN节点,收到Range头后会直接忽略并返回200。表现为下载器拿到200状态码后重新从零开始,最终文件也能下载完成,只是续传逻辑失效。
排查方法:先发一个curl -I -H "Range: bytes=0-100"看响应头。返回206就是支持,返回200就是不支持。如果是一闪而过的临时任务,不支持也就算了;如果是大量任务的目标服务器都不支持,就需要考虑放弃断点续传,直接全量下载。
场景二:本地文件大小和记录字节数不一致
我遇到过最隐蔽的问题:下载任务完成后,total_bytes和downloaded_bytes都正确,但.part文件因为磁盘写入顺序问题,实际大小比记录值少了几KB。下次从断点续传时发现existing_size != resume_position,代码强制从头下载。性能没那么严重,但如果每次断点都从头来,等于前面下载全部作废。
这个问题根因是程序异常退出时,缓冲数据没写入磁盘。对策是下载每块数据后立即f.flush(),或者至少在任务暂停时调用f.flush() + os.fsync()。我在Downloader里加了一行after writing each chunk的f.flush(),开销可以接受。
场景三:临时文件被清理工具删除
下载过程中如果用了磁盘清理软件,或者别的脚本误删了downloads/tmp目录下的.part文件,文件就没了,断点计算自然失效。解决方法是把tmp目录和最终目录分开,不要混用,并且在启动脚本里检查tmp目录是否存在,不存在就创建。
4.2 哈希校验太慢怎么办
30GB的内容用SHA-256校验,耗时取决于磁盘速度和CPU。实测下来机械硬盘上大约每秒500MB读取,计算SHA-256需要一分钟左右;NVMe固态上快很多,能到每秒1GB左右。如果大量任务卡在校验阶段,可以并行校验多个文件,但注意不要把所有CPU吃掉。
我的经验是校验并发数不超过CPU逻辑核心数的一半,用线程池或者asyncio.Semaphore单独控制。网络下载和本地校验其实可以重叠:下载协程把文件写完后,校验协程立刻处理,不等其他任务。
另一个优化是只算不校验时的“懒校验”。如果下载源本身有HTTPS加密和可靠传输(比如从自家服务器拉资源),可以配置expected_checksum为空,跳过哈希校验,省去大量等待。我通常设置一个skip_checksum开关,只有从第三方源下载时才开启严格校验。
4.3 并发参数怎么调才不卡
并发参数不只是一个Semaphore的数字那么简单。实际受三个因素制约:
- 目标服务器带宽:单连接能达到的带宽越接近总带宽,并发数就越不需要设大。如果单个连接已经占满了全部带宽,开10个并发反而可能互相抢带宽,总吞吐量不升反降。
- 本地文件描述符限制:Linux下默认
ulimit -n是1024,开300个并发连接很容易触发“Too many open files”。临时调大是ulimit -n 65535,但更优雅的方式是控制并发数。 - 系统内存:每个协程本身占用很少,但aiohttp的缓冲、临时写入缓冲区会占用内存。并发100和并发10的内存占用差接近一个数量级。
我建议的调参流程:
- 先用
max_concurrency=4跑20个任务,看平均单连接下载速度和总耗时。 - 把并发数翻倍,看总耗时是否减半。如果减半,继续翻倍;如果只缩短10%,说明带宽已经到顶,不要再加了。
- 观察CPU和内存占用,确保整体稳定。
调参的时候别忘了看目标服务器日志,如果出现大量429状态码,说明已经触发限流,立刻把并发数调小。
还有一个实操技巧:给每个任务加一个小的随机延时(比如0.2到1秒),可以有效降低服务器瞬时压力,减少429和超时。我通常会在深入任务开始时加await asyncio.sleep(random.uniform(0.2, 1.0))。
4.4 问题速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 下载总在90%后断掉 | 服务器主动断开长连接 | 给aiohttp请求设更长的ClientTimeout,或在断点续传重试时递增等待时间 |
| 哈希校验一直失败 | 文件在下载过程中被截断,或者.part文件残留 |
校验失败后删除.part文件,强制全量重下 |
| 重启后任务全部重新下载 | tasks.json未持久化或者状态被重置 |
确认save()在每次状态变更后调用,用os.replace原子替换 |
| 进程启动时提示“Too many open files” | 并发数超过文件描述符限制 | 调小max_concurrency,或者ulimit -n 65535 |
| 任务出现大量429 | 并发过高,触发服务端限流 | 降低并发数,加大任务间随机延时 |
| 服务器不支持Range续传 | 目标服务器忽略Range头 | 代码里已经做了判断,200状态码下自动全量下载,无需干预 |
| aiohttp请求超时但进程不退出 | ClientTimeout(total=60)设置过长 |
调整超时时间,并设置retries保证失败任务能被回收 |
磁盘空间被.part文件占满 |
大量任务下载中断,临时文件残留 | 启动时清理超过7天的.part文件,或完成最终校验后立即删除 |
5. 后续扩展与个人经验小结
写完这个框架之后我又做了两个扩展:一是增加了Web管理接口,用FastAPI暴露当前任务状态列表,可以直接在浏览器里看每个任务的进度条;二是接入了Redis队列,支持多台机器共享任务分发。但第二点说实话对单机下载场景帮助不大,反而引入了一个新的故障点。
个人实际跑下来的感受是:做批量下载,稳定性永远比速度重要。跑几十个任务看不出差距,跑上千个任务的时候,能自动恢复、不重复下载、不占用额外流量的调度框架才是真正省心的。很多网上教程只教你怎么用requests下载单个文件,但真正落地生产级别的下载任务,断点续传和哈希校验是绕不开的基本功。
有几次半夜下载任务因为服务器故障中断,起床后发现框架自动重试恢复了,只剩两个任务需要人工处理。这种体验是用Shell脚本循环下载完全没法比的。
如果你也想自己实现一个类似的框架,我的建议是先把状态机梳理清楚,再考虑并发优化。状态都不稳,再快的下载也没有意义。框架的代码量不大,但每一行都是踩过坑之后换来的经验,希望能帮你少走弯路。