Binary Data: Filesystem/S3 statt Datenbank

n8n hält Binärdaten aus PDFs, Bildern und Anhängen standardmäßig im Arbeitsspeicher. Für produktive Instanzen stellen Sie das über die Umgebungsvariable N8N_DEFAULT_BINARY_DATA_MODE um: auf filesystem bei einer einzelnen Instanz, auf database, s3 oder azure im Queue-Modus.

Dieser Artikel vergleicht die fünf Modi, zeigt die zugehörigen Umgebungsvariablen als lauffähige docker-compose-Konfiguration und benennt die Fallstricke bei der Umstellung.

Warum die Voreinstellung im Produktivbetrieb nicht reicht

Die Voreinstellung default legt jede Datei im Arbeitsspeicher des n8n-Prozesses ab, was laut Dokumentation zur Verarbeitung von Binärdaten bei großen Dateien zu Abstürzen führt.

Der Speicherbedarf steigt dabei nicht mit der Zahl der Workflows, sondern mit der Zahl gleichzeitiger Ausführungen. Ein einzelner Stapel mit 50 Rechnungs-PDFs kann eine Instanz mit 1 GB RAM bereits an ihre Grenze bringen.

Der naheliegende Ausweg, alles in die Datenbank zu schreiben, hat eigene Kosten. Eine relationale Datenbank ist für viele kleine Zeilen ausgelegt, nicht für große Blobs. Backups, Replikation und Abfragen werden spürbar langsamer.

Hinzu kommt eine harte Grenze: N8N_BINARY_DATA_DATABASE_MAX_FILE_SIZE steht auf 512 MiB und darf laut Dokumentation 1024 MiB nicht überschreiten. Größere Dateien scheitern.

Welche Speichermodi gibt es und wann passt welcher?

n8n kennt fünf Modi, die Sie über N8N_DEFAULT_BINARY_DATA_MODE setzen. Die Wahl hängt an zwei Fragen: Läuft die Instanz im Queue-Modus, und liegt eine Lizenz für externen Speicher vor?

Wert | Speicherort | Queue-Modus | Lizenz nötig | Geeignet für

Wert: default · Speicherort: Arbeitsspeicher · Queue-Modus: ja · Lizenz nötig: nein · Geeignet für: Tests, kleine Dateien

Wert: filesystem · Speicherort: lokale Festplatte · Queue-Modus: nein · Lizenz nötig: nein · Geeignet für: einzelne Self-Hosted-Instanz

Wert: database · Speicherort: Postgres oder SQLite · Queue-Modus: ja · Lizenz nötig: nein · Geeignet für: Queue-Modus ohne externen Speicher

Wert: s3 · Speicherort: S3-kompatibler Objektspeicher · Queue-Modus: ja · Lizenz nötig: ja · Geeignet für: verteilte Setups, große Dateien

Wert: azure · Speicherort: Azure Blob Storage · Queue-Modus: ja · Lizenz nötig: ja · Geeignet für: Microsoft-lastige Umgebungen

Der Filesystem-Modus ist für die meisten Mittelstandsinstanzen der richtige erste Schritt. Er kostet nichts, braucht keine Lizenz und nimmt den Arbeitsspeicher sofort aus der Gefahrenzone.

Wichtig: n8n unterstützt den Filesystem-Modus laut Dokumentation nicht im Queue-Modus. Wer mit mehreren Workern arbeitet, muss auf database, s3 oder azure ausweichen.

Wie aktivieren Sie den Filesystem-Modus?

Sie setzen N8N_DEFAULT_BINARY_DATA_MODE=filesystem und starten die Instanz neu. Optional legen Sie den Ablageort über N8N_BINARY_DATA_STORAGE_PATH fest, standardmäßig ist das N8N_USER_FOLDER/binaryData.

Drei Variablen sind laut Dokumentation zu den Binärdaten-Variablen relevant. N8N_AVAILABLE_BINARY_DATA_MODES steht standardmäßig auf filesystem und listet die überhaupt erlaubten Modi.

