269 lines
13 KiB
Markdown
269 lines
13 KiB
Markdown
# 贴吧归档工具(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 元数据,不下载媒体文件。
|
||
- 小尾巴、点赞数取决于原帖(很多老帖本来就没有)。
|
||
- 已被删除的帖子/楼层无法恢复。
|