> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Storage-Modul

Ein ObjectStorage-Vertrag, Memory- und S3-kompatible Adapter.

## 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](https://supastack.dev/de/docs/web/before-you-start.md)

[Terminal-Grundlagen](https://supastack.dev/de/docs/web/terminal-basics.md)

[Lokales Web-Setup](https://supastack.dev/de/docs/web/ship-in-5-minutes.md)

[Agentenaufforderungen und Projektspeicher](https://supastack.dev/de/docs/web/agents.md)


## 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=
```


## 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](https://supastack.dev/de/docs/web/project-structure.md)

[Routeninventar hochladen](https://supastack.dev/de/docs/web/project-structure.md)


## Einrichtung und Konfiguration

packages/storage definiert das ObjectStorage-Interface — putObject, getObject und deleteObject gegen Objekt-Locators — mit MemoryObjectStorage für deterministische Tests und S3CompatibleObjectStorage für Produktions-Buckets.

Objekt-Keys werden mit buildWorkspaceObjectKey gebaut und mit assertWorkspaceObjectKey geprüft, sodass jede gespeicherte Datei nach Workspace und Zweck (Avatar, Datei, Logo) namespaced ist. WorkspaceScopedStorageError feuert, wenn ein Key seinen Workspace verlässt.

```
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}
```


## Implementierungsablauf

Anwendungs-Routen lösen den Workspace auf, validieren den Upload, bauen den gescopten Key und rufen den Adapter — Storage sieht nie einen rohen Client-Pfad. Wähle den Adapter im Server-Environment über STORAGE_PROVIDER und seine Credentials.

Exponiere Reads über dieselbe Autorisierungsgrenze; liefere Public-URLs nur für Objekte aus, die das Produkt bewusst veröffentlicht.


## Überprüfung und Fehlerbehebung

MemoryObjectStorage hält Unit-Tests deterministisch — asserte Keys, Content-Types und Cross-Workspace-Verweigerungen dort. Verifiziere den S3-Adapter über den Opt-in-Smoke-Pfad gegen einen echten Bucket, bevor du Uploads shipst.


## Weiter

[API-Modul](https://supastack.dev/de/docs/modules/api.md)