agentbase-docs

对象存储

这是什么 / 何时用

桶(Bucket)与文件的上传、下载、预览与权限控制;配套的短时访问令牌(File Token)。何时用:用户头像、附件、图片素材、需要临时分享链接的文件。权限模型(fileSecurity、404 语义、跨域陷阱)与 permissions.md 的存储小节互为补充。

前置

使用骨架

关键参数与返回

调用关键参数返回 / 说明
createBucketfileSecurity、maximumFileSize、allowedFileExtensionsModels.Bucket
createFilebucketId、fileId(ID.unique())、file、permissions?Models.File($id、name、mimeType、sizeOriginal、$permissions)
getFilePreviewbucketId、fileId、width?、height?、gravity?、quality?、格式等URL 字符串(不含认证)
getFileDownload / getFileViewbucketId、fileIdURL 字符串
createFileTokenbucketId、fileId、expire?(ISO 8601)Token(短链凭据)

UsageRange 枚举:24h / 30d / 90d。

错误与边界:fileSecurity 下 404 语义

判定链:桶级 read 命中 → 直接放行;未命中且 fileSecurity: false → 401;未命中且 fileSecurity: true → 带鉴权查文件级权限 → 匹配返回,**不匹配返回 404(file_not_found),不是 403——隐藏文件存在性。排障口诀:看到 404 先查权限,再查存在性**。

<img> 跨域陷阱

跨域 HTTP(或跨站)环境里,<img src=".../preview?project=..."> 不携带 Session Cookie(SameSite=None 在无 Secure 时被降级、img 标签也带不了 header / fallback cookie),请求以匿名到达 → 桶级 read("users") 不匹配 → 文件级也不匹配 → 404。正确做法:

错误与边界

SDK 类别差异

示例指引

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

建桶(桶级权限基线)

桶默认不授予任何用户角色——用户侧读 / 建文件必须显式配置 permissions;fileSecurity: true 才启用文件级权限。无 Web 页签:建桶属服务端动作(Console 在管理面 UI 配置)。

import { Client, Storage, Permission, Role } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)   // 必须包含 /v1
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setKey(process.env.APPBASE_API_KEY!);        // storage.read / storage.write
const storage = new Storage(client);

await storage.createBucket({
    bucketId: 'attachments',
    name: '附件',
    permissions: [Permission.read(Role.users()), Permission.create(Role.users())],
    fileSecurity: true,      // 启用文件级权限(「房门」)
    enabled: true,
});

上传 / 下载 / 预览

createFile 的 file 用 SDK 的 InputFile 封装(Node 侧从 SDK 的 file 子路径导入);文件级 permissions 需桶开启 fileSecurity 才生效。

import { Storage, InputFile, ID, Permission, Role } from 'agentbase-node-sdk';

const file = await storage.createFile({
    bucketId: 'attachments',
    fileId: ID.unique(),
    file: InputFile.fromPath('./report.pdf'),   // 或 InputFile.fromBuffer(bytes, 'report.pdf')
    permissions: [Permission.read(Role.users())],   // 可选;需桶开启 fileSecurity
});

await storage.getFileDownload('attachments', file.$id);   // 下载(重定向 / 响应)
const previewUrl = storage.getFilePreview('attachments', file.$id, 800);   // 仅拼 URL,不发起认证请求

文件管理:listFiles / getFile / updateFile / deleteFile

listFiles 分页列出桶内文件,getFile 取元数据(不返回内容);updateFile 只更新元数据(文件名与权限,permissions 为全量替换,语义同 updateRow),文件内容不可变。

const files = await storage.listFiles({ bucketId: 'attachments' });   // 分页经 queries
const meta = await storage.getFile({ bucketId: 'attachments', fileId: '<fileId>' });

await storage.updateFile({
    bucketId: 'attachments',
    fileId: '<fileId>',
    name: 'report-updated.pdf',
    // permissions: [...]   // 全量替换:不传则保留当前权限
});

await storage.deleteFile({ bucketId: 'attachments', fileId: '<fileId>' });

跨域 <img>:Blob URL(Web 专有)

跨域环境 <img src=".../preview?project=..."> 带不上 Session Cookie,fileSecurity 桶会以 404(file_not_found)拒绝——用 SDK 认证请求取字节流再转 Blob URL。

// getFilePreview / getFileView 只拼 URL 不发起请求;用 client.call() 发起带认证的请求
// (自动携带 credentials: 'include' + X-Fallback-Cookies header),拿到 ArrayBuffer 再转 Blob URL:
const arrayBuffer: ArrayBuffer = await client.call(
    'GET',
    `${ENDPOINT}/storage/buckets/${bucketId}/files/${fileId}/view`,
    {}, {}, 'arrayBuffer'
);
const blobUrl = URL.createObjectURL(new Blob([arrayBuffer]));
imgElement.src = blobUrl;   // 组件卸载 / 重取时 URL.revokeObjectURL(blobUrl)

邮件链接、第三方、SSR 预览等带不了 Cookie 的场景,由服务端签发有时效令牌;secret 以 ?token= 拼到文件的 view / preview / download 端点。无 Web 页签:签发属服务端动作。

import { Tokens } from 'agentbase-node-sdk';

const tokens = new Tokens(client);
const token = await tokens.createFileToken({
    bucketId: 'attachments',
    fileId: '<fileId>',
    expire: '2026-10-15T06:38:00.000+00:00',   // 可选,ISO 8601;务必设短时效
});
// 常用方法:createFileToken / list / get / update / delete
// token.secret 拼到 /storage/buckets/{bucketId}/files/{fileId}/view?token=<secret>

用量(Console / 管理面口径)

对象存储总览与单桶的聚合用量走 Console SDK:管理面 Session / JWT,client 需指向应用项目并 setMode('admin');普通 Server SDK(API Key)不含这些聚合方法,故本卡无 Node 页签。

import { Client, Storage, UsageRange } from 'agentbase-console-sdk';

// 初始化见 console-sdk/nodejs.md;查应用项目前先指向该项目并进入 admin mode:
// client.setProject('<projectId>').setMode('admin')
const storage = new Storage(client);

const usage = await storage.getUsage({ range: UsageRange.ThirtyDays });   // '30d';枚举 24h / 30d / 90d
const bucketUsage = await storage.getBucketUsage({ bucketId: 'attachments', range: UsageRange.ThirtyDays });
// 关键返回:filesStorageTotal 与 storage 趋势数组

事实源