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://your-account-id.r2.cloudflarestorage.com
Bucket: your-r2-bucket-name
Region: auto
Access Key ID: copied from the Cloudflare R2 API token
Secret Access Key: copied from the 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://your-account-id.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. 當前服務是否需要開啟路徑風格。

一句話流程速查

Prepare S3 Endpoint, Bucket, Region, Access Key, and Secret Key
-> Open Upload Settings
-> Add Channel
-> Select S3
-> Enter Endpoint / Bucket / Region / Access Key / Secret Key
-> Enter a CDN domain if needed
-> Leave path-style access off by default
-> Enable quota limit if needed
-> Save
-> Upload a test image and check the result