存储配置

原理介绍

存储挂载机制

存储配置在运行时创建时设定，通过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提供额外的数据恢复机会。

通过控制台配置存储

1. 登录AgentArts智能体平台。
2. 在左侧导航栏选择“托管与运行 > 智能体运行时”。
3. 单击“托管智能体”，在“高级配置 > 存储配置”中选择存储类型，详情参数可参考表2，关于托管智能体的更多详细操作请参见通过控制台部署智能体运行时。

   表2 添加存储参数说明

   类型	参数	说明
   会话存储	挂载路径	输入会话存储将被挂载的具体目录路径。配置后，每个会话在持久化存储中拥有独立的子目录，这些子目录将作为状态存储挂载到该路径。 挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含“..”，最大长度为4000字符。 存在多个挂载时（包括OBS、SFS Turbo、会话存储之间），禁止使用相同或存在包含关系的路径。
   SFS Turbo	文件系统	选择文件系统。如未创建，单击“创建文件系统”，详细操作说明请参考创建文件系统。 配置后单击刷新。 说明： SFS Turbo和智能体运行时中的出网网络配置必须在同一VPC内，SFS Turbo文件系统使用的安全组需放通NFS协议使用的端口号，具体信息请参考VPC的安全组是否影响高性能弹性文件服务的使用，安全组需要放通运行时出站的子网网段访问SFS Turbo。 选择的文件系统需为NFS协议。 AgentArts部署智能体运行时时挂载NFS文件系统的soft/hard的模式为hard模式，关于soft/hard的模式详情信息请查看挂载SFS Turbo文件系统到Linux云服务器。 为了您的信息安全，请勿在文件系统中存放敏感数据。
   	存储路径	输入文件系统中数据的存储路径。 存储路径以“/”开头，不能包含“..”，最大长度4000字符，默认为/。
   	挂载路径	输入文件系统中数据的挂载路径，使得该目录下的文件和目录可以被访问。 挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含相对路径，最大长度为4000字符。 存在多个挂载时（包括OBS、SFS Turbo、会话存储之间），禁止使用相同或存在包含关系的路径。 同一智能体运行时的多个版本挂载在同一目录时会自动共享。 说明： 挂载路径的Linux文件系统权限，继承自SFS Turbo存储路径的原有权限（SFS Turbo根目录权限为任何用户可读写）。此权限不支持通过chmod/chown等命令修改。
   	读写权限	选择对挂载文件系统的读写权限。 读写：可以读取、写入和修改文件系统中的数据，默认为读写。 说明： Linux文件系统权限和读写权限两者必须同时允许，读写才能成功，如果任一项禁止，读写操作将失败。 只读：只能读取文件系统中的数据，不能写入或修改数据。
   OBS	OBS桶	选择已创建的OBS桶。如未创建，单击“创建OBS桶”，详细操作说明请参考创建桶。 配置后单击刷新。 说明： 挂载路径的OBS文件系统权限，继承自OBS存储路径的原有权限（OBS根目录默认权限为任何用户可读写）。此权限不支持通过chmod/chown等命令修改。 OBS仅支持桶类型，暂不支持并行文件系统。 为了您的信息安全，请勿在文件系统中存放敏感数据。
   	存储路径 (可选)	输入OBS桶内的子目录路径。 挂载OBS桶内的指定子路径，当配置为空时挂载整个桶根目录；非空时挂载桶内指定子目录，必须以'/'开头，支持大小写字母、数字及 ! _ - . * ' ( ) / 等字符且不能包含'..'，路径长度为最大1024字符。
   	挂载路径	输入OBS桶挂载到容器内的路径。 挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含相对路径，最大长度为4000字符。 存在多个挂载时（包括OBS、SFS Turbo、会话存储之间），禁止使用相同或存在包含关系的路径。 说明： 挂载路径的Linux文件系统权限继承自OBS桶存储路径的原有权限。此权限不支持通过chmod/chown等命令修改。
   	读写权限	选择对挂载OBS桶的读写权限。 读写：可以读取、写入和修改OBS桶中的数据，默认为读写。 说明： Linux文件系统权限和读写权限两者必须同时允许，读写才能成功，如果任一项禁止，读写操作将失败。 只读：只能读取OBS桶中的数据，不能写入或修改数据。

通过API配置存储

通过创建或更新运行时API，在请求体的storageConfig字段中配置存储：

{
  "storageConfig": {
    "sfsTurbo": [
      {
        "sfsTurboId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "sfsPath": "/",
        "mountPath": "/mnt/shared",
        "readOnly": false,
        "userId": 1000,
        "groupId": 1000
      }
    ],
    "sessionStorage": {
      "mountPath": "/home/session"
    },
    "obsBucket": [
      {
        "bucketName": "my-bucket",
        "bucketPath": "/data",
        "mountPath": "/data/obs",
        "readOnly": false
      }
    ]
  }
}