对象存储与静态资源
生成出来的图片、视频放在哪里,站点的静态素材从哪里加载。两件事都走 S3 兼容存储;我们自用的线上环境是 Cloudflare R2,但这不是硬依赖。
← 文档索引 · 相关:前置 Cloudflare · 环境变量
1. 谁在用,不配会怎样
| 使用者 | 配置项 | 不配的后果 |
|---|---|---|
mcp-vision、mcp-motion |
STORAGE_*(七个) |
生成结果返回模型提供方的临时 URL,几小时后失效——对话历史里的图片、视频变成裂图 |
thia-web |
staticCdnUrl + staticAssetVersion |
站点展示区的素材(首页 3D 形象、形象文档页、演示区)加载不到,退回 2D / 空白;登录、对话、控制台不受影响 |
**能上传的只有 mcp-vision 与 mcp-motion,读取全部走公开地址。**所以桶必须允许匿名读——
签名 URL 会过期,一个过期地址就等于一条死掉的历史消息。
2. 选一家
任何 S3 兼容存储都能用:Cloudflare R2、AWS S3、阿里云 OSS、腾讯云 COS、MinIO。STORAGE_*
描述的是「S3 协议怎么连」,不绑定厂商。
3. 以 Cloudflare R2 为例
- 建桶:控制台 → R2 → Create bucket,名字即
STORAGE_BUCKET。 - 开公开读取:桶默认是私有的。生产用自定义域(同一 Cloudflare 账户的域名,可接缓存与
WAF);
r2.dev开发域名有限流,只适合试装。 - 建 API Token:R2 → Manage R2 API Tokens,权限
Object Read & Write,拿到 Access Key ID 与 Secret Access Key。 - 填变量(
mcp-vision与mcp-motion各配一份):
| 变量 | R2 上填什么 |
|---|---|
STORAGE_ENDPOINT |
https://<account-id>.r2.cloudflarestorage.com |
STORAGE_REGION |
auto——R2 没有区域可选 |
STORAGE_BUCKET |
第 1 步的桶名 |
STORAGE_ACCESS_KEY_ID / STORAGE_SECRET_ACCESS_KEY |
第 3 步的 AK / SK,放 Secret |
STORAGE_PUBLIC_URL |
第 2 步的公开域前缀,无尾斜杠 |
STORAGE_ACL |
留空(见下) |
STORAGE_FORCE_PATH_STYLE |
false;MinIO 这类只支持 path-style 的实现填 true |
⚠️ **
STORAGE_ACL必须显式设成空字符串。**它的默认值是public-read,而 R2 不支持对象 ACL, 带着默认值上传会被拒绝——症状是每次生成都成功、上传那一步 500。公开与否由第 2 步的桶设置决定, 不靠对象 ACL。
其余厂商同理:端点、区域、桶名换成对方的,公开读取一般用桶策略而不是对象 ACL。
4. 站点素材(staticCdnUrl)
staticCdnUrl 指向桶(或任意静态站)的公开域,页面按 <prefix>/models/... 这样的路径取素材;
staticAssetVersion 是挂在地址后面的版本参数,改一次等于让 CDN 立刻换新。
素材不由镜像提供——public/ 里没有它们。没有素材就留空:展示区退化为 2D 或空白,功能不受影响。
5. 验证
# 1. 匿名读:应为 200,且不是 403 / 404
curl -sI "$STORAGE_PUBLIC_URL/<一个已上传的对象>" | head -3
# 2. 在对话里生成一张图,返回的地址应以 $STORAGE_PUBLIC_URL 开头(不是模型提供方的临时域名),
# 并且换一个浏览器无痕窗口打开仍然能显示