Bestandsopslag instellen

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

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

1. STORAGE_PROVIDER=memory (de default) houdt uploads in-process — passend bij ontwikkeling en tests.

2. Zet voor echte bestanden STORAGE_PROVIDER=s3 met een bucket en een access-key-paar. STORAGE_ENDPOINT selecteert elke S3-compatibele dienst — Supabase Storage op https://<ref>.supabase.co/storage/v1/s3, MinIO of AWS zelf.

3. STORAGE_FORCE_PATH_STYLE staat standaard op true zodra een endpoint is gezet — Supabase en MinIO vereisen dat. Zet het alleen op false voor een virtual-hosted custom endpoint.

4. Wijs STORAGE_PUBLIC_BASE_URL optioneel naar een CDN zodat publieke object-URL's daar resolven.

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

Implementatieworkflow

Uploads en lezingen lopen via geauthenticeerde routes die eerst de workspace resolven — /api/storage/objects plus de dedicated avatar- en logo-routes. Elke opgeslagen key is genamespaceed als {workspaceId}/{purpose}/{safeName} via buildWorkspaceObjectKey.

Credentials blijven server-only; de browser ziet de bucket of keys nooit.

Uploads werken? Ga verder naar Observability instellen.

Verificatie en probleemoplossing

Verifieer dat een upload rondreist, dat een tweede workspace het object niet kan lezen en dat te grote of niet-toegestane content-types falen. Signature- of 403-fouten tegen Supabase of MinIO betekenen meestal dat STORAGE_FORCE_PATH_STYLE verkeerd staat voor het endpoint.