Configurar el almacenamiento de archivos

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.

• Antes de comenzar
• Conceptos básicos de terminales
• Configuración local web
• Mensajes del agente y memoria del proyecto

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=
# Local MinIO Compose overrides: MINIO_ROOT_USER / MINIO_ROOT_PASSWORD

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 de almacenamiento Supabase
• Subir inventario de rutas

Configuración y ajustes

1. STORAGE_PROVIDER=memory (el valor por defecto) mantiene las subidas en el proceso — adecuado para desarrollo y tests.

2. Para archivos reales, define STORAGE_PROVIDER=s3 con un bucket y un par de claves de acceso. STORAGE_ENDPOINT selecciona cualquier servicio compatible con S3 — Supabase Storage en https://<ref>.supabase.co/storage/v1/s3, MinIO o el propio AWS.

3. STORAGE_FORCE_PATH_STYLE pasa a true por defecto una vez definido un endpoint — Supabase y MinIO lo requieren. Ponlo en false solo para un endpoint personalizado de estilo virtual-hosted.

4. Opcionalmente apunta STORAGE_PUBLIC_BASE_URL a una CDN para que las URL públicas de objetos se resuelvan allí.

STORAGE_PROVIDER=s3
STORAGE_ENDPOINT=https://<ref>.supabase.co/storage/v1/s3
STORAGE_REGION=us-east-1            # Supabase: project region
STORAGE_BUCKET=<bucket>
STORAGE_ACCESS_KEY_ID=…
STORAGE_SECRET_ACCESS_KEY=…
STORAGE_PUBLIC_BASE_URL=https://cdn.example.com   # optional

# No bucket yet? Local S3-compatible storage ships in compose:
docker compose --profile storage up -d minio    # console on :9001

Flujo de implementación

Las subidas y lecturas pasan por rutas autenticadas que primero resuelven el workspace — /api/storage/objects más las rutas dedicadas de avatar y logo. Cada clave almacenada queda namespaced como {workspaceId}/{purpose}/{safeName} vía buildWorkspaceObjectKey.

Las credenciales permanecen solo en el servidor; el navegador nunca ve el bucket ni las claves.

¿Las subidas funcionan? Continúa con «Configurar la observabilidad».

Verificación y solución de problemas

Verifica que una subida hace el viaje de ida y vuelta, que un segundo workspace no puede leer el objeto y que los tipos de contenido demasiado grandes o no permitidos fallan. Los errores de firma o 403 contra Supabase o MinIO suelen significar que STORAGE_FORCE_PATH_STYLE es incorrecto para el endpoint.