共享目录-云原生数据库 PolarDB(PolarDB)-阿里云帮助中心

PolarDB Agent LakeBase的共享目录功能可以将卷中已存在的目录，以实时、零拷贝的方式映射到另一个挂载点内的指定路径，让每个隔离的Agent获得一份实时更新的共享内容视图，无需额外拷贝数据或挂载新的FUSE进程。

说明

该功能目前处于邀测阶段。如需使用，请通过钉钉搜索群号34560007316加入技术交流群咨询。

功能特性

在大规模AI Agent应用场景中，每个Agent通过--subdir挂载独立子目录以保证数据隔离，但多个Agent往往需要访问相同的数据资源（如共享技能库、知识库、公共依赖等）。传统做法存在明显代价：

传统做法	问题
启动时将资源拷贝进每个Agent	数据冗余N份更新需逐个重新分发，易版本漂移拷贝大目录拖慢启动
为共享资源再挂载一个挂载点	每个Agent多一个FUSE进程与一组元数据库连接，规模化下资源浪费严重。

共享目录通过--bind参数解决以上问题，具备以下特性：

零数据拷贝：被共享的目录在底层只存一份，所有挂载点看到的是同一份内容。
实时一致：源目录的更新对所有共享方立即可见（取决于客户端缓存配置）。
读写控制：支持完整的POSIX权限管理，可灵活控制各Agent的读写访问。
生命周期自动管理：挂载时建立、卸载时自动清理。

适用范围

已创建PolarDB Agent LakeBase。
源路径（被共享的目录）在卷中已存在。
目标路径（映射目标）在卷中尚不存在，且位于--subdir指定的目录之下。

使用方法

挂载时通过--bind参数将共享目录映射到目标路径：

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir <SUB_DIR> \
    --bind <源路径>:<目标路径>[,<源路径>:<目标路径>...]

参数	说明
源路径	卷中已存在的目录的绝对路径。
目标路径	映射目标的绝对路径。该目录在卷中必须尚不存在，且必须位于`--subdir`指定的目录之下。

权限控制

通过POSIX权限管理控制共享目录的读写权限：

只读访问：共享目录由管理用户（admin）拥有，权限设为0755（owner可读写、其他用户只读）。
可写访问：将共享目录设为组可写，并将Agent加入该组。

重要

只读保护要求Agent以非root用户运行。root（uid 0）会绕过权限检查。

典型应用场景

共享skills和知识库

多个Agent通过--subdir各自隔离运行，但需共享同一份全局技能库（skills）和知识库（knowledge-base），由管理员统一维护、Agent只读使用。

操作步骤：

管理员创建共享内容并设为只读。

lakebase-client mount <META_URL> <MOUNT_POINT>
mkdir -p <MOUNT_POINT>/shared/skills <MOUNT_POINT>/shared/knowledge-base
cp -r /path/to/skills/* <MOUNT_POINT>/shared/skills/
cp -r /path/to/knowledge/* <MOUNT_POINT>/shared/knowledge-base/
chown -R admin:admin <MOUNT_POINT>/shared
chmod -R 755 <MOUNT_POINT>/shared
lakebase-client umount <MOUNT_POINT>

每个Agent使用subdir隔离并通过bind共享目录。

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir /agents/agent-x \
    --bind /shared/skills:/agents/agent-x/skills,/shared/knowledge-base:/agents/agent-x/knowledge-base

Agent看到的目录结构：

<MOUNT_POINT>/
├── skills/            ← 共享只读，来自 /shared/skills
├── knowledge-base/    ← 共享只读，来自 /shared/knowledge-base
└── workspace/         ← Agent私有可写工作区

共享npm依赖

每个Agent启动时都要npm install一大组依赖到node_modules，而这些依赖在各Agent间大部分相同。node_modules通常包含数万到数十万个小文件，每个小文件的写入都会落到底层对象存储、带来固定开销，文件一多便被线性放大。让多个Agent复用同一份公共依赖，可大幅减少重复安装，缩短Agent启动时间。

说明

以下以npm为例说明，其他包管理依赖可类似处理。

方案选择取决于一个核心问题：Agent运行期间，需不需要动态写入node_modules？

不需要（依赖固定、由管理员维护、Agent只消费）：使用共享目录（只读）。
需要（运行时各自安装额外的包，且需相互隔离）：使用Clone（写时复制）。

方案一：只读公共依赖（共享目录）

适用条件：

依赖在Agent启动前已确定、运行期不变。
由管理员或CI统一生成维护。
多个Agent使用同一套（或少数几套固定的）依赖。

原理：公共依赖只物化一次，多个Agent只读Bind同一份、直接使用，完全跳过npm install，从而消除每个Agent重复物化数万个小文件的开销，启动即用、零安装。

操作步骤：

管理员构建公共依赖（一次性操作）。

lakebase-client mount <META_URL> <MOUNT_POINT>
mkdir -p <MOUNT_POINT>/shared/npm-base/v1
cd <MOUNT_POINT>/shared/npm-base/v1 && npm install next ...
chown -R admin:admin <MOUNT_POINT>/shared/npm-base
chmod -R 755 <MOUNT_POINT>/shared/npm-base
lakebase-client umount <MOUNT_POINT>

每个Agent bind只读公共依赖。

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir /agents/agent-x \
    --bind /shared/npm-base/v1/node_modules:/agents/agent-x/node_modules

Agent看到的目录结构：

<MOUNT_POINT>/
├── node_modules/      ← 共享只读公共依赖，来自 /shared/npm-base/v1
└── workspace/         ← Agent私有可写工作区

方案二：公共依赖 + 运行时额外安装（Clone）

适用条件：存在常用的依赖包集合，但Agent在运行期还要各自安装额外的包，且各Agent的改动需相互隔离。

此时应改用Clone（写时复制）：由模板工程Clone出独立、可写的副本，公共依赖与基座共享、不重复占用存储。各Agent在副本上安装增量时，只有新增或改动的部分写入新数据块，互不影响。具体原理与操作步骤（包括以--subdir挂载时“先Bind再本地Clone”与“通过OpenAPI Clone”两种方式，详见目录克隆（Clone）- 公共依赖 + 运行时额外安装。

注意事项

源路径必须为卷中已存在的目录。目标路径必须尚不存在，且必须位于--subdir指定的目录之下。
共享目录随挂载建立、随卸载自动清理。每次挂载需通过--bind重新指定。
所有共享方看到的是同一份底层数据，源目录的修改对共享方可见，更新可见的实时性取决于客户端缓存配置。
只读保护依赖POSIX权限，要求Agent以非root用户运行。root（uid 0）会绕过权限检查。
共享目录在绑定期间受保护：只要还有任一挂载会话通过--bind绑定该目录，则无论从源路径还是bind目标路径，都不能对其执行删除（rmdir）或重命名（rename），操作会返回EBUSY错误。需待所有绑定该目录的挂载卸载后才能删除或重命名。