Medien aus S3 in TYPO3?

typo3-fal-s3 — TYPO3-Dateien in S3, ohne Netzlaufwerk und ohne neue Adressen.

TYPO3 legt Bilder und Downloads im Ordner fileadmin ab. Liegt dieser Ordner in einem Objektspeicher wie Amazon S3, wird er bisher meist als Netzlaufwerk eingehängt. Das ist langsam, braucht Sonderrechte und bricht im falschen Moment. typo3-fal-s3 ist ein Speichertreiber für TYPO3, der direkt mit S3 spricht. Der Wechsel geschieht an Ort und Stelle: Dateien, Verweise und Adressen auf der Website bleiben, wie sie sind.

Was es ist: ein Treiber für die Dateiverwaltung von TYPO3 (FAL), der Amazon S3 und S3-kompatible Speicher anbindet
Für wen: Betreiber von TYPO3-Websites, die ihre Medien in S3 halten, zum Beispiel in Kubernetes ohne gemeinsame Festplatte
Technik: TYPO3-Extension · TYPO3 14.3+ · PHP 8.5+ · async-aws · MIT-Lizenz · Quellcode auf GitHub

Umstellung besprechen →

TL;DR — Passt das zu meinem Setup?

Nutze es wenn …

deine TYPO3-Website ihre Medien in einem S3-Bucket hält und ihn heute als Netzlaufwerk (FUSE-Mount) einhängt
mehrere Server oder Pods dieselben Dateien sehen sollen, ohne gemeinsame Festplatte
keine Zugangsschlüssel in TYPO3 stehen sollen; der Treiber nutzt die Identität des Servers oder Pods

Nutze es nicht wenn …

du noch TYPO3 13 oder älter betreibst; der Treiber setzt TYPO3 14.3 voraus
Dateien im Bucket in Archiv-Speicherklassen wie Glacier liegen; die lassen sich erst nach einer Wiederherstellung lesen
niemand die Dateien ausliefern kann; der Treiber verwaltet sie, ausliefern muss der Webserver oder ein CDN

Aufwand

Ein Composer-Paket, ein Befehl zum Umstellen des Speichers und der Name des Buckets. Der Weg zurück ist derselbe Befehl mit dem alten Treiber.

Warum kein Netzlaufwerk, und was der Treiber anders macht

Das Problem

Ein eingehängter Bucket tut so, als wäre S3 eine Festplatte. Jede Prüfung, ob eine Datei existiert, wird zu einer Anfrage übers Netz. Der Server braucht dafür erweiterte Rechte, und wenn das Laufwerk hängt, hängt die ganze Website. In Kubernetes kommt ein eigener Dienst auf jedem Knoten dazu, der nur das Laufwerk bereitstellt.

Die Lösung

typo3-fal-s3 spricht S3 direkt an, als Treiber in der Dateiverwaltung von TYPO3. Er behält die Ordnerstruktur des Buckets bei. Deshalb lässt sich ein bestehender Speicher umstellen, ohne dass TYPO3 eine Datei neu einlesen muss.

Was	Wie der Treiber es macht
Adressen der Dateien	bleiben gleich, standardmäßig `/fileadmin/…`
Zugang zu S3	über die Identität des Servers oder Pods, kein Schlüssel in TYPO3
Wiederholte Nachfragen	Antworten von S3 landen in einem gemeinsamen Cache; ein Ordner kostet eine Abfrage, nicht eine pro Datei
Zwei Server schreiben dieselbe Bildvariante	beide kommen durch, keiner überschreibt den anderen
Bildvarianten	liegen im Bucket und tragen eine lange Cache-Dauer
Fremde Daten im selben Bucket	werden ausgeblendet und sind schreibgeschützt

Im Betrieb

Seit Oktober 2026 läuft der Treiber auf vier TYPO3-Websites in Kubernetes. Vorher hing an jedem Pod ein Netzlaufwerk mit dem Bucket. Die Umstellung lief Website für Website, mit dem Laufwerk als Rückfall, bis alles sauber lief.

