存储
功能概述
文件存储(Storage)是 Agentbase 面向非结构化与多模态数据提供的企业级对象存储、分块上传、细粒度访问控制、实时图片转换与上传内容安全审核(Moderation)服务。在项目 **企业智能客服与知识中台**(Project ID:enterprise-ai-hub-210)中,Storage 不仅是业务应用存储用户附件、工单截图和音视频素材的基础设施,更是 知识库(Knowledge Base)文档解析 与 多模态智能体记忆(Multimodal Memory) 的底层文件载体。
在 SIT 演示环境 enterprise-ai-hub-210 中,项目配置并运行了两个核心存储桶(Buckets):
- **
kb_enterprise_docs(企业知识库原始文档存储桶)**:承载上传至知识库kb_enterprise_support(企业智能客服与技术支持知识库)的 4 份核心企业文档(Agentbase企业架构白皮书.md、智能客服SOP标准作业手册.md、OceanBase分布式事务与向量索引排障指南.md、AI网关模型路由与限流计费规范.md),启用zstd高效压缩、扩展名白名单与文件级安全控制。 - **
agent_multimedia_bucket(智能体多模态媒体与工单附件桶)**:承载客户张伟(user_zhangwei_001)在提交工单时上传的架构报错截图、语音留言以及qwen-vl-max视觉模型处理的多模态文件,启用实时图片缩放预览(Image transformations)、客户端防枚举保护(Client file listing = false)与上传图片内容安全审核(Fail-Closed Moderation)。
核心概念与架构
Agentbase Storage 采用“存储桶(Bucket)策略隔离 → 分块上传与安全流水线(扩展名/大小校验、杀毒、加密、压缩、内容审核)→ 双层鉴权网关(Bucket Permissions + File Security + File Tokens + Client File Listing Gate)→ 多模态与知识库联动”的完整架构。下图展示了文件从上传入桶到被终端用户或 AI 模块安全访问的全链路:
flowchart TB
subgraph UploadPipeline["文件上传与安全处理流水线 (Create File Pipeline)"]
ClientUp["Client / Server SDK 分块上传<br/>(小文件直传 / 大文件 5MB 分块断点续传)"]
ExtSizeGate["1. 扩展名与大小门禁<br/>Allowed extensions (≤100项) & Maximum file size"]
AVScan["2. 杀毒扫描与内容安全审核<br/>Antivirus & Image Moderation<br/>(超限/违规/不可用时 Fail-Closed 拒绝并清理残余)"]
CompressEncrypt["3. 透明压缩与服务端加密<br/>Compression (none / gzip / zstd)<br/>Encryption (AES 静态加密)"]
end
subgraph Buckets["项目存储桶实例 (enterprise-ai-hub-210)"]
B1["存储桶 1: kb_enterprise_docs<br/>• 承载 4 份企业知识库 Markdown/PDF 源文档<br/>• Compression: zstd | File security: 开启"]
B2["存储桶 2: agent_multimedia_bucket<br/>• 承载工单截图与 qwen-vl-max 视觉多模态素材<br/>• Image transformations: 开启 | Client file listing: 关闭"]
end
subgraph AccessControl["四重访问控制与读取路径 (Access & Preview Gates)"]
ListGate{"listFiles 请求?<br/>检查 Client file listing"}
AuthCheck{"单文件 View / Download / Preview<br/>检查 File Token 或 ACL"}
FileToken["有效文件令牌 (File Token)<br/>?token=<JWT_SECRET> (支持过期时间管理)"]
BucketOrFileACL["桶级权限 (Bucket Permissions) 与<br/>文件级安全 (File Security: OR 逻辑)"]
ImgTransform["实时图片转换引擎 (Image Preview)<br/>缩放宽高 / 裁剪 / 质量 / 圆角 / WebP 格式转换"]
end
subgraph AIModules["AI 模块深度协同"]
KB["知识库 (kb_enterprise_support)<br/>文档切片、向量化与 GraphRAG/Wiki 构建"]
MM["多模态记忆与智能体工作台<br/>(qwen-vl-max 视觉理解与多模态提取)"]
end
ClientUp --> ExtSizeGate --> AVScan --> CompressEncrypt --> B1 & B2
B1 --> KB
B2 --> MM
B1 & B2 --> ListGate & AuthCheck
AuthCheck --> FileToken & BucketOrFileACL --> ImgTransform核心概念与存储桶属性说明
| 核心概念 | 属性名与默认值 | 架构语义与生产行为说明 |
|---|---|---|
| 存储桶(Bucket) | kb_enterprise_docs、agent_multimedia_bucket | 文件的顶层逻辑容器与安全策略边界。每个 Bucket 独立配置启停状态(enabled)、权限列表、大小上限、允许扩展名、压缩算法、加密、杀毒与图片审核策略。 |
| 文件级安全(File security) | fileSecurity(默认:关) | • 关闭时:仅桶级权限(Bucket Permissions)生效,单个文件上的权限设置被忽略。<br/>• 开启时:桶级权限与文件级权限采用逻辑或(OR)评估——用户只要满足桶级权限或该特定文件的文件级权限之一即可访问。 |
| 客户端文件列表开关(Client file listing) | clientFileListing(默认:开) | 将“列出桶内全部文件清单(listFiles)”与“按已知文件 ID / URL 访问单个文件”彻底解耦:<br/>• **设为关闭(false)时**:任何未登录、匿名或普通终端用户 Session/JWT 发起的 listFiles 请求均返回 401 user_unauthorized,彻底防止客户端遍历枚举全桶文件;但文件上传与按已知链接/Token 访问公开或授权图片不受影响,持 API Key 的 Server SDK 仍可正常列出文件。 |
| 分块上传(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)。 |
角色、入口与关联关系
控制台入口与路由
- 主导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 点击左侧栏 数据(Data) 分组下的 Storage。 - 路由地址:
- 存储桶列表与顶层用量页:
/console/project-{region}-{project}/storage(含 Buckets 与 Usage 两个顶层页签)。 - 单个存储桶详情页:
/console/project-{region}-{project}/storage/bucket-{bucketId}(含 Files、Usage、Moderation、Settings 四个子页签)。 - 独立文件上传向导页:
/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;无写权限时桶详情的 Settings 页签自动隐藏)。 - 在 Console 或通过 Server SDK 管理桶内文件需要
files.read/files.write权限。
- 在 Console 管理存储桶(创建/修改/删除桶)需要组织角色具备
与知识库(Knowledge Base)及多模态记忆(Memory)的关联关系
- 知识库(Knowledge Base)文档底座:当在 知识库文档管理 中向
kb_enterprise_support上传Agentbase企业架构白皮书.md、智能客服SOP标准作业手册.md等源文档时,底层直接复用项目 Storage 存储桶完成原始文件持久化、杀毒与静态加密,随后再由知识库解析流水线异步读取并构建向量索引、GraphRAG 知识图谱与 Wiki 页面。 - 多模态记忆(Multimodal Memory)与视觉大模型联动:当智能体需要调用
qwen-vl-max视觉模型分析用户上传的架构图或报错截图时,前端先将图片安全上传至agent_multimedia_bucket,经内置图片内容安全审核(Moderation)放行后,通过文件访问 URL 或 File Token 交由多模态记忆与模型网关处理。 - 云函数(Functions)受控访问:在 云函数 运行时内部访问 Storage 时,自动继承项目上下文与函数执行身份,可安全读写受保护存储桶中的文件。
功能详解与操作指南
1. 创建与查看存储桶(Create bucket)
进入项目 Storage → Buckets 页签,页面展示当前项目下已创建的所有存储桶(如 kb_enterprise_docs 和 agent_multimedia_bucket):
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
创建存储桶操作步骤
- 在 Storage → Buckets 页签右上角点击 Create bucket 按钮(若桶数量已达当前套餐上限,按钮自动禁用)。
- 在弹窗中填写两个基础标识字段:
- Name(必填):存储桶业务显示名称,最长 128 字符(例如:
企业知识库原始文档存储桶或智能体多模态媒体与工单附件桶)。 - Bucket ID(可选):点击 Bucket ID 标签展开自定义输入框,填入如
kb_enterprise_docs或agent_multimedia_bucket(仅允许a-z、A-Z、0-9、.、-、_,最长 36 字符;留空则自动生成唯一 ID)。
- Name(必填):存储桶业务显示名称,最长 128 字符(例如:
- 点击 Create 完成创建,页面自动跳转至该存储桶的详情页。新建存储桶的服务端默认安全基线为:Enabled = 开启、File security = 关闭、Permissions = 空(默认拒绝一切客户端访问)、Compression = none、Encryption = 开启、Antivirus = 开启、Client file listing = 开启。
2. 存储桶设置(Bucket Settings)全参数详解
进入存储桶详情页并切换到 Settings 页签,管理员可逐张卡片调整存储桶的访问控制、压缩加密与防枚举策略:
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
下表详列了 Settings 页全部配置卡片的参数规则、技术边界以及在 enterprise-ai-hub-210 两个示例桶中的最佳实践配置:
| 设置卡片名称 | 配置项与可选值 | kb_enterprise_docs 推荐配置 | agent_multimedia_bucket 推荐配置 | 技术规则与边界说明 |
|---|---|---|---|---|
| Enabled(启用状态) | 布尔开关(开 / 关) | 开启 | 开启 | 关闭后,所有终端用户(Client SDK)均无法访问桶内文件;但持有 API Key 的 Server SDK 仍可正常访问,且底层文件绝不丢失。 |
| Name(桶名称) | 字符串(1–128 字符) | 企业知识库原始文档存储桶 | 智能体多模态媒体与工单附件桶 | 修改桶显示名称不影响 Bucket ID 及任何已生成的 File URL。 |
| Permissions(桶级权限) | 为 Role 添加 Create / Read / Update / Delete | Read: Role.team('team_kb_governance')<br/>Write: Role.team('team_kb_governance', 'reviewer') | Create: Role.users('verified')<br/>Read: Role.team('team_support_ops') | 支持选择 Any、Guests、Users、指定 User、Team + Role、Label 或在编辑器内自定义角色表达式。 |
| File security(文件级安全) | 布尔开关(开 / 关) | 开启 | 开启 | 关闭时:仅桶级权限生效,忽略单文件权限。<br/>开启时:满足桶级权限或单文件权限之一即可访问。切换开关立即对全桶文件鉴权生效! |
| Security settings(加密与杀毒) | Encryption(静态加密)<br/>Antivirus(ClamAV 病毒扫描) | 双项均 开启 | 双项均 开启 | 上传文件落盘前自动执行病毒扫描与静态加密;为保障吞吐,超大分块文件(超过内部大文件阈值)会自动跳过内存全量加密与扫描。 |
| 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(删除存储桶) | 底部危险操作区红色 Delete 按钮 | 仅废弃时使用 | 仅废弃时使用 | 永久且不可逆:输入桶名称确认后,彻底删除该桶及其内部全部文件与令牌。 |
3. 桶级图片内容安全审核(Moderation)与 Fail-Closed 保护
在面向外部用户开放上传的存储桶(如 agent_multimedia_bucket)中,切勿允许未经审核的图片直接落盘并提供公开外链。切换到存储桶详情的 Moderation 页签:
- 开启桶级图片内容审核开关并配置风险拦截策略(更多全局审核规则详见 内容安全审核(Moderation))。
- Fail-Closed 严格边界(上传拒绝即清理):
- 当用户向开启了 Moderation 的存储桶上传图片时,系统会在上传链路中同步调用审核服务。
- 一旦图片被判定违规、图片体积超出审核上限、图片字节读取损坏或后端审核服务不可用,本次上传请求会被立即拒绝,且服务端会自动清理已写入磁盘的临时文件块,绝不在存储桶中残留任何未经审核放行的图片文件。
- 隐私合规审计:审核审计日志仅记录安全的文件名预览与判定结果,绝不记录原始图片字节流或 Base64 编码内容。
4. 上传文件(Create file)、分块续传与图片转换预览
(1)在 Console 上传文件操作步骤
- 进入目标存储桶(如
kb_enterprise_docs)的 Files 页签,点击右上角 Create file 进入上传向导页(/storage/bucket-{bucketId}/create)。 - 选择文件与指定 File ID(Data 区):
- 拖放或点击选择本地文件(如
OceanBase分布式事务与向量索引排障指南.md)。客户端会在本地预先校验文件扩展名是否命中桶的 Allowed file extensions 白名单;而文件大小上限由服务端强制核验,超限文件在上传时会被服务端拒绝。 - 可选展开 File ID 自定义文件唯一标识(或留空自动生成)。
- 拖放或点击选择本地文件(如
- 配置单文件权限(Permissions 区):
- 若当前存储桶已开启 File security,此处显示
"File security enabled",可为该文件单独添加访问角色(如Role.user('user_zhangwei_001')或Role.team('team_support_ops'))。 - 若未开启,此处提示
"File security disabled",需先前往桶 Settings 开启后方可使用单文件权限。
- 若当前存储桶已开启 File security,此处显示
- 点击创建后页面返回文件列表并提示
"File upload in progress"(大文件分块上传未完成前显示Pending徽标,此时关闭浏览器标签页会触发防丢失拦截确认)。
(2)通过 SDK 上传文件与获取实时图片转换预览(getFilePreview)
以下示例展示如何使用 agentbase-web-sdk@2.10.0 将工单截图上传至 agent_multimedia_bucket,并生成指定宽高与 WebP 格式的缩略图预览 URL:
import { Client, Storage, ID, Permission, Role, ImageGravity, ImageFormat } from 'agentbase-web-sdk'; // 版本固定 @2.10.0
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('enterprise-ai-hub-210');
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 类型、大小、创建时间,并支持复制 File URL、点击 Download 下载原文件或修改单文件权限(注意:当前版本 Console 不支持对已上传文件重命名,文件名在上传瞬间确定)。
当需要将某个私有文件(如工单诊断报告或架构白皮书 PDF)临时分享给没有项目账号的外部合作伙伴,或者提供给外部大模型接口拉取时,可使用 File tokens(文件令牌):
- 在文件详情页下方找到 File tokens 卡片(说明:
"Use tokens to provide public access to the file."),点击 Create token。 - 设置过期时间(Expiration):可选预设档位 Never(永不过期)/ 7 Days / 30 days / 90 days / 1 Year,或选择 Custom Date 指定具体到期日(最早为次日)。
- 复制带签名 Token 的访问链接(Copy URL):
- 在令牌列表行点击 Copy URL,弹窗提供三个专用页签:Preview(图片转换预览链接)、View(浏览器内联打开链接)与 Download(触发附件下载链接),URL 末尾自动附带
...&token={secret}。 - 任何持有该完整 URL 的访问者,即使未登录且不具备桶/文件 ACL 权限,只要该令牌未过期且未被删除,即可正常访问该文件。
- 在令牌列表行点击 Copy URL,弹窗提供三个专用页签:Preview(图片转换预览链接)、View(浏览器内联打开链接)与 Download(触发附件下载链接),URL 末尾自动附带
- 安全保管与即时吊销边界:
- 令牌的
secret是签名 JWT,拥有 Console 读取权限的成员在列表中可再次点击复制,因此**请将带有token=的 URL 视作共享密钥妥善保管**;对于外部临时分享,强烈建议设置明确的过期时间(如7 Days),避免使用Never。 - 一旦发现链接泄露或分享结束,只需在 File tokens 列表中点击该令牌右侧的 Delete(或调用 Edit expiry 将其改为已过期),对应的分享链接立即失效。注意:单纯切换存储桶的
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)的 Settings 页签。 - 在 Permissions(或单文件权限)中正常配置允许上传(
Create)和读取(Read)的角色。 - 向下滚动至 Client file listing 卡片,关闭「允许客户端列出文件」开关并点击 Update 保存。
- 关闭后,任何前端客户端(无论匿名、普通登录 Session 还是用户 JWT)调用
storage.listFiles('agent_multimedia_bucket')都会被后端直接拦截并返回401 user_unauthorized(不泄露任何文件名或文件总数);而前端调用createFile上传以及在<img>标签中按已知fileId访问getFileView/getFilePreview均完全正常,后端微服务使用 Server API Key 调用listFiles也同样不受影响。
Q3:为什么上传某些十几兆的大文件时,没有看到它被 Gzip/Zstd 压缩或触发静态加密,或者偶发看到文件列表中停留在 Pending 状态?
原因分析:
- 大文件流式直通优化:为了避免在网关与 Worker 内存中缓存超大字节流引发内存溢出(OOM)或高延迟,当上传文件体积超过内部大文件流式阈值时,系统会自动跳过全量内存压缩(Compression)、静态加密(Encryption)与病毒扫描(Antivirus),直接走高性能分块流式落盘。
- **
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 的存储、鉴权与配额计量规则。