# 存储配置 存储配置用于将外部存储资源挂载到运行时沙箱容器中，实现数据持久化、文件共享和会话状态保存。AgentArts运行时支持SFS Turbo、会话存储和OBS三种存储类型，满足不同场景的数据持久化需求。 #### 原理介绍 **存储挂载机制** 存储配置在运行时创建时设定，通过Miracle沙箱平台将外部存储资源挂载到沙箱容器内。挂载过程无需自定义挂载代码或特权容器，平台自动完成存储编排和挂载。 **版本更新时的配置继承** 运行时版本更新时，存储配置支持增量修改（字段继承机制）： - 未指定某个存储子配置（如sfsTurbo为null）时，继承上一版本的完整配置。 - 指定了某个存储子配置时，使用新配置替换旧配置。 - 会话存储支持字段级继承：未指定的字段（如uid）继承上一版本该字段的值。 #### 存储类型对比 表1存储类型对比 | 存储类型 | 文件特征 | 读写特征 | 性能特点 | 典型场景 | 最大数量 | 网络要求 | |:---|:---|:---|:---|:---|:---|:---| | SFS Turbo | 适量中大文件 | 读写混合、多实例共享 | 中等IOPS、适中时延 | 模型文件、共享数据集、配置文件 | 5 个 | 私网（VPC） | | 会话存储 | 会话级小文件 | 按会话隔离读写 | 低时延、按会话隔离 | 多轮对话上下文、会话临时数据 | 1 个 | 无限制 | | OBS | 海量大文件 | 读多写少 | 高吞吐、低成本 | 用户上传文件、生成结果文件 | 10 个（5 个桶） | 私网（VPC） | **选择建议：** - **模型文件、共享数据**：优先选择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。 以上为最小权限要求。如需配置其他权限，请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)咨询OBS权限相关事宜。 - 使用OBS存储挂载时相关约束及注意事项如下： - 托管智能体时如使用OBS存储配置，需创建访问OBS服务的VPC终端节点。 1. 进入[VPCEP控制台终端节点列表页](https://console.huaweicloud.com/vpc/?agencyId=7dc9c9806c414731b45a360a2e1ddd9e&locale=zh-cn#/ep/list)。 2. 单击右上角"购买终端节点"，进入购买页。 3. 在"购买终端节点"页面，根据提示配置参数，其他参数保持默认，更多参数详细信息请参见[购买终端节点](https://support.huaweicloud.com/usermanual-vpcep/zh-cn_topic_0131645189.html)。 | 参数 | 示例 | 说明 | |:---|:---|:---| | 区域 | 西南-贵阳一 | 终端节点所在区域。要求与运行时出网VPC、OBS桶所在区域保持一致。 | | 计费方式 | 按需计费 | 按需计费是后付费模式，按终端节点的实际使用时长计费，可以随时开通/删除终端节点。 | | 服务类别 | 按名称查找服务 | 选择"按名称查找服务"。 | | 服务名称 | - | 在终端节点服务列表的"名称"列，输入待访问终端节点服务的名称，单击"验证"。 [提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/feedbackBusiness?productTypeId=2a129f7ed0b543c6b92d73e2c26aa590)获取服务名称，提交工单时同步提供OBS桶名给技术支持人员。将从工单中获得的服务名称填写到"服务名称"中，单击"验证"。 | | 虚拟私有云 | - | 选择运行时出网VPC。 | 4. 单击右下角的"立即购买"。 5. 确认终端节点配置，单击"提交"。 - 挂载目录中的文件或文件夹不支持硬链接命令。 - 挂载目录不会准确显示OBS桶的总容量，用户可以通过OBS控制台查看桶容量情况。 - 对象一旦写入即不可变，不支持原地修改。如需变更内容，必须下载完整对象、本地修改后全量重新上传并覆盖原对象。如果文件较大，建议采用分段上传，仅重新上传受影响的分片。 - 一个OBS桶支持挂载到多个Agent或多台云服务器，各挂载进程间互不感知。数据一致性需由用户自行维护，也不能通过OBS锁定文件。建议可通过分布式缓存服务（DCS）的Redis版本实现分布式锁，可避免出现多人对一个文件同时写入的情况。了解分布式缓存服务相关信息，请参见[什么是分布式缓存服务](https://support.huaweicloud.com/productdesc-dcs/dcs-pd-200713001.html)。 - 对于对象存储的多版本功能，AgentArts无法感知到，也没有办法使用多版本的接口。对于开启了多版本控制的桶，AgentArts只能识别当前版本对象和当前版本的删除标记，并且无法对当前版本的对象真正做出修改（对象存储桶里的对象本身是不可修改的，只能覆盖当前版本对象，产生一个新的当前版本对象，原先的对象会变成历史版本对象）。由于上层应用的一些探测性IO（如vim会产生.swp文件），使得多版本桶里将产生大量中间过程对象，且对象无法被AgentArts删除（删除操作会追加删除标记，而不是真正删除）。了解多版本控制与删除对象相关信息，请参见[多版本控制](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829098.html)和[删除对象](https://support.huaweicloud.com/usermanual-obs/obs_03_0726.html)。 - 对象桶模式采用回写模式（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智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。 2. 在左侧导航栏选择"托管与运行 \> 智能体运行时"。 3. 单击"托管智能体"，在"高级配置 \> 存储配置"中选择存储类型，详情参数可参考[表2]，关于托管智能体的更多详细操作请参见[通过控制台部署智能体运行时](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_031.html)。 表2添加存储参数说明 | 类型 | 参数 | 说明 | |:---|:---|:---| | 会话存储 | 挂载路径 | 输入会话存储将被挂载的具体目录路径。配置后，每个会话在持久化存储中拥有独立的子目录，这些子目录将作为状态存储挂载到该路径。 挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含".."，最大长度为4000字符。 存在多个挂载时（包括OBS、SFS Turbo、会话存储之间），禁止使用相同或存在包含关系的路径。 | | SFS Turbo | 文件系统 | 选择文件系统。如未创建，单击"创建文件系统"，详细操作说明请参考[创建文件系统](https://support.huaweicloud.com/usermanual-sfsturbo/sfsturbo_01_0359.html)。 配置后单击![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002741772933.png)刷新。 说明： - SFS Turbo和智能体运行时中的出网网络配置必须在同一VPC内，SFS Turbo文件系统使用的安全组需放通NFS协议使用的端口号，具体信息请参考[VPC的安全组是否影响高性能弹性文件服务的使用](https://support.huaweicloud.com/sfsturbo_faq/sfsturbo_01_0081.html)，安全组需要放通运行时出站的子网网段访问SFS Turbo。 - 选择的文件系统需为NFS协议。 - AgentArts部署智能体运行时时挂载NFS文件系统的soft/hard的模式为hard模式，关于soft/hard的模式详情信息请查看[挂载SFS Turbo文件系统到Linux云服务器](https://support.huaweicloud.com/usermanual-sfsturbo/sfsturbo_01_0361.html#section0)。 - 为了您的信息安全，请勿在文件系统中存放敏感数据。 | | SFS Turbo | 存储路径 | 输入文件系统中数据的存储路径。 存储路径以"/"开头，不能包含".."，最大长度4000字符，默认为/。 | | SFS Turbo | 挂载路径 | 输入文件系统中数据的挂载路径，使得该目录下的文件和目录可以被访问。 - 挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含相对路径，最大长度为4000字符。 - 存在多个挂载时（包括OBS、SFS Turbo、会话存储之间），禁止使用相同或存在包含关系的路径。 - 同一智能体运行时的多个版本挂载在同一目录时会自动共享。 说明： 挂载路径的Linux文件系统权限，继承自SFS Turbo存储路径的原有权限（SFS Turbo根目录权限为任何用户可读写）。此权限不支持通过chmod/chown等命令修改。 | | SFS Turbo | 读写权限 | 选择对挂载文件系统的读写权限。 - 读写：可以读取、写入和修改文件系统中的数据，默认为读写。 说明： Linux文件系统权限和读写权限两者必须同时允许，读写才能成功，如果任一项禁止，读写操作将失败。 - 只读：只能读取文件系统中的数据，不能写入或修改数据。 | | OBS | OBS桶 | 选择已创建的OBS桶。如未创建，单击"创建OBS桶"，详细操作说明请参考[创建桶](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829088.html#section3)。 配置后单击![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002712053966.png)刷新。 说明： - 挂载路径的OBS文件系统权限，继承自OBS存储路径的原有权限（OBS根目录默认权限为任何用户可读写）。此权限不支持通过chmod/chown等命令修改。 - OBS仅支持桶类型，暂不支持并行文件系统。 - 为了您的信息安全，请勿在文件系统中存放敏感数据。 | | OBS | 存储路径 (可选) | 输入OBS桶内的子目录路径。 挂载OBS桶内的指定子路径，当配置为空时挂载整个桶根目录；非空时挂载桶内指定子目录，必须以'/'开头，支持大小写字母、数字及 ! _ - . \* ' ( ) / 等字符且不能包含'..'，路径长度为最大1024字符。 | | OBS | 挂载路径 | 输入OBS桶挂载到容器内的路径。 - 挂载路径为/home、/mnt、/data、/tmp及其子目录，不能包含相对路径，最大长度为4000字符。 - 存在多个挂载时（包括OBS、SFS Turbo、会话存储之间），禁止使用相同或存在包含关系的路径。 说明： 挂载路径的Linux文件系统权限继承自OBS桶存储路径的原有权限。此权限不支持通过chmod/chown等命令修改。 | | OBS | 读写权限 | 选择对挂载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 } ] } } ```