S3 渠道添加说明

适合什么场景

• 你要接入支持 S3 协议的对象存储，例如 Cloudflare R2、Backblaze B2、MinIO、AWS S3 或其他兼容服务。
• 你希望用 Endpoint、Access Key、Secret Key 这一套标准 S3 参数来上传文件。
• 你不想使用 Cloudflare 原生 R2 绑定渠道，或者你的存储服务本身不是 Cloudflare R2 绑定。

添加前要准备什么

需要准备	用途
S3 Endpoint	对象存储的 S3 API 地址
Bucket 名称	文件实际保存的桶
Region	存储区域；Cloudflare R2 通常填 auto
Access Key ID	S3 访问密钥 ID
Secret Access Key	S3 机密访问密钥
CDN 域名	可选，用于自定义文件访问域名

以 Cloudflare R2 的 S3 API 为例：

Endpoint: https://你的AccountID.r2.cloudflarestorage.com
Bucket: 你的R2桶名
Region: auto
Access Key ID: 从 Cloudflare R2 API Token 里复制
Secret Access Key: 从 Cloudflare R2 API Token 里复制

入口位置

1. 进入系统配置。
2. 打开上传设置。
3. 点击右上角“添加渠道”。
4. 选择 S3。

字段说明

字段	作用	是否必填
渠道名称	用来区分当前 S3 渠道，例如 s3test、R2-S3	是
启用渠道	控制这个渠道是否参与上传选择	建议开启
Endpoint	S3 服务地址，需要填写完整 https:// 地址	是
自定义 CDN 域名	可选。填写后，读取文件时优先按这个域名生成访问地址	否
存储桶名称	Bucket 名称，例如 s3test、img-r2	是
存储桶区域	Region。Cloudflare R2 通常填 auto	是
访问密钥 ID	Access Key ID	是
机密访问密钥	Secret Access Key	是
路径风格	兼容开关，默认关闭；部分 MinIO、OpenList 或自建 S3 服务可能需要开启	否
容量限制	控制这个 S3 渠道是否按容量阈值参与上传选择	否
容量上限	开启容量限制后填写，例如 10 GB	开启容量限制时填写
阈值	达到多少比例后不再继续写入，例如 90%	开启容量限制时填写
备注	方便自己记录用途	否

用 Cloudflare R2 的 S3 API 创建密钥

1. 打开 Cloudflare Dashboard。
2. 进入 R2 Object Storage。
3. 找到 Manage R2 API Tokens 或 API Token 管理入口。


4. 创建一个允许访问目标 Bucket 的 R2 API Token。

5. 复制生成的 Access Key ID 和 Secret Access Key。

6. 回到 R2 Bucket 页面，确认 Bucket 名称。
7. 记录当前账号的 S3 API 地址，格式通常是：

https://你的AccountID.r2.cloudflarestorage.com

添加步骤

1. 打开上传设置页面。
2. 点击“添加渠道”。
3. 选择 S3。
4. 渠道名称填一个自己能看懂的名字，例如 s3test。
5. Endpoint 填 S3 API 地址。
6. 如果有自定义 CDN，就填写 自定义 CDN 域名；没有就留空。
7. 存储桶名称 填 Bucket 名称。
8. 存储桶区域 填 Region。Cloudflare R2 示例里填 auto。
9. 填写 访问密钥 ID 和 机密访问密钥。
10. 路径风格 默认关闭；只有当前服务明确要求 path-style 时再打开。
11. 如果要控制容量，就打开容量限制，填写容量上限和阈值。
12. 点击保存。

添加完成后怎么检查

检查项	检查方式
渠道卡片是否出现	保存后，上传设置页面应显示 S3 渠道卡片
渠道是否启用	卡片右上角开关应保持开启
关键字段是否保存	详情页能看到 Endpoint、Bucket、Region、路径风格等信息
上传是否正常	上传一张测试图片，确认对象已进入目标 Bucket
链接是否能打开	上传返回的图片链接能正常访问
容量显示是否正常	开启容量限制后，卡片应显示已用容量和上限

S3 容量统计不是去对象存储官方接口实时查桶，而是按图床本地文件记录重新计算。保存 S3 配置后，系统会按当前 D1 记录重算一次容量账。

常见问题

路径风格要不要打开？

默认不要打开。

只有当前 S3 兼容服务不支持虚拟主机风格地址，或者服务商文档明确要求 path-style 时再打开。部分 MinIO、自建 S3、OpenList 兼容接口可能需要开启。

CDN 域名有什么用？

如果你给 Bucket 前面接了自己的 CDN 或自定义访问域名，可以填这里。

填写后，系统生成访问链接时会优先使用这个域名。没有 CDN 就留空。

为什么上传失败？

优先检查：

1. Endpoint 是否完整包含 https://。
2. Bucket 名称是否写对。
3. Region 是否符合服务商要求。
4. Access Key ID 和 Secret Access Key 是否复制完整。
5. 当前密钥是否有目标 Bucket 的写入权限。
6. 当前服务是否需要开启路径风格。

一句话流程速查

准备 S3 Endpoint、Bucket、Region、Access Key、Secret Key
-> 打开上传设置
-> 添加渠道
-> 选择 S3
-> 填写 Endpoint / Bucket / Region / Access Key / Secret Key
-> 按需填写 CDN 域名
-> 默认关闭路径风格
-> 按需开启容量限制
-> 保存
-> 上传测试图片检查结果