AgentbaseDocs
文档目录

存储

Storage 提供文件上传、存储桶(Bucket)管理与文件访问控制,并在上传路径上接入内容安全审核。入口:项目侧栏 Storage,页面两个页签:Buckets / Usage。

创建存储桶

截图未公开:原图可能包含账号或资源标识。

创建后的默认值(服务端默认,可在桶 Settings 中修改):

属性默认说明
Enabled开关闭后终端用户无法访问文件;持有 API Key 的 Server SDK 仍可访问,文件不丢失
File security关关闭时仅桶级权限生效(见下文「文件详情与文件令牌」)
Permissions无创建时不授予任何权限;需在 Settings 中添加
Maximum file size套餐单文件上限以套餐 fileSize 或部署环境变量为准;0 表示不限
Allowed file extensions空(全部允许)最多 100 条
Compressionnone可选 none / gzip / zstd
Encryption开大文件跳过加密
Antivirus开大文件跳过扫描

桶与桶设置

桶详情页页签:Files / Usage / Moderation / Settings(无写权限时 Settings 隐藏)。

桶设置(Settings)

Settings 页逐卡修改并保存:

卡片字段与规则
Enabled桶启用开关;关闭后终端用户无法访问文件,Server SDK(带 API Key)不受影响,不删除数据
Name桶名,必填,最长 128 字符
Permissions桶级权限编辑器:为角色添加 read / write 权限;角色可选 Any、All guests、All users、Guests、Users、指定 User、Team + 角色、Label、自定义 user:{id} / team:{id}/{role};支持在编辑器内创建新角色
File security文件级安全开关,语义与风险见下节
Security settingsEncryption 加密开关(大文件不加密);Antivirus 杀毒扫描开关(大文件跳过扫描)
Compression算法下拉:None / Gzip / Zstd;大文件跳过压缩
Image transformations允许通过 API 对图片做缩放 / 裁剪 / 格式转换
Maximum file size数值 + 单位(Bytes,1000 进制)。上限受套餐 fileSize 约束,超出显示套餐提示与 Upgrade plan。固定说明:"This does not set the total storage capacity for the project."(这里不是项目总容量)
Allowed file extension扩展名标签输入(快捷项 jpg / png / svg / gif / html / pdf / mp4),最多 100 条;留空允许全部类型
Client file listing允许客户端列出文件开关(默认开)。关闭后,仅授权的管理客户端(Server SDK / 项目 API Key)可列出桶内文件;上传权限与公开文件链接访问不受影响

File security 语义(重要)

删除桶

Settings 底部 Delete bucket:桶与桶内全部文件永久删除,不可恢复;确认框需确认桶名。删除桶不可恢复。

桶级内容审核(Moderation)

fail closed 边界(上传拒绝即清理)

文件列表开关(Client file listing)

截图未公开:原图可能包含账号或资源标识。

桶 Settings 的 Client file listing 卡控制客户端能否列出桶内文件:

文件列表与上传

文件列表(Files)

上传(Create file)

文件详情与文件令牌

文件详情页位于 /storage/bucket-{bucketId}/file-{fileId}。

文件详情

权限与 fileSecurity 的关系

桶 fileSecurity访问条件
关闭仅桶级权限生效;文件级权限被忽略
开启桶级权限或该文件的文件级权限,满足其一即可访问

文件令牌(File tokens)

令牌用于把私有文件以带密钥的 URL 提供给无权限的访问者。文件详情页的 File tokens 卡片管理(说明原文:"Use tokens to provide public access to the file.")。

创建与编辑:

使用(Copy URL):

保管语义(如实说明):

Usage 页签

与其他能力的关系