Leitfaden zur File Upload API: Architektur, Sicherheit und Anbieterauswahl

Den Upload-Auftrag vor der Auswahl eines Widgets definieren

Ein produktiver Upload beginnt, bevor das erste Byte übertragen wird. Die Anwendung identifiziert den Nutzer, entscheidet, welcher Vorgang zulässig ist, legt die erlaubte Anzahl und Größe der Dateien fest und erstellt einen Datensatz, der länger als ein Browser-Tab bestehen kann. Die Übertragung ist nur eine Phase. Validierung, Verarbeitung, Export, Benachrichtigung und Abgleich bestimmen, ob das Produkt die Datei anschließend sicher verwenden kann.

Formulieren Sie einen Abschlussvertrag aus Produktsicht. „Die Anfrage gab 200 zurück“ ist wenig aussagekräftig; „Das Original und die erforderlichen Derivate sind unter diesem Mandanten gespeichert, der Asset-Datensatz nennt ihre Versionen und ein doppelter Callback ändert nichts“ ist testbar. Halten Sie fest, bei welchen Fehlern Nutzer einen erneuten Versuch starten dürfen, welche einen neuen Upload erfordern und welche einen für den Operator sichtbaren Zustand zur Wiederherstellung hinterlassen.

Einen von vier expliziten Byte-Pfaden auswählen

Bei einer Weiterleitung über die Anwendung sendet der Browser die Datei an Ihren Server, der sie weiterleitet oder speichert. Das ist nachvollziehbar und gibt der Anwendung unmittelbare Kontrolle, doch jedes Byte beansprucht eingehende Bandbreite, Arbeitsspeicher oder temporären Festplattenspeicher, Verbindungszeit und ausgehende Bandbreite. Dieses Modell eignet sich für kleine, selten übertragene Dateien, wenn der vorhandene Server Limits durchsetzen und Daten sicher streamen kann, ohne vollständige Inhalte zwischenzuspeichern.

„Direkt in die Cloud“ ist mehrdeutig, benennen Sie daher das Ziel. Ein Browser kann mit kurzlebigen Zugangsdaten direkt in einen Objektspeicher oder direkt zu einem Verarbeitungsdienst wie Transloadit hochladen. Alternativ kann er einen Dienst anweisen, eine vorhandene Remote-URL zu importieren. Die direkte Speicherung minimiert Übertragungsstationen, wenn die dauerhafte Speicherung die einzige Aufgabe ist. Bei der direkten Verarbeitung bleibt die Anwendung außerhalb des Datenpfads, während ein Workflow Dateien validiert, transformiert und in einen eigenen Speicher exportiert.

Wiederaufnahme getrennt von Wiederholungsversuchen konzipieren

Ein Wiederholungsversuch startet einen Vorgang erneut; eine fortsetzbare Übertragung setzt dagegen einen bestehenden Upload ab einem vom Server bestätigten Byte-Offset fort. Bei tus behält der Client die Upload-URL, fragt den Server nach Upload-Offset und sendet nur die verbleibenden Bytes. Speichern Sie diese URL außerhalb des flüchtigen Komponentenzustands, wenn nach einem Neuladen oder Absturz eine Wiederherstellung möglich sein soll. Erstellen Sie zudem sorgfältig Fingerprints der Dateien, damit die lokale Datei eines Nutzers niemals der Upload-Ressource eines anderen zugeordnet wird.

Fortsetzbare Uploads bedeuten weder unbegrenzte Zeit noch eine idempotente Verarbeitung. Eine Transloadit Assembly hat ab ihrer Erstellung weiterhin acht Stunden Zeit, um den Upload abzuschließen. Das Erstellen einer Ersatz-Assembly kann Arbeit duplizieren, sofern die Anwendung die alte Kennung nicht abgleicht. Legen Sie fest, wie der Client mit Pausen, Offline-Zeiten, abgelaufenen Ressourcen, geänderten Dateien, abgebrochenen Uploads und einer verlorenen Abschlussantwort umgeht, nachdem der Server die letzten Bytes akzeptiert hat.

