Docs
文档目录

存储

功能概述

文件存储(Storage)是 Agentbase 面向非结构化与多模态数据提供的企业级对象存储、分块上传、细粒度访问控制、实时图片转换与上传内容安全审核(Moderation)服务。在项目 企业智能客服与知识中台(Project ID:enterprise-ai-hub-210)中,Storage 不仅是业务应用存储用户附件、工单截图和音视频素材的基础设施,更是 知识库(Knowledge Base)文档解析 与 多模态智能体记忆(Multimodal Memory) 的底层文件载体。

在 SIT 演示环境 enterprise-ai-hub-210 中,项目配置并运行了两个核心存储桶(Buckets):

  1. kb_enterprise_docs(企业知识库原始文档存储桶):承载上传至知识库 kb_enterprise_support(企业智能客服与技术支持知识库)的 4 份核心企业文档(Agentbase企业架构白皮书.md、智能客服SOP标准作业手册.md、OceanBase分布式事务与向量索引排障指南.md、AI网关模型路由与限流计费规范.md),启用 zstd 高效压缩、扩展名白名单与文件级安全控制。

  2. 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 模块安全访问的全链路:

存储:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心概念与存储桶属性说明

核心概念属性名与默认值架构语义与生产行为说明
存储桶(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 的 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)。

角色、入口与关联关系

控制台入口与路由

与知识库(Knowledge Base)及多模态记忆(Memory)的关联关系

  1. 知识库(Knowledge Base)文档底座:当在 知识库文档管理 中向 kb_enterprise_support 上传 Agentbase企业架构白皮书.md、智能客服SOP标准作业手册.md 等源文档时,底层直接复用项目 Storage 存储桶完成原始文件持久化、杀毒与静态加密,随后再由知识库解析流水线异步读取并构建向量索引、GraphRAG 知识图谱与 Wiki 页面。

  2. 多模态记忆(Multimodal Memory)与视觉大模型联动:当智能体需要调用 qwen-vl-max 视觉模型分析用户上传的架构图或报错截图时,前端先将图片安全上传至 agent_multimedia_bucket,经内置图片内容安全审核(Moderation)放行后,通过文件访问 URL 或 File Token 交由多模态记忆与模型网关处理。

  3. 云函数(Functions)受控访问:在 云函数 运行时内部访问 Storage 时,自动继承项目上下文与函数执行身份,可安全读写受保护存储桶中的文件。


功能详解与操作指南

1. 创建与查看存储桶(Create bucket)

进入项目 Storage → Buckets 页签,页面展示当前项目下已创建的所有存储桶(如 kb_enterprise_docs 和 agent_multimedia_bucket):

