Storagemodule

Walkthrough voor beginners

Vereisten: Lees de twee onderstaande beginnershandleidingen, voltooi de lokale webconfiguratie en open deze monorepo in de root van uw editor. Webinstellingen horen thuis in apps/web/.env.local; Next.js leest de root .env niet. /dashboard in de standaard nepmodus is een demo zonder database; /auth heeft een gemigreerde database nodig.

Korte termen: een werkruimte bestaat uit de afzonderlijke gebruikers, gegevens en instellingen van één team. De server is de vertrouwde backend; houd providersleutels uit de browser- en telefooncode. Een migratie is een versiebeheer van de database, waarbij tabellen worden gemaakt of bijgewerkt. Een AI-model is de motor die antwoord geeft; de modelcatalogus is de serverlijst met beschikbare model-ID's en prijzen. Een provider is een externe service, zoals een AI-, e-mail- of factureringsservice. Een recht is een subsidie ​​waarmee een werkruimte een functie kan gebruiken. Een webhook is een bericht dat de ene service naar de URL van een andere service verzendt.

1. Bewaar STORAGE_PROVIDER=memory voor een proefperiode zonder referentie. Als deze checkout geen zichtbare uploadcontrole heeft, vraag dan uw codeeragent om 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 en de overeenkomende instellingenpagina te inspecteren voordat u een kleine voorbeeldafbeelding bedient.

2. Om de persistentie te controleren, stelt u STORAGE_PROVIDER=s3, STORAGE_REGION en STORAGE_BUCKET in apps/web/.env.local in, voegt u lokaal testreferenties voor de server toe en start u opnieuw op.

3. De afbeelding moet opnieuw worden geladen vanuit de opslag. Geheugenbestanden verdwijnen wanneer het proces opnieuw start; Controleer voor S3-fouten de bucket, het eindpunt en het toegangsbeleid.

Voor aangepaste code begint u met de meegeleverde prompts/README.md en kopieert u de dichtstbijzijnde prompt: prompts/new-app-screen.md voor een app-scherm of prompts/new-landing-page.md voor een openbare pagina. Voor server-, database- of providerwerk geeft u uw codeeragent de taak van deze handleiding en vraagt ​​u hem om AGENTS.md, .ai/PROJECT_CONTEXT.md en overeenkomende .ai/-mirrors te lezen; inspecteer de exacte bronbestanden die hier worden genoemd; maak een lijst van bestanden en controleer deze voordat u deze bewerkt; behoud van het eigendom van de werkruimte en geheimen voor de server; en laat je het verschil zien. Vertel het gewenste gedrag, invoer- en uitvoervelden, toegestane rollen, verwacht succes en fouten, en het testaccount, de provider of het apparaat. Gebruik voorbeeldwaarden; plak nooit een echt geheim.

• Voordat u begint
• Basisbeginselen van de terminal
• Lokale webinstellingen
• Agentprompts en projectgeheugen

Selecteer de opslag-backend

STORAGE_PROVIDER=memory is de standaard zonder inloggegevens. local schrijft objecten naar schijf onder STORAGE_LOCAL_DIR (standaard ./.data/storage, expliciet vereist in productie) en streamt ze via HMAC-ondertekende verlopende URL’s op /api/storage/local/[...key] (STORAGE_LOCAL_SIGNING_SECRET, valt terug op AUTH_SECRET) voor implementaties op één server. s3 gebruikt apps/web/src/storage-runtime.ts om de AWS SDK-client samen te stellen boven op het compacte @supastack/storage-contract, met standaard ondersteuning voor Supabase Storage en MinIO met pad-stijl URL’s.

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=

Hergebruik de uploadgrenzen

De verzonden routes omvatten objecten, avatars, profiellogo's en organisatielogo's onder /api/storage/. Ze lossen identiteits-/werkruimtemachtigingen op en valideren de uploadvorm vóór opslag. Inspecteer het grootte-/typebeleid van de gekozen route in plaats van willekeurige clientobjectsleutels te accepteren.

Openbare URL's zijn presentatie, geen autorisatie. Houd beschermde inhoud achter de geverifieerde leesgrens van de applicatie en configureer bucket/CDN-beleid voor de gegevens van uw product.

Test echt opslaggedrag

Test toegestane/geweigerde uploads, MIME en afwijzing van grootte, paden naar externe werkruimten, ontbrekende objecten en providerfouten. De geheugenmodus blijft niet bestaan ​​tussen processen; verifieer opslag en ophalen met de geselecteerde backend vóór release.

• Supabase-opslag instellen
• Route-inventaris uploaden

Setup en configuratie

packages/storage definieert de ObjectStorage-interface — put, get en delete op object-locators — met MemoryObjectStorage voor deterministische tests en S3CompatibleObjectStorage voor productiebuckets.

Object-keys worden gebouwd met buildWorkspaceObjectKey en gecheckt met assertWorkspaceObjectKey, zodat elk opgeslagen bestand genamespaceed is per workspace en doel (avatar, file, logo). WorkspaceScopedStorageError grijpt in wanneer een key zijn workspace ontvlucht.

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}

Implementatieworkflow

Applicatieroutes resolven de workspace, valideren de upload, bouwen de gescopede key en roepen de adapter aan — storage ziet nooit een ruw client-pad. Selecteer de adapter in de serveromgeving via STORAGE_PROVIDER en zijn credentials.

Exposeer lezingen via dezelfde autorisatiegrens; serveer publieke URL's alleen voor objecten die het product bewust publiceert.

Verificatie en probleemoplossing

MemoryObjectStorage houdt unit-tests deterministisch — assert keys, content-types en cross-workspace-denials daar. Verifieer de S3-adapter via de optionele smoke-route tegen een echte bucket voordat je uploads shipt.