For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /de/docs/web/storage.md (or send Accept: text/markdown).

Datei-Storage

Workspace-scoped Uploads über den Object-Storage-Vertrag.

Zu dieser Anleitung fragen

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.

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.

Einrichtung und Konfiguration

STORAGE_PROVIDER wählt den Adapter: memory für Tests und lokale Entwicklung, s3 für jeden S3-kompatiblen Bucket (STORAGE_BUCKET, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_PUBLIC_BASE_URL). Credentials bleiben server-only.

packages/storage besitzt den ObjectStorage-Vertrag — putObject/getObject/deleteObject gegen Objekt-Locators — plus assertWorkspaceObjectKey und buildWorkspaceObjectKey, damit jedes gespeicherte Objekt nach Workspace und Zweck (Avatar, Datei, Logo) namespaced ist.

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

Implementierungsablauf

Halte Uploads hinter der authentifizierten Route-Schicht: Workspace auflösen, Content-Type und Größe validieren, den workspace-scoped Key bauen, dann über den Adapter speichern. Reads genauso ausliefern, außer ein Objekt ist bewusst öffentlich.

Avatare und Organisations-Logos haben dedizierte Routen mit eigener Validierung; beliebige Produkt-Dateien gehen über /objects mit deklariertem Zweck.

Überprüfung und Fehlerbehebung

Verifiziere, dass anonyme Uploads abgelehnt werden, ein Workspace die Objekt-Keys eines anderen nicht lesen kann, übergroße oder unzulässige Content-Types fehlschlagen und ein gelöschtes Objekt nicht mehr auflöst. Nutze den Memory-Adapter in Tests; verifiziere den echten Bucket über den Opt-in-Smoke-Pfad.