Aggiungere un canale S3

Quando usarlo

Usa il canale S3 quando:

• vuoi collegare un servizio di object storage compatibile S3, come Cloudflare R2, Backblaze B2, MinIO, AWS S3 o altri provider compatibili.
• preferisci la configurazione S3 standard con Endpoint, Access Key e Secret Key.
• non vuoi usare il canale nativo Cloudflare R2 tramite binding, oppure il tuo provider non è Cloudflare R2.

Prima di iniziare

Requisito	A cosa serve
S3 Endpoint	Endpoint API S3 del servizio di archiviazione.
Nome bucket	Bucket in cui verranno salvati i file.
Region	Regione dello storage. Per Cloudflare R2 di solito è auto.
Access Key ID	ID della chiave di accesso S3.
Secret Access Key	Chiave segreta S3.
Dominio CDN	Dominio personalizzato opzionale per accedere ai file.

Esempio per Cloudflare R2 tramite API S3:

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

Dove aggiungerlo

1. Apri Impostazioni di sistema.
2. Vai a Impostazioni di caricamento.
3. Clicca su Aggiungi canale in alto a destra.
4. Seleziona S3.

Riferimento campi

Campo	Funzione	Obbligatorio
Nome canale	Nome riconoscibile, per esempio s3test o R2-S3.	Sì
Abilita canale	Decide se il canale partecipa alla scelta del caricamento.	Consigliato
Endpoint	Endpoint S3 completo, incluso https://.	Sì
Dominio CDN personalizzato	Opzionale. Se presente, i link generati useranno preferibilmente questo dominio.	No
Nome bucket	Nome del bucket, per esempio s3test o img-r2.	Sì
Regione bucket	Regione. Per Cloudflare R2 di solito è auto.	Sì
Access Key ID	ID della chiave S3.	Sì
Secret Access Key	Chiave segreta S3.	Sì
Path-style access	Opzione di compatibilità, disattivata per impostazione predefinita. Alcuni servizi MinIO, OpenList o S3 autogestiti possono richiederla.	No
Limite quota	Decide se il canale viene scelto in base alla capacità.	No
Limite capacità	Richiesto dopo aver attivato il limite quota, per esempio 10 GB.	Obbligatorio con limite quota
Soglia	Ferma le scritture quando l'uso raggiunge questa percentuale, per esempio 90%.	Obbligatorio con limite quota
Nota	Appunti per la manutenzione.	No

Creare chiavi S3 API per Cloudflare R2

1. Apri la dashboard Cloudflare.
2. Vai a R2 Object Storage.
3. Trova Manage R2 API Tokens o la voce per gestire i token API.

4. Crea un token API R2 con accesso al bucket di destinazione.

5. Copia Access Key ID e Secret Access Key.

6. Torna alla pagina del bucket R2 e conferma il nome del bucket.
7. Annota l'endpoint API S3 dell'account. Di solito ha questo formato:

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

Passaggi di configurazione

1. Apri Impostazioni di caricamento.
2. Clicca su Aggiungi canale.
3. Seleziona S3.
4. Inserisci un nome canale chiaro, per esempio s3test.
5. Inserisci l'endpoint API S3 in Endpoint.
6. Se usi un CDN personalizzato, inseriscilo in Custom CDN domain; altrimenti lascia vuoto.
7. Inserisci il nome del bucket.
8. Inserisci la region. Nell'esempio Cloudflare R2 usa auto.
9. Inserisci Access Key ID e Secret Access Key.
10. Lascia Path-style access disattivato, salvo richiesta esplicita del provider.
11. Se vuoi il controllo della capacità, abilita il limite quota e inserisci limite e soglia.
12. Salva.

Verifica

Controllo	Come verificare
Scheda canale	Dopo il salvataggio compare una scheda S3 nelle Impostazioni di caricamento.
Canale attivo	L'interruttore in alto a destra della scheda resta acceso.
Campi salvati	La vista dettaglio mostra Endpoint, Bucket, Region, Path-style access e campi collegati.
Caricamento funzionante	Carica un'immagine di prova e verifica che l'oggetto compaia nel bucket.
Link apribile	Il link restituito dopo il caricamento si apre normalmente.
Capacità visibile	Se il limite quota è attivo, la scheda mostra capacità usata e limite configurato.

Le statistiche di capacità S3 sono calcolate dai record locali dei file in ImgHost, non interrogando il bucket del provider in tempo reale. Dopo il salvataggio, il sistema ricalcola il riepilogo quote dai record D1 attuali.

FAQ

Devo attivare Path-style access?

Di solito no.

Attivalo solo se il provider S3 compatibile non supporta URL virtual-hosted-style o se la documentazione lo richiede. Alcuni endpoint MinIO, S3 autogestiti e compatibili OpenList possono averne bisogno.

A cosa serve il dominio CDN?

Se metti un CDN o un dominio di accesso personalizzato davanti al bucket, inseriscilo qui.

Dopo la configurazione, ImgHost preferirà quel dominio nei link generati. Se non usi un CDN, lascia il campo vuoto.

Perché il caricamento fallisce?

Controlla prima questi punti:

1. L'Endpoint include l'URL completo con https://.
2. Il nome del bucket è corretto.
3. La Region corrisponde ai requisiti del provider.
4. Access Key ID e Secret Access Key sono stati copiati integralmente.
5. La chiave ha permesso di scrittura sul bucket di destinazione.
6. Il provider non richiede Path-style access, oppure l'opzione è stata attivata se necessaria.

Checklist rapida

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