Thêm S3 Channel

Phù hợp nhất khi nào

Dùng S3 channel khi:

• Bạn muốn kết nối object storage service tương thích S3, như Cloudflare R2, Backblaze B2, MinIO, AWS S3 hoặc provider tương thích khác.
• Bạn thích mô hình cấu hình S3 chuẩn: Endpoint, Access Key và Secret Key.
• Bạn không muốn dùng native Cloudflare R2 binding channel, hoặc storage provider của bạn không phải Cloudflare R2.

Cần chuẩn bị gì trước khi bắt đầu

Requirement	Purpose
S3 Endpoint	S3 API endpoint của object storage service.
Bucket name	Bucket dùng để lưu files.
Region	Storage region. Với Cloudflare R2 thường là auto.
Access Key ID	S3 access key ID.
Secret Access Key	S3 secret access key.
CDN domain	Custom domain tùy chọn cho file access.

Ví dụ Cloudflare R2 qua 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

Thêm ở đâu

1. Mở System Settings.
2. Vào Upload Settings.
3. Nhấn Add Channel ở góc trên bên phải.
4. Chọn S3.

Field Reference

Field	Tác dụng	Required
Channel name	Tên dễ nhận biết cho S3 channel, ví dụ s3test hoặc R2-S3.	Yes
Enable channel	Kiểm soát channel này có tham gia upload selection hay không.	Recommended
Endpoint	Full S3 service endpoint, bao gồm https://.	Yes
Custom CDN domain	Optional. Khi đặt, generated file links sẽ ưu tiên domain này.	No
Bucket name	Bucket name, ví dụ s3test hoặc img-r2.	Yes
Bucket region	Region. Với Cloudflare R2 thường là auto.	Yes
Access Key ID	S3 access key ID.	Yes
Secret Access Key	S3 secret access key.	Yes
Path-style access	Compatibility switch. Mặc định off. Một số MinIO, OpenList hoặc self-hosted S3 service có thể cần.	No
Quota limit	Kiểm soát S3 channel này có tham gia upload selection theo capacity hay không.	No
Capacity limit	Required sau khi bật quota limit, ví dụ 10 GB.	Required khi bật quota limit
Threshold	Dừng ghi khi usage đạt percentage này, ví dụ 90%.	Required khi bật quota limit
Remark	Ghi chú để tự bảo trì.	No

Tạo Cloudflare R2 S3 API Keys

1. Mở Cloudflare Dashboard.
2. Vào R2 Object Storage.
3. Tìm Manage R2 API Tokens hoặc mục quản lý API token.


4. Tạo R2 API token có quyền access target bucket.

5. Copy Access Key ID và Secret Access Key được tạo.

6. Quay lại trang R2 bucket và xác nhận bucket name.
7. Ghi lại S3 API endpoint của account. Thường có dạng:

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

Các bước thiết lập

1. Mở Upload Settings.
2. Nhấn Add Channel.
3. Chọn S3.
4. Nhập channel name dễ nhận biết, ví dụ s3test.
5. Nhập S3 API endpoint trong Endpoint.
6. Nếu dùng custom CDN, nhập trong Custom CDN domain; nếu không thì để trống.
7. Nhập bucket name.
8. Nhập region. Với ví dụ Cloudflare R2, dùng auto.
9. Nhập Access Key ID và Secret Access Key.
10. Giữ path-style access ở off trừ khi provider yêu cầu rõ.
11. Nếu muốn capacity control, bật quota limit rồi nhập capacity limit và threshold.
12. Nhấn Save.

Cách kiểm tra

Check	Cách kiểm tra
Channel card xuất hiện	Sau khi save, trang Upload Settings cần hiển thị S3 channel card.
Channel enabled	Switch ở góc trên bên phải card nên ở trạng thái on.
Key fields đã lưu	Detail view cần hiển thị Endpoint, Bucket, Region, path-style access và các field liên quan.
Upload hoạt động	Upload test image và xác nhận object xuất hiện trong target bucket.
Link mở được	Image link trả về sau upload cần mở bình thường.
Capacity display hoạt động	Nếu bật quota limit, card cần hiển thị used capacity và configured limit.

S3 capacity statistics được tính từ local file records của ImgBed, không query provider bucket theo real time. Sau khi save S3 configuration, system sẽ recalculate quota ledger từ current D1 records.

FAQ

Có nên bật path-style access không?

Thường là không.

Chỉ bật khi S3-compatible provider không hỗ trợ virtual-hosted-style URLs, hoặc provider documentation yêu cầu path-style access rõ ràng. Một số MinIO, self-hosted S3 và OpenList-compatible endpoints có thể cần.

CDN domain dùng để làm gì?

Nếu bạn đặt CDN hoặc custom access domain trước bucket, nhập domain đó ở đây.

Sau khi cấu hình, generated file links sẽ ưu tiên domain này. Nếu không dùng CDN, để trống.

Vì sao upload fail?

Kiểm tra các mục này trước:

1. Endpoint là full https:// URL.
2. Bucket name chính xác.
3. Region khớp với yêu cầu của provider.
4. Access Key ID và Secret Access Key được copy đầy đủ.
5. Key có write permission cho target bucket.
6. Provider không yêu cầu path-style access, hoặc đã bật path-style access nếu cần.

Quick Checklist

Chuẩn bị S3 Endpoint, Bucket, Region, Access Key và Secret Key
-> Mở Upload Settings
-> Add Channel
-> Chọn S3
-> Nhập Endpoint / Bucket / Region / Access Key / Secret Key
-> Nhập CDN domain nếu cần
-> Giữ path-style access off theo mặc định
-> Bật quota limit nếu cần
-> Save
-> Upload test image và kiểm tra kết quả