Files
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

179 lines
6.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 操作手册
## 环境
```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 |