从东方年代记吧一次性备份脚本整理成的贴吧存档工具:crawl/update/verify/as-of/restore/rebuild/images/build-zim,SQLite 事件流 + 回收站 + 中文全文索引 ZIM。
179 lines
6.8 KiB
Markdown
179 lines
6.8 KiB
Markdown
# 操作手册
|
||
|
||
## 环境
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.venv\Scripts\python -m pip install -r requirements.txt
|
||
```
|
||
|
||
之后所有命令都用 `.venv\Scripts\python`。数据目录用 `--data` 指定,一个吧一个目录。
|
||
|
||
## 首次全量
|
||
|
||
```powershell
|
||
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` 里的帖。
|
||
|
||
## 日常增量
|
||
|
||
```powershell
|
||
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 页。
|
||
|
||
## 对账(发现删帖 / 编辑)
|
||
|
||
```powershell
|
||
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 帖:
|
||
|
||
```powershell
|
||
python tieba.py verify --data data --threads 50 --priority recent --rate 1.0
|
||
```
|
||
|
||
## 恢复
|
||
|
||
```powershell
|
||
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'` 的楼;之前单独被删的层保持回收站状态。
|
||
|
||
## 查历史
|
||
|
||
```powershell
|
||
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)
|
||
|
||
```powershell
|
||
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:
|
||
|
||
```powershell
|
||
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 问题。
|
||
|
||
## 一致性检查
|
||
|
||
```powershell
|
||
python tieba.py rebuild --data data
|
||
```
|
||
|
||
三件事:事件重放是否幂等、回收站里的楼有没有对应删除事件、`post_add` 有没有指向不存在的楼。
|
||
全部通过返回 0。
|
||
|
||
## 贴标签 / 发版
|
||
|
||
```powershell
|
||
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` 不要搬,到新位置重建。
|
||
搬到新机器后:
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.venv\Scripts\python -m pip install -r requirements.txt
|
||
python tieba.py stats --data data # 确认能读
|
||
```
|
||
|
||
## 定时任务(Windows)
|
||
|
||
```powershell
|
||
# 每天 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 |
|