For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /es/docs/modules/storage.md (or send Accept: text/markdown).
Módulo de almacenamiento
Un contrato ObjectStorage, adaptadores memory y compatible con S3.
Guía paso a paso para principiantes
Requisitos previos: lea las dos guías para principiantes a continuación, finalice la configuración local web y abra este monorepo en la raíz de su editor. La configuración web pertenece a apps/web/.env.local; Next.js no lee la raíz .env. /dashboard en el modo falso predeterminado es una demostración sin base de datos; /auth necesita una base de datos migrada.
Términos breves: un espacio de trabajo son los usuarios, datos y configuraciones separados de un equipo. El servidor es el backend confiable; Mantenga las claves del proveedor fuera del código del navegador y del teléfono. Una migración es un cambio de base de datos versionada que crea o actualiza tablas. Un modelo de IA es el motor que responde; el catálogo de modelos es la lista del servidor de ID de modelos disponibles y precios. Un proveedor es un servicio externo, como inteligencia artificial, correo electrónico o servicio de facturación. Un derecho es una concesión que permite que un espacio de trabajo utilice una función. Un webhook es un mensaje que un servicio envía al URL de otro servicio.
1. Para una prueba sin credenciales, conserve STORAGE_PROVIDER=memory. Si esta caja no tiene control de carga visible, solicite a su agente de codificación que inspeccione apps/web/app/api/storage/avatar/route.ts, apps/web/app/api/storage/logo/route.ts, apps/web/app/api/storage/organization-logo/route.ts y la página de configuración correspondiente antes de cablear una pequeña imagen de muestra.
2. Para verificar la persistencia, configure STORAGE_PROVIDER=s3, STORAGE_REGION y STORAGE_BUCKET en apps/web/.env.local, agregue localmente las credenciales de prueba solo del servidor y reinicie.
3. La imagen debería recargarse desde el almacenamiento. Los archivos de memoria desaparecen cuando se reinicia el proceso; para errores de S3, verifique el depósito, el punto final y la política de acceso.
Para obtener código personalizado, comience con el prompts/README.md proporcionado y copie el mensaje más cercano: prompts/new-app-screen.md para una pantalla de aplicación o prompts/new-landing-page.md para una página pública. Para trabajos de servidor, base de datos o proveedor, asigne a su agente de codificación la tarea de esta guía y pídale que lea AGENTS.md, .ai/PROJECT_CONTEXT.md y los espejos .ai/ correspondientes; inspeccionar los archivos fuente exactos nombrados aquí; enumerar archivos y verificaciones antes de editarlos; preservar la propiedad del espacio de trabajo y los secretos exclusivos del servidor; y mostrarte la diferencia. Dígale el comportamiento que desea, los campos de entrada y salida, los roles permitidos, los éxitos y errores esperados y la cuenta, proveedor o dispositivo de prueba. Utilice valores de muestra; Nunca pegues un verdadero secreto.
Selecciona el backend de almacenamiento
STORAGE_PROVIDER=memory es el valor predeterminado sin credenciales. local escribe objetos en disco bajo STORAGE_LOCAL_DIR (por defecto ./.data/storage, obligatorio explícitamente en producción) y los transmite mediante URL con firma HMAC y caducidad en /api/storage/local/[...key] (STORAGE_LOCAL_SIGNING_SECRET, con respaldo en AUTH_SECRET) para despliegues de un solo servidor. s3 utiliza apps/web/src/storage-runtime.ts para componer el cliente del SDK de AWS sobre el contrato reducido @supastack/storage, admitiendo Supabase Storage y MinIO con URL de estilo de ruta habilitadas por defecto.
STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=Reutiliza los límites de carga
Las rutas incluidas cubren objetos, avatares, logotipos de perfil y logotipos de organización bajo /api/storage/. Resuelven la identidad y los permisos del espacio de trabajo y validan la forma de la carga antes del almacenamiento. Inspecciona la política de tamaño/tipo de la ruta elegida en lugar de aceptar claves de objeto arbitrarias del cliente.
Las URL públicas son para presentación, no para autorización. Mantén el contenido protegido detrás del límite de lectura verificada de la aplicación y configura la política del bucket/CDN para los datos de tu producto.
Prueba el comportamiento del almacenamiento real
Prueba las cargas permitidas/denegadas, el rechazo de MIME y tamaño, rutas de otro espacio de trabajo, objetos ausentes y fallos del proveedor. El modo memoria no persiste entre procesos; verifica el almacenamiento y la recuperación con el backend seleccionado antes del lanzamiento.
Configuración y ajustes
packages/storage define la interfaz ObjectStorage — putObject, getObject y deleteObject contra locators de objetos — con MemoryObjectStorage para tests deterministas y S3CompatibleObjectStorage para buckets de producción.
Las claves de objeto se construyen con buildWorkspaceObjectKey y se comprueban con assertWorkspaceObjectKey, así que cada archivo almacenado está namespaced por workspace y propósito (avatar, archivo, logo). WorkspaceScopedStorageError se dispara cuando una clave escapa de su workspace.
interface ObjectStorage {
putObject(input: PutObjectInput): Promise<StoredObject>
getObject(locator: ObjectLocator): Promise<StoredObject | undefined>
deleteObject(locator: ObjectLocator): Promise<boolean>
getPublicUrl(locator: ObjectLocator): string
}
key = {workspaceId}/{purpose}/{safeName}Flujo de implementación
Las rutas de aplicación resuelven el workspace, validan la subida, construyen la clave con scope y llaman al adaptador — el storage nunca ve una ruta cruda del cliente. Selecciona el adaptador en el entorno del servidor a través de STORAGE_PROVIDER y sus credenciales.
Expón las lecturas a través del mismo límite de autorización; sirve URLs públicas solo para objetos que el producto publica deliberadamente.
Verificación y solución de problemas
MemoryObjectStorage mantiene los tests unitarios deterministas — afirma claves, tipos de contenido y denegaciones entre workspaces ahí. Verifica el adaptador S3 a través de la ruta smoke opcional contra un bucket real antes de lanzar subidas.