存储配置

原理介绍

存储挂载机制

存储配置在运行时创建时设定，通过Miracle沙箱平台将外部存储资源挂载到沙箱容器内。挂载过程无需自定义挂载代码或特权容器，平台自动完成存储编排和挂载。

版本更新时的配置继承

运行时版本更新时，存储配置支持增量修改（字段继承机制）：

• 未指定某个存储子配置（如sfsTurbo为null）时，继承上一版本的完整配置。
• 指定了某个存储子配置时，使用新配置替换旧配置。
• 会话存储支持字段级继承：未指定的字段（如uid）继承上一版本该字段的值。

存储类型对比

选择建议：

• 模型文件、共享数据：优先选择SFS Turbo，支持多实例共享读写。
• 会话上下文持久化：选择会话存储，每个会话独立子目录，自动隔离。
• 用户上传/生成文件：选择OBS，海量存储、低成本。

使用约束与限制

• SFS Turbo和OBS存储仅在私网访问（VPC网络模式）下支持配置。
• SFS Turbo最多添加5个，OBS最多添加10个（最多5个不同桶），会话存储仅支持1个。
• 所有挂载路径不能包含".."，防止路径穿越。
• 会话存储配置后不支持取消，仅支持修改挂载路径。
• 会话存储底层基于OBS对象存储（FUSE挂载），配置umask后文件权限由挂载参数决定，运行时chmod/chown命令不生效。
• SFS Turbo文件系统需为NFS协议，且与运行时在同一VPC内。
• 使用OBS桶挂载功能时，需为运行时委托配置相应的OBS权限。根据文件系统的访问模式，所需的最小权限如下：
  • 文件系统只读操作：obs:bucket:headBucket、obs:bucket:listBucket、obs:object:getObject。
  • 文件系统读写操作：obs:bucket:headBucket、obs:bucket:listBucket、obs:object:getObject、obs:object:putObject、obs:object:deleteObject。

  以上为最小权限要求。如需配置其他权限，请提交工单咨询OBS权限相关事宜。

• 使用OBS存储挂载时相关约束及注意事项如下：
  • 托管智能体时如使用OBS存储配置，需创建访问OBS服务的VPC终端节点。
    1. 进入VPCEP控制台终端节点列表页。
    2. 单击右上角“购买终端节点”，进入购买页。
    3. 在“购买终端节点”页面，根据提示配置参数，其他参数保持默认，更多参数详细信息请参见购买终端节点。

       参数	示例	说明
       区域	西南-贵阳一	终端节点所在区域。要求与运行时出网VPC、OBS桶所在区域保持一致。
       计费方式	按需计费	按需计费是后付费模式，按终端节点的实际使用时长计费，可以随时开通/删除终端节点。
       服务类别	按名称查找服务	选择“按名称查找服务”。
       服务名称	-	在终端节点服务列表的“名称”列，输入待访问终端节点服务的名称，单击“验证”。 提交工单获取服务名称，提交工单时同步提供OBS桶名给技术支持人员。将从工单中获得的服务名称填写到“服务名称”中，单击“验证”。
       虚拟私有云	-	选择运行时出网VPC。

    4. 单击右下角的“立即购买”。
    5. 确认终端节点配置，单击“提交”。
  • 挂载目录中的文件或文件夹不支持硬链接命令。
  • 挂载目录不会准确显示OBS桶的总容量，用户可以通过OBS控制台查看桶容量情况。
  • 对象一旦写入即不可变，不支持原地修改。如需变更内容，必须下载完整对象、本地修改后全量重新上传并覆盖原对象。如果文件较大，建议采用分段上传，仅重新上传受影响的分片。
  • 一个OBS桶支持挂载到多个Agent或多台云服务器，各挂载进程间互不感知。数据一致性需由用户自行维护，也不能通过OBS锁定文件。建议可通过分布式缓存服务（DCS）的Redis版本实现分布式锁，可避免出现多人对一个文件同时写入的情况。了解分布式缓存服务相关信息，请参见什么是分布式缓存服务。
  • 对于对象存储的多版本功能，AgentArts无法感知到，也没有办法使用多版本的接口。对于开启了多版本控制的桶，AgentArts只能识别当前版本对象和当前版本的删除标记，并且无法对当前版本的对象真正做出修改（对象存储桶里的对象本身是不可修改的，只能覆盖当前版本对象，产生一个新的当前版本对象，原先的对象会变成历史版本对象）。由于上层应用的一些探测性IO（如vim会产生.swp文件），使得多版本桶里将产生大量中间过程对象，且对象无法被AgentArts删除（删除操作会追加删除标记，而不是真正删除）。了解多版本控制与删除对象相关信息，请参见多版本控制和删除对象。
  • 对象桶模式采用回写模式（write-back），读和写都会经过客户端本地的文件系统进行中转，通过tmpdir或use_cache参数控制临时文件目录所在的位置。在应用与AgentArts的交互过程中，应用不直接与AgentArts交互，而是先与FUSE交互。应用与FUSE的交互遵循POSIX语义，其中write()只会写到本地文件系统的临时文件，需要在应用调用文件的close()操作时，修改才会真正的上传到OBS。这意味着：
    • 数据在close()返回成功之前不在OBS上。进程崩溃、断电、kill -9等异常退出会导致未关闭文件的数据永久丢失。
    • close() 可能阻塞较长时间（取决于文件大小和网络带宽）。例如100GB文件的close可能需要数分钟。大对象上传场景，可以通过max_dirty_data参数，在写满部分分段大小时就提前触发上传，以提升整体上传效率。
    • 启用use_cache时，已写入但未上传的数据保留在磁盘缓存文件中，下次打开同一文件时有机会恢复。未启用use_cache时，关闭后本地数据立即释放。

    基于以上模式，建议在关键数据写入后检查close()返回值，避免close()方法返回错误被吞噬；对持久性要求高的场景使用fsync()定期刷新（需权衡性能）；启用use_cache提供额外的数据恢复机会。

在环境中配置存储

详细操作请参见存储配置中的存储配置。