配置文件存储和上传
完成后,用户可以上传文件,并通过限时链接下载。文件保存在你自己的 S3 兼容存储桶或 R2 绑定中。
用户上传的文件和 AI 生成的媒体保存在同一个存储桶中。文件由服务端写入,浏览器不直接上传到存储桶,因此存储桶保持私有,也不需要 CORS 规则。存储在后台配置,不需要环境变量。
准备工作
- 拥有
config.read和config.write的管理员账号。 - 一个存储桶,或者应用运行在 Cloudflare Workers 上,且绑定了名为
BUCKET的 R2 存储桶。
按应用的运行环境选择驱动:
| 驱动 | 适用场景 | 需要准备 |
|---|---|---|
| S3 兼容端点 | 任意运行环境:Node、Docker、Cloudflare Workers。 | 存储桶和访问密钥。 |
| 平台原生绑定 | 应用运行在 Cloudflare Workers,且绑定了名为 BUCKET 的 R2 存储桶。 | 只需绑定,不需要密钥。 |
在存储服务商创建存储桶
| 厂商 | 适用场景 |
|---|---|
| Cloudflare R2 | Workers 原生绑定或兼容 S3 的端点 |
| Amazon S3 | 使用区域签名的 AWS 私有桶 |
| MinIO | 自托管对象存储 |
接入存储桶
创建存储桶和访问密钥
在供应商控制台创建存储桶,并创建一个能在该桶内读、写、删除对象的 API 密钥。
| 供应商 | 端点 | Region | 访问密钥 |
|---|---|---|---|
| Cloudflare R2 | https://<account-id>.r2.cloudflarestorage.com | auto | Cloudflare 控制台 → R2 → 管理 API 令牌,授予该桶的对象读写权限。 |
| AWS S3 | https://s3.<region>.amazonaws.com | 存储桶所在区域,例如 eu-west-1 | IAM 用户访问密钥,对该桶具有 s3:PutObject、s3:GetObject、s3:DeleteObject 权限。 |
| MinIO | 服务器的 API 地址,例如 http://minio.internal:9000 | 除非服务器另有设置,填 us-east-1 | MinIO 控制台 → Access Keys。 |
填写连接信息
进入 设置 → 存储配置(/admin/config/storage),勾选 启用上传,选择 S3 兼容端点,然后填写:
- 连接信息 → Bucket 名称:刚创建的存储桶。
- 连接信息 → Region:该厂商指南中的签名区域,默认
us-east-1。 - 连接信息 → S3 endpoint:该厂商的 S3 API 地址,不要带存储桶名称。
- 密钥配置 → Access Key ID 和 Secret Access Key:密钥对。
首次配置时,S3 选项在这些字段保存之前一直置灰,直接保存仍会使用它。
保存
点击 保存存储配置,页面提示 存储配置已保存。,运行状态 面板中 存储驱动 下的 读取方式 显示 sigv4。
每次打开页面时密钥字段都是空的,留空表示保留已保存的值。
设置限制和公开域名
限制文件大小
在 限制与 MIME 类型 中设置 最大文件字节数,默认 10485760(10 MB)。
限制文件类型
修改 图片 MIME 类型、视频 MIME 类型、音频 MIME 类型 和 文件 MIME 类型(用逗号分隔的内容类型)。默认值分别为 image/png, image/jpeg, image/webp, image/gif;video/mp4, video/webm;audio/mpeg, audio/wav, audio/ogg;application/pdf, text/plain。
添加公开域名(可选)
如果已有 CDN 或自定义域名能访问桶内对象,在 连接信息 → CDN 或公开访问域名 中填写基础地址,例如 https://assets.example.com。之后每次上传都会用这个域名加对象路径记录一条公开链接。应用不会把存储桶设为公开,之前上传的文件保留原来记录的链接。
保存
点击 保存存储配置。
取消勾选 启用上传 再保存,会关闭上传,但不会删除已保存的密钥。
通过 API 上传
用户在 /app/assets/upload 上传文件。脚本使用会话 Cookie 或带 上传文件 的 API Key。接口接受 multipart/form-data(file 字段)或 JSON(base64 字段)。不传 folderId 时文件存入用户的 /uploads 目录。
curl -X POST https://your-domain.example/api/assets/upload \
-H "Authorization: Bearer $API_KEY" \
-F "file=@./report.pdf" \
-F "resourceType=file"
# 201 => { "ok": true, "file": { "id": "file_...", "objectKey": "...", "publicUrl": null, ... } }每个用户有三个目录:/、/uploads 和存放 AI 产出的 /generated。上传到其他目录会被拒绝。签名下载链接最长 24 小时后过期。
尚未配置存储时
没有备用存储。上传会报 S3-compatible storage credentials are not configured.(/api/assets/upload 返回 HTTP 503),无法生成签名链接,/setup 中 对象存储 显示为未就绪。
验证
查看上传页面
以任意已登录用户打开 /app/assets/upload。驱动可用时标题旁的徽标显示 R2 已就绪(无论使用哪家供应商都显示这个文案),否则显示 存储未配置。
上传文件
选择 资源类型,选一个符合该类型白名单的 文件,点击 上传。表单显示 已上传 加文件名,失败时显示供应商返回的错误。
下载文件
在 /app/assets 中打开这个文件,点击 生成签名 URL。在新标签页打开按钮下方的 URL,文件可以正常加载。
查看后台
平台 → 资源(/admin/assets)中可以看到该文件及其所有者,/setup 中 对象存储 显示为就绪。
pnpm validate:files 会检查两种驱动的接入。pnpm validate:storage-drivers 会在你的存储桶中真实写入、读取和删除对象。
常见问题
上传返回 "Content type ... is not allowed"
文件类型不在所传资源类型的列表中。在 存储配置 对应的 MIME 列表中添加该类型,或传入正确的资源类型。
上传返回 "Folder does not exist"
目录 ID 不是调用者自己的目录。在 /api/assets/upload 中省略 folderId,文件会存入 /uploads。
S3 上传报 "Storage upload failed (403)"
错误中带有供应商自己的错误码和信息。检查 Access Key、Secret、存储桶名称,以及 Region 是否与端点的签名要求一致。
绑定驱动的签名链接返回 503
指向你站点的链接只在选中绑定驱动且存在 BUCKET 绑定时返回文件。切换驱动前签发的链接无法使用,请重新生成。