Wichtigste Erkenntnisse
- Wählen Sie das Speichermodell vor dem Anbieter: Objektspeicher, kollaborativer Dateispeicher und Dateiübertragungsserver lösen unterschiedliche betriebliche Probleme.
- Behandeln Sie Import und Export als getrennte Vertrauensgrenzen, mit Template-Zugangsdaten nach dem Prinzip der geringsten Rechte nur für die Pfade und Aktionen, die jeder Workflow benötigt.
- Schließen Sie nicht von einer zurückgegebenen URL auf öffentlichen Zugriff; Bucket-Richtlinien, Freigabeeinstellungen, signierte URLs und Serverberechtigungen entscheiden, ob ein Ergebnis abrufbar ist.
Die Wahl einer Speicherintegration ist eine Architekturentscheidung, keine Suche nach einem Anbieternamen. Objektspeicher, kollaborative Dateidienste und Dateiübertragungsserver bieten unterschiedliche Berechtigungsmodelle, URL-Garantien, Listenverhalten und Fehlermodi. Dieser Leitfaden gruppiert die unterstützten Ziele nach diesen Unterschieden, sodass Sie einen Workflow bewusst wählen können, statt nahezu identische Beispiele zu kopieren.
Worauf es besonders ankommt
- Planen Sie große Ordnerimporte anhand des Rekursions- und Paginierungsvertrags, den der jeweilige Robot vorgibt, statt anzunehmen, dass jeder Anbieter Baumstrukturen gleich auflistet.
- Behalten Sie stabile Asset-Bezeichner und Assembly-IDs in Ihrer Anwendung, da sich Dateinamen, Ordner, Links und Anbieter-Metadaten unabhängig voneinander ändern können.
Beim Speichermodell beginnen, nicht beim Anbieter-Logo
Objektspeicher eignet sich naturgemäß für anwendungseigene Medienbibliotheken. Amazon S3, Azure Blob Storage, Backblaze B2, Cloudflare R2, DigitalOcean Spaces, Google Cloud Storage, MEGA S4 Object Storage, MinIO, OpenStack Swift, Supabase Storage, Tigris, Wasabi und Rackspace Cloud Files bieten Bucket- oder Container-orientierte Ziele über eigene Transloadit-Robots. Sie unterscheiden sich dennoch bei Zugangsdaten, Endpunkt- oder Regionsfeldern, Zugriffskontrollen und Ergebnis-URLs, daher beschreibt „Objektspeicher“ die Architektur und kein gemeinsames Konfigurationsformat.
Box und Dropbox sind konten- und ordnerorientierte Cloud-Dateidienste. Ihre Ordner, Links und nutzerseitigen Berechtigungssysteme können wertvoll sein, wenn Personen direkt mit exportierten Dateien arbeiten. FTP und SFTP richten sich dagegen an Dateiübertragungsserver und bestehende Dateisystemkonventionen. Wählen Sie diese Modelle, weil ein Partner oder ein Altsystem sie erfordert, nicht weil ihre Pfadangaben zufällig Objektschlüsseln ähneln.
Objektspeicher
Bevorzugen Sie dieses Modell für Anwendungs-Assets, die über stabile Schlüssel, Lebenszyklusregeln und anbietergesteuerte Bucket- oder Container-Richtlinien adressiert werden.
Kollaborativer Speicher
Bevorzugen Sie Box oder Dropbox, wenn Kontoordner und vom Anbieter verwaltete Links Teil des geforderten Produkterlebnisses sind.
Dateiübertragung
Bevorzugen Sie SFTP oder FTP, wenn das empfangende System durch ein Serverkonto, einen Verzeichnisbaum und einen etablierten Übertragungsvertrag definiert ist.
Jedes Ziel dem passenden Transloadit-Robot-Paar zuordnen
Der Zielname entspricht jeweils einem Import-Robot und einem Speicher-Robot: /s3/import und /s3/store, /azure/import und /azure/store, /backblaze/import und /backblaze/store, /box/import und /box/store, /cloudflare/import und /cloudflare/store, /digitalocean/import und /digitalocean/store sowie /dropbox/import und /dropbox/store. Dieselbe Paarung gilt für /ftp, /google, /mega, /minio, /sftp, /supabase, /swift, /tigris, /wasabi und /cloudfiles, etwa /sftp/import mit /sftp/store.
Ein Import-Robot erstellt Dateien, die spätere Steps verarbeiten können. Ein Speicher-Robot verwendet ausgewählte Ergebnisse von Steps und schreibt sie an das Ziel. Diese Richtung ist beim Entwurf von Berechtigungen und Beobachtbarkeit entscheidend: Eine erfolgreiche Transformation belegt keinen erfolgreichen Export, und ein erfolgreicher Import belegt nicht, dass die Quelle nach der Verarbeitung verfügbar bleibt. Erfassen Sie den Endzustand der Assembly und prüfen Sie das Ergebnis des Speicher-Steps, von dem Sie tatsächlich abhängen.
Explizite Eingaben
Die use-Beziehung wählt die vorgelagerten Dateien aus; der Speicher-Robot exportiert nicht automatisch jedes Ergebnis der Assembly.
Explizites Ziel
Ein anbieterspezifischer Step ist die Grenze, an der Pfad-, Zugriffs-, Metadaten- und Zugangsdaten-Anforderungen Teil des Workflow-Vertrags werden.
Expliziter Abschluss
Die Anwendung sollte ein Asset erst dann als dauerhaft kennzeichnen, wenn das erforderliche Speicherergebnis abgeschlossen und seine Zielidentität erfasst wurde.
Speicherzugangsdaten eingegrenzt und serverseitig kontrolliert halten
Erstellen Sie den Anbieterzugriff in Template-Zugangsdaten und referenzieren Sie den Datensatz namentlich aus einem gespeicherten Template. Der Anbieter bestimmt weiterhin, was diese Zugangsdaten dürfen. Beschränken Sie sie auf die kleinstmöglichen Quell- und Zielpfade, Operationen, Buckets, Container oder Ordner, die der Workflow benötigt. Unterstützt ein Anbieter getrennte Lese- und Schreib-Zugangsdaten, sorgt die Trennung für eine sauberere Widerrufsgrenze und verringert die Auswirkung eines fehlerhaften Templates.
Senden Sie keine rohen Anbieterschlüssel in Assembly Instructions, die der Browser kontrolliert, und verwenden Sie keine Client-Felder, um ein uneingeschränktes Ziel auszuwählen. Vertrauenswürdiger Servercode sollte den Nutzer autorisieren, ein geprüftes Template wählen und nur begrenzte Geschäftsfelder wie einen Asset-Bezeichner liefern. Wenn mehrere Mandanten oder Ziele sich eine Workflow-Form teilen, halten Sie die Zuordnung von Mandant zu genehmigtem Template oder Zugangsdaten an dieser vertrauenswürdigen Grenze.
Geringste Rechte
Gewähren Sie Auflisten und Lesen nur dort, wo ein Import sie benötigt, und Schreiben nur dort, wo ein Export Objekte erstellen darf.
Vertrauensdomänen trennen
Verwenden Sie unterschiedliche Zugangsdaten, wenn Umgebungen, Mandanten, Quellpräfixe oder Zielberechtigungen unabhängig voneinander widerrufen werden sollen.
Vertrauenswürdige Auswahl
Halten Sie beliebige Robot-Namen, Endpunkt-Hosts und die Wahl der Zugangsdaten aus Anfragen heraus, die von einem nicht vertrauenswürdigen Browser oder Agenten gesteuert werden.
Öffentliche, private, signierte und benutzerdefinierte URL-Auslieferung bewusst gestalten
Anbieterintegrationen nutzen kein gemeinsames Vokabular für Zugriffskontrolle. Amazon S3 bietet sowohl acl als auch sign_urls_for, während Cloudflare R2 sign_urls_for, aber keine acl-Option bietet. Azure verwendet Shared-Access-Signaturen. Beim Amazon-S3-Robot lautet der Standardwert public-read; bei einem Bucket mit aktiviertem Block Public Access kann dieser Standard mit einem Berechtigungsfehler fehlschlagen, statt das Objekt zu veröffentlichen. Verwenden Sie für private S3-Auslieferung private bei Buckets, die Objekt-ACLs berücksichtigen, oder bucket-default, wenn ACLs deaktiviert sind oder Block Public Access aktiviert ist. Der Wert bucket-default überlässt die Entscheidung der Bucket-Richtlinie und macht s3:PutObjectAcl überflüssig. Beim Wasabi-Speicher-Robot wird ein nicht gesetztes acl standardmäßig auf private gesetzt; setzen Sie public-read nur explizit für öffentliche Wasabi-Auslieferung. Wasabi unterstützt bucket-default nicht. Box und Dropbox können Freigabelinks des jeweiligen Anbieters erstellen. Andere Ziele hängen primär von der Bucket-, Container-, Ordner- oder Serverkonfiguration ab, die nicht im Assembly Step, sondern separat vorgenommen wird.
Berechtigung und Adressgenerierung sind getrennte Fragen. Ein URL-Präfix oder eine URL-Vorlage kann dafür sorgen, dass ein Ergebnis auf einen CDN- oder Anwendungs-Hostnamen verweist, aber das Umschreiben einer Adresse konfiguriert nicht den Ursprung, gewährt keinen Lesezugriff und kopiert die Datei nicht. Umgekehrt kann ein privates Objekt eine syntaktisch gültige URL haben, die korrekt einen Autorisierungsfehler zurückgibt. Prüfen Sie den genauen Konsumentenpfad, das Ablaufverhalten und die Widerrufslogik des gewählten Anbieters.
Öffentliche Objekte
Verwenden Sie Anbieterrichtlinien oder eine explizite ACL erst, nachdem Sie entschieden haben, ob anonymer Abruf tatsächlich Teil des Produktvertrags ist.
Signierter Zugriff
Testen Sie bei kontrolliertem Zugriff den Signaturablauf, Zeitabweichungen (Clock Skew), zwischengespeicherte Antworten und das Verhalten, nachdem ein Objekt ersetzt oder gelöscht wurde.
Benutzerdefinierte URLs
Behandeln Sie CDN-Hostnamen und benutzerdefinierte URL-Vorlagen als Routing-Konfiguration, die mit den tatsächlichen Leserechten des Anbieters übereinstimmen muss.
Einen klaren Export-Step aufbauen, bevor Anbietervarianten hinzukommen
Ein Speicher-Workflow sollte seinen Datenfluss offensichtlich machen. Das folgende Template nimmt einen Upload entgegen, erstellt ein begrenztes WebP-Derivat und exportiert nur dieses Derivat zu Cloudflare R2. Der Name der Zugangsdaten wird innerhalb des Transloadit-Kontos aufgelöst, während der Pfad Assembly Variables verwendet, um vom Client ausgewählte Anbieterschlüssel zu vermeiden. Ein produktives Template sollte zusätzlich die Validierung, Benennung, Metadaten und Überschreibungsrichtlinie enthalten, die die Anwendung benötigt.
Dieselbe Graphform kann als Orientierung für ein anderes Ziel dienen, doch der Anbieter-Step ist keine einfach austauschbare Konfiguration. Ersetzen Sie den Speicher-Robot erst, nachdem Sie dessen Schema gelesen und entschieden haben, wie Zugangsdaten, Bucket- oder Ordnerauswahl, Zugriff, URLs und Kollisionen funktionieren sollen. Behalten Sie separate, geprüfte Templates bei, wenn die Unterschiede betrieblich wichtig sind, auch wenn ihre Transformations-Steps identisch bleiben.
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"optimized": {
"use": ":original",
"robot": "/image/resize",
"resize_strategy": "fit",
"width": 1600,
"height": 1600,
"format": "webp"
},
"exported": {
"use": "optimized",
"robot": "/cloudflare/store",
"credentials": "my-r2-credentials",
"path": "media/${assembly.id}/${file.id}.${file.ext}"
}
}
}Ordnerimporte als fortsetzbare Bestandsarbeit behandeln
Ein Import einer einzelnen Datei kann den schwierigen Teil einer Migration verbergen. Anbieter unterscheiden sich darin, wie Ordner oder Präfixe dargestellt werden, ob die Traversierung standardmäßig rekursiv oder optional ist, wie viele Einträge eine Seite zurückgibt und welcher Fortsetzungswert die nächste Seite anfordert. Lesen Sie das Schema des gewählten Import-Robots und testen Sie ein verschachteltes Fixture, das größer als eine Seite ist, bevor Sie sich für ein Backfill darauf verlassen.
Halten Sie Migrationsabsicht und Fortschritt in Ihrem eigenen System fest. Erfassen Sie die Quellidentität, die aktuelle Seite oder den aktuellen Batch, die erwartete Zielidentität, die Assembly-ID und das Endergebnis. Wiederholen Sie Vorgänge bei Fehlschlägen idempotent und gleichen Sie Zählungen ab, statt anzunehmen, dass ein erneutes Auflisten eines stetig wachsenden Root-Verzeichnisses jedes fehlende Objekt kostengünstig findet. Bevorzugen Sie für die fortlaufende Datenaufnahme dauerhafte Ereignisse oder ein datenbankgestütztes Manifest gegenüber wiederholten vollständigen Bucket-Scans.
Repräsentative Fixtures
Testen Sie leere Ordner, verschachtelte Namen, ungewöhnliche Zeichen, doppelte Basisnamen und ein Listing, das mindestens eine Seitengrenze überschreitet.
Dauerhafte Kontrollpunkte
Speichern Sie den Fortschritt außerhalb des Prozesses, damit ein Worker-Neustart kein vollständiges erneutes Auflisten erzwingt oder die aktuelle Seite stillschweigend überspringt.
Abgleich
Vergleichen Sie erwartete Quelldatensätze mit abgeschlossenen Zieldatensätzen und weisen Sie fehlende, doppelte oder überholte Objekte explizit aus.
Wiederherstellung nach Fehlern und Lebenszyklus-Zuständigkeit validieren
Testen Sie falsche Zugangsdaten, eine fehlende Quelle, einen nicht erreichbaren Endpunkt, einen verweigerten Zielpfad, eine Namenskollision, eine abgelaufene Signatur und einen teilweisen Mehrdateiexport. Benachrichtigungen können wiederholt werden, daher muss die Behandlung des Abschlusses idempotent sein. Verknüpfen Sie die Assembly-ID mit dem Anwendungs-Asset und legen Sie fest, welche Endzustände automatisch wiederholt werden dürfen, eine manuelle Prüfung erfordern oder die Quelle unangetastet lassen sollten.
Exportierter Speicher und der temporäre Speicher von Transloadit unterliegen unterschiedlicher Verantwortung und unterschiedlichen Lebenszyklen. Ein abgeschlossenes Assembly-Ergebnis ist kein Backup, und das Löschen eines Anwendungsdatensatzes löscht nicht automatisch Kopien bei jedem Anbieter, Cache oder temporärem Verarbeitungsort. Dokumentieren Sie Aufbewahrung, Ersetzung und Löschung für Quelle, Derivat, Ergebnismetadaten und öffentliche Adresse, und testen Sie diese Vorgänge ebenso sorgfältig wie den ursprünglichen Erfolgspfad.
Duplikatsichere Fertigstellung
Verwenden Sie eine Idempotenzregel auf Anwendungsebene, damit ein wiederholter Callback oder erneuter Versuch kein unbeabsichtigtes zweites dauerhaftes Asset erzeugt.
Beobachtbarkeit auf Step-Ebene
Überwachen Sie Import, Transformation und Export getrennt, damit ein erfolgreicher vorgelagerter Step keine fehlgeschlagene dauerhafte Übergabe verdeckt.
Lebenszyklus-Vertrag
Halten Sie fest, welches System jede Quelle, jedes temporäre Ergebnis, jedes Derivat, jede zwischengespeicherte Antwort und jeden Anwendungsdatensatz löscht, einschließlich des Zeitpunkts.
Wissenswerte technische Details
- Unterstützte Ziele nutzen gepaarte Import- und Speicher-Robots, darunter Amazon S3, Azure Blob Storage, Backblaze B2, Box, Cloudflare R2, DigitalOcean Spaces, Dropbox, FTP, Google Cloud Storage, MEGA S4 Object Storage, MinIO, SFTP, Supabase Storage, OpenStack Swift, Tigris, Wasabi und Rackspace Cloud Files.
- Ein Speicher-Step exportiert nur Ergebnisse, die durch seinen
use-Wert ausgewählt werden. Ob ein Original, ein Derivat oder beides exportiert wird, bestimmt somit der Assembly-Graph und nicht der Ziel-Anbieter. - Template-Zugangsdaten sind Datensätze auf Kontoebene, die per Namen referenziert werden. Das hält Anbieterschlüssel aus Browser-Bundles und Assembly Instructions heraus, erfordert aber weiterhin, dass die Zugangsdaten selbst beim Anbieter entsprechend eingeschränkt sind.
- Zugriffskontrollen sind anbieterspezifisch: Amazon S3 stellt sowohl
aclals auchsign_urls_forbereit, Cloudflare R2 stelltsign_urls_for, aber keineacl-Option bereit, Azure kann Shared-Access-Signaturen erzeugen, und Box oder Dropbox können Freigabelinks erstellen. - Ein benutzerdefiniertes URL-Präfix oder eine URL-Vorlage ändert die im Assembly-Ergebnis gemeldete Adresse; es gewährt für sich genommen keinen Zugriff, konfiguriert kein CDN, lädt keine weitere Kopie hoch und beweist nicht, dass das Objekt öffentlich lesbar ist.
- Import-Robots unterscheiden sich im Verhalten bei Verzeichnisdurchlauf, rekursivem Auflisten, Seitengröße und Fortsetzungs-Token, sodass eine Massenmigration dem Schema des gewählten Robots folgen und den Fortschritt außerhalb einer einzigen In-Memory-Schleife speichern muss.
- FTP und SFTP speichern Dateien in einem Server-Dateisystem statt in einem objektbasierten Namensraum; SFTP unterstützt schlüsselbasierte Authentifizierung und die Konfiguration von Dateiberechtigungen, während FTP auf seinem eigenen Transport- und Server-Berechtigungsmodell beruht.
- Temporäre Assembly-Ergebnisse sind kein dauerhafter Anwendungsspeicher, daher sollte jedes Ergebnis, das das temporäre Aufbewahrungsfenster überdauern muss, exportiert und mit dem führenden System der Anwendung abgeglichen werden.
Ein praxisnaher Ansatz
- 1
Klassifizieren Sie das Ziel nach Speichermodell, erforderlicher Region, Verantwortungsgrenze und erwartetem Abrufpfad.
- 2
Erstellen Sie Template-Zugangsdaten nach dem Prinzip der geringsten Rechte und testen Sie Import- und Speicherberechtigungen unabhängig voneinander.
- 3
Überprüfen Sie das Verhalten bei privaten, öffentlichen, signierten, abgelaufenen, ersetzten und gelöschten Objekten anhand repräsentativer Dateien.
- 4
Testen Sie Paginierung, rekursive Importe, Wiederholungsversuche, doppelte Exporte und Teilfehler, bevor Sie den Produktivverkehr migrieren.
Wann Transloadit hilfreich ist
Verwenden Sie einen nativen Import- oder Speicher-Robot von Transloadit, wenn ein Workflow Dateien zwischen der Verarbeitung und einem unterstützten Speicherdienst verschieben soll, ohne dass Ihre Anwendung die Bytes durchleiten muss. Wählen Sie das Ziel zuerst nach betrieblichen Anforderungen aus und konfigurieren Sie dann dessen Zugangsdaten und Zugriffsverhalten explizit.
Architekturgrenze
Transloadit importiert Dateien, verarbeitet sie und exportiert ausgewählte Ergebnisse über den konfigurierten Robot. Für dauerhafte Speicherung, Bucket- oder Ordnerrichtlinien, den Objekt-Lebenszyklus, Replikation und Auslieferung bleibt weiterhin das Ziel verantwortlich. Für die Autorisierung der Nutzer, Asset-Datensätze, Veröffentlichungsentscheidungen und das Löschen aller Kopien bleibt weiterhin Ihre Anwendung verantwortlich.
Häufig gestellte Fragen
Bedeutet eine Ergebnis-URL, dass die exportierte Datei öffentlich ist?
Nein. Die Adresse in einem Assembly-Ergebnis beschreibt, wo sich das Objekt laut einem Anbieter oder einer konfigurierten URL-Zuordnung befindet. Ob ein Aufrufer es abrufen kann, hängt weiterhin von der Bucket-Richtlinie, einer Objekt-ACL, einem Freigabelink des Anbieters, einer gültigen Signatur oder von Dateisystem- und Webserver-Berechtigungen ab. Testen Sie den Zugriff über einen nicht authentifizierten Client, statt das Vorhandensein von url oder ssl_url als Berechtigungsprüfung zu behandeln.
Sollten Import und Export dieselben Zugangsdaten teilen?
Meist nicht. Geben Sie Zugangsdaten für den Import nur Lese- und Listenzugriff auf das notwendige Quellpräfix und Zugangsdaten für den Export nur Schreibzugriff auf ihr Zielpräfix. Getrennte Datensätze begrenzen die Auswirkung geleakter oder falsch konfigurierter Zugangsdaten und erleichtern die Interpretation anbieterseitiger Audit-Logs. Ein einzelner, umfassenderer Zugangsdaten-Datensatz mag praktisch sein, aber Praktikabilität ist kein Beleg dafür, dass beide Richtungen dieselben Berechtigungen benötigen.
Wann sollte ich SFTP oder FTP anstelle von Objektspeicher verwenden?
Verwenden Sie eine native Integration, wenn sie zum Anbieter passt und der Workflow das Durchleiten von Datei-Bytes über Anwendungsserver vermeiden soll. Wählen Sie SFTP, wenn ein bestehender Partnervertrag SSH-Dateiübertragung oder ein Server-Dateisystem verlangt. Nutzen Sie FTP nur zur Kompatibilität mit einem Endpunkt, der keinen stärkeren unterstützten Weg bieten kann, und schränken Sie dann Konto, Zielpfad und Netzwerkzugänglichkeit so weit ein, wie es der Server zulässt.
Wie sollte meine Anwendung Dateien anbieterübergreifend nachverfolgen?
Speichern Sie die Assembly-ID, die anbieterunabhängige Asset-ID, den Zielschlüssel oder -pfad sowie die vorgesehene Version in Ihrer Datenbank. Behandeln Sie Benachrichtigungen als wiederholbare Ereignisse und gestalten Sie die Verarbeitung des Abschlusses idempotent. Sichern Sie bei einem großen Import den Fortschritt seiten- oder batchweise und gleichen Sie erwartete Assets mit abgeschlossenen Exporten ab. Ordnernamen und Freigabe-URLs des Anbieters sind nützliche Präsentationsdaten, aber fragile primäre Bezeichner.
Kann ich den Anbieter wechseln, indem ich nur den Robot-Namen ändere?
Nicht risikofrei, ohne den Vertrag zu prüfen. Der Assembly-Graph mag ähnlich bleiben, aber Zugangsdaten, Bucket- oder Container-Felder, Pfadregeln, Zugriffseinstellungen, Ergebnis-URL-Felder, Rekursion und Paginierung können sich unterscheiden. Erstellen Sie einen Anbieteradapter in vertrauenswürdigem Anwendungscode oder pflegen Sie geprüfte Templates pro Ziel. Erlauben Sie keinem Browser, einen beliebigen Robot auszuwählen oder Speicherzugangsdaten in ansonsten vertrauenswürdige Instructions einzuschleusen.