Files
tieba-archiver/docs/design.md
T
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

5.0 KiB
Raw Blame History

设计说明

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