Die Absicht serverseitig autorisieren und den Bytes misstrauen

Ein öffentlicher Auth Key darf im Browsercode enthalten sein, das Auth Secret von Transloadit oder dauerhafte Zugangsdaten für den Speicher jedoch niemals. Authentifizieren Sie den Nutzer in Ihrer Anwendung, wählen Sie serverseitig ein gespeichertes Template aus und geben Sie kurzlebige signierte Parameter mit einer eindeutigen nonce zurück. Setzen Sie allow_steps_override auf false, wenn es keinen legitimen Grund dafür gibt, dass der Browser Steps ersetzt, da ein vom Client ausgewählter Step-Graph andernfalls die Verarbeitung oder das Exportverhalten ändern könnte.

Eine gültige Signatur belegt, dass die Parameter-Nutzlast autorisiert wurde. Sie belegt nicht, dass die hochgeladenen Bytes mit einem Dateinamen, einer Dateiendung, einem deklarierten MIME-Typ, einem Mandanten oder einer Moderationsrichtlinie übereinstimmen. Begrenzen Sie Anfrageinhalte vor rechenintensiven Arbeiten, untersuchen Sie die ermittelten Dateieigenschaften, lehnen Sie nicht unterstützte Inhalte ab und führen Sie Scans durch, wenn das Bedrohungsmodell dies erfordert. Halten Sie außerdem nicht vertrauenswürdige Ausgaben von öffentlichen Speichern fern, bis der Workflow einen genehmigten Zustand erreicht.

Dauerhaften Speicher von der Upload-Verarbeitung trennen

Ein Upload-Endpunkt ist nicht automatisch ein führendes System. Legen Sie fest, welchem Bucket oder welcher Asset-Datenbank das Original zugeordnet ist, wie Derivate damit verknüpft sind, welche Kennungen Umbenennungen überdauern und wer jede Kopie löscht. Transloadit bewahrt temporäre Ergebnisse mindestens 24 Stunden auf, während ihre Zugriffs-URLs nach wenigen Stunden ablaufen können. Exportieren Sie Dateien, die dauerhaft erhalten bleiben müssen. Temporäre URLs sind nur für den kurzfristigen Abruf vorgesehen, nicht für das Einbetten oder die wiederholte Auslieferung im Produkt.

Integrieren Sie den Export in die Assembly, wenn der Workflow nur bei erfolgreicher Verarbeitung und dauerhafter Speicherung als erfolgreich gilt. Ein Export-Robot kann gespeicherte Template-Zugangsdaten verwenden, um Ergebnisse im Rahmen des Workflows an das ausgewählte Ziel zu schreiben. Alternativ können Sie Dateien zunächst direkt in einen eigenen Speicher hochladen und die Verarbeitung durch ein kontrolliertes Ereignis auslösen. Dieser Pfad erzeugt frühzeitig eine dauerhafte Kopie, erfordert jedoch zusätzliche Orchestrierung und eine weitere Übertragung an den Verarbeitungsdienst.

An der Eigentumsgrenze zwischen Eigenentwicklung und Zukauf entscheiden

Entwickeln Sie den Übertragungspfad selbst, wenn die Anforderungen eng begrenzt sind und das Team bereit ist, den gesamten Lebenszyklus zu verantworten. Ein kleines authentifiziertes Formular, das kurze Dateien per Streaming in einen bestehenden Bucket überträgt, rechtfertigt möglicherweise keine weitere Plattform. Die Schätzung muss dennoch Multipart-Parsing, Backpressure, die Durchsetzung von Größenlimits, fortsetzbare Uploads oder deren bewussten Verzicht, Bereinigung, Schutz vor Missbrauch, Beobachtbarkeit, Upgrades und die Behandlung von Fehlern außerhalb der Lebensdauer der Anfrage berücksichtigen.

