افزودن S3 Channel

چه زمانی مناسب است

S3 channel را زمانی استفاده کنید که:

• می‌خواهید هر سرویس object storage سازگار با S3 را وصل کنید؛ مثل Cloudflare R2، Backblaze B2، MinIO، AWS S3 یا provider سازگار دیگر.
• مدل استاندارد S3 را ترجیح می‌دهید: Endpoint، Access Key و Secret Key.
• نمی‌خواهید از native Cloudflare R2 binding channel استفاده کنید، یا storage provider شما Cloudflare R2 نیست.

پیش از شروع چه چیزهایی لازم است

مورد	کاربرد
S3 Endpoint	endpoint مربوط به S3 API سرویس object storage.
Bucket name	bucket که files در آن ذخیره می‌شوند.
Region	storage region. برای Cloudflare R2 معمولاً auto است.
Access Key ID	S3 access key ID.
Secret Access Key	S3 secret access key.
CDN domain	custom domain اختیاری برای دسترسی به files.

نمونه برای 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. System Settings را باز کنید.
2. وارد Upload Settings شوید.
3. از گوشه بالا سمت راست Add Channel را بزنید.
4. S3 را انتخاب کنید.

Field Reference

Field	کاربرد	Required
Channel name	نام قابل‌تشخیص برای این S3 channel، مثل s3test یا R2-S3.	Yes
Enable channel	مشخص می‌کند این channel در upload selection شرکت کند یا نه.	Recommended
Endpoint	endpoint کامل S3 service همراه https://.	Yes
Custom CDN domain	اختیاری. اگر تنظیم شود، generated file links این domain را ترجیح می‌دهند.	No
Bucket name	bucket name، مثل s3test یا img-r2.	Yes
Bucket region	Region. برای Cloudflare R2 معمولاً auto.	Yes
Access Key ID	S3 access key ID.	Yes
Secret Access Key	S3 secret access key.	Yes
Path-style access	compatibility switch. پیش‌فرض off است. بعضی MinIO، OpenList یا self-hosted S3 services ممکن است به آن نیاز داشته باشند.	No
Quota limit	مشخص می‌کند این S3 channel بر اساس capacity در upload selection شرکت کند یا نه.	No
Capacity limit	پس از enable شدن quota limit لازم است، مثل 10 GB.	Required when quota limit is enabled
Threshold	وقتی usage به این درصد رسید، نوشتن متوقف می‌شود، مثل 90%.	Required when quota limit is enabled
Remark	یادداشت برای نگهداری خودتان.	No

ساخت Cloudflare R2 S3 API Keys

1. Cloudflare Dashboard را باز کنید.
2. به R2 Object Storage بروید.
3. Manage R2 API Tokens یا entry مدیریت API token را پیدا کنید.


4. یک R2 API token بسازید که به target bucket دسترسی داشته باشد.

5. Access Key ID و Secret Access Key ساخته‌شده را copy کنید.

6. به صفحه R2 bucket برگردید و bucket name را confirm کنید.
7. S3 API endpoint مربوط به account را یادداشت کنید. معمولاً شبیه این است:

https://your-account-id.r2.cloudflarestorage.com

مراحل setup

1. Upload Settings را باز کنید.
2. Add Channel را بزنید.
3. S3 را انتخاب کنید.
4. یک channel name قابل‌تشخیص وارد کنید، مثل s3test.
5. S3 API endpoint را در Endpoint وارد کنید.
6. اگر custom CDN دارید، آن را در Custom CDN domain وارد کنید؛ در غیر این صورت خالی بگذارید.
7. bucket name را وارد کنید.
8. region را وارد کنید. برای مثال Cloudflare R2 از auto استفاده کنید.
9. Access Key ID و Secret Access Key را وارد کنید.
10. path-style access را off نگه دارید، مگر اینکه provider صریحاً آن را لازم بداند.
11. اگر capacity control می‌خواهید، quota limit را enable کنید و capacity limit و threshold را وارد کنید.
12. Save را بزنید.

روش بررسی

Check	روش بررسی
Channel card appears	پس از Save، Upload Settings باید S3 channel card را نشان دهد.
Channel is enabled	switch بالای card باید روشن بماند.
Key fields are saved	detail view باید Endpoint، Bucket، Region، path-style access و fields مربوطه را نشان دهد.
Upload works	یک test image upload کنید و مطمئن شوید object در target bucket ایجاد شده است.
Link opens	image link برگشتی پس از upload باید عادی باز شود.
Capacity display works	اگر quota limit enabled باشد، card باید used capacity و configured limit را نشان دهد.

آمار capacity در S3 از local file records داخل ImgBed محاسبه می‌شود، نه از query لحظه‌ای provider bucket. پس از save کردن S3 configuration، system quota ledger را از current D1 records دوباره محاسبه می‌کند.

FAQ

آیا path-style access را enable کنم؟

معمولاً نه.

فقط وقتی enable کنید که provider سازگار با S3 شما virtual-hosted-style URLs را پشتیبانی نمی‌کند، یا documentation provider صریحاً path-style access را لازم می‌داند.

CDN domain برای چیست؟

اگر جلوی bucket یک CDN یا custom access domain گذاشته‌اید، آن را اینجا وارد کنید.

پس از تنظیم، generated file links این domain را ترجیح می‌دهند. اگر CDN ندارید، خالی بگذارید.

چرا upload fail می‌شود؟

اول این موارد را بررسی کنید:

1. Endpoint شامل URL کامل https:// باشد.
2. bucket name درست باشد.
3. Region با requirement provider هماهنگ باشد.
4. Access Key ID و Secret Access Key کامل copy شده باشند.
5. key برای target bucket دسترسی write داشته باشد.
6. provider به path-style access نیاز نداشته باشد، یا اگر نیاز دارد، path-style access enabled باشد.

Quick Checklist

S3 Endpoint, Bucket, Region, Access Key و Secret Key را آماده کنید
-> Upload Settings را باز کنید
-> Add Channel
-> S3 را انتخاب کنید
-> Endpoint / Bucket / Region / Access Key / Secret Key را وارد کنید
-> در صورت نیاز CDN domain وارد کنید
-> path-style access را پیش‌فرض off بگذارید
-> در صورت نیاز quota limit را enable کنید
-> Save
-> یک test image upload کنید و نتیجه را بررسی کنید