断点续爬不是万能的:检查点与去重在你数据上会漏什么
断点续爬不是万能的:检查点与去重在你数据上会漏什么
在 Scrapling 的 Spider 体系里,断点续爬的入口非常轻:给构造器传一个 crawldir,按一次 Ctrl+C,下次用同样的目录再跑一遍,队列就接上了。这套能力在社区文章里被反复转述成"企业级断点续爬",甚至有人把它描述为"布隆过滤器去重 + 检查点恢复"的组合。
但把 scrapling/spiders/checkpoint.py、scheduler.py、request.py 摊开来看,事实要朴素得多:检查点只存两个字段,去重是一个精确哈希集合,而且这两件事都有明确的、会在真实数据上咬人的边界。这篇文章不谈"怎么开启续爬",只谈它保证了什么、在你不知道的地方漏了什么、以及重启后你该拿什么去对账。
检查点存的是两样东西,而不是"爬虫状态"
整个持久化结构就九行代码,在 scrapling/spiders/checkpoint.py 里:
@dataclass
class CheckpointData:
"""Container for checkpoint state."""
requests: List["Request"] = field(default_factory=list)
seen: Set[bytes] = field(default_factory=set)
requests:来自Scheduler.snapshot(),即调度器内部_pending字典里所有尚未complete()的请求(排队中 + 在途);seen:一个set[bytes],装的是每个请求 SHA-1 指纹的原始字节。
序列化方式是 pickle.dumps(data, protocol=pickle.HIGHEST_PROTOCOL),写到 checkpoint.pkl。写入走"临时文件 + replace()"的原子路径(checkpoint.py 第 46-53 行),这一点做得是扎实的;但原子写只保证文件不残缺,不保证内容可校验——文件里没有版本号、没有校验和、没有指纹算法规格。
没被存进去的东西,才是坑
对照 scrapling/spiders/engine.py 的 crawl() 与 CrawlerEngine.__init__(),以下状态在重启后全部归零或需要用户自建:
| 状态 | 重启后的行为 | 源码位置 |
|---|---|---|
CrawlStats(请求数、字节数、状态码分布、items_scraped) |
每次 crawl() 重新 CrawlStats(...) |
engine.py 第 363 行 |
self._items 已产出的条目 |
启动时 self._items.clear(),上一轮结果只存在于上一轮的 CrawlResult |
engine.py 第 359 行 |
| AutoThrottle 学到的每域名延迟 | 文档明确写了不进入检查点,恢复后从 autothrottle_start_delay 重来 |
docs/spiders/advanced.md 第 104 行 |
crawl_strategy(bfs/dfs)、指纹开关 |
从当前 Spider 类重新读取,检查点里没有记录 | engine.py 第 41-46 行 |
| robots.txt 缓存、每域名 delay | _domain_delays.clear() |
engine.py 第 365-366 行 |
这解释了一个很常见的错觉:"我续爬了,所以数据是连续的。" 事实上,续爬续的是"接下来要请求哪些 URL",不是"哪些数据已经落库"。如果你把 ItemList 直接 to_jsonl() 到同一个文件,第二次运行会覆盖同一个文件名;如果你用 stream() 边消费边入库,那么暂停前已经 yield 出去的条目不会有任何记录留在 checkpoint.pkl 里。
在途请求:优雅暂停和在途强停的真实差别
Scheduler.snapshot() 取自 _pending,而 complete() 是在 _task_wrapper 的 finally 中调用的:
async def _task_wrapper(self, request: Request) -> None:
try:
await self._process_request(request)
finally:
self.scheduler.complete(request)
self._active_tasks -= 1
也就是说,在途请求在快照里是存在的。优雅暂停(第一次 Ctrl+C)会等 _active_tasks == 0 再保存(engine.py 第 396 行),此时在途请求已经 complete,快照干净。而第二次 Ctrl+C 的强制停止路径是"先 save、再 cancel_scope.cancel()"(第 398-407 行),快照里就留下了那些"已经被取消、但 callback 可能已经产出了部分 item"的请求。恢复后它们会被重新请求、重新解析,于是同一份数据在你的下游出现两次。
这不是理论推演。仓库里有一个专门的回归测试文件 tests/spiders/test_force_stop_checkpoint.py,文件头注释把一个真实 bug 写得很清楚:曾经是"先 cancel() 再 _save_checkpoint()",导致保存被 Cancelled 打断、self.paused 没被置 True,最终 finally 里按"正常完成"把上一份检查点删掉,长时间爬取的进度不可恢复地清零。这个 bug 修好了,但它提醒你:断点续爬的正确性依赖"暂停语义"的实现细节,而不是一个可以无条件信任的开关。
去重是精确集合,不是布隆过滤器
先把社区里流传最广的一个说法纠正掉:Scrapling 的 Spider 没有布隆过滤器。Scheduler 里是 self._seen: set<a href="https://link.gitcode.com/i/34036f1b7864088134a91211495899fc" target="_blank">bytes] = set()([scrapling/spiders/scheduler.py 第 31 行),enqueue() 里做的是精确成员判断:
fingerprint = request.update_fingerprint(self._include_kwargs, self._include_headers, self._keep_fragments)
if not request.dont_filter and fingerprint in self._seen:
log.debug("Dropped duplicate request: %s", request)
return False
好处是零误判:不存在布隆过滤器那种"把新 URL 判成旧 URL 从而永久丢弃"的风险。代价是容量边界:seen 从不做淘汰,一个 URL 抓完了也永远留在集合里。每个元素是 20 字节的 SHA-1 摘要,但 Python set 的存储开销通常是摘要本身的数倍,加上每次 save() 都要把整个 seen 重新 pickle 写盘,千万级 URL 时内存和 checkpoint.pkl 都会到 GB 量级,而且每 5 分钟一次的检查点写入是 O(N) 的全量重写。这不是 bug,是设计取舍——只是你必须知道它不能无限期地跑下去。
指纹到底由什么构成
Request.update_fingerprint()(scrapling/spiders/request.py 第 72-128 行)参与哈希的字段是:
sid + body + method + canonicalize_url(url, keep_fragments)
(可选)+ kwargs(排除 data/json)
(可选)+ headers(key/value 全部 hex 编码后排序)
默认 fp_include_kwargs=False、fp_include_headers=False、fp_keep_fragments=False,这三个默认值决定了四类最常见的"漏":
-
靠请求头区分的接口会被合并。 同一路径、靠
X-Requested-With、Referer、Authorization或Accept-Language区分返回内容的站点(多租户 API、区域化站点、需要登录态的分页接口),默认只有一个指纹。第一次请求被记住后,后续变体全部被当作重复丢弃——丢的是 URL,不是报错,日志里只有一行 DEBUG。修法是覆写fp_include_headers = True,代价是同 URL 不同 cookie 的请求也会各自成为独立抓取任务。 -
#之后的 hash 路由会被折叠。keep_fragments=False会调用canonicalize_url(url, keep_fragments=False),https://site/list#/detail/1001与#/detail/1002变成同一个指纹。对 Vue/React 的 hash 路由站点,这等于把整站详情页压缩成一个。需要fp_keep_fragments = True。 -
表单与 JSON body 的顺序敏感。
orjson.dumps(post_data)没有加OPT_SORT_KEYS(第 98 行),urlencode(post_data)也按插入顺序编码(第 89 行)。于是{"a":1,"b":2}与{"b":2,"a":1}是两个指纹,服务端视为同一请求——方向是"重复"而非"漏",但同样污染数据。 -
params会被并进 URL 再规范化。 第 101 行update_url_params(self.url, params),所以分页参数是参与指纹的;这点没问题。真正被忽略的是utm_*之类的跟踪参数:canonicalize_url不会清除它们,同一页面的多种外链形式会各自抓一遍(重复侧)。
还有一个方向相反的陷阱:fp_include_kwargs=True 会把 proxy、timeout、浏览器相关参数一起算进指纹(过滤规则只排除了 data 和 json)。如果你的代理池是轮换的,开着这个开关就等于"每个 URL 在每条代理上都是一个新任务",指纹空间爆炸,去重形同失效。
续爬中途改指纹开关,会让 seen 集合变成两个世界
这一点最隐蔽。Request.__getstate__ 会把 self.__dict__ 整体拷贝(request.py 第 157-162 行),其中包含已算好的 _fp;而 update_fingerprint() 开头就是 if self._fp is not None: return self._fp。
于是这样的操作序列会发生什么:第一轮按默认开关跑了 20 万条并把 seen 存进检查点;你修改 Spider,加上 fp_include_headers = True 再续爬。此时:
- 从
checkpoint.pkl恢复的seen全是旧算法的指纹; - 恢复的 pending 请求带着旧算法的
_fp缓存; - 新产生的请求按新算法算指纹。
同一个 URL 在两套指纹空间里互不相识,结果既可能重复抓取,也可能因为新指纹恰好命中旧集合里某个无关条目而被误丢。而检查点里没有任何字段记录"这份 seen 是用哪套开关生成的",框架无法替你报警。指纹配置是数据库 schema,改它就要换 crawldir。 同理,crawl_strategy 从 bfs 换成 dfs 后续爬,docs/spiders/generic-templates.md 明确要求保持一致,因为 Scheduler.restore() 会按当前策略决定是否 reversed() 回填队列顺序。
重启之后,你怎么知道数据是对的
框架给了你一个明确的信号:CrawlResult.paused。crawl() 结束时会设置 self.paused = True 并跳过检查点删除,正常完成才 cleanup()(engine.py 第 443-445 行)。所以第一层校验很简单:
result = MySpider(crawldir="crawl_data/my_spider").start()
if result.paused:
... # 本次是中途暂停,下游不要做"最终一致性"校验
但它远不够。CheckpointManager.load() 在异常时是吞掉错误并返回 None:
except Exception as e:
log.error(f"Failed to load checkpoint (starting fresh): {e}")
return None
_restore_from_checkpoint() 拿到 None 就返回 False,crawl() 于是把 resuming 当成 False,重新执行 start_requests()。换句话说,一个损坏的(或用了旧版 Spider 类导致反序列化失败的)checkpoint.pkl,会让你在毫无察觉的情况下把整站重爬一遍——日志里只有一行 ERROR,退出码是 0,result.paused 是 False。这比报错更危险,因为你的下游会认为"这次跑完了"。
三条可落地的对账手段
一、把 resuming 也记录下来。 on_start(resuming=...) 是框架提供的钩子,不要只用来打日志:
async def on_start(self, resuming: bool = False):
self.logger.info("resuming=%s", resuming)
if not resuming and Path(self.crawldir, "checkpoint.pkl").exists():
# 有检查点却没恢复成功 = 反序列化失败,必须人工介入
raise RuntimeError("checkpoint exists but was not restored — refusing to re-crawl silently")
二、给 item 建幂等键,而不是信任 URL 去重。 调度层去重只保证"同一个指纹不会被入队两次",它对你入库的 dict 一无所知。真正可靠的做法是在 on_scraped_item() 里补一个业务主键,并在存储侧做 upsert:
async def on_scraped_item(self, item):
item["_key"] = f'{item["sku"]}@{item["crawl_date"]}'
return item
配合 ItemList.to_jsonl() 追加写 + 存储侧按 _key 去重,强停造成的在途重放就不会变成重复行。
三、审计指纹字段,而不是猜。 想知道某个接口为什么"少了一半数据",把生成指纹的入参打出来最快。update_fingerprint 返回的是 digest,但你可以自己复算参与项:
req = Request("https://example.com/api?page=2", sid="default",
headers={"X-Tenant": "b"})
fp = req.update_fingerprint(include_kwargs=True, include_headers=True)
print(fp.hex(), req.url, req._session_kwargs)
对同一批种子 URL 分别用默认开关和全开关各跑一次,只对比 stats.requests_count——差出来的部分,就是默认指纹吞掉的那批"变体请求"。这个数字应该写进你的爬虫 README,而不是等数据上线后才发现。
一个必须接受的结论
断点续爬在 Scrapling 里是调度层的断点,不是数据层的断点。它可靠地保证了三件事:原子写入的队列快照、精确无假阳性的 URL 去重、以及暂停后跳过 start_requests() 的续跑。它不保证、也不打算保证的是:已产出条目的持久化、跨运行的统计连续、指纹配置的一致性、以及损坏检查点的显式失败。
把这四件事各自补上一道自己的校验,crawldir 才真的能用来跑长任务;否则你拿到的只是"这次跑完了"的假象,而不是"数据是全的"的证据。
