Files
tieba-archiver/README.md
T
dsh a66bbdf261 docs: 记录缺失表情 image_emoticon51-59 的抢救路径
CDN、GitHub 镜像、Wayback(含 CDX)、图片搜索、APK 渠道、EIF 解包全部失败;结论为限时表情未存档。
2026-11-18 14:01:08 +08:00

12 KiB
Raw Blame History

贴吧归档工具(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

data/cookies.txt 接受四种形态,工具会统一解析并写成 JSON:

  1. 浏览器请求头整条(最省事,推荐):

    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
    
  2. JSON 对象:{"BDUSS": "...", "STOKEN": "..."}

  3. DevTools 的 Copy as cURL:整条命令贴进去(认 -H 'Cookie: ...' / -b '...')

  4. 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/

表情

渲染机制、已知缺失(image_emoticon51–59)和抢救记录见 docs/emoji.md。

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 元数据,不下载媒体文件。
  • 小尾巴、点赞数取决于原帖(很多老帖本来就没有)。
  • 已被删除的帖子/楼层无法恢复。