从东方年代记吧一次性备份脚本整理成的贴吧存档工具:crawl/update/verify/as-of/restore/rebuild/images/build-zim,SQLite 事件流 + 回收站 + 中文全文索引 ZIM。
113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
# 设计说明
|
||
|
||
这份文档解释**为什么这么做**。命令怎么用看 [README](../README.md),表和字段看
|
||
[schema.md](schema.md),日常怎么跑看 [operations.md](operations.md)。
|
||
|
||
## 目标与非目标
|
||
|
||
**目标**:把一个贴吧尽可能完整地存到本地,并且**以后还能增量更新、能查历史、能发现删帖**。
|
||
|
||
**非目标**:实时镜像、重新发布、抓取登录后才可见的内容。
|
||
|
||
## 三条主线
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ enum / update │ 主题列表:新帖、老帖的 reply_num 变化
|
||
└──────┬───────┘
|
||
↓
|
||
┌──────────────┐
|
||
│ crawl / update│ 楼层、楼中楼、用户资料 → JSONL / 事件
|
||
└──────┬───────┘
|
||
↓
|
||
┌──────────────┐ ┌──────────────┐
|
||
│ event 表 │ ──→ │ post/comment │ 物化(当前状态)
|
||
└──────┬───────┘ └──────────────┘
|
||
↑ │
|
||
┌──────┴───────┐ ↓
|
||
│ verify │ as-of(倒放事件,看历史)
|
||
└──────────────┘
|
||
```
|
||
|
||
- **update**:只加。新主题 + 老帖尾部新楼层(发 `post_add` / `comment_add`),从不判断“某层没了”。
|
||
- **verify**:对账。完整翻帖,才敢说哪层被删、哪层被改。
|
||
- **事件流**:每次观测记一条不可变事件;当前表是“快照 + 事件”物化的结果。
|
||
|
||
## 关键决策
|
||
|
||
### 抓取阶段只写 JSONL,不碰数据库
|
||
|
||
追加写不会因为 SQLite 锁、同步盘(OneDrive)、断电而失败;崩了最多丢最后一行。
|
||
`done.txt` 记到帖级,重跑自动跳过。数据库只在 `import` / `update` 这类明确的阶段写。
|
||
|
||
### 事件是唯一真相,表是物化结果
|
||
|
||
如果直接 `UPDATE/DELETE`,就永远失去“它曾经存在过”的证据。事件流让三件事同时成立:
|
||
|
||
1. 删帖不丢内容(回收站);
|
||
2. 任意时间点可重放(`as-of`);
|
||
3. 物化表错了可以 `rebuild --check` 发现。
|
||
|
||
代价是纪律:所有写路径都要发事件,手改数据库要明白下一次重放可能把它盖掉。
|
||
|
||
### 删除要两次确认
|
||
|
||
贴吧的“看不到”有很多种原因:真删了、审核中、风控临时屏蔽、服务器抖动。
|
||
所以第一次缺只记 `verify_suspect`,第二次完整核对还缺才发 `post_del`。
|
||
整帖 4xx 同理(`thread_suspect`)。
|
||
|
||
### 回收站用状态位,不物理搬家
|
||
|
||
`status='recycled'` + 视图,而不是把人搬到另一张表:
|
||
|
||
- 恢复是一条 `UPDATE`,不用回滚事务;
|
||
- 不用重排楼层号(删楼后楼层号会漂,历史引用不该跟着变);
|
||
- schema 只维护一份。
|
||
|
||
### as-of 用倒放,不用正放
|
||
|
||
这份归档在引入事件流之前就已经是全量快照,没有历史事件;
|
||
所以基准态就是当前物化表,回到某时刻 = 撤销该时刻之后的事件(id 倒序)。
|
||
因此它只能回答**备份之后**的时间点——这是数据决定的,不是实现偷懒。
|
||
|
||
### 点赞只采样,不追求“精确历史”
|
||
|
||
点赞是连续变量,两次观测之间发生什么永远不知道。所以:
|
||
|
||
- `content_hash` 刻意**不含**点赞,点赞变化不触发 `post_edit`;
|
||
- 变化点写 `post_stat_history`,查询时标注“观测时间”;
|
||
- `view_num` 直接丢弃(服务器自己都不准)。
|
||
|
||
### 楼中楼删除只在“完整重取”时判断
|
||
|
||
内联只返回前 50 条,拿它比对会把“没显示”误判成“被删”。
|
||
只有 `reply_num <= 内联条数` 的楼层才认为完整,才做比对,同样两次确认。
|
||
|
||
### 限速是全局的
|
||
|
||
所有 worker 共用一个令牌桶(默认 1.3 请求/秒)。贴吧的额度按账号/IP 算,
|
||
并发开大只会换来更多 429;实测 429 之后退避比省下来的时间更贵。
|
||
|
||
### 用户资料每 500 个 / 60 秒落盘
|
||
|
||
用户资料只在内存里攒着,进程被强杀会全丢(真实踩过:丢过约 3000 个作者)。
|
||
现在攒够 500 个或过 60 秒就写一次。
|
||
|
||
## 正确性怎么保证
|
||
|
||
| 手段 | 管什么 |
|
||
|---|---|
|
||
| pid / cid / uid 主键 + `INSERT OR REPLACE` | 重跑不产生重复行 |
|
||
| `done.txt` / `thread_seen` | 重跑不重复请求 |
|
||
| `rebuild --check` 幂等重放 | 物化表与事件流一致 |
|
||
| 两次确认 | 删除不误伤 |
|
||
| `label` 的 sha256 | 存档搬走后能核对完整性 |
|
||
|
||
## 已知限制
|
||
|
||
- 限速是账号/IP 硬顶,新号约 1–2 请求/秒,匿名更低。
|
||
- 删除/编辑只有 `verify` 能发现,全吧一轮要几小时,通常按周分批。
|
||
- 楼中楼的删除只能覆盖“完整重取”的楼层。
|
||
- 视频/语音只存元数据,不下载媒体。
|
||
- 备份之前的历史无法重建(没有事件)。
|