Docs
文档目录

存储

功能概述

存储用于管理项目中的文件。你可以创建存储桶,配置访问权限、文件大小和允许的扩展名,并通过控制台或 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)。

角色、入口与关联关系

控制台入口与路由

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

  1. 知识库文档底座:知识库使用存储保存源文档,再由解析流水线读取处理。是否执行杀毒和加密取决于环境、存储设备、桶配置及文件大小;请按下文条件核实。

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

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


功能详解与操作指南

1. 创建与查看存储桶

在项目侧栏进入 基础设施 → 存储,选择 存储桶 页签,可搜索和查看当前项目的存储桶。

存储桶列表页

图 1:2.12.0 环境中的存储桶列表;示例存储桶 ID 已遮盖。

创建存储桶操作步骤

  1. 点击 创建存储桶。若按钮不可用,先检查账号是否具有存储桶写入权限。

  2. 在窗口中填写名称,并可在存储桶 ID 输入框填写自定义标识。ID 最多 36 个字符,首字符须为字母或数字,其余字符可使用字母、数字、句点、连字符或下划线;留空时系统自动生成。

  3. 根据需要设置 允许客户端列举文件。新建窗口默认开启;关闭后,列举文件需要获得授权的服务端或项目管理身份,上传和单个文件访问仍按各自权限控制。

  4. 点击 确认。创建成功后进入存储桶详情页,可继续上传文件或调整设置。

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 / 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(加密与杀毒)加密(静态加密)
病毒扫描(ClamAV 病毒扫描)
双项均 开启双项均 开启文件先写入存储设备,所有分片完成后才进行后续处理。杀毒还要求环境启用、桶开启、使用本地存储且文件不超过 20,000,000 字节;加密仅对不超过 20,000,000 字节的文件执行。请确认部署环境配置,桶开关开启不代表所有文件均已扫描或加密。
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(删除存储桶)底部危险操作区红色 删除 按钮仅废弃时使用仅废弃时使用永久且不可逆:确认删除前核对目标桶及其文件与令牌。

3. 桶级图片内容安全审核(Moderation)与 Fail-Closed 保护

对面向外部用户上传的存储桶(如 agent_multimedia_bucket),可启用图片内容审核,并按业务需要限制文件的公开访问。切换到存储桶详情的 内容审核 页签:

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

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

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

    • 图片违规、超过审核上限、读取失败或审核服务不可用时,上传请求失败。执行到相应清理步骤时会尝试删除已写入的文件及相关记录;上游步骤异常可能使清理未执行,清理本身也可能失败。应结合错误与日志核查实际状态。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  4. 关闭后,匿名及普通应用用户的 Session/JWT 调用 storage.listFiles('agent_multimedia_bucket') 会返回 401 user_unauthorized。API Key 身份和项目管理特权身份不受该开关限制,仍需满足适用认证和授权;普通应用团队的 owner 不自动成为项目管理者。上传与单文件访问仍需分别满足原有权限和设置。

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

原因分析:

  1. 文件大小与处理条件:超过 20,000,000 字节时,内存压缩和应用层加密会跳过;杀毒也仅在环境与桶均启用、存储设备为本地且文件不超过 20,000,000 字节时执行。这些处理发生在写入存储设备之后。

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


相关文档