AgentbaseDocs
文档目录

存储

功能概述

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

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


核心概念与架构

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)。

角色、入口与关联关系

控制台入口与路由

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


功能详解与操作指南

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

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

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

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

创建存储桶操作步骤

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')<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 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 页签:

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

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

(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(文件令牌):


常见问题与排障

Q1:我已经把存储桶 agent_multimedia_bucket 的 File security 打开了,并且在上传图片时为客户 user_zhangwei_001 配置了单文件 Read 权限,为什么后来管理员把桶的 File security 关掉后,客户突然打不开自己的图片了?

原因分析: 这是 File security(文件级安全) 开关的核心鉴权语义:

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

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

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

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

原因分析:


相关文档