Die Pods haben kein fileadmin-Laufwerk mehr und brauchen keine Sonderrechte dafür.
Jede Website liest und schreibt mit einer eigenen Rolle, die nur ihren Bucket sieht.
Keine Datei musste neu eingelesen werden, keine Adresse hat sich geändert.

Ausgeliefert werden die Dateien vom Webserver der Website. Damit das schnell geht, hält caddy-fs-s3cache eine lokale Kopie vor.

fileadmin noch als Netzlaufwerk eingehängt? Ich helfe bei der Umstellung, den Rechten und der Auslieferung. Anfragen →

Einbau und Konfiguration

Für Betreiber einer TYPO3-14-Website. Drei Schritte.

1. Paket installieren

composer require koh/typo3-fal-s3

2. Bucket nennen

Jede Einstellung kann aus einer Umgebungsvariable kommen, dann bleibt der Datensatz in TYPO3 für alle Umgebungen gleich.

KOH_FAL_S3_BUCKET=my-media-bucket
KOH_FAL_S3_REGION=eu-north-1

3. Speicher umstellen

vendor/bin/typo3 koh_fal_s3:storage --uid 1 --driver KohS3
vendor/bin/typo3 cache:flush

Der Befehl merkt sich die alte Einstellung. --driver Local stellt sie wieder her.

Die wichtigsten Optionen

Option	Standard	Bedeutung
`bucket`	Pflicht	Name des S3-Buckets
`region`, `endpoint`, `pathStyle`	aus der AWS-Konfiguration	AWS-Region; eigener Endpunkt und Pfad-Adressierung für S3-kompatible Speicher wie MinIO oder RustFS
`keyPrefix`	leer	Nur ein Unterordner des Buckets wird zum Speicher
`publicBaseUri`	`/fileadmin/`	Unter welcher Adresse der Webserver die Dateien ausliefert
`excludedPrefixes`	einige bekannte Ordner	Bereiche des Buckets, die TYPO3 nicht sieht und nicht beschreibt
`malwareGate`	aus	Verweigert Dateien, die der Virenscan von AWS als gefährlich markiert hat
`fallbackProcessingFolder`	aus	Legt auch die Bildvarianten aus Extensions in den Bucket statt auf die lokale Platte

Rechte

Der Treiber braucht auf dem Bucket das Recht, ihn aufzulisten (s3:ListBucket). Fehlt es, meldet S3 für eine fehlende Datei „verboten“ statt „nicht gefunden“. Auf den Dateien braucht er Lesen, Schreiben und Löschen. Zugangsdaten stehen nicht in TYPO3. Sie kommen wie bei allen AWS-Werkzeugen aus der Umgebung oder in Kubernetes aus der Identität des Pods.

Häufige Fallstricke

Der Treiber liefert keine Dateien aus. Er erzeugt Adressen wie /fileadmin/bild.jpg. Unter dieser Adresse muss der Webserver die Datei aus dem Bucket holen, zum Beispiel mit caddy-fs-s3cache oder über ein CDN. Ohne diesen Teil gibt es nur leere Bilder.
Der gemeinsame Cache gehört in Redis oder Valkey. Standardmäßig liegt er in der Datenbank, das reicht zum Start. Ein Cache nur im Arbeitsspeicher lässt jeden Seitenaufruf S3 neu fragen.
Archiv-Speicherklassen sperren Dateien. Liegt eine Datei in Glacier oder einer Archivstufe von Intelligent-Tiering, lässt sie sich erst nach einer Wiederherstellung lesen. Für eine Website gehören diese Stufen ausgeschaltet.
Änderungen an TYPO3 vorbei sehen andere erst später. Was ein anderes System direkt in den Bucket schreibt, erkennt TYPO3 nach Ablauf des Caches, standardmäßig nach einem Tag. Die Frist ist einstellbar.

Nächster Schritt

fileadmin in S3 ohne Netzlaufwerk?

Wenn deine TYPO3-Website ihre Medien über ein eingehängtes Laufwerk aus S3 holt, hilft typo3-fal-s3. Ich unterstütze bei der Umstellung, bei den Rechten in AWS und bei der Auslieferung über den Webserver.