对象存储
这是什么 / 何时用
桶(Bucket)与文件的上传、下载、预览与权限控制;配套的短时访问令牌(File Token)。何时用:用户头像、附件、图片素材、需要临时分享链接的文件。权限模型(fileSecurity、404 语义、跨域陷阱)与 permissions.md 的存储小节互为补充。
前置
- Server API Key:
storage.read/storage.write(桶与文件管理);客户端上传 / 下载走用户 Session + 桶 / 文件权限。 - 预览类能力依赖实例的图片处理组件;自托管排障见 troubleshooting.md。
使用骨架
- 建桶:
storage.createBucket({ bucketId, name, permissions?, fileSecurity?, enabled?, maximumFileSize?, allowedFileExtensions?, compression?, encryption?, antivirus? })。 - 桶级
permissions是「大门」(如create("users")、read("users")、read("label:admin"))。 fileSecurity: true启用文件级权限(「房门」);false时只看桶级。
- 桶级
- 上传:
storage.createFile({ bucketId, fileId, file, permissions? });file用 SDK 的InputFile(表单 File /fromPath/fromBuffer/fromBytes;Node 侧从 SDK 的file子路径导入)。文件级$permissions缺省时按桶配置与建行同型的默认规则处理,需要精细控制时显式传Permission列表。 - 读取:
getFile元数据;getFileDownload(下载 URL / 响应);getFileView/getFilePreview(预览,可带宽高、gravity、quality 等——这两个方法只拼 URL 字符串,不发起认证请求)。 - 管理:
listFiles/updateFile(改名、权限)/deleteFile。 - File Token(无 Cookie 场景):Server SDK
Tokensservice 对指定文件签发有时效令牌——createFileToken({ bucketId, fileId, expire? })、list/get/update/delete;响应含用于 view / preview / download 的 secret / URL 字段(以当前 SDK 模型为准)。路径前缀/v1/tokens/buckets/{bucketId}/files/{fileId}。 - 用量:
storage.getUsage({ range })、storage.getBucketUsage({ bucketId, range })(Console / 管理面口径)。
关键参数与返回
| 调用 | 关键参数 | 返回 / 说明 |
|---|---|---|
createBucket | fileSecurity、maximumFileSize、allowedFileExtensions | Models.Bucket |
createFile | bucketId、fileId(ID.unique())、file、permissions? | Models.File($id、name、mimeType、sizeOriginal、$permissions) |
getFilePreview | bucketId、fileId、width?、height?、gravity?、quality?、格式等 | URL 字符串(不含认证) |
getFileDownload / getFileView | bucketId、fileId | URL 字符串 |
createFileToken | bucketId、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。正确做法:
- Blob URL:用 SDK
client.call('GET', url, {}, {}, 'arrayBuffer')发起带认证的请求,URL.createObjectURL(new Blob(...))后再赋给<img src>(可封装成useImageBlob类 Hook)。 - File Token:不能带 Cookie 的场景(邮件链接、第三方、SSR 生成的预览)由服务端签发短时 Token 生成可访问 URL。
错误与边界
- 413 超过桶
maximumFileSize;400 扩展名不在allowedFileExtensions。 - 删除他人文件 403:文件级
delete用了上传者个人角色——团队协作改Role.team(teamId)。 - Token 泄露等同于有效期内可读该文件:
expire设短、只对必要文件签发、由后端 / Function 签发后把短链给前端,绝不把创建 Token 的 API Key 放进浏览器。 - 长期团队共享优先
Permission+ Session;Token 只用于临时、无 Cookie 场景。 - 2.6.0 安全默认值:远程 Avatar/Favicon/Screenshot 类抓取默认收紧;外链资源访问失败时先确认实例安全策略而不是关闭防护。
SDK 类别差异
- Client SDK(Web):用户 Session 上传 / 下载 / 预览;
getFilePreview/getFileView的 URL 不带认证(见上);跨域场景用 Blob URL。 - Server SDK:桶与文件全生命周期、显式授权、File Token 签发(
Tokensservice);Node 的InputFile从file子路径导入。 - Console SDK:桶管理(管理面视角)与存储用量(
storage.getUsage/getBucketUsage)。 - 差异入口:client-sdk/web.md、
server-sdk/nodejs.md。
示例指引
- 各语言写法集中在语言树
examples/;Blob URL / Hook 封装、错误对照表与调试步骤见skills/ob-agentbase/references/storage-permissions.md、skills/ob-agentbase/references/file-tokens.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
建桶(桶级权限基线)
桶默认不授予任何用户角色——用户侧读 / 建文件必须显式配置 permissions;fileSecurity: true 才启用文件级权限。无 Web 页签:建桶属服务端动作(Console 在管理面 UI 配置)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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,
});import io.agentbase.services.Storage;
Storage storage = new Storage(client); // client 初始化见 server-sdk/java.md
// 位置参数形态(permissions / fileSecurity / maximumFileSize 等语义同 Node 面):
storage.createBucket("attachments", "附件", null, true, true,
26214400L, null, null, true, false, true);from agentbase.services.storage import Storage
storage = Storage(client) # client 初始化见 examples/python.md
storage.create_bucket(bucket_id='attachments', name='附件',
file_security=True, enabled=True) # permissions 传权限字符串数组storage := agentbase.NewStorage(cl) // facade 构造器;cl 为已装载 API Key 的 Client
_, err := storage.CreateBucket("attachments", "附件",
storage.WithCreateBucketFileSecurity(true),
storage.WithCreateBucketEnabled(true))
// permissions 以权限字符串数组传入;确切 option 名以模块源码为准curl -sS -X POST "$APPBASE_ENDPOINT/storage/buckets" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{
"bucketId": "app-assets",
"name": "App Assets",
"fileSecurity": true,
"permissions": [
"read(\"users\")",
"update(\"team:dev/owner\")",
"delete(\"team:dev/owner\")",
"create(\"label:admin\")"
]
}'上传 / 下载 / 预览
createFile 的 file 用 SDK 的 InputFile 封装(Node 侧从 SDK 的 file 子路径导入);文件级 permissions 需桶开启 fileSecurity 才生效。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Storage, ID, Permission, Role } from 'agentbase-node-sdk';
import { InputFile } from 'agentbase-node-sdk/file';
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,不发起认证请求import { Storage, ID, Permission, Role } from 'agentbase-web-sdk'; // 用户已登录
const file = await storage.createFile({
bucketId: 'attachments',
fileId: ID.unique(),
file: document.getElementById('fileInput').files[0], // 表单 File
});
const download = await storage.getFileDownload({ bucketId: 'attachments', fileId: '<fileId>' });
const previewUrl = storage.getFilePreview('attachments', '<fileId>', 800); // URL 字符串,不带认证import io.agentbase.ID;
import io.agentbase.services.Storage;
Storage storage = new Storage(client);
var file = storage.createFile("attachments", ID.unique(),
InputFile.fromPath(java.nio.file.Paths.get("./report.pdf")), null);
storage.getFileDownload("attachments", file.getId()); // 下载(重定向 / 响应)
storage.getFilePreview("attachments", file.getId(), 800); // 仅拼 URL,不发起认证请求
// InputFile 工厂:fromPath / fromFile / fromBytes;预览宽高 / 质量等参数见源码from agentbase.id import ID
from agentbase.input_file import InputFile
from agentbase.services.storage import Storage
storage = Storage(client)
uploaded = storage.create_file(bucket_id='attachments', file_id=ID.unique(),
file=InputFile.from_path('/path/to/report.pdf'))
download: bytes = storage.get_file_download(bucket_id='attachments', file_id=uploaded.id)
preview_url = storage.get_file_preview(bucket_id='attachments', file_id=uploaded.id,
width=800) # 仅拼 URL,不发起认证请求
# view / download 返回字节流;preview 需桶开启 transformationsstorage := agentbase.NewStorage(cl)
uploaded, err := storage.CreateFile("attachments", id.Unique(),
file.NewInputFile("./report.pdf", "report.pdf"))
download, err := storage.GetFileDownload("attachments", uploaded.Id) // *[]byte
// PreviewUrl:storage.GetFilePreview("attachments", uploaded.Id)(仅拼 URL,
// 宽高 / gravity / quality 等 option 见模块源码)
_ = downloadcurl -sS -X POST "$APPBASE_ENDPOINT/storage/buckets/app-assets/files" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-F fileId="unique()" \
-F 'permissions[]=read("users")' \
-F file="@./pink.png"
# 下载:GET /storage/buckets/{bucketId}/files/{fileId}/download(attachment)
# 内联查看:/view;图片预览:/preview?width=800&height=600(需桶开启 transformations)文件管理:listFiles / getFile / updateFile / deleteFile
listFiles 分页列出桶内文件,getFile 取元数据(不返回内容);updateFile 只更新元数据(文件名与权限,permissions 为全量替换,语义同 updateRow),文件内容不可变。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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>' });// 用户 Session:列出 / 元数据 / 删除自己有权操作的文件
const files = await storage.listFiles({ bucketId: 'attachments' });
const meta = await storage.getFile({ bucketId: 'attachments', fileId: '<fileId>' });
await storage.deleteFile({ bucketId: 'attachments', fileId: '<fileId>' });
// 改名 / 权限更新走服务端或 REST PUT(见 REST 页签;permissions 全量替换)var files = storage.listFiles("attachments", null, null); // queries / search
var meta = storage.getFile("attachments", "<fileId>"); // 元数据,不返回内容
storage.updateFile("attachments", "<fileId>", "report-updated.pdf",
null); // permissions 全量替换;不传则保留当前权限
storage.deleteFile("attachments", "<fileId>"); // 文件内容不可变files = storage.list_files(bucket_id='attachments') # 分页经 queries
meta = storage.get_file(bucket_id='attachments', file_id='<file_id>') # 元数据,不返回内容
storage.update_file(bucket_id='attachments', file_id='<file_id>',
name='report-updated.pdf') # permissions 全量替换;不传则保留
storage.delete_file(bucket_id='attachments', file_id='<file_id>')files, err := storage.ListFiles("attachments") // 分页经 WithListFilesQueries
meta, err := storage.GetFile("attachments", "<fileId>") // 元数据,不返回内容
_, err = storage.UpdateFile("attachments", "<fileId>",
storage.WithUpdateFileName("report-updated.pdf")) // permissions 全量替换;不传则保留
_, err = storage.DeleteFile("attachments", "<fileId>")
_, _ = files, meta# 列出文件(queries[] 分页;total=false 跳过计数降低开销)
curl -sS "$APPBASE_ENDPOINT/storage/buckets/attachments/files?queries[]=limit(25)&total=false" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 元数据:GET /storage/buckets/{bucketId}/files/{fileId}
# 改名 / 权限(全量替换,内容不可变):PUT
curl -sS -X PUT "$APPBASE_ENDPOINT/storage/buckets/attachments/files/<fileId>" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"name": "report-updated.pdf", "permissions": ["read(\"label:vip\")"]}'
# 删除:DELETE /storage/buckets/{bucketId}/files/{fileId}跨域 <img>:Blob URL(Web 专有)
跨域环境 <img src=".../preview?project=..."> 带不上 Session Cookie,fileSecurity 桶会以 404(file_not_found)拒绝——用 SDK 认证请求取字节流再转 Blob URL。
- Web(用户 Session)
// 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)File Token:无 Cookie 场景的短时访问
邮件链接、第三方、SSR 预览等带不了 Cookie 的场景,由服务端签发有时效令牌;secret 以 ?token= 拼到文件的 view / preview / download 端点。无 Web 页签:签发属服务端动作。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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>import io.agentbase.services.Tokens;
Tokens tokens = new Tokens(client);
var token = tokens.createFileToken("attachments", "<fileId>",
"2026-10-15T06:38:00.000+00:00"); // expire 可空;务必设短时效
// token 的 secret 拼到 /storage/buckets/attachments/files/<fileId>/view?token=<secret>
// 常用方法:createFileToken / list / get / update / deletefrom agentbase.services.tokens import Tokens # services 清单含 tokens 模块
tokens = Tokens(client)
token = tokens.create_file_token(bucket_id='attachments', file_id='<file_id>',
expire='2026-10-15T06:38:00.000+00:00') # 务必设短时效
# token.secret 拼到 /storage/buckets/attachments/files/<file_id>/view?token=<secret>
# 常用方法:create_file_token / list / get / update / deletetokens := agentbase.NewTokens(cl) // facade 构造器
token, err := tokens.CreateFileToken("attachments", "<fileId>",
tokens.WithCreateFileTokenExpire("2026-10-15T06:38:00.000+00:00")) // 务必设短时效
// token 的 secret 拼到 /storage/buckets/attachments/files/<fileId>/view?token=<secret>
// 常用方法:CreateFileToken / List / Get / Update / Delete
_ = tokencurl -sS -X POST "$APPBASE_ENDPOINT/tokens/buckets/attachments/files/<fileId>" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"expire": "2026-10-15T06:38:00.000+00:00"}'
# 响应含 secret(JWT 形态);拼 URL:/v1/storage/buckets/attachments/files/<fileId>/view?token=<secret>
# 列出文件名下令牌:GET /v1/tokens/buckets/{bucketId}/files/{fileId};吊销:DELETE /v1/tokens/{tokenId}用量(Console / 管理面口径)
对象存储总览与单桶的聚合用量走 Console SDK:管理面 Session / JWT,client 需指向应用项目并 setMode('admin');普通 Server SDK(API Key)不含这些聚合方法,故本卡无 Node 页签。
- Console(Node)
- REST(curl)
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 趋势数组curl -sS "$APPBASE_ENDPOINT/storage/usage?range=30d" \
-b "$APPBASE_CONSOLE_COOKIE" -H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
# 单桶:GET /storage/buckets/{bucketId}/usage?range=30d(range 枚举 24h / 30d / 90d)
# 关键返回字段:filesStorageTotal、storage 趋势事实源
skills/ob-agentbase/references/storage-permissions.mdskills/ob-agentbase/references/file-tokens.mdskills/ob-agentbase/references/console-sdk.md(存储用量口径)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
storage/tokensservice 面)