Die folgende docker-compose-Datei ist vollständig und lauffähig. Entscheidend ist das benannte Volume: ohne es verschwinden alle Binärdaten beim nächsten Container-Neustart.

1services:
2  n8n:
3    image: docker.n8n.io/n8nio/n8n:2.36.9
4    restart: unless-stopped
5    ports:
6      - "127.0.0.1:5678:5678"
7    environment:
8      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
9      - N8N_AVAILABLE_BINARY_DATA_MODES=filesystem
10      - N8N_BINARY_DATA_STORAGE_PATH=/home/node/.n8n/binaryData
11    volumes:
12      - n8n_data:/home/node/.n8n
13
14volumes:
15  n8n_data:
Copy

Planen Sie den Plattenplatz großzügig. n8n räumt Binärdaten nur zusammen mit den zugehörigen Ausführungen auf, und das nur im aktuell aktiven Modus.

Wie richten Sie den S3-Modus ein?

Der S3-Modus lagert Binärdaten in einen S3-kompatiblen Objektspeicher aus und setzt laut Dokumentation zur externen Speicherung einen gültigen Lizenzschlüssel voraus. Verfügbar ist er auf den Self-Hosted-Plänen Business und Enterprise, nicht auf n8n Cloud.

Ohne aktive Lizenz startet die Instanz im Modus s3 gar nicht erst. Aktivieren Sie den Lizenzschlüssel also vor der Umstellung, nicht danach.

Fünf Variablen beschreiben den Bucket. N8N_EXTERNAL_STORAGE_S3_AUTH_AUTO_DETECT schaltet stattdessen auf die Standard-Credential-Chain um, etwa für eine IAM-Rolle, und ignoriert dann Key und Secret.

1services:
2  n8n:
3    image: docker.n8n.io/n8nio/n8n:2.36.9
4    restart: unless-stopped
5    environment:
6      - N8N_AVAILABLE_BINARY_DATA_MODES=filesystem,s3
7      - N8N_DEFAULT_BINARY_DATA_MODE=s3
8      - N8N_EXTERNAL_STORAGE_S3_HOST=s3.eu-central-1.amazonaws.com
9      - N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME=n8n-binary-data
10      - N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION=eu-central-1
11      - N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY=${S3_ACCESS_KEY}
12      - N8N_EXTERNAL_STORAGE_S3_ACCESS_SECRET=${S3_ACCESS_SECRET}
13    volumes:
14      - n8n_data:/home/node/.n8n
15
16volumes:
17  n8n_data:
Copy

Die Zugangsdaten stehen bewusst nicht in der Compose-Datei, sondern in einer separaten .env neben ihr. Die Dokumentation zeigt eine Beispiel-Policy mit s3:* auf dem Bucket.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Sid": "n8nBinaryData",
6      "Effect": "Allow",
7      "Action": ["s3:*"],
8      "Resource": [
9        "arn:aws:s3:::n8n-binary-data",
10        "arn:aws:s3:::n8n-binary-data/*"
11      ]
12    }
13  ]
14}
Copy

n8n legt die Objekte unter workflows/{workflowId}/executions/{executionId}/binary_data/{binaryFileId} ab. Diese Struktur brauchen Sie für die Lifecycle-Regel im nächsten Abschnitt.

Für Azure Blob Storage gilt dasselbe Lizenzmodell. Statt der S3-Variablen setzen Sie dann N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME sowie eine Connection String oder ein Paar aus Account-Name und Account-Key.

Was ist bei der Migration zu beachten?

n8n delegiert das Aufräumen im S3-Modus vollständig an den Objektspeicher, deshalb ist eine Lifecycle-Regel im Bucket laut Dokumentation Pflicht. Ohne sie wächst der Speicher unbegrenzt.

