Datei-Storage einrichten

Schritt-für-Schritt für Einsteiger

Voraussetzungen: Lesen Sie die beiden folgenden Einsteigerhandbücher, schließen Sie die lokale Web-Einrichtung ab und öffnen Sie dieses Monorepo im Stammverzeichnis in Ihrem Editor. Webeinstellungen gehören in apps/web/.env.local; Next.js liest das Stammverzeichnis .env nicht. /dashboard im Standard-Fake-Modus ist eine Demo ohne Datenbank; /auth benötigt eine migrierte Datenbank.

Kurze Begriffe: Ein Arbeitsbereich umfasst die einzelnen Benutzer, Daten und Einstellungen eines Teams. Der Server ist das vertrauenswürdige Backend; Halten Sie Anbieterschlüssel aus Browser- und Telefoncodes fern. Eine Migration ist eine versionierte Datenbankänderung, die Tabellen erstellt oder aktualisiert. Ein KI-Modell ist der Motor, der antwortet; Der Modellkatalog ist die Liste der verfügbaren Modell-IDs und Preise des Servers. Ein Anbieter ist ein externer Dienst wie ein KI-, E-Mail- oder Abrechnungsdienst. Eine Berechtigung ist eine Bewilligung, die einem Arbeitsbereich die Nutzung einer Funktion ermöglicht. Ein Webhook ist eine Nachricht, die ein Dienst an den URL eines anderen Dienstes sendet.

1. Für eine Testversion ohne Anmeldeinformationen behalten Sie STORAGE_PROVIDER=memory. Wenn dieser Checkout über keine sichtbare Upload-Kontrolle verfügt, bitten Sie Ihren Programmierer, 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 und die entsprechende Einstellungsseite zu überprüfen, bevor Sie ein kleines Beispielbild verbinden.

2. Um die Persistenz zu überprüfen, legen Sie STORAGE_PROVIDER=s3, STORAGE_REGION und STORAGE_BUCKET in apps/web/.env.local fest, fügen Sie lokal nur serverbasierte Testanmeldeinformationen hinzu und starten Sie neu.

3. Das Bild sollte aus dem Speicher neu geladen werden. Speicherdateien verschwinden, wenn der Prozess neu startet; Überprüfen Sie bei S3-Fehlern Bucket, Endpunkt und Zugriffsrichtlinie.

Beginnen Sie für benutzerdefinierten Code mit dem bereitgestellten prompts/README.md und kopieren Sie die nächstgelegene Eingabeaufforderung: prompts/new-app-screen.md für einen App-Bildschirm oder prompts/new-landing-page.md für eine öffentliche Seite. Geben Sie Ihrem Programmieragenten für Server-, Datenbank- oder Anbieterarbeiten die Aufgabe dieses Handbuchs und bitten Sie ihn, AGENTS.md, .ai/PROJECT_CONTEXT.md und passende .ai/-Spiegel zu lesen; Überprüfen Sie die hier genannten genauen Quelldateien. Listen Sie Dateien auf und prüfen Sie sie vor der Bearbeitung. Bewahren Sie den Arbeitsbereichseigentum und die Nur-Server-Geheimnisse. und zeige dir den Unterschied. Teilen Sie ihm das gewünschte Verhalten, Eingabe- und Ausgabefelder, zulässige Rollen, erwartete Erfolge und Fehler sowie das Testkonto, den Anbieter oder das Gerät mit. Beispielwerte verwenden; Fügen Sie niemals ein echtes Geheimnis ein.

• Bevor Sie beginnen
• Terminal-Grundlagen
• Lokales Web-Setup
• Agentenaufforderungen und Projektspeicher

Speicher-Backend auswählen

STORAGE_PROVIDER=memory ist der Standard ohne Anmeldeinformationen. local schreibt Objekte unter STORAGE_LOCAL_DIR auf die Festplatte (Standard ./.data/storage, in der Produktion explizit erforderlich) und streamt sie über HMAC-signierte, ablaufende URLs unter /api/storage/local/[...key] (STORAGE_LOCAL_SIGNING_SECRET, fällt auf AUTH_SECRET zurück) für Einzelserver-Deployments. s3 verwendet apps/web/src/storage-runtime.ts, um den AWS-SDK-Client über den schlanken @supastack/storage-Vertrag zusammenzusetzen, und unterstützt Supabase Storage und MinIO standardmäßig mit Pfad-URLs.

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

Vorhandene Upload-Grenzen verwenden

Die bereitgestellten Routen decken Objekte, Avatare, Profil- und Organisationslogos unter /api/storage/ ab. Sie lösen Identität und Workspace-Berechtigungen auf und prüfen die Upload-Form vor dem Speichern. Prüfen Sie die Größen- und Typregeln der gewählten Route, statt beliebige Client-Objektschlüssel zu akzeptieren.

Öffentliche URLs dienen der Darstellung und nicht der Autorisierung. Halten Sie geschützte Inhalte hinter der verifizierten Lesegrenze der Anwendung und konfigurieren Sie Bucket- und CDN-Richtlinien passend zu den Produktdaten.

Verhalten des echten Speichers überprüfen

Testen Sie erlaubte und verweigerte Uploads, Ablehnungen nach MIME-Typ oder Größe, Pfade fremder Workspaces, fehlende Objekte und Provider-Ausfälle. Der Speichermodus memory bleibt nicht über Prozesse hinweg erhalten; prüfen Sie vor der Veröffentlichung Speicherung und Abruf mit dem ausgewählten Backend.

• Supabase-Speicher-Setup
• Routeninventar hochladen

Einrichtung und Konfiguration

1. STORAGE_PROVIDER=memory (der Default) hält Uploads im Prozess — richtig für Entwicklung und Tests.

2. Für echte Dateien setze STORAGE_PROVIDER=s3 mit Bucket und Access-Key-Paar. STORAGE_ENDPOINT wählt jeden S3-kompatiblen Dienst — Supabase Storage unter https://<ref>.supabase.co/storage/v1/s3, MinIO oder AWS selbst.

3. STORAGE_FORCE_PATH_STYLE ist standardmäßig true, sobald ein Endpoint gesetzt ist — Supabase und MinIO verlangen es. Setze es nur bei einem Virtual-Hosted-Custom-Endpoint auf false.

4. Zeige STORAGE_PUBLIC_BASE_URL optional auf ein CDN, damit öffentliche Objekt-URLs dort auflösen.

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

Implementierungsablauf

Uploads und Reads laufen über authentifizierte Routen, die zuerst den Workspace auflösen — /api/storage/objects plus die dedizierten Avatar- und Logo-Routen. Jeder gespeicherte Key ist als {workspaceId}/{purpose}/{safeName} über buildWorkspaceObjectKey namespaced.

Credentials bleiben server-only; der Browser sieht nie Bucket oder Keys.

Uploads laufen? Weiter zu Observability einrichten.

Überprüfung und Fehlerbehebung

Verifiziere, dass ein Upload den Roundtrip schafft, ein zweiter Workspace das Objekt nicht lesen kann und übergroße oder unzulässige Content-Types fehlschlagen. Signatur- oder 403-Fehler gegen Supabase oder MinIO bedeuten meist, dass STORAGE_FORCE_PATH_STYLE falsch für den Endpoint ist.