Files
dsh 53f4d00d2e docs: 完整操作流程(workflow.md)与打包示例
新增 docs/workflow.md:新吧备份、增量、ZIM 构建、Kiwix 发布、常见坑;examples/ 收录 adnmb 与小说打包脚本。
2026-11-21 15:06:34 +08:00

269 lines
13 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.
# 贴吧归档工具(tieba-archiver)
把一个贴吧完整备份到本地:主题、楼层、楼中楼、图片、用户资料、点赞、小尾巴、
楼中楼回复对象。全程断点续传,中断重跑同一条命令即可。
这套工具是从 `东方年代记吧_全量备份_2011-2026`(东方年代记吧那次一次性备份)的脚本整理出来的,
数据布局和表结构与那份成品库完全兼容。
## 环境
Python 3.11+(`aiotieba` 的要求),Windows / Linux 都能跑。
```powershell
python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
```
之后所有命令都用 `.venv\Scripts\python`(Linux 是 `.venv/bin/python`)。
## 文档
| 文档 | 内容 |
|---|---|
| [docs/design.md](docs/design.md) | 为什么这么设计:事件流、两次确认、回收站、as-of 语义、限速 |
| [docs/schema.md](docs/schema.md) | 表 / 视图 / 事件类型 / 状态机 |
| [docs/operations.md](docs/operations.md) | 首次全量、日常增量、对账、恢复、定时任务、故障排查 |
| [CHANGELOG.md](CHANGELOG.md) | 版本变更 |
## 快速开始
```powershell
# 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
```
## Cookie 格式
`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/
```
## 完整流程
从零备份一个吧 → 入库补图 → 构建 ZIM → 发布到 Kiwix → 增量更新,见 [docs/workflow.md](docs/workflow.md)。
## 表情
渲染机制、已知缺失(`image_emoticon51–59`)和抢救记录见 [docs/emoji.md](docs/emoji.md)。
## ZIM(Kiwix / 内网离线阅读)
```powershell
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` 是观测时间,不是“事情发生的时间”——贴吧没有通知接口,只能观测。
```powershell
python tieba.py verify --data data --threads 500 --priority recent
```
一轮只核对 500 帖的话,几周才能覆盖全吧;想确认某次删除,同一个帖要在**两轮**里都缺席。
### as-of 的语义
```powershell
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` 调大。
## 兼容已有的旧备份
表结构和目录布局一致,可以直接指过去看统计(只读):
```powershell
python tieba.py stats --data ..\东方年代记吧_全量备份_2011-2026\data
```
## 测试
```powershell
python -m unittest discover -s tests -v
```
44 项离线断言:Cookie 各种格式(含 RT 里的分号)、回复正则、建库/补列、导入幂等、
fragment 落库、图片路径与 md5 分桶、页数上限行为。
## 已知限制
- 贴吧的限速是账号/IP 硬顶:新账号约 1–2 请求/秒,匿名更低;大量 429 时只能等或换号。
- 楼中楼的赞踩只有单独的 `get_comments` 接口才带,内联返回的楼中楼没有。
- 视频/语音只存 fragment 元数据,不下载媒体文件。
- 小尾巴、点赞数取决于原帖(很多老帖本来就没有)。
- 已被删除的帖子/楼层无法恢复。