存储桶列表页(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

创建存储桶操作步骤

  1. 在 Storage → Buckets 页签右上角点击 Create bucket 按钮(若桶数量已达当前套餐上限,按钮自动禁用)。

  2. 在弹窗中填写两个基础标识字段:

    • Name(必填):存储桶业务显示名称,最长 128 字符(例如:企业知识库原始文档存储桶 或 智能体多模态媒体与工单附件桶)。

    • Bucket ID(可选):点击 Bucket ID 标签展开自定义输入框,填入如 kb_enterprise_docs 或 agent_multimedia_bucket(仅允许 a-z、A-Z、0-9、.、-、_,最长 36 字符;留空则自动生成唯一 ID)。

  3. 点击 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 / DeleteRead: 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(加密与杀毒)Encryption(静态加密)
Antivirus(ClamAV 病毒扫描)
双项均 开启双项均 开启上传文件落盘前自动执行病毒扫描与静态加密;为保障吞吐,超大分块文件(超过内部大文件阈值)会自动跳过内存全量加密与扫描。
Compression(压缩算法)下拉选择:None / Gzip / ZstdZstd(高压缩比、极速解压)None(图片/音视频本身已压缩)对 Markdown、JSON、文本与未压缩文档推荐开启 Zstd 或 Gzip;大文件自动跳过实时压缩。
Image transformations布尔开关(开 / 关)关闭(纯文档桶无需图片转换)开启开启后允许客户端通过 getFilePreview 接口对桶内图片执行实时缩放、裁剪、圆角、背景色与格式转换。
Maximum file size(单文件大小上限)数值 + 单位(Bytes / KB / MB / GB,按 1000 进制换算)50 MB20 MB注意:该值限制的是单个上传文件的最大体积(受套餐 fileSize 硬上限约束),而非整个项目的总存储容量配额。
Allowed file extensions(扩展名白名单)扩展名标签列表(最多 100 项,不含前导点号)md, pdf, docx, txt, html, csvjpg, 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 页签:

  1. 开启桶级图片内容审核开关并配置风险拦截策略(更多全局审核规则详见 内容安全审核(Moderation))。

  2. Fail-Closed 严格边界(上传拒绝即清理):

    • 当用户向开启了 Moderation 的存储桶上传图片时,系统会在上传链路中同步调用审核服务。

    • 一旦图片被判定违规、图片体积超出审核上限、图片字节读取损坏或后端审核服务不可用,本次上传请求会被立即拒绝,且服务端会自动清理已写入磁盘的临时文件块,绝不在存储桶中残留任何未经审核放行的图片文件。

    • 隐私合规审计:审核审计日志仅记录安全的文件名预览与判定结果,绝不记录原始图片字节流或 Base64 编码内容。

4. 上传文件(Create file)、分块续传与图片转换预览

(1)在 Console 上传文件操作步骤

  1. 进入目标存储桶(如 kb_enterprise_docs)的 Files 页签,点击右上角 Create file 进入上传向导页(/storage/bucket-{bucketId}/create)。

  2. 选择文件与指定 File ID(Data 区):

    • 拖放或点击选择本地文件(如 OceanBase分布式事务与向量索引排障指南.md)。客户端会在本地预先校验文件扩展名是否命中桶的 Allowed file extensions 白名单;而文件大小上限由服务端强制核验,超限文件在上传时会被服务端拒绝。

    • 可选展开 File ID 自定义文件唯一标识(或留空自动生成)。

  3. 配置单文件权限(Permissions 区):

    • 若当前存储桶已开启 File security,此处显示 "File security enabled",可为该文件单独添加访问角色(如 Role.user('user_zhangwei_001') 或 Role.team('team_support_ops'))。

    • 若未开启,此处提示 "File security disabled",需先前往桶 Settings 开启后方可使用单文件权限。

  4. 点击创建后页面返回文件列表并提示 "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(文件令牌):

  1. 在文件详情页下方找到 File tokens 卡片(说明:"Use tokens to provide public access to the file."),点击 Create token。

  2. 设置过期时间(Expiration):可选预设档位 Never(永不过期)/ 7 Days / 30 days / 90 days / 1 Year,或选择 Custom Date 指定具体到期日(最早为次日)。

  3. 复制带签名 Token 的访问链接(Copy URL):

    • 在令牌列表行点击 Copy URL,弹窗提供三个专用页签:Preview(图片转换预览链接)、View(浏览器内联打开链接)与 Download(触发附件下载链接),URL 末尾自动附带 ...&token={secret}。

    • 任何持有该完整 URL 的访问者,即使未登录且不具备桶/文件 ACL 权限,只要该令牌未过期且未被删除,即可正常访问该文件。

  4. 安全保管与即时吊销边界:

    • 令牌的 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(文件级安全) 开关的核心鉴权语义:

解决方案: 需要按单文件隔离授权的存储桶,请始终保持桶 Settings → File security 为开启状态。

Q2:如何允许前端用户向存储桶上传工单附件、并且允许通过已知图片链接直接展示图片,但严禁任何前端用户调用 listFiles 拉取整个桶的文件列表?

解决方案: 这正是 Client file listing(客户端文件列表开关) 的标准应用场景:

  1. 进入目标存储桶(如 agent_multimedia_bucket)的 Settings 页签。

  2. 在 Permissions(或单文件权限)中正常配置允许上传(Create)和读取(Read)的角色。

  3. 向下滚动至 Client file listing 卡片,关闭「允许客户端列出文件」开关并点击 Update 保存。

  4. 关闭后,任何前端客户端(无论匿名、普通登录 Session 还是用户 JWT)调用 storage.listFiles('agent_multimedia_bucket') 都会被后端直接拦截并返回 401 user_unauthorized(不泄露任何文件名或文件总数);而前端调用 createFile 上传以及在 <img> 标签中按已知 fileId 访问 getFileView / getFilePreview 均完全正常,后端微服务使用 Server API Key 调用 listFiles 也同样不受影响。

Q3:为什么上传某些十几兆的大文件时,没有看到它被 Gzip/Zstd 压缩或触发静态加密,或者偶发看到文件列表中停留在 Pending 状态?

原因分析:

  1. 大文件流式直通优化:为了避免在网关与 Worker 内存中缓存超大字节流引发内存溢出(OOM)或高延迟,当上传文件体积超过内部大文件流式阈值时,系统会自动跳过全量内存压缩(Compression)、静态加密(Encryption)与病毒扫描(Antivirus),直接走高性能分块流式落盘。

  2. Pending 状态原因:大文件采用 5 MB 分块上传(Chunked Upload),如果客户端在上传中途断网、关闭浏览器页面或某一个分块被网络防火墙阻断,服务端尚未收到最后一个合并分块,该文件记录就会保持在 Pending 状态且不可访问详情。可通过客户端携带原 fileId 重新发起续传,或在列表中勾选该 Pending 记录直接删除清理。


相关文档