Archiviazione file

Procedura dettagliata per principianti

Prerequisiti: leggi le due guide per principianti di seguito, completa la configurazione locale del Web e apri questo monorepo alla radice nel tuo editor. Le impostazioni Web appartengono a apps/web/.env.local; Next.js non legge la radice .env. /dashboard nella modalità falsa predefinita è una demo senza database; /auth necessita di un database migrato.

Termini rapidi: uno spazio di lavoro è costituito da utenti, dati e impostazioni separati di un team. Il server è il backend affidabile; mantenere le chiavi del provider fuori dal browser e dal codice del telefono. Una migrazione è una modifica del database con versione che crea o aggiorna tabelle. Un modello AI è il motore che risponde; il catalogo dei modelli è l'elenco del server degli ID e dei prezzi dei modelli disponibili. Un fornitore è un servizio esterno come un servizio di intelligenza artificiale, posta elettronica o fatturazione. Un diritto è una concessione che consente a un'area di lavoro di utilizzare una funzionalità. Un webhook è un messaggio che un servizio invia allo URL di un altro servizio.

1. Per una prova senza credenziali, mantenere STORAGE_PROVIDER=memory. Se questo pagamento non ha un controllo di caricamento visibile, chiedi al tuo agente di codifica di ispezionare 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 e la pagina delle impostazioni corrispondenti prima di collegare una piccola immagine di esempio.

2. Per verificare la persistenza, impostare STORAGE_PROVIDER=s3, STORAGE_REGION e STORAGE_BUCKET in apps/web/.env.local, aggiungere localmente le credenziali di test solo del server e riavviare.

3. L'immagine dovrebbe essere ricaricata dalla memoria. I file di memoria scompaiono al riavvio del processo; per gli errori S3, controlla il bucket, l'endpoint e la policy di accesso.

Per il codice personalizzato, inizia con prompts/README.md in dotazione e copia il prompt più vicino: prompts/new-app-screen.md per la schermata di un'app o prompts/new-landing-page.md per una pagina pubblica. Per il lavoro su server, database o provider, assegna al tuo agente di codifica il compito di questa guida e chiedigli di leggere AGENTS.md, .ai/PROJECT_CONTEXT.md e i mirror .ai/ corrispondenti; controllare gli esatti file sorgente nominati qui; elencare file e controlli prima della modifica; preservare la proprietà dello spazio di lavoro e i segreti solo del server; e mostrarti la differenza. Indicagli il comportamento desiderato, i campi di input e output, i ruoli consentiti, i successi e gli errori previsti e l'account, il fornitore o il dispositivo di prova. Utilizzare valori campione; non incollare mai un vero segreto.

• Prima di iniziare
• Nozioni di base sui terminali
• Configurazione locale Web
• Messaggi dell'agente e memoria del progetto

Seleziona il backend di archiviazione

STORAGE_PROVIDER=memory è l’impostazione predefinita senza credenziali. local scrive gli oggetti su disco in STORAGE_LOCAL_DIR (./.data/storage per impostazione predefinita, richiesto esplicitamente in produzione) e li trasmette tramite URL firmati con HMAC a scadenza su /api/storage/local/[...key] (STORAGE_LOCAL_SIGNING_SECRET, con fallback su AUTH_SECRET) per i deployment su singolo server. s3 usa apps/web/src/storage-runtime.ts per comporre il client AWS SDK sul contratto essenziale @supastack/storage, supportando Supabase Storage e MinIO con URL path-style abilitati per impostazione predefinita.

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

Riutilizzare i limiti di caricamento

I percorsi spediti coprono oggetti, avatar, loghi di profili e loghi di organizzazioni sotto /api/storage/. Risolvono le autorizzazioni di identità/area di lavoro e convalidano la forma di caricamento prima dell'archiviazione. Ispeziona la politica di dimensione/tipo del percorso scelto invece di accettare chiavi arbitrarie dell'oggetto client.

Gli URL pubblici sono presentazioni, non autorizzazioni. Mantieni i contenuti protetti entro il limite di lettura verificato dell'applicazione e configura la policy bucket/CDN per i dati del tuo prodotto.

Testare il comportamento di archiviazione reale

Testare caricamenti consentiti/negati, MIME e rifiuto delle dimensioni, percorsi di aree di lavoro esterne, oggetti mancanti e errori del provider. La modalità memoria non persiste tra i processi; verificare l'archiviazione e il recupero rispetto al backend selezionato prima del rilascio.

• Configurazione archiviazione Supabase
• Carica inventario percorsi

Installazione e configurazione

STORAGE_PROVIDER seleziona l'adattatore: memory per test e sviluppo locale, s3 per qualsiasi bucket compatibile S3 (STORAGE_BUCKET, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_PUBLIC_BASE_URL). Le credenziali restano solo server.

packages/storage possiede il contratto ObjectStorage — putObject/getObject/deleteObject sui locator di oggetti — più assertWorkspaceObjectKey e buildWorkspaceObjectKey così ogni oggetto archiviato è namespacato per workspace e scopo (avatar, file, logo).

Uploads and reads go through authenticated routes:
  /api/storage/objects
  /api/storage/avatar
  /api/storage/logo
  /api/storage/organization-logo

Flusso di implementazione

Mantieni gli upload dietro il livello di route autenticate: risolvi il workspace, valida content type e dimensione, costruisci la chiave con scope workspace, poi archivia tramite l'adattatore. Servi le letture allo stesso modo a meno che un oggetto sia deliberatamente pubblico.

Avatar e logo di organizzazione hanno route dedicate con la propria validazione; file di prodotto arbitrari passano per /objects con uno scopo dichiarato.

Verifica e risoluzione dei problemi

Verifica che gli upload anonimi siano rifiutati, che un workspace non possa leggere le chiavi oggetto di un altro, che content type troppo grandi o non consentiti falliscano, e che un oggetto eliminato smetta di risolversi. Usa l'adattatore memory nei test; verifica il bucket reale tramite il percorso smoke opzionale.