从东方年代记吧一次性备份脚本整理成的贴吧存档工具:crawl/update/verify/as-of/restore/rebuild/images/build-zim,SQLite 事件流 + 回收站 + 中文全文索引 ZIM。
贴吧归档工具(tieba-archiver)
把一个贴吧完整备份到本地:主题、楼层、楼中楼、图片、用户资料、点赞、小尾巴、 楼中楼回复对象。全程断点续传,中断重跑同一条命令即可。
这套工具是从 东方年代记吧_全量备份_2011-2026(东方年代记吧那次一次性备份)的脚本整理出来的,
数据布局和表结构与那份成品库完全兼容。
环境
Python 3.11+(aiotieba 的要求),Windows / Linux 都能跑。
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
之后所有命令都用 .venv\Scripts\python(Linux 是 .venv/bin/python)。
文档
| 文档 | 内容 |
|---|---|
| docs/design.md | 为什么这么设计:事件流、两次确认、回收站、as-of 语义、限速 |
| docs/schema.md | 表 / 视图 / 事件类型 / 状态机 |
| docs/operations.md | 首次全量、日常增量、对账、恢复、定时任务、故障排查 |
| CHANGELOG.md | 版本变更 |
快速开始
# 1. 初始化(一个数据目录 = 一个吧)
python tieba.py init --kw 东方年代记 --data data
# 2. 把浏览器里的 Cookie 粘进 data\cookies.txt(格式见下一节)
# 3. 验证登录态(会打印账号 id 和昵称)
python tieba.py check-cookie --data data
# 4. 枚举主题(先 3 页试水)
python tieba.py enum --pages 3 --data data
python tieba.py enum --data data
# 5. 抓楼层 / 楼中楼 / 用户资料(Ctrl+C 可停)
python tieba.py crawl --threads 20 --data data
python tieba.py crawl --data data
# 6. 入库
python tieba.py import --data data
# 7. 补图(可反复跑)
python tieba.py images --data data
python tieba.py import-images --data data
# 8. 统计
python tieba.py stats --data data
Cookie 格式
data/cookies.txt 接受四种形态,工具会统一解析并写成 JSON:
-
浏览器请求头整条(最省事,推荐):
BAIDUID=xxxx:FG=1;BDUSS_BFESS=yyyy;BAIDUID_BFESS=xxxx:FG=1;BDUSS=zzzz;STOKEN=ssss;RT="z=1&dm=baidu.com&si=abc;co=def;st=ghi";XFT=tttt -
JSON 对象:
{"BDUSS": "...", "STOKEN": "..."} -
DevTools 的 Copy as cURL:整条命令贴进去(认
-H 'Cookie: ...'/-b '...') -
Netscape cookies.txt(制表符分隔)
两个坑:
RT的值本身带引号和分号(RT="...;...;"),按;硬切会把后面的字段全切错位。 解析器带引号状态,只有引号外的;才分段——有单测覆盖。BDUSS是必填的,STOKEN建议一起给。BDUSS 等于账号密码,不要提交到 git (.gitignore已经排除cookies.txt和data/)。
BDUSS 过期的典型症状:
| 现象 | 说明 |
|---|---|
get_self_info 报 1990006 请手动输入帐号信息完成登录 |
登录失效 |
init_websocket 报 isUserAvailable(0) userId(0) |
没登录,ws 通道起不来 |
请求大量 429 Too Many Requests、速度掉到 ~1 请求/秒 |
退化成匿名配额 |
重新从浏览器导一次 Cookie 即可。
命令
| 命令 | 作用 | 常用参数 |
|---|---|---|
init |
建目录、写 config.json、建库 |
--kw 吧名 --force |
check-cookie |
解析 Cookie 并真的登录一次 | --cookies 路径(默认数据目录里的) |
enum |
枚举主题列表,写 threads.jsonl |
--pages N |
crawl |
抓楼层/楼中楼/用户资料 | --threads N --workers W --rate R |
update |
增量备份:新主题 + 老帖尾部新楼层 | --pages N --threads N --rate R |
verify |
与服务器对账:发现删除/编辑(完整翻帖 + 两次确认) | --threads N --priority --tids --rate |
as-of |
看某帖在指定时间点的样子(倒放事件) | --tid --at --limit --json |
restore |
从回收站恢复(整帖/单层/单条楼中楼) | --tid --pid --cid |
rebuild |
检查事件流与物化表是否一致 | --check(默认) |
events |
查看事件流 | --tid --kind --limit |
import |
JSONL → SQLite(幂等) | |
images |
按 URL 补图(md5 去重) | --workers W --limit N |
import-images |
index.jsonl → image 表 |
|
stats |
主题/楼层/楼中楼/图片/用户/覆盖率 | --live(读正在写的库) |
export |
从数据库导出 threads.jsonl |
|
label |
给存档贴标签:备份截止/内容截止、统计、库的 sha256 | --label --version --no-hash |
fetch-emoji |
下载贴吧经典表情到 data/emoji/(渲染用) |
--force |
build-zim |
打包成 ZIM(Kiwix 离线格式,自带全文索引) | --out --limit --no-images --title |
selftest |
离线自检,不联网 |
所有子命令都接受 --data DIR(默认 ./data)和 -q。
数据目录
data/
├─ config.json 采集参数(rate/workers/comment_rn/page_cap…)
├─ cookies.txt Cookie(统一 JSON)
├─ tieba.db SQLite 主库
├─ ARCHIVE.md 存档标签(人眼可读)
├─ ARCHIVE.json 存档标签(机器可读,含 sha256)
├─ threads.jsonl 主题清单(enum/export 写)
├─ raw/
│ ├─ posts.jsonl 楼层(含 fragment、赞踩、小尾巴)
│ ├─ comments.jsonl 楼中楼(含 reply_to_id)
│ ├─ users.jsonl 用户资料
│ ├─ done.txt 已抓完的 tid
│ └─ err.jsonl 失败记录
├─ imgs/
│ ├─ index.jsonl 每张图一行(md5/url/尺寸/路径)
│ ├─ state.json 下载游标
│ └─ ab/cd/<md5>.jpg 按 md5 分桶
└─ export/
ZIM(Kiwix / 内网离线阅读)
pip install libzim # 只有打包需要,Windows/Linux x64 都有 wheel
python tieba.py build-zim --data data --out dist/forum.zim
产物是一个单文件 ZIM,丢进 kiwix-serve 的目录即可浏览,自带中文全文索引(Xapian), 不需要另外部署站点。
- 页面平铺:
index.html、list-<n>.html、thread-<tid>[-<页>].html,图片在i/<md5>.jpg, 表情在e/<表情 id>.png(先跑一次fetch-emoji); - CSS 文件名带内容哈希,改样式重建即自动失效客户端缓存;
- 只打包
live内容,回收站默认不进; - 体积 ≈ 图片总量 + 10%:东方年代记吧那份 13.6 GiB 图片 → 约 14 GB;
- ZIM 不可增量,
update之后要整包重打(所以建议按版本发布,别每天打); --limit N只打最新 N 个主题,用来试水;--no-images出纯文本包;- Windows 上单个 ZIM 超过 2 GiB 会被 libzim 写坏(上游 issue #1127:writer 的
ftell在 Windows 上被long截成 32 位,header 偏移写成 0xFFFF…,实测 2.47 GB 打不开)。要单文件只有两条路: Linux 上构建,或者装个 WSL(见下)。
事件流与回收站
从 v1.1 起,post / comment 不再是唯一真相,而是物化结果:
v1.0 快照(现有库)
+ events/<批次>.jsonl 和 event 表(add / del / edit / thread_deleted)
↓ 物化(import / verify 当场应用)
post / comment / thread(查询、预览都读它)
update只产生post_add:抓新帖、抓老帖尾部新楼层,从不判断“没了”。verify是唯一能产生删除/修改事件的地方:把帖从头完整翻一遍,拿 pid 集合和正文 hash 对账。- 删除两次确认:第一次只记
verify_suspect,第二次还缺才发post_del; - 编辑:
content_hash(正文/图片/作者,不含点赞)变了才发post_edit; - 整帖 4xx:也要两次确认才发
thread_deleted; - 楼中楼:只对「内联返回条数 = reply_num」的楼层做完整比对,缺的 cid 也两次确认后发
comment_del。
- 删除两次确认:第一次只记
- 回收站不物理删:
post.status为live/recycled,recycle_reason区分post_deleted(单层被删)和thread_deleted(跟整帖一起没的);恢复整帖时只翻回后者。 查询用视图:post_live/post_recycled/comment_live/comment_recycled。 - 点赞只记变化点:
post_stat_history(pid, ts, agree, disagree);view_num不存。 event.ts是观测时间,不是“事情发生的时间”——贴吧没有通知接口,只能观测。
python tieba.py verify --data data --threads 500 --priority recent
一轮只核对 500 帖的话,几周才能覆盖全吧;想确认某次删除,同一个帖要在两轮里都缺席。
as-of 的语义
python tieba.py as-of --data data --tid 2066421636 --at 2026-11-16
基准态就是当前物化表,as-of 做的是「把该时刻之后的事件按 id 倒序撤销」——所以它能回答
「从这次备份往后,某个时间点是什么样」,不能回答备份之前的历史(那部分没有事件)。
编辑事件里带 old_content / old_frags / old_imgs / old_content_hash,撤销时才回得去。
数据模型
| 表 | 作用 |
|---|---|
thread |
主题(标题/作者/回复数/是否精品/抓取状态) |
post |
楼层。content 纯文本,frags 是 fragment JSON,sign 小尾巴,agree/disagree 赞踩 |
comment |
楼中楼。pid 是所属楼层,rto 是协议给的回复对象 user_id,reply_to_name/reply_to_uid 是从正文解析出来的 |
user |
作者资料:portrait、吧等级、成长等级、性别、IP、吧务/会员标记 |
image |
图片 URL、md5、体积、本地路径、下载状态 |
event / batch |
事件流(post_add / comment_add / del / edit / thread_deleted)与每次运行的批次 |
post_stat_history |
点赞变化点(只记变化,永久保留) |
thread_seen |
增量判定快照(reply_num / max_floor) |
verify_suspect / thread_suspect |
删除的第一次怀疑,等第二轮确认 |
forum / kv |
吧信息与元数据 |
fragment 类型:text / emoji / img / at / link / video / voice。
图片、视频、语音的 fragment 里存的是百度原始地址,本地文件按 md5 去重。
楼中楼的回复对象:协议 reply_to_id 在老数据里大量是 0,真正的对象藏在正文
「回复 某某 :」前缀里。import 会先解析昵称,再在本帖作者里按昵称唯一匹配 uid。
设计说明
- 抓取阶段只写 JSONL,不碰 SQLite。 追加写不会因为数据库锁/同步盘(OneDrive)
失败,崩了最多丢最后一行;
done.txt记录到帖级,重跑自动跳过。 - 全局限速:所有 worker 共用一个节奏(默认 1.3 请求/秒)。贴吧的额度是按账号/IP 算的,并发开大只会换来更多 429。
- 429 不做死等:一页连续空结果 3 次就放弃这个帖(不写
done.txt),下一轮再补; 这样不会被几个大水楼拖住整体进度。 - 末页空结果不算 429:
err为空且has_more=False时视为正常翻到底并写done.txt。 真实踩过:有 5 个帖最后一页不足 30 楼,第 2 页返回空,被误判成限流重试了两小时。 - 已删帖(
err.code == 4)直接标记完成,避免每轮重试。 - 用户资料周期落盘:每 500 个新用户或 60 秒写一次。进程被强杀最多丢一分钟。
- WAL 模式:库在本地盘时读写并发更好;
stats默认用只读 immutable 快照, 不创建-wal/-shm。 - 页数上限(
page_cap,默认 400)防超长水楼跑飞,可在config.json调大。
兼容已有的旧备份
表结构和目录布局一致,可以直接指过去看统计(只读):
python tieba.py stats --data ..\东方年代记吧_全量备份_2011-2026\data
测试
python -m unittest discover -s tests -v
44 项离线断言:Cookie 各种格式(含 RT 里的分号)、回复正则、建库/补列、导入幂等、 fragment 落库、图片路径与 md5 分桶、页数上限行为。
已知限制
- 贴吧的限速是账号/IP 硬顶:新账号约 1–2 请求/秒,匿名更低;大量 429 时只能等或换号。
- 楼中楼的赞踩只有单独的
get_comments接口才带,内联返回的楼中楼没有。 - 视频/语音只存 fragment 元数据,不下载媒体文件。
- 小尾巴、点赞数取决于原帖(很多老帖本来就没有)。
- 已被删除的帖子/楼层无法恢复。