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