Der zweite Stolperstein steht ausdrücklich in der Dokumentation: Das Pruning wirkt nur auf den aktuell aktiven Modus. Wechseln Sie von s3 zurück auf filesystem, bleiben die alten Objekte im Bucket liegen.

Vier Schritte in dieser Reihenfolge haben sich bewährt:

1. Lizenzschlüssel aktivieren, sofern s3 oder azure das Ziel ist.
2. Bucket samt IAM-Policy und Lifecycle-Regel anlegen.
3. Variablen setzen und die Instanz neu starten.
4. Den alten Speicherort separat bereinigen, denn n8n migriert nichts.

NordFlux unterstützt bei der n8n-Einrichtung inklusive einer Speicherkonfiguration, die zum tatsächlichen Datenvolumen passt.

Typische Fehler und Ursachen

Fünf Fehlerbilder treten bei der Umstellung besonders häufig auf.

Die Instanz startet nach der Umstellung auf `s3` nicht mehr.

Ursache: Es liegt kein gültiger Lizenzschlüssel vor. Lösung: Lizenz aktivieren oder N8N_DEFAULT_BINARY_DATA_MODE vorübergehend auf filesystem beziehungsweise database zurücksetzen. Quelle: Externe Speicherung.

Binärdaten verschwinden nach jedem Container-Neustart.

Ursache: Der Pfad aus N8N_BINARY_DATA_STORAGE_PATH liegt im Container, nicht in einem persistenten Volume. Lösung: Den Pfad unterhalb des gemounteten .n8n-Volumes wählen. Quelle: Binärdaten-Variablen.

Im Queue-Modus mit mehreren Workern schlagen Ausführungen mit fehlenden Dateien fehl.

Ursache: Der Modus steht auf filesystem, den n8n im Queue-Modus nicht unterstützt. Jeder Worker sähe nur seine eigene Platte. Lösung: Auf database, s3 oder azure wechseln. Quelle: Binärdaten verarbeiten.

Der S3-Bucket wächst dauerhaft, obwohl alte Ausführungen gelöscht sind.

Ursache: Es fehlt die Lifecycle-Regel, denn n8n überlässt das Pruning dem Objektspeicher. Lösung: Eine Ablaufregel auf dem Präfix workflows/ setzen. Quelle: Externe Speicherung.

Der Upload einer großen Datei scheitert im Modus `database`.

Ursache: Die Datei überschreitet N8N_BINARY_DATA_DATABASE_MAX_FILE_SIZE mit Standardwert 512 MiB. Lösung: Den Wert bis maximal 1024 MiB anheben oder auf externen Speicher wechseln. Quelle: Binärdaten-Variablen.

Häufige Fragen zu Binärdaten in n8n

Was ist der Unterschied zwischen Filesystem- und S3-Modus?

Der Filesystem-Modus schreibt Binärdaten auf die lokale Festplatte des n8n-Servers und passt zu einzelnen Instanzen außerhalb des Queue-Modus. Der S3-Modus lagert sie in einen externen Objektspeicher aus, den mehrere Worker gemeinsam nutzen. Dafür braucht er eine Lizenz.

Brauche ich für den S3-Modus zwingend eine Lizenz?

Ja. Ohne gültigen Lizenzschlüssel startet die Instanz im Modus s3 laut Dokumentation nicht. Verfügbar ist der Modus auf den Self-Hosted-Plänen Business und Enterprise, nicht auf n8n Cloud. Für kleinere Setups reicht der kostenlose Filesystem-Modus.

Funktioniert der Filesystem-Modus auch im Queue-Modus?

Nein. n8n unterstützt diese Kombination nicht. Betreiber mit mehreren Workern verwenden stattdessen database oder, mit passender Lizenz, s3 beziehungsweise azure.

Was passiert mit bereits gespeicherten Binärdaten beim Wechsel des Modus?

Sie werden weder migriert noch gelöscht. Das Pruning arbeitet immer nur auf dem aktiven Modus. Alte Dateien im vorherigen Speicherort bleiben liegen und müssen manuell bereinigt werden.