Files
tieba-archiver/docs/operations.md
T
dsh 0824e0ef83 v1.2.0: 事件流对账、增量 update、ZIM 发布与表情渲染
从东方年代记吧一次性备份脚本整理成的贴吧存档工具:crawl/update/verify/as-of/restore/rebuild/images/build-zim,SQLite 事件流 + 回收站 + 中文全文索引 ZIM。
2026-11-18 11:41:25 +08:00

6.8 KiB
Raw Blame History

操作手册

环境

python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt

之后所有命令都用 .venv\Scripts\python。数据目录用 --data 指定,一个吧一个目录。

首次全量

python tieba.py init --kw 东方年代记 --data data
# 把浏览器 Cookie 贴进 data\cookies.txt(格式见 README)
python tieba.py check-cookie --data data

python tieba.py enum --data data                 # 枚举全部主题(约 1000 页,十几分钟)
python tieba.py crawl --data data                # 抓楼层/楼中楼/用户(断点续传)
python tieba.py import --data data               # JSONL → SQLite
python tieba.py images --data data               # 补图(可反复跑)
python tieba.py import-images --data data

python tieba.py label --data data --label "某某吧 全量备份(2011–2026)" --version v1.0

crawl 中途 Ctrl+C 没关系,重跑同一条命令会跳过 done.txt 里的帖。

日常增量

python tieba.py update --data data --pages 3
python tieba.py images --data data
python tieba.py import-images --data data

update 做三件事:

  1. 从主题列表第 1 页开始翻,整页没有新 tid 就停;
  2. 新主题完整抓;
  3. 老主题里 reply_num 变大(thread_seen 快照对比)的,从已知最大楼层所在页回退一页翻到末尾。

新楼层直接发 post_add 事件并物化,不经过 import。图片 URL 自动进 image 表, 由 images 下载。

频率:一天一次到一周一次都行,成本 ≈ 枚举页数 + 有更新的帖数 × 1~2 页。

对账(发现删帖 / 编辑)

python tieba.py verify --data data --threads 500 --priority recent
  • --priority recent(默认):先核对回复多的活跃帖;oldest / random / unhashed 可选; unhashed 只挑还没算过 content_hash 的帖,覆盖率推进最均匀,适合日常刷;
  • 一轮 500 帖的话,几周覆盖全吧;全吧约 3 万请求、8 小时(1 请求/秒);
  • 删除要两轮才确认:第一轮记 verify_suspect,第二轮还缺才进回收站;
  • 顺带采样点赞(只记变化点),并给没算过 content_hash 的楼补上指纹;
  • 单页 429 会自动重试(cfg.tries 次 + 退避),不会整帖放弃;建议 --rate 1.0,1.2 以上 429 明显变多。

只看某个吧里最活跃的 50 帖:

python tieba.py verify --data data --threads 50 --priority recent --rate 1.0

恢复

python tieba.py restore --data data --tid 7684489339   # 整帖
python tieba.py restore --data data --pid 142749830877 # 单层
python tieba.py restore --data data --cid 24662612524  # 单条楼中楼

整帖恢复只翻回 recycle_reason='thread_deleted' 的楼;之前单独被删的层保持回收站状态。

查历史

python tieba.py as-of --data data --tid 2066421636 --at 2026-12-01
python tieba.py as-of --data data --tid 2066421636 --at "2026-12-01 12:00" --json
python tieba.py events --data data --tid 2066421636 --kind post_del

as-of 只能回答这份备份之后的时间点(备份前没有事件)。

发布 ZIM(给 Kiwix)

python tieba.py build-zim --data data --out dist/forum-2026-11-17.zim
  • 单文件、自带全文索引,推到内网 kiwix-serve 目录即可;
  • 体积 ≈ 图片 + 10%,14 GiB 图片大概出 14 GB 的包;
  • 整包构建,不支持增量:建议按版本发(v1.0、v1.1),别每天打;
  • 试水用 --limit 300,纯文本包用 --no-images;
  • Windows 版 libzim 写 >2 GiB 的包会坏,所以本地用 --max-bytes 1.8G 分卷; 服务器(Linux)上直接出单文件。

在 Windows 上出单文件(WSL)

Windows 原生 libzim 有 2 GiB bug(见下),想在本机出 14 GB 单文件就走 WSL:

wsl --install -d Ubuntu            # 已装过可跳过
wsl -u root -e bash -lc "apt-get update && apt-get install -y python3 python3-venv"
wsl -u root -e bash -lc "python3 -m venv /opt/zimvenv && /opt/zimvenv/bin/pip install libzim"
wsl -u root -e /opt/zimvenv/bin/python /mnt/c/.../tieba-archiver/tieba.py build-zim \
    --data /mnt/c/.../data --out /mnt/c/.../dist/forum.zim
  • 数据从 /mnt/c 读,ZIM 一定要写到 WSL 原生文件系统(如 /root/forum.zim), 直接写 /mnt/c 会在收尾(Adding checksum)阶段卡死;构建完再 cp 到 C 盘;
  • 同一份代码在 Linux/WSL 下没有 2 GiB 问题。

一致性检查

python tieba.py rebuild --data data

三件事:事件重放是否幂等、回收站里的楼有没有对应删除事件、post_add 有没有指向不存在的楼。 全部通过返回 0。

贴标签 / 发版

python tieba.py label --data data --label "某某吧 全量备份" --version v1.1

写 data/ARCHIVE.md 和 data/ARCHIVE.json,同时把 archive_label / archive_version / archive_finished_at / archive_content_cutoff 写进库里的 kv。

  • 备份截止 = max(库里的 fetched_at / user.updated_at / thread_seen.seen_at, 原始数据文件 mtime);
  • 内容截止 = 最后一帖的发布时间;
  • 打标签会 wal_checkpoint(TRUNCATE) 再算 sha256,所以重复跑哈希稳定、截止时间不会漂。

搬移 / 备份

整个数据目录可以直接拷走;.venv 不要搬,到新位置重建。 搬到新机器后:

python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
python tieba.py stats --data data        # 确认能读

定时任务(Windows)

# 每天 04:10 增量
schtasks /Create /SC DAILY /ST 04:10 /TN tieba-update /TR "cmd /c cd /d C:\path\to\tieba-archiver && .venv\Scripts\python.exe tieba.py update --data data --pages 3"

对账建议手动跑(要观察 429、失败率),别放进定时任务。

故障排查

现象 原因 处理
1990006 请手动输入帐号信息完成登录 Cookie 失效 重新导 BDUSS/STOKEN
大量 429 Too Many Requests 触发限速 降 --rate(1.0 甚至 0.6),别加并发
TiebaServerError(4, '贴子可能已被删除') 帖没了 正常,会记 deleted 事件
第 N 页连续空结果 429 或末页空 程序会重试;末页空会被正确识别为翻到底
unable to open database file 库在同步盘/被杀软占用 挪到本地盘
回收站里有不该删的楼 误判 restore --pid,并检查 evidence
rebuild 报不一致 物化表被手改过 用 events 查最近事件,restore 修正

数据体积参考

项 东方年代记吧
主题 / 楼层 / 楼中楼 30,486 / 422,208 / 434,311
库 413 MB
图片 62,187 个文件 / 13.6 GiB
整个目录 14.6 GiB