Almacenamiento de ficheros
Sin configurar nada, los ficheros van al bucket de R2 que declaras en bindings.bucket (R2 por
defecto) y todo lo que cuenta Ficheros vale tal cual. Esta guía es para cuando
quieres otra cosa: otro bucket de R2 para una colección, o un servicio compatible con S3 (R2 por su
API S3, AWS S3, MinIO, Backblaze B2…).
Perfiles: se declaran una vez y se nombran
Sección titulada «Perfiles: se declaran una vez y se nombran»Un perfil es un sitio donde guardar ficheros, con un nombre. Se declara en storage, dentro de
defineConfig, y cada colección con upload (y la biblioteca de medios) dice a cuál va:
import { defineCollection, defineConfig } from '@kevolution-co/cms'
const documentos = defineCollection({ slug: 'documentos', upload: { storage: 'archivo', maxFileSize: 2 * 1024 ** 3 }, fields: [],})
export default defineConfig({ storage: { // Un servicio compatible con S3. Los secretos van por NOMBRE de variable, nunca por valor. archivo: { adapter: 's3', endpoint: 'https://0123abcd.r2.cloudflarestorage.com', bucket: 'archivo', region: 'auto', addressing: 'path', credentials: { accessKeyId: 'ARCHIVO_S3_KEY_ID', secretAccessKey: 'ARCHIVO_S3_SECRET', }, }, // Otro bucket de R2 por su binding: no se firma nada y no hay secretos. contratos: { adapter: 'r2', binding: 'R2_CONTRATOS' }, }, // La biblioteca de medios (`ssd`) también elige perfil. Sin la clave, va a `default`. media: { storage: 'default' }, collections: [documentos],})defaultexiste siempre. Es el bucket de R2 debindings.bucket: lo que usa toda colección que no nombra perfil. No hace falta declararlo. Si lo declaras enstorage, lo redefines (por ejemplodefault: { adapter: 'r2', binding: 'R2_ARCHIVO' }) y todo lo que no nombra perfil va ahí.- Un proyecto sin
storagees el de siempre: mismo bucket, mismas claves, mismas cabeceras, mismo esquema de base de datos. Añadir perfiles no genera ninguna migración. - Un perfil
r2guarda en un bucket de R2 por su binding. Sinbinding, es el debindings.bucket. Es la forma de tener varios buckets por colección, y no cuesta nada: no hay red ni firma de por medio. - Un perfil
s3habla con un servicio compatible con S3 por HTTPS, firmando cada petición (SigV4) desde el Worker. Sin SDK y sin dependencias nuevas.
Campo del perfil s3 |
Obligatorio | Qué es |
|---|---|---|
endpoint |
sí | https://host[:puerto]. http:// solo vale en localhost, 127.0.0.1 y [::1]. Sin usuario, ruta, query ni fragmento |
bucket |
sí | Nombre del bucket (3 a 63 caracteres: minúsculas, números, puntos y guiones) |
region |
no | 'auto' por defecto. AWS necesita la región real |
addressing |
no | 'path' (por defecto: endpoint/bucket/clave) o 'virtual' (bucket.endpoint/clave, solo con un nombre de host) |
credentials.accessKeyId |
sí | El nombre de la variable de entorno que lleva la clave de acceso |
credentials.secretAccessKey |
sí | El nombre de la variable con el secreto |
credentials.sessionToken |
no | El nombre de la variable con un token de sesión temporal |
Las referencias se comprueban al cargar el config, antes de que el sitio arranque: un perfil que no
existe (UNKNOWN_STORAGE), un nombre de variable que no sea MAYUSCULAS_CON_GUION_BAJO, un endpoint
inválido o un perfil mal formado (INVALID_STORAGE_CONFIG) lanzan un ConfigError que nombra el sitio
exacto. Un valor que parece una clave de acceso escrita donde va un nombre de variable (en mayúsculas y
cifras, sin guion bajo, de 16 caracteres o más: los ID de AWS, DigitalOcean, Wasabi, Scaleway…) se
rechaza sin repetirlo en el mensaje, y también el nombre de una variable o un binding del propio CMS
(BETTER_AUTH_SECRET, DB, KV, R2, EMAIL): no son credenciales de almacenamiento. Los mensajes
de validación solo repiten un texto del config si es un nombre corto de perfil o de clave ("archivo",
"enpoint"); una URL con contraseña o una clave pegada donde no iba salen como «una cadena de N
caracteres».
Secretos: en variables de entorno del Worker
Sección titulada «Secretos: en variables de entorno del Worker»El config nombra variables; los valores no están en el repositorio. En local van en .dev.vars
(ignorado por git) y en producción son secretos del Worker:
ARCHIVO_S3_KEY_ID=…ARCHIVO_S3_SECRET=…npx wrangler secret put ARCHIVO_S3_KEY_IDnpx wrangler secret put ARCHIVO_S3_SECRETLos secretos se leen y se comprueban la primera vez que algo toca el CMS en cada isolate, que es lo más parecido a un arranque que tiene un Worker (el entorno solo existe dentro de una petición). Solo se piden los de los perfiles que alguna colección referencia: un perfil declarado y sin usar no exige nada.
| Qué pasa | Error | Qué dice |
|---|---|---|
| Falta la variable | MISSING_STORAGE_SECRET |
El nombre de la variable y el perfil, y cómo ponerla |
| Está, pero mal formada | INVALID_STORAGE_SECRET |
El nombre y el motivo (vacía, con espacios o saltos de línea, con caracteres que no son ASCII imprimible, demasiado larga). Nunca el valor ni un trozo |
El binding de un perfil r2 no está en wrangler.jsonc |
MISSING_BUCKET |
El perfil y el binding que hay que declarar en r2_buckets |
| Las credenciales tienen buena forma y el servicio las rechaza | StorageError UNAUTHORIZED |
En la primera operación, con el perfil y el código del proveedor; al cliente le llega el 500 genérico y el detalle va al registro |
Qué no sale nunca: el valor de un secreto (ni un trozo) no aparece en un mensaje de error, en
JSON.stringify, en util.inspect, en un registro, en la cause de un error, en la configuración
pública que lee el navegador ni en la salida de doctor y deploy: lo único que se imprime es el
nombre de la variable y el motivo. Las credenciales viven en una clausura del adaptador.
El endpoint viene solo del config del anfitrión. Ninguna petición, fila, campo del panel ni
cabecera puede fijarlo ni leerlo: si pudiera, el servidor firmaría y enviaría a donde dijera un
desconocido (SSRF). Por eso storage, credentials, endpoint y bucket no viajan en la
configuración pública, ni en el HTML del panel, ni en los datos de sus páginas. Y por eso mismo:
compatibility_date y el adaptador S3
Sección titulada «compatibility_date y el adaptador S3»El adaptador S3 manda cache: 'no-store' en cada petición, para que Cloudflare no sirva de su caché
algo que firmó. El runtime solo admite esa opción desde la compatibility_date 2024-11-11, o con
el flag cache_option_enabled; sin ninguna de las dos lanza «The ‘cache’ field on
‘RequestInitializerDict’ is not implemented» y toda operación del perfil S3 falla con MISCONFIGURED.
El flag cache_option_disabled lo apaga aunque la fecha sea reciente.
{ "compatibility_date": "2026-07-29" }cms doctor avisa de esto si hay un perfil s3 en uso.
doctor y deploy
Sección titulada «doctor y deploy»cms doctorpide el bindingR2(y los de los perfilesr2con otrobinding) solo si alguna colección va a un perfilr2: un proyecto con la biblioteca y todas las colecciones en S3 no necesitar2_buckets. ElR2de siempre sigue siendo un aviso; el binding que tú nombras en un perfil, si falta enwrangler.jsonc, es un error, porque sin él el CMS no arranca. Para cada perfils3en uso comprueba que.dev.varstiene las variables y que su forma es válida, sin imprimir ningún valor: una variable que falta es un aviso (los secretos de producción no se ven desde un comando que no usa la red) y una mal formada es un error. Avisa también de un perfil declarado que ninguna colección usa y de lacompatibility_datede arriba.cms deployavisa de loswrangler secret putpendientes: lista, solo por nombre, las variables de los perfiles S3 en uso que no aparecen enwrangler secret list, y la línea exacta para ponerlas. Es un aviso: el despliegue sigue, pero sin esos secretos el CMS no arranca en producción.
Qué está probado y qué no
Sección titulada «Qué está probado y qué no»No hay presets por proveedor: se configura un servicio S3 genérico (endpoint, bucket, region,
addressing). La tabla separa lo que se ejecutó de lo que dice el proveedor y no se ha
comprobado.
| Destino | Estado | Cómo se llega a él |
|---|---|---|
| Servidor S3 falso del repositorio | Probado | Una misma batería de contrato corre contra el adaptador de R2, el de memoria y el de S3 contra el falso: subida, lectura con rangos y condicionales, borrado, subida por trozos, listado, errores |
| Firma SigV4 | Probada | Los vectores oficiales de AWS, y 104 firmas distintas comparadas con botocore (path y virtual, con y sin token, subida por trozos, listado) |
R2 por el binding (adapter: 'r2') |
Probado | Es el camino de siempre, con miniflare |
| R2 por su API S3 | Documentado por Cloudflare, no probado | endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com, region: 'auto', addressing: 'path' |
| AWS S3 | Documentado por AWS, no probado | endpoint: https://s3.<región>.amazonaws.com, region real, addressing: 'virtual' |
| MinIO | Documentado, no probado | endpoint: http://127.0.0.1:9000 en local (http solo en loopback), addressing: 'path' |
| Backblaze B2 y demás | Documentado por el proveedor, no probado | El endpoint S3 de la cuenta, con la región del bucket |
En el repositorio hay una suite de extremo a extremo para probarlo contra un servicio de verdad,
pnpm test:storage-e2e en pkgs/cms. No corre en CI y no se ha ejecutado contra ningún proveedor.
Trabaja dentro de un prefijo aleatorio y solo borra lo que cuelga de él, pero exige confirmar que el
bucket es desechable.
Cambiar de backend no mueve los ficheros
Sección titulada «Cambiar de backend no mueve los ficheros»La receta para mover una colección sin perder nada, con la misma estructura de claves en los dos lados
(<carpeta>/<id>/<nombre> en la biblioteca, <slug>/<id>/<nombre> en una colección tuya, y
<id>/<nombre> para un fichero en la raíz de la biblioteca):
-
Congela las escrituras de esa colección: modo mantenimiento o un
access.createque rechace. Un fichero subido mientras copias puede quedarse fuera de la copia. -
Copia conservando las claves, del bucket viejo al nuevo, y verifica:
Ventana de terminal rclone copy viejo:mi-bucket nuevo:mi-bucket --checksum --transfers 8rclone check viejo:mi-bucket nuevo:mi-bucketCon el CLI de AWS,
aws s3 sync --endpoint-url …hace lo mismo. Entre dos buckets de R2 de un mismo Worker en local,wrangler r2 object getyputcon--localcopian un objeto por clave. -
Cambia
upload.storage(omedia.storage) y despliega. -
Comprueba tres filas al azar en
/api/cms/cdn/<slug>/<id>/<nombre>y que filas y objetos cuadran. -
Conserva el bucket viejo unos días antes de borrarlo.
Lo que puede perder datos, en orden de gravedad:
- Borrar el bucket viejo antes de terminar la copia. Es lo único irrecuperable.
- Una subida por trozos empezada con un backend y cerrada tras el cambio. El
uploadIdpertenece al backend anterior: el cierre falla con un400y el cliente tiene que empezar de nuevo. Cambia de perfil cuando no haya subidas en vuelo. - Borrar un documento después de cambiar manda el borrado al backend nuevo (es idempotente) y deja el objeto viejo en el anterior: gastas espacio, no pierdes nada.
- Una fila con
filename.o..(subida antes de que el CMS los renombrara afile) daINVALID_KEYcon S3. Detéctala antes de migrar:SELECT id FROM <colección> WHERE filename IN ('.', '..'). - El caso sin copia: pasar del binding de R2 a la API S3 de R2 sobre el mismo bucket no mueve nada, porque las claves son las mismas.
Subidas por trozos: la dependencia uploadId – clave
Sección titulada «Subidas por trozos: la dependencia uploadId – clave»En una subida por trozos, part, complete y abort llevan el uploadId que dio create y la
clave, que el servidor vuelve a deducir de lo que manda el cliente. El adaptador no comprueba que el
uploadId pertenezca a esa clave: se apoya en que el almacén rechace un par que no casa con
NoSuchUpload, que es lo que hacen R2, S3 y MinIO según su documentación (no se ha verificado contra
ellos). Un almacén que ignorase el uploadId al abortar dejaría borrar el objeto de otro documento a
quien conozca su id y su nombre, que son públicos. Si vas a usar un servicio compatible que no sea de los
tres, pruébalo antes con pnpm test:storage-e2e.
Ficheros huérfanos: no hay barrido automático
Sección titulada «Ficheros huérfanos: no hay barrido automático»Un huérfano es un objeto en el bucket sin fila en la base de datos. El CMS escribe el objeto antes que la fila a propósito (lo contrario sería una fila apuntando a nada), y limpia lo que puede cuando algo falla, pero hay casos en los que no llega:
- La limpieza compensatoria falla a su vez (la red cae justo entonces).
- Una escritura por S3 acaba en timeout: su resultado es desconocido y puede haber dejado el objeto.
- Cambiaste de backend y borraste un documento (el objeto viejo queda en el sitio anterior).
- Cierras una subida por trozos y el servidor tarda en ensamblar más que nuestro plazo (más abajo).
Ningún proceso del CMS los recoge. Si te importa el espacio, un barrido es manual: lista las claves
del bucket (rclone lsf, aws s3 ls --recursive), saca los ids de la tabla de la colección (por ejemplo
wrangler d1 execute DB --remote --command "SELECT id FROM ssd") y borra los objetos cuyo segmento <id>
no esté en la tabla. Salta los objetos recientes (un día es razonable): una subida en curso tiene el
objeto antes que la fila, y borrarlo la rompe.
Reglas de ciclo de vida
Sección titulada «Reglas de ciclo de vida»Dos reglas del bucket, que el CMS no puede poner por ti:
-
Subidas por trozos incompletas. Una subida abandonada a medias deja sus trozos en el bucket y se factura. R2 las aborta a los 7 días por defecto; AWS S3 no lo hace salvo que lo pidas:
regla.json {"Rules": [{"ID": "abortar-multipart-incompletos","Status": "Enabled","Filter": {},"AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 }}]}Ventana de terminal aws s3api put-bucket-lifecycle-configuration --bucket mi-bucket \--lifecycle-configuration file://regla.jsonEs la sintaxis de la documentación de AWS; no se ha ejecutado desde aquí.
-
Versionado. Si activas el versionado del bucket, borrar un fichero desde el CMS no libera espacio: S3 añade una marca de borrado y las versiones anteriores siguen ahí, facturando. El CMS borra por clave, sin pedir versión. Añade una regla que caduque las versiones no actuales (
NoncurrentVersionExpiration) si quieres que el espacio vuelva. A cambio, el versionado te deja recuperar un fichero borrado o sobrescrito por error.
Límites
Sección titulada «Límites»| Qué | Cuánto |
|---|---|
Subida de un golpe (POST) |
25 MB, con cualquier backend: el envío se carga entero en memoria. maxFileSize no lo mueve |
| Subida por trozos | Trozos de 5 MiB como mínimo (salvo el último), a 5 GiB como máximo, hasta 10.000 por objeto. Los trozos de una subida miden todos lo mismo (R2 lo exige; el CMS lo hace siempre) |
| Tamaño de un trozo en la petición | 95 MiB como máximo (el cuerpo de petición del plan más bajo de Workers) |
| Techo de un fichero | Unos 928 GiB, y maxFileSize (5 GiB por defecto) manda por debajo. Ver Limitaciones |
| Clave de un objeto | ASCII [A-Za-z0-9._-] por segmentos, sin segmentos . ni .., hasta 1024 bytes. Lo que no cumpla se rechaza con INVALID_KEY antes de salir una petición |
| Cerrar una subida por trozos | El servidor S3 puede tardar en ensamblar: el adaptador espera hasta 60 s sin un solo byte y 10 minutos en total |
| Conexiones | Cloudflare limita a 6 las conexiones salientes abiertas a la vez por invocación; las demás esperan |
Lo que sigue sin resolver
Sección titulada «Lo que sigue sin resolver»Son conocidos y se aceptaron para esta versión. Conviene tenerlos presentes si dependes de S3:
- Huérfano si el servidor termina de ensamblar después de nuestro plazo. Si el cierre de una subida por trozos se queda sin respuesta más de 60 s, el adaptador corta la espera y falla; si el servidor acaba de ensamblar después, el objeto aparece sin fila y nadie lo borra. Hace falta el barrido manual.
- Reintentar un cierre que falló con
UNAVAILABLEno sirve. La segunda llamada recibeINVALID_UPLOAD(o409UPLOAD_ALREADY_COMPLETEDsi la fila llegó a crearse): un cierre repetido se rechaza por diseño, para que la limpieza no pueda llevarse un objeto vivo. El cliente empieza otra subida. Dos cierres que llegan a la vez (un doble clic) sí pasan los dos esa guarda. - Un
404sin<Code>esMISCONFIGUREDenget,delete,abort… (solo en S3). Un proxy o un endpoint equivocado que devuelve404sin el XML de S3 hace fallar la operación en vez de darla por buena. Enhead, un404sí es «no existe». R2 por binding no tiene esta distinción.
Una instancia propia: el parámetro adapters
Sección titulada «Una instancia propia: el parámetro adapters»El config solo lleva datos que se pueden serializar. Si necesitas un adaptador que no cabe ahí (uno
tuyo, o uno de pruebas), pásalo por código: buildAPI y el RestCMS de handle aceptan un último
parámetro adapters, un mapa de nombre de perfil a StorageAdapter. Gana sobre un perfil del mismo
nombre y no trae ningún secreto que leer. El paquete exporta createS3Adapter, StorageAdapter y
StorageError. Ver buildAPI.