Ein verwalteter Dienst wird attraktiver, wenn der Workflow unzuverlässige Netzwerke, große Dateien, Browser-UX, Remote-Quellen, Medienprüfung, Transformation oder mehrere Speicherziele kombiniert. Der Zukauf entbindet Sie nicht von der Verantwortung für Ihre Anwendung: Mandantenprüfungen, Autorisierung, Asset-Datensätze, Aufbewahrung, Veröffentlichung und Vorfallbehandlung bleiben in Ihrer Hand. Oft eignet sich eine hybride Architektur am besten, bei der eigener Speicher und der Geschäftszustand eine verwaltete Übertragungs- und Verarbeitungsebene umgeben.

Anbieter mit Fehlertests statt anhand der Funktionsanzahl vergleichen

Erstellen Sie eine Bewertungsmatrix anhand der tatsächlichen Auslastung Ihres Produkts. Vergleichen Sie Browser- und mobile Clients, die Unterstützung offener Protokolle, die maximale Dateigröße, das Verhalten bei parallelen Vorgängen, geografische Endpunkte, Remote-Importe, den Verarbeitungsumfang, Speicherziele, die Isolierung von Zugangsdaten, die Webhook-Verifizierung, die Aufbewahrung von Statusdaten, den Support und Ausstiegsoptionen. Kennzeichnen Sie jede Funktion als erforderlich, optional oder irrelevant, bevor Sie sich Anbieterseiten ansehen.

Testen Sie jeden ernst zu nehmenden Kandidaten mit denselben Testdaten. Unterbrechen Sie einen großen Upload, laden Sie die Seite neu, senden Sie ein doppeltes Abschlussereignis, widerrufen Sie Speicherzugangsdaten, lehnen Sie eine Datei nach dem Empfang ab, überschreiten Sie einen Grenzwert und lassen Sie die abschließende Antwort verloren gehen. Messen Sie die für Nutzer sichtbare Wiederherstellung, erneut übertragene Bytes, die Zeit bis zu einem dauerhaft gespeicherten Ergebnis, Nachweise für den Betrieb und die Bereinigung. Eine ausgereifte Dateiauswahl sagt wenig darüber aus, wie sich das System unter echten Produktionsbedingungen verhält.

Einen signierten Upload mit Uppy und Transloadit implementieren

Im Browserbeispiel übernimmt Uppy die Dateiauswahl und die tus-Übertragung, während das Transloadit-Plugin Assembly-Parameter von Ihrer Anwendung anfordert. Der Serverendpunkt muss den aktuellen Nutzer authentifizieren, bevor er das Objekt aus calcSignature zurückgibt. Er sollte das Template selbst auswählen, statt beliebige Steps oder ein vom Aufrufer vorgegebenes Speicherziel zu akzeptieren, und er sollte die Anfragerate für Autorisierungen unabhängig vom Upload-Datenverkehr begrenzen.

Aktivieren Sie vor der Nutzung dieses Beispiels „Require a correct Signature“ in den Workspace-Einstellungen, speichern Sie das folgende Template und hinterlegen Sie dessen ID serverseitig in TRANSLOADIT_UPLOAD_TEMPLATE_ID. Speichern Sie den AWS-Zugang zu Ihrem privaten Bucket als Template-Zugangsdaten mit dem Namen my_s3_credentials. Der Auth Key darf den Browser erreichen, das Auth Secret und die AWS-Zugangsdaten nicht. Der Signatur-Endpunkt muss Cache-Control: no-store zurückgeben, damit jeder autorisierte Vorgang neue Parameter erhält.

