Añadir un canal S3

Cuándo conviene

Use el canal S3 cuando:

• Quiera conectar cualquier servicio de almacenamiento de objetos compatible con S3, como Cloudflare R2, Backblaze B2, MinIO, AWS S3 u otro proveedor compatible.
• Prefiera el modelo estándar de configuración S3: Endpoint, Access Key y Secret Key.
• No quiera usar el canal nativo de Cloudflare R2 con binding, o su proveedor de almacenamiento no sea Cloudflare R2.

Qué necesita antes de empezar

Requisito	Propósito
Endpoint S3	El endpoint de la API S3 del servicio de almacenamiento de objetos.
Nombre del bucket	El bucket donde se almacenarán los archivos.
Región	Región de almacenamiento. Para Cloudflare R2, normalmente es auto.
Access Key ID	ID de la clave de acceso de S3.
Secret Access Key	Clave de acceso secreta de S3.
Dominio CDN	Dominio personalizado opcional para acceder a los archivos.

Ejemplo para Cloudflare R2 mediante la 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

Dónde añadirlo

1. Abra Ajustes del sistema.
2. Vaya a Ajustes de carga.
3. Haga clic en Añadir canal en la esquina superior derecha.
4. Seleccione S3.

Referencia de campos

Campo	Qué hace	Obligatorio
Nombre del canal	Un nombre fácil de reconocer para este canal S3, como s3test o R2-S3.	Sí
Activar canal	Controla si este canal participa en la selección de carga.	Recomendado
Endpoint	Endpoint completo del servicio S3, incluido https://.	Sí
Dominio CDN personalizado	Opcional. Si se configura, los enlaces de archivo generados prefieren este dominio.	No
Nombre del bucket	Nombre del bucket, como s3test o img-r2.	Sí
Región del bucket	Región. Para Cloudflare R2, normalmente es auto.	Sí
Access Key ID	ID de la clave de acceso de S3.	Sí
Secret Access Key	Clave de acceso secreta de S3.	Sí
Acceso path-style	Conmutador de compatibilidad. Desactivado por defecto. Algunos servicios MinIO, OpenList o S3 autoalojados pueden requerirlo.	No
Límite de cuota	Controla si este canal S3 participa en la selección de carga según la capacidad.	No
Límite de capacidad	Obligatorio después de activar el límite de cuota, por ejemplo 10 GB.	Obligatorio cuando el límite de cuota está activado
Umbral	Detiene la escritura cuando el uso alcanza este porcentaje, por ejemplo 90%.	Obligatorio cuando el límite de cuota está activado
Observación	Notas para su propio mantenimiento.	No

Crear claves de API S3 para Cloudflare R2

1. Abra el Cloudflare Dashboard.
2. Vaya a R2 Object Storage.
3. Busque Manage R2 API Tokens o la entrada de administración de tokens de API.

4. Cree un token de API de R2 que pueda acceder al bucket de destino.

5. Copie los valores generados Access Key ID y Secret Access Key.

6. Vuelva a la página del bucket R2 y confirme el nombre del bucket.
7. Registre el endpoint de API S3 de la cuenta. Normalmente se ve así:

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

Pasos de configuración

1. Abra Ajustes de carga.
2. Haga clic en Añadir canal.
3. Seleccione S3.
4. Introduzca un nombre de canal que pueda reconocer, por ejemplo s3test.
5. Introduzca el endpoint de la API S3 en Endpoint.
6. Si usa un CDN personalizado, introdúzcalo en el campo de dominio CDN personalizado; si no, deje el campo vacío.
7. Introduzca el nombre del bucket.
8. Introduzca la región. Para el ejemplo de Cloudflare R2, use auto.
9. Introduzca el Access Key ID y el Secret Access Key.
10. Deje desactivado el acceso path-style salvo que su proveedor lo requiera explícitamente.
11. Si quiere control de capacidad, active el límite de cuota e introduzca el límite de capacidad y el umbral.
12. Haga clic en Guardar.

Cómo verificarlo

Comprobación	Cómo verificarlo
Aparece la tarjeta del canal	Después de guardar, la página Ajustes de carga debería mostrar una tarjeta de canal S3.
El canal está activado	El interruptor de la esquina superior derecha de la tarjeta debería permanecer activado.
Los campos clave están guardados	La vista de detalle debería mostrar Endpoint, Bucket, Region, acceso path-style y los campos relacionados.
La carga funciona	Cargue una imagen de prueba y confirme que el objeto aparece en el bucket de destino.
El enlace se abre	El enlace de imagen devuelto después de la carga debería abrirse con normalidad.
La visualización de capacidad funciona	Si el límite de cuota está activado, la tarjeta debería mostrar la capacidad usada y el límite configurado.

Las estadísticas de capacidad de S3 se calculan a partir de los registros de archivos locales de ImgHost, no consultando el bucket del proveedor en tiempo real. Después de guardar una configuración S3, el sistema recalcula el libro de cuotas a partir de los registros D1 actuales.

FAQ

¿Debo activar el acceso path-style?

Normalmente, no.

Actívelo solo cuando su proveedor compatible con S3 no admita URL de estilo virtual-hosted, o cuando la documentación del proveedor exija explícitamente acceso path-style. Algunos endpoints de MinIO, S3 autoalojado y compatibles con OpenList pueden necesitarlo.

¿Para qué sirve el dominio CDN?

Si coloca un CDN o un dominio de acceso personalizado delante del bucket, introdúzcalo aquí.

Después de configurarlo, los enlaces de archivo generados preferirán este dominio. Si no usa CDN, deje el campo vacío.

¿Por qué falla la carga?

Revise primero estos puntos:

1. El Endpoint incluye la URL completa con https://.
2. El nombre del bucket es correcto.
3. La Region coincide con el requisito del proveedor.
4. El Access Key ID y el Secret Access Key se copiaron completos.
5. La clave tiene permiso de escritura en el bucket de destino.
6. El proveedor no requiere acceso path-style, o se activó si era necesario.

Lista rápida

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