# 操作手册 ## 环境 ```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 |