Installieren Sie @uppy/core, @uppy/dashboard und @uppy/transloadit im Frontend sowie das Node-SDK transloadit auf dem Server. Initialisieren Sie das Browserbeispiel, nachdem ein Element wie <div id="photo-upload"></div> vorhanden ist. Implementieren Sie /api/transloadit-params in Ihrem Framework mit Sitzungsauthentifizierung und Upload-Autorisierung, bevor Sie die Signatur-Hilfsfunktion aufrufen. Lehnen Sie nicht authentifizierte oder nicht autorisierte Anfragen ab. Die Hilfsfunktion selbst ist kein Authentifizierungsendpunkt.

Das Beispiel erlaubt ein JPEG-, PNG- oder WebP-Bild bis 10 MiB. Die Einschränkungen von Uppy geben sofortiges Feedback. Die signierten Limits auth.max_size und auth.max_number_of_files sowie der serverseitige Filter des Templates setzen die Richtlinie durch. waitForEncoding: true wartet auf die Assembly einschließlich des Exports, statt das Ende der Übertragung mit dem Abschluss des Workflows gleichzusetzen.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

// Mount this once after <div id="photo-upload"></div> exists in your page.
const uppy = new Uppy({
  restrictions: {
    maxNumberOfFiles: 1,
    maxFileSize: 10 * 1024 * 1024,
    allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
  },
}).use(Dashboard, { inline: true, target: '#photo-upload' }).use(Transloadit, {
  async assemblyOptions() {
    const response = await fetch('/api/transloadit-params', {
      credentials: 'same-origin',
      cache: 'no-store',
    })
    if (!response.ok) {
      throw new Error('Could not authorize this upload')
    }
    return response.json()
  },
  waitForEncoding: true,
  retryDelays: [0, 1000, 3000, 5000, 10000],
})

uppy.on('transloadit:assembly-created', (assembly) => {
  // Associate this ID with the server-side operation before the user leaves the page.
  console.log('Assembly started:', assembly.assembly_id)
})

uppy.on('transloadit:complete', (assembly) => {
  // Record completion against the ID persisted at transloadit:assembly-created.
  console.log('Processing completed. Assembly:', assembly.assembly_id)
})

uppy.on('transloadit:assembly-error', () => {
  // Show this through the application’s accessible status UI, not raw API errors or URLs.
  console.error('Processing failed. Check the Assembly in your workspace.')
})

uppy.on('upload-error', () => {
  // Transloadit API signature rejections and Assembly errors also reach this event.
  // Failures thrown by assemblyOptions() use Uppy’s general error event instead.
  // Deduplicate application notices.
  console.error('The upload workflow failed. Check its status before retrying.')
})

import { randomUUID } from 'node:crypto'
import { Transloadit } from 'transloadit'

function requiredEnvironmentValue(name: string): string {
  const value = process.env[name]
  if (value == null) throw new Error(`Missing environment variable: ${name}`)
  return value
}

const transloadit = new Transloadit({
  authKey: requiredEnvironmentValue('TRANSLOADIT_KEY'),
  authSecret: requiredEnvironmentValue('TRANSLOADIT_SECRET'),
})

export function createAuthorizedUploadParameters(): { params: string; signature: string } {
  // Call this only after the server has authenticated the request and authorized the operation.
  const params = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      max_size: 10 * 1024 * 1024,
      max_number_of_files: 1,
      nonce: randomUUID(),
    },
    template_id: requiredEnvironmentValue('TRANSLOADIT_UPLOAD_TEMPLATE_ID'),
  }
  return transloadit.calcSignature(params)
}

Annahme, Validierung, Verarbeitung und Export verbinden

Eine Assembly verbindet den vollständigen Pfad: authentifizierter Uppy-Upload → Validierung mit /file/filter → Verarbeitung mit /image/resize → Export mit /s3/store in einen kundeneigenen Bucket. Das gespeicherte Template definiert den Workflow. Jede use-Abhängigkeit bestimmt, welche Dateien den nächsten Step erreichen. Uppy stellt die Upload-Oberfläche bereit; Transloadit führt den verwalteten Workflow aus, nicht Ihr Anwendungsserver.

