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

113 lines
5.0 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.
# 设计说明
这份文档解释**为什么这么做**。命令怎么用看 [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` 能发现,全吧一轮要几小时,通常按周分批。
- 楼中楼的删除只能覆盖“完整重取”的楼层。
- 视频/语音只存元数据,不下载媒体。
- 备份之前的历史无法重建(没有事件)。