关于：用户自带七牛云和 Cloudflare R2 存储使用教程

更新时间：2026-05-26 目前所有用户组都开放了：自带储存，你可以把自己的七牛云或 Cloudflare R2 接入平台。开启后，你上传的参考图和生成完成后的图片、视频会保存到你自己的云存储里，方便你长期管理、下载和迁移。 入口： 用户中心 -> 我的存储 ## 1. 开启前先了解 自带存储开启后： - 平台会使用你填写的密钥，把参考图和生成结果上传到你的七牛云或 R2。 - 密钥只会在服务器端用于上传，页面不会公开显示完整密钥。 - 你需要保证 Bucket 可以通过“访问域名”公开读取文件，否则生成结果可能无法正常预览或下载。 - 只是添加存储配置不会自动生效，必须在“存储使用方式”里勾选“使用我的存储覆盖平台存储”。 不适合自带存储的情况： - 你还没有七牛云或 Cloudflare 账号。 - 你不会配置 Bucket 的公开访问域名。 - 你只想正常生成图片，不想自己管理云存储。此时继续使用平台默认存储即可。 ## 2. 页面字段怎么填 在“添加我的存储”里会看到这些字段： | 字段 | 说明 | |---|---| | 存储类型 | 选择 `七牛云` 或 `Cloudflare R2` | | 配置名称 | 给自己看的名字，例如 `我的七牛云`、`我的 R2` | | Access Key / Access Key ID | 云存储提供的访问密钥 ID | | Secret Key / Secret Access Key | 云存储提供的访问密钥密码 | | Bucket | 存储空间名称 | | 区域 / Region | 七牛云必填，例如 `z0`；R2 可填 `auto` 或留空 | | Endpoint | R2 必填；七牛云通常留空 | | 访问域名 | 用来公开访问文件的域名，例如 `https://img.example.com` | | 目录前缀 | 可留空；也可填 `kuyu`，用于把平台文件放到单独目录下 | | 启用 | 勾选后，这条配置才可被使用 | 平台保存文件时会生成类似这样的路径： uploads/references/2026/05/xxx.png uploads/results/2026/05/xxx.mp4 如果你填写了目录前缀 `kuyu`，实际路径会变成： kuyu/uploads/results/2026/05/xxx.png 最终访问地址就是： 访问域名 + "/" + 文件路径 所以“访问域名”必须能访问到同一个 Bucket 里的文件。 ## 3. 七牛云使用教程 ### 3.1 准备七牛云空间 1. 登录七牛云控制台。 2. 进入对象存储 Kodo。 3. 新建一个空间 Bucket。 4. 访问控制建议选择公开空间。 5. 绑定一个可访问的域名，并开启 HTTPS。测试时可以先用七牛提供的临时域名，但正式使用建议绑定自己的域名。 常用区域代码： | 七牛云区域 | Region 填写 | |---|---| | 华东-浙江 | `z0` | | 华北-河北 | `z1` | | 华南-广东 | `z2` | | 北美-洛杉矶 | `na0` | | 亚太-新加坡 | `as0` | | 华东-浙江2 | `cn-east-2` | | 亚太-河内 | `ap-southeast-2` | | 亚太-胡志明 | `ap-southeast-3` | 如果你不知道选哪个区域，按你的主要访问用户所在地选择。中国内地用户通常选华东、华北或华南；海外用户可考虑新加坡或北美。 ### 3.2 获取七牛云密钥 1. 进入七牛云账号的密钥管理页面。 2. 找到 `Access Key` 和 `Secret Key`。 3. 不要把 Secret Key 发给别人，也不要截图公开。 ### 3.3 在平台里填写七牛云 在“用户中心 -> 我的存储 -> 添加我的存储”里填写： 存储类型：七牛云 配置名称：我的七牛云 Access Key / Access Key ID：七牛 Access Key Secret Key / Secret Access Key：七牛 Secret Key Bucket：你的七牛空间名 区域 / Region：z0 Endpoint：留空 访问域名：https://你的七牛访问域名 目录前缀：可留空，或填 kuyu 启用：勾选 填完后先点“测试连接”。测试成功后，再点“保存存储配置”。 ## 4. Cloudflare R2 使用教程 ### 4.1 准备 R2 Bucket 1. 登录 Cloudflare Dashboard。 2. 进入 R2。 3. 新建一个 Bucket。 4. 记录你的 Cloudflare Account ID。 5. 给这个 Bucket 绑定自定义域名，或开启公开的 `r2.dev` 访问域名。正式使用建议绑定自己的域名。 R2 需要区分两个地址： | 地址 | 用途 | 示例 | |---|---|---| | Endpoint | 平台服务器上传文件用 | `https://<ACCOUNT_ID>.r2.cloudflarestorage.com` | | 访问域名 | 浏览器打开图片/视频用 | `https://assets.example.com` | 不要把自定义访问域名填到 Endpoint 里。Endpoint 必须是 `r2.cloudflarestorage.com` 这个上传接口地址。 ### 4.2 创建 R2 API 密钥 1. 在 Cloudflare R2 的 API Tokens / 管理 API 令牌页面创建 R2 访问密钥。 2. 权限至少需要允许写入目标 Bucket。 3. 创建后保存 `Access Key ID` 和 `Secret Access Key`。Secret 通常只显示一次。 ### 4.3 在平台里填写 R2 在“用户中心 -> 我的存储 -> 添加我的存储”里填写： 存储类型：Cloudflare R2 配置名称：我的 R2 Access Key / Access Key ID：R2 Access Key ID Secret Key / Secret Access Key：R2 Secret Access Key Bucket：你的 R2 Bucket 名称 区域 / Region：auto Endpoint：https://<ACCOUNT_ID>.r2.cloudflarestorage.com 访问域名：https://你的 R2 访问域名 目录前缀：可留空，或填 kuyu 启用：勾选 填完后先点“测试连接”。测试成功后，再点“保存存储配置”。 ## 5. 正式启用我的存储 保存配置后，还需要打开“存储使用方式”： 1. 在“用户中心 -> 我的存储”左侧找到“存储使用方式”。 2. 勾选“使用我的存储覆盖平台存储”。 3. 点击“保存使用方式”。 4. 页面显示当前为“我的存储”后，后续新上传参考图和新生成结果才会进入你的七牛云或 R2。 注意： - 已经生成过的旧文件不会自动迁移到你的云存储。 - 如果取消勾选，会恢复为用户组默认存储。 - 如果你保存了多个存储配置，系统会优先使用已启用的配置。 ## 6. 测试连接失败怎么办 ### 提示“上传成功，但访问域名无法读取测试文件” 说明平台已经把文件传到你的 Bucket，但浏览器打不开这个文件。请检查： - Bucket 是否允许公开读取。 - 访问域名是否绑定到了同一个 Bucket。 - 域名 DNS、CNAME、HTTPS 证书是否生效。 - 是否填写了目录前缀，导致文件路径多了一层目录。 - R2 自定义域名是否已绑定到目标 Bucket。 ### 七牛云上传失败 请检查： - Region 是否填对，例如 `z0`、`z1`、`z2`、`as0`。 - Bucket 是否真的在这个区域。 - Access Key 和 Secret Key 是否复制完整。 - Endpoint 是否误填。七牛云通常留空即可。 - 七牛空间是否为公开空间，访问域名是否可用。 ### R2 返回 403 或签名错误 请检查： - Endpoint 是否为 `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`。 - Region 是否填写 `auto` 或留空。 - Bucket 名称是否正确。 - Access Key ID 和 Secret Access Key 是否来自 R2。 - API Token 是否有目标 Bucket 的写入权限。 ### R2 上传成功但访问 404 请检查： - 自定义访问域名是否绑定到了同一个 R2 Bucket。 - 是否把 Endpoint 当成访问域名填写了。 - 文件是否在 `目录前缀/uploads/...` 路径下。 - Cloudflare 域名和 SSL 状态是否已经生效。 ## 7. 使用建议 - 建议单独新建一个 Bucket 给平台使用，不要和其他网站文件混在一起。 - 建议填写目录前缀，例如 `kuyu`，以后更容易管理和清理。 - 建议开启云存储的生命周期规则，定期清理旧文件，避免长期占用空间。 - 不要关闭 Bucket 的公开读取，除非平台后续支持私有文件签名访问。 - 不要删除正在使用的 Access Key。删除后，平台将无法继续上传到你的存储。 - 修改密钥后，需要回到“我的存储配置”里更新并重新测试。 ## 8. 一句话检查清单 正式启用前确认这几项： - 已创建 Bucket。 - 已获得 Access Key 和 Secret Key。 - 七牛云已填写正确 Region；R2 已填写正确 Endpoint。 - 已配置能公开访问文件的访问域名。 - “测试连接”成功。 - “使用我的存储覆盖平台存储”已勾选并保存。 ## 9. 官方参考 - 七牛云 Kodo Node.js SDK：<https://developer.qiniu.com/kodo/sdk/nodejs> - 七牛云上传凭证：<https://developer.qiniu.com/kodo/1208/upload-token> - 七牛云存储区域和访问域名：<https://developer.qiniu.com/kodo/1671/region-endpoint-fq> - Cloudflare R2 S3 API 兼容说明：<https://developers.cloudflare.com/r2/api/s3/api/> - Cloudflare R2 公开 Bucket 和自定义域名：<https://developers.cloudflare.com/r2/buckets/public-buckets/> -【白嫖 Cloudflare】之免费图床搭建：PicGo + Cloudflare R2，手把手教<https://developer.volcengine.com/articles/7535311242543267866>