PolarDB Agent LakeBase 独占目录加速模式

概述

PolarDB Agent LakeBase 独占目录加速模式顺应了“每个 Agent 独占一棵子树”的天然特性。默认情况下，PolarDB Agent LakeBase 按网络文件系统的 close-to-open 一致性提供服务（文件关闭时即完成到对象存储的持久化，其内容随后对其他主机可见），这些保证在多方共享访问时是必要的，但在每个 Agent 独占一个子目录的场景下并不需要，反而带来额外的时延开销。

加速模式在确认独占访问的前提下，通过一组细粒度挂载参数安全地省去这些开销。将一致性的协调范围收敛到单主机，并把持久化时机交由 fsync 显式控制，从而显著提升 SQLite、包依赖安装、工程构建等本地化负载的性能。

功能特性

在大规模 AI Agent 场景中，每个 Agent 通过 --subdir 挂载独立子目录并由单个主机独占访问，运行 SQLite 数据库、npm install 安装依赖、构建工程产物等负载。这类负载的共同特征是元数据操作密集、文件锁频繁、小文件读写多、关闭文件频繁，而 PolarDB Agent LakeBase 默认为“可能存在其他并发访问方”付出的一致性开销（每次加锁一次数据库往返、读前强制刷盘、关闭文件同步等待落盘等），在独占场景下都是不必要的成本。

加速模式针对性地移除这些开销，具备以下特性：

• 读写不互相阻塞：读操作直接从写入方的内存缓冲获取最新数据，无需先强制刷盘，读写互不等待，且读到的内容始终最新。

• 文件锁本地化：文件锁在本机内核处理，省去每次加解锁一次元数据库事务往返，显著加速 SQLite 等锁密集型负载。

• 页缓存常驻与小写聚合：内核页缓存常驻不被主动失效，写入先进入页缓存并异步聚合下发，将大量小写合并为大块，降低小写密集负载的开销。

• 元数据缓存延长：文件属性与目录项在本机缓存更久，stat、lookup 等重复的元数据查询不再反复回源，加速目录遍历与依赖解析等元数据密集操作。

• 关闭文件不阻塞：关闭文件不再同步等待数据落到对象存储，数据由后台持续写出，fsync 作为持久化屏障，与本地文件系统的行为一致。

• 按需组合、单独启停：每个能力对应一个独立参数，可按业务对性能与一致性的偏好自由组合；不启用任何参数时，行为与默认完全一致。

适用范围

加速模式面向 Agent 独占子目录 这一典型隔离场景，使用前请确认满足以下前提：

• 已创建PolarDB Agent LakeBase并完成挂载。

• 每个 Agent 通过 --subdir 挂载独立子目录，该子目录由单个主机独占访问（主机内可多进程并发）。

• 同一子目录不被多个主机同时读写。加速模式将一致性协调范围收敛到单主机，跨主机并发读写同一子目录的场景不适用。

注意事项

• 独占模式前提：加速模式假设子目录由单个主机独占访问，且不会强制校验这一点。若同一子目录被多个主机同时读写，可能出现读到非最新的数据或元数据、跨主机文件锁不互斥等问题（元数据的滞后时长取决于所设置的缓存时间）。请确保满足适用范围。

• 持久化时机：加速模式下，持久化由后台线程异步执行，读（--drop-read-flush-barrier）或关闭文件（--drop-close-flush-barrier）等操作不再同步等待数据持久化到 OSS。这与本地文件系统语义一致，使用 fsync 作为唯一的持久化屏障。这意味着未 fsync 的数据存在一个短暂的丢失窗口，在崩溃时可能丢失。请在关键节点显式调用 fsync（SQLite等工具内部为相同逻辑），fsync 成功即表示数据已可靠落到对象存储。

• 崩溃丢失窗口：写入的数据先由本机页缓存承接，再由后台持续写出到对象存储，因此在调用 fsync 之前存在一个丢失窗口。其量级与本地文件系统的脏页回写窗口相当（Linux 默认脏页最长驻留 30 秒），具体取决于文件的使用方式：

  文件使用方式	丢失窗口
  写入后随即关闭	关闭后数秒内完成持久化
  长期打开、持续写入且从不 fsync	约数十秒
  长期打开但自身按事务 fsync	由应用自身的提交频率决定，不受上述影响

  若业务对丢失窗口有更严格的要求，请在关键节点显式调用 fsync。

• 本地盘写入缓冲区的额外取舍：启用 --writeback 后，持久化边界退到本机盘缓冲区，节点本地磁盘故障可能丢失已 fsync 的数据，详见（可选）本地盘写入缓冲区。

• 错误上报时机：启用 --drop-close-flush-barrier 后，写入类错误（如磁盘配额超限、空间不足）的上报点从关闭文件移到 fsync。请在 fsync 处检查返回值。

• 可组合、可单独启停：下述使用方法中的参数彼此独立，可按业务对性能与一致性的偏好裁剪。不启用任何参数时，行为与默认完全一致，无兼容性影响。

使用方法

挂载时按需组合以下参数即可启用对应的优化能力：

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir <SUB_DIR> \
    --attr-cache=300s --entry-cache=300s --dir-entry-cache=300s \
    --drop-read-flush-barrier \
    --local-lock \
    --keep-page-cache -o writeback_cache \
    --drop-close-flush-barrier

（可选）本地盘写入缓冲区

对于脉冲式写入、最求更低写延迟的场景，可额外启用本地盘写入缓冲区：写入先落本机盘缓冲区，再异步批量上传对象存储，平滑突发写、降低写延迟。

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir <SUB_DIR> \
    --writeback  \
    --cache-size=1024  \
    --cache-dir=/local-ssd/lakebase-cache

典型应用场景