存储
Storage 提供文件上传、存储桶(Bucket)管理与文件访问控制,并在上传路径上接入内容安全审核。入口:项目侧栏 Storage,页面两个页签:Buckets / Usage。
创建存储桶
截图未公开:上游原图包含真实账号或资源标识。
- Buckets 页签点击 Create bucket;桶数达到套餐上限时按钮禁用。
- 弹窗只有两个字段:Name(必填,最长 128 字符)与可选的 Bucket ID(点击标签展开自定义输入:
a-z A-Z 0-9、句点、连字符、下划线,≤36 字符;缺省自动生成)。 - 成功后跳转到桶详情页。
创建后的默认值(服务端默认,可在桶 Settings 中修改):
| 属性 | 默认 | 说明 |
|---|---|---|
| Enabled | 开 | 关闭后终端用户无法访问文件;持有 API Key 的 Server SDK 仍可访问,文件不丢失 |
| File security | 关 | 关闭时仅桶级权限生效(见下文「文件详情与文件令牌」) |
| Permissions | 无 | 创建时不授予任何权限;需在 Settings 中添加 |
| Maximum file size | 套餐单文件上限 | 以套餐 fileSize 或部署环境变量为准;0 表示不限 |
| Allowed file extensions | 空(全部允许) | 最多 100 条 |
| Compression | none | 可选 none / gzip / zstd |
| Encryption | 开 | 大文件跳过加密 |
| Antivirus | 开 | 大文件跳过扫描 |
桶与桶设置
桶详情页页签:Files / Usage / Moderation / Settings(无写权限时 Settings 隐藏)。
桶设置(Settings)
Settings 页逐卡修改并保存:
| 卡片 | 字段与规则 |
|---|---|
| Enabled | 桶启用开关;关闭后终端用户无法访问文件,Server SDK(带 API Key)不受影响,不删除数据 |
| Name | 桶名,必填,最长 128 字符 |
| Permissions | 桶级权限编辑器:为角色添加 read / write 权限;角色可选 Any、All guests、All users、Guests、Users、指定 User、Team + 角色、Label、自定义 user:{id} / team:{id}/{role};支持在编辑器内创建新角色 |
| File security | 文件级安全开关,语义与风险见下节 |
| Security settings | Encryption 加密开关(大文件不加密);Antivirus 杀毒扫描开关(大文件跳过扫描) |
| Compression | 算法下拉:None / Gzip / Zstd;大文件跳过压缩 |
| Image transformations | 允许通过 API 对图片做缩放 / 裁剪 / 格式转换 |
| Maximum file size | 数值 + 单位(Bytes,1000 进制)。上限受套餐 fileSize 约束,超出显示套餐提示与 Upgrade plan。固定说明:"This does not set the total storage capacity for the project."(这里不是项目总容量) |
| Allowed file extension | 扩展名标签输入(快捷项 jpg / png / svg / gif / html / pdf / mp4),最多 100 条;留空允许全部类型 |
| Client file listing | 允许客户端列出文件开关(默认开)。关闭后,仅授权的管理客户端(Server SDK / 项目 API Key)可列出桶内文件;上传权限与公开文件链接访问不受影响 |
File security 语义(重要)
- 关闭:用户必须持有桶级权限才能访问文件;文件级权限被忽略。文案原文:"If file security is disabled, users can access files only if they have Bucket permissions. File permissions will be ignored."
- 开启:用户持有桶级权限或该文件的文件级权限之一即可访问;上传页与文件详情页会出现文件级权限编辑器。
- 切换开关立即作用于桶内全部文件的鉴权路径:关闭后,仅靠文件级权限访问的用户会立即失去访问;开启后,原来只能靠桶权限的访问方式保持不变。
删除桶
Settings 底部 Delete bucket:桶与桶内全部文件永久删除,不可恢复;确认框需确认桶名。删除桶不可恢复。
桶级内容审核(Moderation)
- 桶详情 Moderation 页签配置图片内容审核;开启后对该桶上传的图片执行审核。
fail closed 边界(上传拒绝即清理)
- 图片超过审核大小限制、读取失败或审核服务不可用时,本次上传被拒绝并清理已上传内容,不会留下未审核内容。
- 审核日志只使用文件名预览,不记录原始图片字节或 Base64 内容。
文件列表开关(Client file listing)
截图未公开:上游原图包含真实账号或资源标识。
桶 Settings 的 Client file listing 卡控制客户端能否列出桶内文件:
- 默认开启:持有相应权限的客户端可列出桶内文件(同现状)。
- 关闭:应用客户端与匿名请求无法枚举文件列表,只有持 API Key 的 Server SDK / 管理客户端可以列文件;上传与公开文件链接(含文件令牌)访问的权限不受此开关影响。
- 适合「只允许写入与按链接取用、不允许枚举」的桶(如用户上传收集类场景)。
文件列表与上传
文件列表(Files)
- 列:Filename / Type / Size / Created,文件名带缩略图;行内菜单提供 Update(进入详情)与 Delete。
- 分块上传未完成的文件显示
Pending徽标且不可进入详情。 - 支持搜索、勾选批量删除(不可逆)与分页。
上传(Create file)
- Files 页签点击 Create file,进入独立上传向导页(
/storage/bucket-{bucketId}/create)。 - Data 区:拖放或点击选择文件(一次一个文件);可选自定义 File ID。客户端只校验扩展名(与桶 Allowed file extension 比对);文件大小由服务端强制校验,超限在上传时被拒绝。
- Permissions 区:
- 桶开启 fileSecurity 时显示 "File security enabled":可为本文件添加文件级权限(授予文件或桶权限之一的用户即可访问)。
- 未开启时显示 "File security disabled":如需文件级权限,先到桶 Settings 开启 fileSecurity;否则仅桶权限生效。
- 提交后立即返回列表并提示 "File upload in progress";上传进行中离开页面会有浏览器拦截确认。上传失败(含内容审核拒绝)会显示具体错误。
文件详情与文件令牌
文件详情页位于 /storage/bucket-{bucketId}/file-{fileId}。
文件详情
- 预览:页头缩略图;点击在新窗口打开原文件。
- 元数据:Filename、MIME type、Size、Created、Updated。
- File URL:可复制的文件访问 URL;Download 按钮下载原文件。
- 文件级权限:桶开启 fileSecurity 时可编辑本文件的权限(角色格式同桶权限)。
- 重命名:当前版本 Console 不提供文件改名入口(源码事实:文件名仅在上传时确定)。
- Delete file:文件永久删除,不可恢复;确认框需确认文件名。
权限与 fileSecurity 的关系
| 桶 fileSecurity | 访问条件 |
|---|---|
| 关闭 | 仅桶级权限生效;文件级权限被忽略 |
| 开启 | 桶级权限或该文件的文件级权限,满足其一即可访问 |
- 上传时即可为文件赋权限;之后可在文件详情页调整。
- 文件的查看 / 预览 / 下载端点在鉴权失败时,若请求携带有效文件令牌仍可放行(见下节)。
文件令牌(File tokens)
令牌用于把私有文件以带密钥的 URL 提供给无权限的访问者。文件详情页的 File tokens 卡片管理(说明原文:"Use tokens to provide public access to the file.")。
创建与编辑:
- 点击 Create token。
- 选择过期时间,预设:Never / 7 Days / 30 days / 90 days / 1 Year / Custom Date(自定义日期最早为明天)。缺省为永不过期。
- 令牌列表列:Created / Expiration / Last accessed 及操作;无过期显示
Never,过期显示红色Expired,14 天内到期显示Expires soon。 - 行操作:Copy URL、Edit expiry(改过期时间)、Delete。
使用(Copy URL):
- Copy File URL 弹窗提供三个标签:Preview / View / Download,URL 形如
…/files/{fileId}/view?...&token={secret}。 - 无过期时间的令牌会显示警示:"This token doesn't expire. Be cautious when sharing links."
- 失效边界:删除令牌后对应 URL 立即失效;令牌过期后同样失效。修改桶 fileSecurity 对令牌有效性没有源码依据,不应作为失效手段。
保管语义(如实说明):
- 令牌 secret 不是「仅显示一次」:创建后的列表响应中始终包含(以签名 JWT 形式下发),持 Console 读权限的成员可再次复制。按共享密钥对待:只发给应能访问该文件的人,发现泄露立即删除令牌。
- 令牌的 Last accessed 粒度最多每 24 小时更新一次。
Usage 页签
- Storage 顶层 Usage:Total buckets 桶数趋势(默认近 30 天)。
- 桶级 Usage:Total files 与 Total transformations 累计图表。按桶的字节容量不在此展示;项目级用量聚合见项目侧栏 Metering(见界面与路由速查)。