Ir al contenido

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…).

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:

cms.config.ts
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],
})
  • default existe siempre. Es el bucket de R2 de bindings.bucket: lo que usa toda colección que no nombra perfil. No hace falta declararlo. Si lo declaras en storage, lo redefines (por ejemplo default: { adapter: 'r2', binding: 'R2_ARCHIVO' }) y todo lo que no nombra perfil va ahí.
  • Un proyecto sin storage es 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 r2 guarda en un bucket de R2 por su binding. Sin binding, es el de bindings.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 s3 habla 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:

.dev.vars
ARCHIVO_S3_KEY_ID=…
ARCHIVO_S3_SECRET=…
Ventana de terminal
npx wrangler secret put ARCHIVO_S3_KEY_ID
npx wrangler secret put ARCHIVO_S3_SECRET

Los 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:

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.

wrangler.jsonc
{ "compatibility_date": "2026-07-29" }

cms doctor avisa de esto si hay un perfil s3 en uso.

  • cms doctor pide el binding R2 (y los de los perfiles r2 con otro binding) solo si alguna colección va a un perfil r2: un proyecto con la biblioteca y todas las colecciones en S3 no necesita r2_buckets. El R2 de siempre sigue siendo un aviso; el binding que tú nombras en un perfil, si falta en wrangler.jsonc, es un error, porque sin él el CMS no arranca. Para cada perfil s3 en uso comprueba que .dev.vars tiene 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 la compatibility_date de arriba.
  • cms deploy avisa de los wrangler secret put pendientes: lista, solo por nombre, las variables de los perfiles S3 en uso que no aparecen en wrangler 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.

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.

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):

  1. Congela las escrituras de esa colección: modo mantenimiento o un access.create que rechace. Un fichero subido mientras copias puede quedarse fuera de la copia.

  2. Copia conservando las claves, del bucket viejo al nuevo, y verifica:

    Ventana de terminal
    rclone copy viejo:mi-bucket nuevo:mi-bucket --checksum --transfers 8
    rclone check viejo:mi-bucket nuevo:mi-bucket

    Con 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 get y put con --local copian un objeto por clave.

  3. Cambia upload.storage (o media.storage) y despliega.

  4. Comprueba tres filas al azar en /api/cms/cdn/<slug>/<id>/<nombre> y que filas y objetos cuadran.

  5. 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 uploadId pertenece al backend anterior: el cierre falla con un 400 y 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 a file) da INVALID_KEY con 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.

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.json

    Es 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.

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

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 UNAVAILABLE no sirve. La segunda llamada recibe INVALID_UPLOAD (o 409 UPLOAD_ALREADY_COMPLETED si 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 404 sin <Code> es MISCONFIGURED en get, delete, abort… (solo en S3). Un proxy o un endpoint equivocado que devuelve 404 sin el XML de S3 hace fallar la operación en vez de darla por buena. En head, un 404 sí 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.