Rivet Actors SQLite 大读取负载深度剖析：prefetch、LRU 缓存与 RTT 预算如何决定大查询延迟

Rivet Actors SQLite 大读取负载深度剖析prefetch、LRU 缓存与 RTT 预算如何决定大查询延迟【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors本文基于 Rivet actors 仓库内部设计文档 workload-large-reads.md 展开系统讲解大型读取这一负载类别在 v1逐页 KV与 v2sharded LTX prefetch两代 SQLite VFS 下的行为差异四类典型场景整表扫描、冷启动工作集、索引范围扫描、重复扫描的往返次数RTT推演、LRU 缓存在顺序访问下的退化问题以及由此导出的缓存容量、prefetch 深度、preload hint 与协议包的调优建议。读完后你将掌握一套以 RTT 为预算的存储延迟分析方法并知道当前仓库中哪些源码VFS 实现、优化标志、基准测试印证了这些设计决策。背景为什么大读取值得单独做一篇负载分析Rivet 把 SQLite 数据库放在 actor 进程内运行数据通过 KV 通道持久化到引擎侧。这意味着每一次缓存未命中的页读取都要付出一次引擎 KV 往返round trip。在设计约束文档 constraints.md 中C1 要求热读必须零 RTTC6 设定了生产环境约 20 ms 的往返延迟假设——这两个约束直接决定了大读取场景的性能几乎完全由每 RTT 能捎带多少页和缓存命中策略决定。本文分析的数字基于本地开发环境的 2.9 ms RTT 基准对应仓库中真实捕获的基准数据 BENCH_RESULTS.md1 MiB 插入耗时 832 ms、约 287 次 KV 往返。按 C6 的 20 ms 生产目标折算所有 RTT 受限的时延需要乘以约 7 倍。文档明确标注这些是推演估计而非实测定性结论成立最终调优常量需以 bench 为准。全局分析假设原文档列出了一组贯穿所有场景的假设理解它们是读懂后续 RTT 推演 arithmetic 的前提往返成本本地开发环境每次引擎 KV 往返约 2.9 ms无论一次kv_get携带 1 个还是 128 个键单次kv_get都按约 3 ms 计因为延迟由引擎隧道主导而非 UDB 读取本身。页大小SQLitePRAGMA page_size 4096v1/v2 相同即 1 MiB 表数据 ≈ 256 页。SQLite pager 缓存v1、v2 均未覆写PRAGMA cache_size因此每连接默认为 2000 页约 8 MiB的进程内页缓存位于 VFS 之上只有未命中这部分缓存的读才会到达 VFS 边界。VFS 读缓存v1 的read_cache通过RIVETKIT_SQLITE_NATIVE_READ_CACHE显式开启默认关闭v2 的 LRU 缓存常驻开启默认 5000 页 20 MiB。对比时统一采用 v1 的出厂默认不启用读缓存在关键处单独标注开启读缓存的变体。SQLite xRead 粒度SQLite pager 每未命中一页只向 VFS 索要一片 4 KiB从不索要 64 KiB 条带。因此 v1 的单次读批处理机会为零页其唯一的 RTT 摊销手段是启动预加载与查询中途的读取无关。B-tree 扫描中数据页与索引页的比例约 50 B/行、4 KiB 页的小行表每叶页约容纳 70–80 行100 万行约 1.3 万叶页加约 200 内部页50 MB 表12800 页的内部节点仅占数据量的 1–2%。RTT 推演中简化为几乎全是叶页。LZ4 对 SQLite 页的压缩比综合公开数据4 KiB B-tree 叶页的 LZ4 块模式压缩比约 2.0–3.0×推演采用 2.2×平均每页 1.8 KiB。v2 预取深度mvSQLite 移植版默认热步长下每次读预测 8 个后续页predictor.multi_predict批次作为一次kv_get携带[target, ...predictions]即顺序扫描时单次 RTT 最多 9 键。Materializer 状态场景 1–4 假设 materializer 已追平四层读路径在稳态下走第 4 层PAGE/。场景 1内存装得下、VFS 缓存装不下的整表扫描SELECT * FROM users100 万行表磁盘约 50 MB计上表 B-tree 叶页、少量内部页与索引根页共约 12,800 页。v1 行为SQLite pager 缓存持有前 2000 页之后的页既发生页错误又因严格向前遍历不断驱逐早期叶页LRU 线性扫描 零复用扫描结束时缓存里只剩最后 2000 页。12,800 个唯一叶页 × 每次一个xRead12,800 次xRead每次一个 4 KiB 块没有预取每次xRead都未命中 VFS 读缓存默认关闭即便开启冷扫描时缓存也是空的退化为一次仅携带1 个键的batch_get。往返次数约 12,800聚合时延 12,800 × 3 ms ≈ 38.4 s。若设置RIVETKIT_SQLITE_SQLITE_NATIVE_READ_CACHE1即RIVETKIT_SQLITE_NATIVE_READ_CACHE1重复同一扫描几乎免费无界 HashMap 的内存代价约 60 MB但冷扫描仍是约 38 s。这就是生产环境里用户在任何有一定规模的表上看到的典型病理形态。v2 行为SQLite 侧同样发起 12,800 次xRead。v2 四层读路径层 1LRU 缓存——冷启动为空边扫边填充默认 5000 页容量下扫过第 5000 页后早期页被驱逐扫描不复用层 2写缓冲——只读查询为空层 3未 materialize 日志——假设 materializer 已追平零成本层 4已 materialize 的 PAGE/——读取落在这里。预取预测器在前几次读后观测到 1 步长随后每次调用输出PREFETCH_DEPTH 8 个预测。每 4 次层 4 查询合并为一次kv_sqlite_preload或经既有路径的胖kv_get携带9 个键目标页 8 个预测页随后 8 次读全部缓存命中零 RTT。有效 RTT 速率12,800 / 9 ≈ 1,422次往返聚合时延约 4.3 s相对 v1 提速约 9×。把缓存提升到 2000 页与 SQLite pager 缓存相等消除尾页被驱逐问题时首次扫描不变收益体现在场景 4。缓存有效性与盈亏点对于长于缓存的严格向前扫描v1 的 60 MB 可选 HashMap 与 v2 的 20 MB LRU 在扫描过程中都不提供价值缓存只在扫描之后、且同一批页再次被触碰时场景 4才有用。真正在扫描中途起作用的是预取批次。预取预测器评级(a) 非常有效。1 步长是步长检测器置信度最高的典型工况预期 8–16× 的 RTT 降幅取决于PREFETCH_DEPTH。盈亏点v2 在此场景从不劣于 v1——即使关掉预取v2 付出的 12,800 RTT 与 v1 相同预取深度 2 即立刻回本。场景 2冷启动时的工作集读取Actor 启动后立即执行SELECT * FROM users WHERE region us-east返回 10 万行。region索引约 300 个内部页匹配约 800 个索引叶页非覆盖索引下每匹配行需回表取数据页10 万行平均每数据页约 10 行需取约10,000 个数据页大致按 table-rowid 序、偏随机。v1 行为冷启动META 有界预加载最近触碰过的页未必包含 users 表任何页。现实估计启动 1 RTT 预加载正文约 1 RTT。查询执行B-tree 根 → 索引根 → 索引叶约 800 索引叶页 3–5 个根/内部页 ≈ 805 次xRead各为一次 1 键batch_get回表取约 10,000 个数据页各为一次 1 键batch_get。往返次数2启动 805 10,000 ≈ 10,807聚合时延 ≈ 32.4 s。数据页读取呈近似聚簇的随机不是严格 1 步长v1 即使开启了读缓存对真正冷启动也无济于事。v2 行为冷启动路径一次kv_sqlite_preload操作取回 META 页 1 LOGIDX 扫描若用户声明的预加载 hint 覆盖了 users 表根页与region索引根同一次 RTT 内返回。启动共 1 RTT。查询执行分两个子阶段索引扫描约 805 页前几次读训练预测器识别 1 步长热身后每 RTT 携带 1 目标 8 预测 9 键805 / 9 ≈ 90RTT数据页回表约 10,000 页这是难点。数据页访问顺序与 rowid 序相关但不是 1 步长regionus-east的行散布在全表步长检测器停滞Markov bigram 只在特定 (Δk) 对反复出现时有帮助取决于负载。现实估计数据页读取平均 3 页/调用10,000 / 3 ≈ 3,333RTT。往返次数1 90 3,333 ≈ 3,424聚合时延 ≈ 10.3 s相对 v1 提速约 3×瓶颈在数据页回表阶段。若预加载 hint 覆盖相关 region 的(region, rowid)索引叶页用户知道自己热分区索引扫描子阶段压缩到ceil(index_leaf_bytes / ~1 MiB) ≈ 1–2RTT省约 270 ms——不是瓶颈。该场景暴露的 v2 设计缺口数据页回表是真实成本而预取预测器只能部分发力。v2 目前没有办法告诉引擎给我这个索引叶条目集合所引用的全部数据页候选方向是大幅加深预取窗口代价取回不需要的页浪费 payload 预算或在kv_sqlite_preload中新增回表dereferencehint接受一个 pgnos 列表并在一次胖批次中取回。后者可视为把预加载 hint 从启动时加载泛化为查询中途、与 SQLite 无关的加载。它能把 3,333 RTT 压缩到10,000 / 512 ≈ 20RTT按每操作约 512 键的信封总量降到 1 90 20 ≈ 111 RTT 333 ms。原文档将其列为开放问题。缓存有效性与盈亏点冷运行缓存完全无热度结束时 8 MiB pager 缓存持有约 2000 个数据页v2 的 5000 页 LRU 可装下半数据页加索引叶页同 region 重放查询可复用全部装得下的内容。预测器评级(b) 有一定效果——索引遍历子阶段很好1 步长数据页子阶段中等对恰好重复的 delta 走 Markov bigram。这正是预测器诚实边界显现的场景。盈亏点即使预测器完全失效v2 也优于 v1因为 preload 把启动折叠进 1 RTT。场景 3带预取机会的大索引范围扫描SELECT * FROM events WHERE ts BETWEEN a AND b ORDER BY ts时间索引表。索引自上而下严格顺序遍历约 2,000 个索引叶页约 10 MB 索引数据events为追加写表ts 与 rowid 强相关数据页访问大体按 rowid 顺序、带少量小跳跃共约 20,000 个数据页。阶段v1 RTTv2 RTT索引遍历2,000 页2,000 × 1 键/次2,000 / 9 ≈ 2221 步长深度 8数据页取回20,000 页20,000 × 1 键/次20,000 / 7 ≈ 2,857平均每 RTT 7 页合计约 22,000 RTT ≈ 66 s约 3,080 RTT ≈ 9.2 s提速约 7×数据页阶段步长检测器在多数时刻保持有效Markov bigram 填补小跳跃现实预取效率约7 页/RTT每 8–9 次预测出现一次步长未命中。缓存有效性5000 页 LRU约 20 MiB装不下约 90 MiB 的工作集扫描内部无复用若仪表盘刷新重复扫描缓存尾部保留最后约 5,000 页见场景 4。预测器评级(a) 非常有效。这是预测器最友好的真实负载形态——mvSQLite 论文描述预测器时使用的动机示例正是这个形状。盈亏点v2 明确更优。无预测器时与 v1 持平有预测器时 6–8×。该负载下的 v2 设计要点预取饱和后胖批次kv_sqlite_preload操作信封成为约束。每调用约 512 键、每次只预取约 8 页仅用了 512 槽位中的 9 个。若预测器在步长饱和时输出更宽的预测如接下来 100 页2,857 个数据页 RTT 可压缩到20,000 / 100 200RTT在预测器之上再提速 14×。步长饱和时可变预取深度是一个具体可调参数是 v2 发版候选。场景 4重复的整表扫描报表仪表盘每分钟轮询同一查询即场景 1 的 12,800 页全扫描。v1 行为默认读缓存关闭每次扫描重新取回全部 12,800 页每次 38.4 s零复用。开启可选读缓存首次扫描 38.4 s所有页进入无界 HashMap约 60 MB后续扫描 0 RTT仅受 SQLite 执行 CPU 限制约 1–3 s。内存随工作集增长缓存不驱逐。注意该可选路径按文件状态 HashMap 持有所有页、无上限10 GiB 数据库会击穿 actor 内存。它不可作为 v1 的常开模式交付。v2 行为首次扫描4.3 s场景 1。12,800 页中 5000 页留在 LRU 里且按 LRU 顺序驻留的是最后 5,000 页。第二次扫描页 1, 2, 3… 顺序请求页 1–7,800 已被向前遍历驱逐未命中页 7,801–12,800 命中缓存页 1–7,800 走层 4 预取7,800 / 9 ≈ 867RTT页 7,801–12,800 全部命中0 RTT后续每次扫描867 RTT × 3 ms ≈ 2.6 s。第三次及以后形态相同——每次扫描的缓存内容都是最后 5,000 页的稳态不再改善。长于 LRU 的向前扫描收敛于前 N−cache_size 页未命中、后 cache_size 页命中的稳态。核心问题LRU 在顺序扫描下退化v2 仅凭最后 5,000 页被缓存获得一次性 40%/扫描的提速但收敛不到可选读缓存 v1 的理想值。根本原因LRU 缓存在向前遍历访问模式下退化——缓存驱逐的恰恰是即将再次需要的页。两个修复方向MRU 驱逐或预测器感知驱逐长顺序扫描时改按最近使用驱逐重复扫描即可命中每轮的前 N 页步长置信度下降时回退 LRU。mvSQLite 记录了这一权衡但未处理v2 面临同样选择。查询时kv_sqlite_preloadhint应用告知 actor即将整表扫描请预加载页[1..12800]v2 可提前发一两个胖批读。按 512 键/操作12,800 / 512 25RTT ≈ 75 ms 完成预热之后扫描全在内存中执行。前提缓存大到装得下整个扫描当前 5,000 页需 12,800提供运行时 preload API而不只是启动期 hint。 两者都是对当前 v2 设计的扩展。预测器评级(b) 有一定效果——预测器只帮未命中阶段重复访问的关键杠杆是缓存策略而非预取。原文档直言这是 v2 设计相对 v1一个大可选缓存最弱的场景。盈亏点若用户在内存充足时启用 v1 可选读缓存首扫之后的重复扫描 v1 获胜v2 要么把缓存扩大到覆盖工作集要么在顺序扫描下切换驱逐策略否则无法反超。调优建议汇总原文档 Recommendations 一节给出的都是可调参数而非定论全部继承如下缓存容量默认 LRU 缓存从 mvSQLite 继承的 5,000 页提升到10,000 页40 MiBRivet actor 通常同时只跑一个 SQLite 连接单 actor 内存预算可以吸收40 MiB 覆盖多数小型报表数据库工作集场景 1 与 4。缓存容量按 actor 可配置并设合理上限如每 actor 上限 100 MiB保证 actor 密度。当预测器报告步长饱和时考虑MRU 驱逐规避场景 4 的退化步长置信度下降时回退 LRU。预取深度默认PREFETCH_DEPTH 8与 mvSQLite 一致适合场景 1 与 3。步长检测器饱和时允许深度上调连续 16 次 1 步长饱和时把预取信封提到 payload 上限min(remaining_payload_budget, 256)页/调用。这是大顺序扫描场景 3 受益最大的具体提速点。信封受kv_sqlite_preload的 9 MiB / 512 键限制约束——按 2.2× LZ4512 页在线上传输完全装得下。预加载 hint启动期 hint见 walkthrough.md对场景 2冷启动工作集有用前提是用户足够了解 schema 能声明索引根与热数据范围。运行时 hint新能力当前未定义暴露逐查询 API如c.db.preloadPages(pageno_list)或c.db.preloadTableRange(table_name, low, high)。这是场景 4重复扫描的杠杆也能解决场景 2 的数据页回表阶段——在查询执行前让应用告诉 v2这些行我会用到。实现方式是查询前发一次或几次胖kv_sqlite_preload调用。它要求应用理解自己的访问模式对真正有需求的场景报表查询、仪表盘可以接受。协议调优9 MiB / 512 键每操作信封对预取饱和的场景 3 是恰当的不要缩小到低于此值。考虑引入独立的scatter-gather 读操作kv_sqlite_fetch_pages(pgno_list)与kv_sqlite_preload区分线上形态相同但语义是在一个 RTT 内给我这份 PAGE/ 键列表。预测器今天实际上已经通过kv_get在使用它升级为一等操作后引擎可假设单事务快照避免无谓的额外工作。开放问题 / 设计缺口索引扫描到数据页的回表场景 2是预取预测器的最弱点——预测器无法预知索引叶指向哪些数据页。诚实的修复是应用 hint扫完这段索引范围后预热被引用的数据页或 VFS 层在返回索引叶字节前先窥探其内容。两者都不在当前 v2 设计中。顺序扫描的 MRU vs LRU 驱逐场景 4没有它v2 在重复整表扫描上打不过 v1 可选缓存文档倾向步长感知 MRU。默认缓存容量需先调研典型 actor 的 RAM 配额再定 10,000 页这个数字。预测器在索引 → 数据页回表上的效率没有硬数据——文中的 3×、7× 是按 mvSQLite 文档套用预期负载的经验值值得专门 bench。运行时 preload hint 不在当前 v2 设计中加上它是小协议扩展 中等规模 VFS 改动建议 v2.0 范围内能容纳就上否则放 v2.1。仓库源码印证设计推演与当前实现上述推演是设计期文档Status: Draft 2026-04-15但仓库中已有多处源码与文档相互印证可帮助判断哪些机制已经落地1. VFS 页缓存与读缓存已从可选变为默认全开。在引擎侧 VFS 配置 vfs.rs 中VfsConfig含retain_read_cache字段其取值来自优化标志的page_cache_mode.caches_any_pages()can_read_cached_page在每次页读取前做统一裁决。这与 optimization_flags.rs 中SqliteVfsPageCacheModeOff / Target / Startup / Prefetch / All的枚举一一对应默认值为All且带有vfs_page_cache_capacity_pages、vfs_protected_cache_pages、vfs_staging_cache_ttl_ms、pager_cache_size_kib等容量参数。从源码结构看这印证了 tuning-parameters.md 中缓存默认常驻、容量按 actor 可调的方向也呼应场景 4 结论中不要让读缓存成为 opt-in的立场。2. 预取 / 预加载机制已作为优化标志存在。optimization_flags.rs 定义了SqliteOptimizationFlags包含read_ahead_mode默认Adaptive即自适应预读对应文中步长饱和时调整深度的思路、read_ahead、adaptive_read_ahead、recent_page_hints、cache_hit_predictor_training、preload_hint_flush、preload_hints_on_open、preload_hint_hot_pages、preload_hint_early_pages、preload_hint_scan_ranges、startup_preload_max_bytes等字段全部默认开启。每项都对应一个RIVETKIT_SQLITE_OPT_*环境变量如RIVETKIT_SQLITE_OPT_READ_AHEAD_MODE、RIVETKIT_SQLITE_OPT_VFS_PAGE_CACHE_MODE、RIVETKIT_SQLITE_OPT_STARTUP_PRELOAD_MAX_BYTES并有测试断言非法值会被钳制回默认值。这正是文中运行时预加载、per-actor 可调建议的落地形态。3. 启动预加载有独立的指标与失败语义。actor 侧指标 metrics.rs 定义了rivetkit_actor_sqlite_startup_preload_pages_total计数器区分requested/loaded由 database.rs 中的record_startup_preload_pages上报内联测试 vfs.rs 中的delayed_startup_preload_response_fails_closed_and_reopen_is_clean验证了预加载响应延迟时失败即关闭、重新打开干净的语义——对应文中场景 2 冷启动路径对kv_sqlite_preload的依赖必须可靠的前提。4. RTT 预算的现实基准。文中 2.9 ms/RTT 的本地基准与 BENCH_RESULTS.md 完全对齐1 MiB 插入 832 ms、287 次 put 往返10 MiB 插入 9,438 ms且该文件记录的 debug trace 结论瓶颈在 SQLite VFS / KV 通道而非 SQLite 本身正是 v2 立项与本文所有以 RTT 为预算推演的事实起点。5. 约束与决策链。本文所有场景推演引用的约束C1 热读零 RTT、C6 约 20 ms 生产 RTT与Option Dsharded LTX delta log布局决策分别固化在 constraints.md 与 design-decisions.md 中SPEC.md 是该设计线的总体规格。阅读顺序建议先 constraints → 再本文大读取负载分析 → 最后 tuning-parameters。小结这篇负载分析的价值在于给出了一套可复用的推理框架把大读取延迟分解为启动 RTT 索引遍历 RTT 数据页回表 RTT 缓存命中四项逐项用 512 键/9 MiB 的胖批次信封和步长预测器去压缩。四个场景的结论可以浓缩为顺序扫描场景 1、31 步长预取是决定性杠杆9 页/RTT 带来 7–9× 提速且步长饱和时应进一步放大预取深度冷启动回表场景 2预测器只能做到 3×真正解法是运行时回表 hint这一协议扩展重复扫描场景 4预取帮不上忙LRU 在顺序访问下退化胜负手是 MRU/步长感知驱逐或把缓存撑到覆盖工作集。对当前仓库而言这些结论并非纸面推演depot-client的 VFS 已具备自适应预读、页缓存模式开关与启动预加载指标RIVETKIT_SQLITE_OPT_*标志体系提供了逐 actor 验证上述参数的入口。若你在 Rivet actor 上遇到大查询慢的问题值得按本文顺序先定位落在哪个场景再用对应的环境变量与 preload hint 做针对性调优。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考