Der Filter prüft den erkannten MIME-Typ und die Dateigröße und leitet nur akzeptierte Bilder an die Vorschau- und Export-Steps weiter. Mit error_on_decline: true führt eine Ablehnung zu einem Assembly-Fehler. MIME- und Größenprüfungen sind weder Malware-Scans noch Inhaltsmoderation. Fügen Sie diese Steps vor Verarbeitung und Export ein, wenn Ihre Richtlinie sie erfordert.

Verwenden Sie einen privaten S3-Bucket mit aktiviertem Block Public Access und angemessen eingeschränkten Template-Zugangsdaten. acl: "bucket-default" lässt die Objekt-ACL weg und nutzt die Zugriffsrichtlinie des Buckets. Es macht einen öffentlichen Bucket nicht privat. Der Export speichert das akzeptierte Original und eine auf 1600 × 1600 Pixel begrenzte Vorschau unter Assembly- und dateispezifischen Pfaden. Kein Export liest direkt aus dem ungefilterten Step :original.

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^image/(jpeg|png|webp)$"]
      ],
      "declines": [["${file.size}", ">", 10485760]],
      "error_on_decline": true
    },
    "preview": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600
    },
    "exported": {
      "use": ["accepted_images", "preview"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "acl": "bucket-default",
      "path": "uploads/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}

Ein großes Video vom unterbrochenen Upload bis zum privaten Export testen

Für Video-Workflows benötigen Sie Template-Zugangsdaten namens large-upload-output mit IAM-Zugangsdaten, deren s3:PutObject-Berechtigung auf das private Präfix upload-tests/ beschränkt ist. Beachten Sie die IAM-Einrichtung für /s3/store für die Berechtigungen s3:ListBucket und s3:GetBucketLocation auf Bucket-Ebene; die Regionsabfrage entfällt, wenn die Template-Zugangsdaten bucket_region angeben. Ersetzen Sie YOUR_AUTH_KEY durch den Auth Key des Workspaces (nicht dessen Auth Secret), speichern Sie das folgende Template und verlangen Sie Signature Authentication für dieses Template. Verwenden Sie einen privaten Bucket mit aktiviertem Block Public Access und der Object-Ownership-Einstellung Bucket owner enforced. Die Einstellung acl: "bucket-default" übermittelt keine Objekt-ACL; der Zugriff wird weiterhin durch Ihre Bucket- und IAM-Richtlinien gesteuert. Setzen Sie für den Test TRANSLOADIT_UPLOAD_TEMPLATE_ID am authentifizierten Signierungsendpunkt auf die ID dieses gespeicherten Video-Templates. Verwenden Sie die obige Uppy-Integration mit einer vom Nutzer ausgewählten Datei und genau einer Uppy-Instanz. Die Template-Grenzen von 256 MiB und genau einer Datei sind Beispielregeln. Übernehmen Sie diese Grenzen in die Uppy-Core-Option restrictions (maxFileSize, maxNumberOfFiles), um frühzeitig Rückmeldung bei der Dateiauswahl zu geben; serverseitige Prüfungen bleiben erforderlich. Für diesen Video-Test ersetzen Sie die Bildbeschränkung durch allowedFileTypes: ["video/*"] und setzen sowohl maxFileSize im Browser als auch auth.max_size in den signierten Parametern auf 256 * 1024 * 1024; beide Dateianzahlgrenzen bleiben auf 1. Prüfen Sie vor dem Test die Upload-Grenzen Ihres Workspaces und die unterstützten Quellformate. Das Template erkennt die Video-MIME-Familie, erzeugt die größenbegrenzte MP4-Version und exportiert diese sowie das akzeptierte Original. Die gezeigten Prüfungen sind keine vollständige Richtlinie zum Schutz vor Schadsoftware oder ungeeigneten Inhalten.

Das Ende der Übertragung ist nicht das Ende des Workflows. Mit waitForEncoding: true wartet der Browser auf die Verarbeitung. Ihre Anwendung benötigt trotzdem eine dauerhaft gespeicherte Assembly-ID und verifizierte Benachrichtigungen oder eine Abfrage zum Assembly Status, falls der Tab geschlossen wird. Ein fehlgeschlagener Export darf das Asset nicht als bereit markieren. Prüfen Sie ASSEMBLY_COMPLETED, die erforderliche Videoversion und beide privaten S3-Objekte. Vergleichen Sie vor der Erfolgsmeldung die Prüfsumme des exportierten Originals mit der Eingabe. Diese privaten Objekte sind nicht automatisch öffentliche Wiedergabe-URLs.

Führen Sie drei ununterbrochene Kontrollläufe und drei Läufe mit Unterbrechung mit demselben eigenen Video von 100–200 MiB durch. Erfassen Sie die genaue Dateigröße und SHA-256-Prüfsumme, Dauer und Codecs, Browser- und Paketversionen, Template, Region, Tarif und Netzwerkaufbau. Wenden Sie in Chrome DevTools ein benutzerdefiniertes Drosselungsprofil an und notieren Sie dessen Einstellungen, wechseln Sie bei etwa 25 % Upload-Fortschritt für 10 Sekunden zu Offline und stellen Sie das Profil ohne Neuladen wieder her. Bei Netzwerkfehlern, die gemeldet werden, während der Browser offline ist und noch Wiederholungsversuche verfügbar sind, pausiert das installierte Uppy-tus-Plugin seine Warteschlange bis zu einem online-Ereignis. Jeder Wiederholungsversuch verbraucht weiterhin einen Versuch; Upload-Fortschritt kann den Zähler zurücksetzen. Die Summe von retryDelays ist keine Offline-Zeitgrenze. Prüfen Sie, dass eine HEAD-Anfrage den gespeicherten Upload-Offset meldet und folgende PATCH-Anfragen dieselbe tus-Ressource fortsetzen. Dies prüft eine im Browser nachgebildete Unterbrechung, nicht Server-Failover oder sämtliche Netzwerkbedingungen.

Messen Sie vom Upload-Start bis zur ersten abgeschlossenen Assembly mit überprüften exportierten Objekten, nicht nur bis zum letzten übertragenen Byte. Erfassen Sie außerdem die Zeit vom Wiederverbinden bis zum Abschluss, erneut übertragene Bytes soweit beobachtbar, Fehler, doppelte Assemblies und die tatsächliche Anzahl der Läufe. Dies ist ein reproduzierbares Testverfahren, kein veröffentlichtes Benchmark-Ergebnis. Begrenzte Wiederholungsversuche können durch wiederholte Anfragefehler ausgeschöpft werden, die Upload-Frist der Assembly von acht Stunden gilt weiterhin, und dieses Beispiel stellt den nur im Arbeitsspeicher gehaltenen Zustand nach Neuladen oder Schließen des Tabs nicht wieder her. Testen Sie Abbruch, abgelaufene Autorisierung, Dateien über dem Limit und widerrufene Exportzugangsdaten getrennt. Die API für fortsetzbare Uploads beschreibt die Protokollübergabe; die Demo für Video, Thumbnails und S3 EN (English) zeigt Verarbeitung und öffentlichen Export.

{
  "allow_steps_override": false,
  "auth": {
    "key": "YOUR_AUTH_KEY",
    "max_size": 268435456,
    "max_number_of_files": 1
  },
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_video": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^video/"]],
      "error_on_decline": true
    },
    "rendition": {
      "use": "accepted_video",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/360p",
      "width": 640,
      "height": 360,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_video", "rendition"],
      "robot": "/s3/store",
      "credentials": "large-upload-output",
      "acl": "bucket-default",
      "path": "upload-tests/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}