存储
功能概述
存储用于管理项目中的文件。你可以创建存储桶,配置访问权限、文件大小和允许的扩展名,并通过控制台或 SDK 上传和读取文件。具体的压缩、加密与内容审核选项以部署环境提供的功能为准。
例如,一个项目可以分别创建文档存储桶和媒体附件存储桶,再根据访问需求设置桶级权限与文件级权限。下文的存储桶名称和数据均为示例,不代表任何环境中已存在这些资源。
核心概念与架构
Agentbase Storage 采用“存储桶(Bucket)策略隔离 → 分块上传与安全流水线(扩展名/大小校验、杀毒、加密、压缩、内容审核)→ 双层鉴权网关(Bucket Permissions + File Security + File Tokens + Client File Listing Gate)→ 多模态与知识库联动”的完整架构。
核心概念与存储桶属性说明
| 核心概念 | 属性名与默认值 | 架构语义与生产行为说明 |
|---|---|---|
| 存储桶(Bucket) | kb_enterprise_docs、agent_multimedia_bucket | 文件的顶层逻辑容器与安全策略边界。每个 Bucket 独立配置启停状态(enabled)、权限列表、大小上限、允许扩展名、压缩算法、加密、杀毒与图片审核策略。 |
| 文件级安全(File security) | fileSecurity(默认:关) | • 关闭时:仅桶级权限(Bucket Permissions)生效,单个文件上的权限设置被忽略。 • 开启时:桶级权限与文件级权限采用逻辑或(OR)评估——用户只要满足桶级权限或该特定文件的文件级权限之一即可访问。 |
| 客户端文件列表开关(Client file listing) | clientFileListing(默认:开) | 将“列出桶内全部文件清单(listFiles)”与“按已知文件 ID / URL 访问单个文件”彻底解耦:• 设为关闭( false)时:任何未登录、匿名或普通终端用户 Session/JWT 发起的 listFiles 请求均返回 401 user_unauthorized,彻底防止客户端遍历枚举全桶文件;但文件上传与按已知链接/Token 访问公开或授权图片不受影响,API Key 身份和项目管理特权身份不受该开关限制,仍须满足适用的认证和授权。 |
| 分块上传(Chunked Upload) | Pending 状态 → 完成态 | 当上传大文件(超过 5 MB)时,SDK 自动将文件切分为块(Chunks)并携带 Content-Range 头顺序上传,支持断点续传;分块未全部合并完成前,文件在列表中显示 Pending 徽标且不可访问详情。 |
| 文件令牌(File Tokens) | ?token=<SECRET>(签名 JWT) | 在不开放桶级/文件级公开权限的前提下,为特定私有文件签发带过期时间(如 7 Days、30 days、Never 或自定义日期)的免登录分享访问链接。删除令牌或到达过期时间后对应链接立即失效。 |
| 存储模式兼容性 | Shared V2 & JsonTable | 存储桶元数据(Configured buckets)与文件目录完美支持 Shared V2 与 JsonTable 两种项目存储模式,并在 ProjectTableModeConversion 模式转换时自动无损迁移全部属性(含 clientFileListing)。 |
角色、入口与关联关系
控制台入口与路由
主导航路径:登录控制台 → 选择项目 → 在左侧基础设施分组下点击存储。
路由地址:
存储桶列表与顶层用量页:
/console/project-{region}-{project}/storage(含 存储桶 与 用量 两个顶层页签)。单个存储桶详情页:
/console/project-{region}-{project}/storage/bucket-{bucketId}(含 文件、用量、内容审核、设置 四个子页签)。独立文件上传向导页:
/console/project-{region}-{project}/storage/bucket-{bucketId}/create单个文件详情与令牌管理页:
/console/project-{region}-{project}/storage/bucket-{bucketId}/file-{fileId}
操作权限门禁:
在 Console 管理存储桶(创建/修改/删除桶)需要组织角色具备
buckets.read/buckets.write权限(owner、admin、developer、editor;无写权限时桶详情的 设置 页签自动隐藏)。在 Console 或通过 Server SDK 管理桶内文件需要
files.read/files.write权限。
与知识库(Knowledge Base)及多模态记忆(Memory)的关联关系
知识库文档底座:知识库使用存储保存源文档,再由解析流水线读取处理。是否执行杀毒和加密取决于环境、存储设备、桶配置及文件大小;请按下文条件核实。
多模态记忆(Multimodal Memory)与视觉大模型联动:当智能体需要调用
qwen-vl-max视觉模型分析用户上传的架构图或报错截图时,前端先将图片安全上传至agent_multimedia_bucket,经内置图片内容安全审核(Moderation)放行后,通过文件访问 URL 或 File Token 交由多模态记忆与模型网关处理。云函数(Functions)受控访问:在 云函数 运行时内部访问 Storage 时,自动继承项目上下文与函数执行身份,可安全读写受保护存储桶中的文件。
功能详解与操作指南
1. 创建与查看存储桶
在项目侧栏进入 基础设施 → 存储,选择 存储桶 页签,可搜索和查看当前项目的存储桶。
图 1:2.12.0 环境中的存储桶列表;示例存储桶 ID 已遮盖。
创建存储桶操作步骤
点击 创建存储桶。若按钮不可用,先检查账号是否具有存储桶写入权限。
在窗口中填写名称,并可在存储桶 ID 输入框填写自定义标识。ID 最多 36 个字符,首字符须为字母或数字,其余字符可使用字母、数字、句点、连字符或下划线;留空时系统自动生成。
根据需要设置 允许客户端列举文件。新建窗口默认开启;关闭后,列举文件需要获得授权的服务端或项目管理身份,上传和单个文件访问仍按各自权限控制。
点击 确认。创建成功后进入存储桶详情页,可继续上传文件或调整设置。
2. 存储桶设置(Bucket Settings)全参数详解
进入存储桶详情页并切换到 设置 页签,管理员可逐张卡片调整存储桶的访问控制、压缩加密与防枚举策略:
图:2.12.0 测试项目中的存储桶设置;请根据实际权限和安全需求配置。
下表详列了 设置 页全部配置卡片的参数规则、技术边界以及在 enterprise-ai-hub-210 两个示例桶中的最佳实践配置:
| 设置卡片名称 | 配置项与可选值 | kb_enterprise_docs 推荐配置 | agent_multimedia_bucket 推荐配置 | 技术规则与边界说明 |
|---|---|---|---|---|
| Enabled(启用状态) | 布尔开关(开 / 关) | 开启 | 开启 | 关闭后普通应用用户不能访问该桶;API Key 身份和项目管理特权身份不受此开关限制,但仍需满足适用的认证及授权要求。关闭开关不会删除文件。 |
| Name(桶名称) | 字符串(1–128 字符) | 企业知识库原始文档存储桶 | 智能体多模态媒体与工单附件桶 | 修改桶显示名称不影响 Bucket ID 及任何已生成的 File URL。 |
| Permissions(桶级权限) | 为 Role 添加 Create / Read / Update / Delete | Read: Role.team('team_kb_governance')Write: Role.team('team_kb_governance', 'reviewer') | Create: Role.users('verified')Read: Role.team('team_support_ops') | 支持选择 Any、Guests、Users、指定 User、Team + Role、Label 或在编辑器内自定义角色表达式。 |
| File security(文件级安全) | 布尔开关(开 / 关) | 开启 | 开启 | 关闭时:仅桶级权限生效,忽略单文件权限。 开启时:满足桶级权限或单文件权限之一即可访问。切换开关立即对全桶文件鉴权生效! |
| Security settings(加密与杀毒) | 加密(静态加密) 病毒扫描(ClamAV 病毒扫描) | 双项均 开启 | 双项均 开启 | 文件先写入存储设备,所有分片完成后才进行后续处理。杀毒还要求环境启用、桶开启、使用本地存储且文件不超过 20,000,000 字节;加密仅对不超过 20,000,000 字节的文件执行。请确认部署环境配置,桶开关开启不代表所有文件均已扫描或加密。 |
| Compression(压缩算法) | 下拉选择:None / Gzip / Zstd | Zstd(高压缩比、极速解压) | None(图片/音视频本身已压缩) | 对 Markdown、JSON、文本与未压缩文档推荐开启 Zstd 或 Gzip;大文件自动跳过实时压缩。 |
| Image transformations | 布尔开关(开 / 关) | 关闭(纯文档桶无需图片转换) | 开启 | 开启后允许客户端通过 getFilePreview 接口对桶内图片执行实时缩放、裁剪、圆角、背景色与格式转换。 |
| Maximum file size(单文件大小上限) | 数值 + 单位(Bytes / KB / MB / GB,按 1000 进制换算) | 50 MB | 20 MB | 注意:该值限制的是单个上传文件的最大体积(受套餐 fileSize 硬上限约束),而非整个项目的总存储容量配额。 |
| Allowed file extensions(扩展名白名单) | 扩展名标签列表(最多 100 项,不含前导点号) | md, pdf, docx, txt, html, csv | jpg, png, webp, gif, mp4, mp3 | 界面提供 jpg、png、svg、gif、html、pdf、mp4 快捷标签;留空表示允许上传任意扩展名文件。 |
| Client file listing(客户端文件列表) | 布尔开关(默认:开) | 开启(供授权知识治理团队浏览) | 关闭(限制普通应用客户端列出文件) | 关闭后,匿名及普通应用用户的 listFiles 请求返回 401 user_unauthorized。API Key 身份和项目管理特权身份不受此开关限制,仍需满足适用的认证及授权要求;应用团队中的普通用户不因此成为项目管理者。上传和单文件访问仍按各自权限校验。 |
| Delete bucket(删除存储桶) | 底部危险操作区红色 删除 按钮 | 仅废弃时使用 | 仅废弃时使用 | 永久且不可逆:确认删除前核对目标桶及其文件与令牌。 |
3. 桶级图片内容安全审核(Moderation)与 Fail-Closed 保护
对面向外部用户上传的存储桶(如 agent_multimedia_bucket),可启用图片内容审核,并按业务需要限制文件的公开访问。切换到存储桶详情的 内容审核 页签:
开启桶级图片内容审核开关并配置风险拦截策略(更多全局审核规则详见 内容安全审核(Moderation))。
Fail-Closed 严格边界(上传拒绝即清理):
当用户向开启了 Moderation 的存储桶上传图片时,系统会在上传链路中同步调用审核服务。
图片违规、超过审核上限、读取失败或审核服务不可用时,上传请求失败。执行到相应清理步骤时会尝试删除已写入的文件及相关记录;上游步骤异常可能使清理未执行,清理本身也可能失败。应结合错误与日志核查实际状态。
隐私合规审计:审核审计日志仅记录安全的文件名预览与判定结果,绝不记录原始图片字节流或 Base64 编码内容。
4. 上传文件(Create file)、分块续传与图片转换预览
(1)在 Console 上传文件操作步骤
进入目标存储桶(如
kb_enterprise_docs)的 文件 页签,点击右上角 创建文件 进入上传向导页(/storage/bucket-{bucketId}/create)。选择文件与指定 File ID(Data 区):
拖放或点击选择本地文件(如
OceanBase分布式事务与向量索引排障指南.md)。客户端会在本地预先校验文件扩展名是否命中桶的 Allowed file extensions 白名单;而文件大小上限由服务端强制核验,超限文件在上传时会被服务端拒绝。可选展开 File ID 自定义文件唯一标识(或留空自动生成)。
配置单文件权限(Permissions 区):
若当前存储桶已开启 文件安全,此处显示
"File security enabled",可为该文件单独添加访问角色(如Role.user('user_zhangwei_001')或Role.team('team_support_ops'))。若未开启,此处提示
"File security disabled",需先前往桶 设置 开启后方可使用单文件权限。
点击创建后页面返回文件列表并提示
"File upload in progress"(大文件分块上传未完成前显示Pending徽标,此时关闭浏览器标签页会触发防丢失拦截确认)。
(2)通过 SDK 上传文件与获取实时图片转换预览(getFilePreview)
以下示例展示如何使用 agentbase-web-sdk@2.12.0 将工单截图上传至 agent_multimedia_bucket,并生成指定宽高与 WebP 格式的缩略图预览 URL:
运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。
import { Client, Storage, ID, Permission, Role, ImageGravity, ImageFormat } from 'agentbase-web-sdk'; // 版本固定 @2.12.0
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
.setProject('<APPBASE_PROJECT_ID>');
const storage = new Storage(client);
// 1. 上传工单报错截图(当文件 > 5MB 时 SDK 自动切换为分块上传并汇报进度)
const uploadedFile = await storage.createFile(
'agent_multimedia_bucket',
ID.unique(),
document.getElementById('ticketScreenshotInput').files[0],
[
// 提单客户张伟本人与 VIP 技术支持团队可读
Permission.read(Role.user('user_zhangwei_001')),
Permission.read(Role.team('team_support_ops')),
Permission.delete(Role.user('user_zhangwei_001'))
],
(progress) => {
console.log(`上传进度: ${progress.progress}% (${progress.chunksUploaded}/${progress.chunksTotal} 块)`);
}
);
// 2. 生成实时图片转换预览链接(需桶已开启 Image transformations)
// 将原图居中裁剪缩放为 800x600、质量 85%、自动转换为高压缩比 webp 格式
const previewUrl = storage.getFilePreview(
'agent_multimedia_bucket',
uploadedFile.$id,
800, // width (宽度像素)
600, // height (高度像素)
ImageGravity.Center, // gravity (裁剪重心)
85, // quality (1-100 压缩质量)
0, // borderWidth
'', // borderColor
8, // borderRadius (圆角像素)
1, // opacity
0, // rotation
'FFFFFF', // background
ImageFormat.Webp // output (输出格式转换为 webp)
);5. 文件详情与文件令牌(File Tokens)免登录安全分享
点击文件列表中的任意文件进入详情页(/storage/bucket-{bucketId}/file-{fileId}),可查看文件的缩略图预览、MIME 类型、大小、创建时间,并支持复制 文件 URL、点击 下载 下载原文件或修改单文件权限(注意:当前版本 Console 不支持对已上传文件重命名,文件名在上传瞬间确定)。
当需要将某个私有文件(如工单诊断报告或架构白皮书 PDF)临时分享给没有项目账号的外部合作伙伴,或者提供给外部大模型接口拉取时,可使用 File tokens(文件令牌):
在文件详情页下方找到 文件令牌 卡片(说明:
"Use tokens to provide public access to the file."),点击 创建令牌。设置过期时间(Expiration):可选预设档位 Never(永不过期)/ 7 Days / 30 days / 90 days / 1 Year,或选择 自定义日期 指定具体到期日(最早为次日)。
复制带签名 Token 的访问链接(Copy URL):
在令牌列表行点击 复制 URL,弹窗提供三个专用页签:预览(图片转换预览链接)、查看(浏览器内联打开链接)与 下载(触发附件下载链接),URL 末尾自动附带
...&token={secret}。任何持有该完整 URL 的访问者,即使未登录且不具备桶/文件 ACL 权限,只要该令牌未过期且未被删除,即可正常访问该文件。
安全保管与即时吊销边界:
令牌的
secret是签名 JWT,拥有 Console 读取权限的成员在列表中可再次点击复制,因此请将带有token=的 URL 视作共享密钥妥善保管;对于外部临时分享,强烈建议设置明确的过期时间(如7 Days),避免使用Never。一旦发现链接泄露或分享结束,只需在 文件令牌 列表中点击该令牌右侧的 删除(或调用 编辑过期时间 将其改为已过期),对应的分享链接立即失效。注意:单纯切换存储桶的
File security开关并不会使已签发的 File Token 失效,吊销访问必须直接删除令牌。
常见问题与排障
Q1:我已经把存储桶 agent_multimedia_bucket 的 File security 打开了,并且在上传图片时为客户 user_zhangwei_001 配置了单文件 Read 权限,为什么后来管理员把桶的 File security 关掉后,客户突然打不开自己的图片了?
原因分析: 这是 File security(文件级安全) 开关的核心鉴权语义:
当
File security处于开启状态时,系统采用桶级权限 OR 文件级权限鉴权,因此客户凭单文件上的Role.user('user_zhangwei_001')即可访问。一旦将桶的
File security切换为关闭,系统立即忽略桶内所有文件的单文件级权限,强制要求访问者必须命中桶级权限(Bucket Permissions)。如果桶级 Permissions 中只配置了内部团队Role.team('team_support_ops')而没有包含客户角色,客户就会立即失去访问权。
解决方案: 需要按单文件隔离授权的存储桶,请始终保持桶 Settings → File security 为开启状态。
Q2:如何允许前端用户向存储桶上传工单附件、并且允许通过已知图片链接直接展示图片,但限制普通应用用户调用 listFiles 拉取桶的文件列表?
解决方案: 这正是 Client file listing(客户端文件列表开关) 的标准应用场景:
进入目标存储桶(如
agent_multimedia_bucket)的 设置 页签。在 权限(或单文件权限)中正常配置允许上传(
Create)和读取(Read)的角色。向下滚动至 客户端文件列表 卡片,关闭「允许客户端列出文件」开关并点击 Update 保存。
关闭后,匿名及普通应用用户的 Session/JWT 调用
storage.listFiles('agent_multimedia_bucket')会返回401 user_unauthorized。API Key 身份和项目管理特权身份不受该开关限制,仍需满足适用认证和授权;普通应用团队的 owner 不自动成为项目管理者。上传与单文件访问仍需分别满足原有权限和设置。
Q3:为什么上传某些十几兆的大文件时,没有看到它被 Gzip/Zstd 压缩或触发静态加密,或者偶发看到文件列表中停留在 Pending 状态?
原因分析:
文件大小与处理条件:超过 20,000,000 字节时,内存压缩和应用层加密会跳过;杀毒也仅在环境与桶均启用、存储设备为本地且文件不超过 20,000,000 字节时执行。这些处理发生在写入存储设备之后。
Pending状态原因:大文件采用 5 MB 分块上传(Chunked Upload),如果客户端在上传中途断网、关闭浏览器页面或某一个分块被网络防火墙阻断,服务端尚未收到最后一个合并分块,该文件记录就会保持在Pending状态且不可访问详情。可通过客户端携带原fileId重新发起续传,或在列表中勾选该Pending记录直接删除清理。
相关文档
知识库文档管理:了解上传至知识库
kb_enterprise_support的文档如何复用 Storage 存储桶并进行解析切片。内容安全审核(Moderation):配置存储桶上传图片的违规识别策略与 Fail-Closed 拦截规则。
认证概览(Auth Overview):查阅存储桶与单文件权限中使用的
Role.any()、Role.users()、Role.user()、Role.team()语法。云函数(Functions):在服务端无服务器函数中结合项目上下文读写 Storage 文件。
核心概念与权限模型:全局了解 Agentbase 的存储、鉴权与配额计量规则。

