Uploads und Frontend-Integration # Sichere Datei-Uploads in Next.js mit Uppy und signierten Transloadit Templates Sicherer Next.js-App-Router-Upload mit Uppy, Serversignierung, gesperrtem Template, verbindlicher Prüfung, fortsetzbarem Transfer und asynchronem Abschluss. Veröffentlicht am 24. August 2026 ## Wichtigste Erkenntnisse * Bewahren Sie das Auth Secret von Transloadit in einem `server-only`-Modul auf und geben Sie nur kurzlebige signierte Assembly-Optionen zurück. * Autorisieren Sie den signierenden Route Handler und begrenzen Sie seine Anfragerate; der Besitz einer Anwendungs-URL ist keine Upload-Berechtigung. * Sperren Sie das gespeicherte Template, verlangen Sie Signaturen und wiederholen Sie clientseitige Dateibeschränkungen an einer vertrauenswürdigen Verarbeitungsgrenze. Für einen sicheren Browser-Upload reicht es nicht, das Auth Secret in eine API-Route zu verschieben. Der Server muss jede Signaturanfrage autorisieren, die signierte Nutzlast muss ein beschränktes Template benennen, der Empfänger muss die Dateirichtlinie durchsetzen, und die Anwendung muss die Verarbeitung abgleichen, nachdem der Nutzer die Seite verlassen hat. Dieses App-Router-Design weist jede Verantwortung ausdrücklich zu. ## In diesem Leitfaden 1. [Anwendungsautorisierung und Upload-Ausführung trennen](#secure-file-uploads-nextjs-uppy-section-1) 2. [Das Template vor dem Bereitstellen des Upload-Formulars sperren](#secure-file-uploads-nextjs-uppy-section-2) 3. [Eine kurzlebige Anfrage in einem server-only-Modul signieren](#secure-file-uploads-nextjs-uppy-section-3) 4. [Den Signatur-Endpunkt des App Router schützen](#secure-file-uploads-nextjs-uppy-section-4) 5. [Uppy einmal innerhalb einer Client Component einbinden](#secure-file-uploads-nextjs-uppy-section-5) 6. [Fortschritt, Wiederholungsversuche und Abschluss abgleichen](#secure-file-uploads-nextjs-uppy-section-6) 7. [Die Kontrollen als Angreifer und als Nutzer mit unterbrochener Verbindung testen](#secure-file-uploads-nextjs-uppy-section-7) ## Worauf es besonders ankommt * Erstellen Sie eine Uppy-Instanz für die Client-Komponente und lassen Sie das gepflegte Transloadit-Plugin die fortsetzbare Übertragung koordinieren. * Behandeln Sie den Browserfortschritt als Übertragungsfortschritt und verwenden Sie verifizierte Benachrichtigungen für einen dauerhaft gespeicherten Verarbeitungsabschluss. * Speichern Sie den Zugriff auf Speicherdienste von Drittanbietern mit geringstmöglichen Rechten in Template-Zugangsdaten statt in Anfragefeldern oder Client-Umgebungsvariablen. ## Anwendungsautorisierung und Upload-Ausführung trennen Der Browser ist ein nicht vertrauenswürdiger Aufrufer, selbst wenn die Oberfläche Teil Ihrer Next.js-Anwendung ist. Eine Client Component darf den öffentlichen Auth Key und eine Template ID enthalten, jedoch niemals das Auth Secret für den Workspace, unverarbeitete Speicherzugangsdaten oder die Berechtigung, beliebige Verarbeitungs-Steps auszuwählen. Hinterlegen Sie das Auth Secret hinter einem Route Handler. Dieser Endpunkt muss entscheiden, ob der aktuelle Nutzer der Anwendung genau diesen Upload starten darf. Diese Entscheidung ist von der Integrität der Transloadit-Anfrage getrennt. Eine gültige Signatur belegt, dass Ihr Server die serialisierten Assembly-Parameter für einen begrenzten Zeitraum genehmigt hat. Sie belegt nicht, dass die Person, die Ihren Server um eine Signatur bittet, Eigentümerin eines Projekts ist, ihr Kontingent einhält, eine CSRF-Prüfung bestanden hat oder das Ergebnis veröffentlichen darf. Der Autorisierungsadapter der Anwendung muss diese Regeln vor der Signierung durchsetzen. Das gespeicherte Template beschränkt anschließend, was Transloadit ausführt. ### Next.js-Anwendungsserver Der Anwendungscode authentifiziert die Sitzung, prüft Ressourceneigentum und CSRF-Richtlinie, wendet Begrenzungen für die Anfragerate oder das Kontingent an und stellt zweckgebundene signierte Optionen aus. ### Uppy-Upload-Client Übernimmt Dateiauswahl, barrierefreie Upload-Oberfläche, Browserbeschränkungen, Fortschritt, Wiederholungsversuche und die Koordination fortsetzbarer Übertragungen. ### Transloadit-Verarbeitung Erstellt die Assembly, setzt die signierte Anfrage und das gespeicherte Template durch, prüft Dateien, führt die Verarbeitung aus und exportiert die konfigurierten Ergebnisse. ## Das Template vor dem Bereitstellen des Upload-Formulars sperren Speichern Sie den Verarbeitungsworkflow als Template. Setzen Sie `allow_steps_override` auf `false`, damit ein Browser nicht zusammen mit seiner `template_id` andere Steps übermitteln kann. Aktivieren Sie für dieses Template „Gültige Signatur verlangen“ oder verlangen Sie korrekte Signaturen für den gesamten Workspace. Dies sind separate Steuerelemente: Das gesperrte Template legt den Verarbeitungsgraphen fest, während die Signaturprüfung signierte Parameter zurückweist, die verändert, abgelaufen oder aus anderen Gründen ungültig sind. Ihre Anwendung entscheidet weiterhin, welcher Nutzer diese Parameter erhalten darf. Wiederholen Sie kostengünstige Schnittstellenbeschränkungen an der Verarbeitungsgrenze. Das Beispiel begrenzt jede Datei auf 50 MiB und die Zahl der Dateien pro Assembly auf fünf. Zudem prüft es mit `/file/filter` die erkannten MIME-Metadaten, statt dem Dateinamen oder der Browserdeklaration zu vertrauen. Passen Sie die genaue Positivliste an das Produkt an. Ergänzen Sie Verifizierung, Malware-Scanning, Quarantäne oder eine Prüfung durch Menschen, wenn das Inhaltsrisiko dies erfordert. Keine einzelne MIME-Prüfung macht beliebige nutzergenerierte Inhalte sicher. Der Wert `user_uploads` bezeichnet Template-Zugangsdaten, die im Workspace gespeichert sind. Gewähren Sie diesem externen Principal nur die Speicheroperationen sowie den Zugriff auf den Bucket und die Pfade, die dieser Workflow benötigt. Der Browser empfängt und signiert den zugrunde liegenden Zugriffsschlüssel nicht. Die Zugangsdaten können daher unabhängig vom Next.js-Bundle rotiert werden. Die Rotation muss jedoch koordiniert erfolgen, da sie jedes Template betrifft, das auf diesen Eintrag verweist. Gesperrtes Template mit verbindlichen Limits und beschränktem Speicherzugriff ``` { "allow_steps_override": false, "auth": { "max_number_of_files": 5, "max_size": 52428800 }, "notify_url": "https://app.example.com/api/transloadit-notifications", "steps": { ":original": { "robot": "/upload/handle" }, "accepted_images": { "use": ":original", "robot": "/file/filter", "accepts": [ ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp)$"] ], "error_on_decline": true, "error_msg": "Only JPEG, PNG, and WebP images are accepted" }, "stored": { "use": "accepted_images", "robot": "/s3/store", "credentials": "user_uploads" } } } ``` ## Eine kurzlebige Anfrage in einem `server-only`-Modul signieren Speichern Sie die Serverkonfiguration in Umgebungsvariablen ohne das Präfix `NEXT_PUBLIC_` und importieren Sie `server-only` am Anfang des Signaturmoduls. Next.js lässt den Build fehlschlagen, wenn Client-Code dieses Modul importiert. Der Marker ist eine nützliche Schutzmaßnahme, aber kein Secret-Manager: Zugriffsrichtlinien für die Produktion, das Entfernen vertraulicher Daten aus Logs, die Isolation von Vorschauumgebungen und die Rotation von Zugangsdaten bleiben weiterhin wichtig. Der konfigurierte Auth Key wird vom Node SDK hinzugefügt. Anschließend serialisiert das SDK die Parameter und gibt genau diesen `params`-String zusammen mit seiner Signatur zurück. Geben Sie beide Werte unverändert zurück. Wenn Sie den String nach dem Signieren parsen, ein Feld hinzufügen oder ihn in einer anderen Reihenfolge erneut serialisieren, entsteht eine andere Payload, die abgelehnt werden sollte. Im Beispiel läuft die Gültigkeit nach fünf Minuten ab, da Uppy die Optionen unmittelbar vor dem Erstellen der Assembly anfordert und für jede Autorisierung eine neue Nonce hinzufügt. Wählen Sie das Template auf dem Server aus. Übernehmen Sie weder `template_id`, `steps`, `notify_url`, Export-Zugangsdaten noch unbegrenzte Transformationswerte aus dem Request-Body, um sie ungeprüft zu signieren. Wenn das Produkt tatsächlich mehrere Upload-Workflows anbietet, ordnen Sie nach Prüfung der Nutzerberechtigung einen kleinen Vorgang auf Anwendungsebene wie `avatar` oder `product-gallery` einem Template und Grenzwerten aus einer Positivliste zu. Eine rein serverseitige Hilfsfunktion zum Signieren eines festgelegten Templates ``` import 'server-only' import { randomUUID } from 'node:crypto' import { Transloadit } from 'transloadit' export interface AssemblyOptions { params: string signature: string } type TransloaditEnvironmentName = | 'TRANSLOADIT_KEY' | 'TRANSLOADIT_SECRET' | 'TRANSLOADIT_TEMPLATE_ID' function readServerEnvironment(name: TransloaditEnvironmentName): string { const value = process.env[name] if (value == null || value === '') { throw new Error('Missing Transloadit server configuration') } return value } const templateId = readServerEnvironment('TRANSLOADIT_TEMPLATE_ID') const transloadit = new Transloadit({ authKey: readServerEnvironment('TRANSLOADIT_KEY'), authSecret: readServerEnvironment('TRANSLOADIT_SECRET'), }) export function createAssemblyOptions(): AssemblyOptions { const requestParameters = { auth: { expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(), nonce: randomUUID(), }, template_id: templateId, } return transloadit.calcSignature(requestParameters) } ``` ## Den Signatur-Endpunkt des App Router schützen Ein Route Handler ist wie jeder andere HTTP-Endpunkt erreichbar. Die Funktion `authorizeUpload` im Beispiel ist bewusst anwendungsspezifisch: Verbinden Sie sie mit der vorhandenen Sitzungsbibliothek des Projekts, Prüfungen der Ressourceneigentümerschaft, der CSRF-Strategie und der gemeinsamen Begrenzung der Anfragerate. Geben Sie eine Ablehnung zurück, bevor Sie die Signatur erzeugen. Legen Sie bei mandantenfähigen Anwendungen Grenzwerte sowohl nach Mandant als auch nach Nutzer fest und prüfen Sie den Mandanten, dem das spätere Asset gehören wird. Die Route akzeptiert keine beliebigen Assembly-Parameter und kennzeichnet eine erfolgreiche Antwort mit `no-store`. Ihre öffentliche Fehlermeldung ist bewusst allgemein gehalten. Protokollieren Sie serverseitig eine interne Request- oder Trace-ID, die Entscheidungskategorie und die Akteur-ID. Geben Sie jedoch keine Stacktraces, Konto-IDs, Antwortinhalte von Drittanbietern oder Details zu Zugangsdaten an den Browser zurück. Lassen Sie unerwartete Fehler von der zentralen, bereinigten Fehlerbehandlung der Anwendung verarbeiten, statt jeden Aufruf in einen unnötig ausführlichen catch-Block einzuschließen. Die Begrenzung der Anfragerate für die Signatur-Route steuert die Erstellung von Assemblies, ersetzt jedoch weder Abrechnungslimits des Kontos noch Dateilimits des Templates oder Anwendungskontingente. Wenden Sie alle drei an. Eine Signatur ist eine kurzlebige Berechtigung: Wer die vollständige signierte Payload erhält, kann versuchen, sie während ihrer Gültigkeit zu übermitteln. Senden Sie sie daher nur über HTTPS und vermeiden Sie Analytics, Browser-Speicher, URLs und Logs, in denen sie erhalten bleibt. Ein authentifizierter Signatur-Endpunkt für den App Router ``` import type { NextRequest } from 'next/server' import { NextResponse } from 'next/server' import { authorizeUpload } from '../../../server/upload-authorization' import { type AssemblyOptions, createAssemblyOptions, } from '../../../server/transloadit-options' interface ErrorResponse { error: string } export async function POST( request: NextRequest, ): Promise> { const permission = await authorizeUpload(request) if (!permission.allowed) { return NextResponse.json({ error: 'Upload not allowed' }, { status: 403 }) } return NextResponse.json(createAssemblyOptions(), { headers: { 'Cache-Control': 'no-store' }, }) } ``` ### Authentifizieren Rufen Sie eine aktuelle serverseitige Sitzung ab, statt einer vom Client übermittelten Nutzer- oder Mandanten-ID zu vertrauen. ### Autorisieren Prüfen Sie vor dem Erstellen der signierten Berechtigung, ob der Akteur für die Zielressource und den betreffenden Vorgang hochladen darf. ### Begrenzen Erzwingen Sie zusätzlich zu den Template-Limits Begrenzungen der Anfragerate pro Nutzer und Mandant sowie Grenzen für parallele Verarbeitung, Speicherrichtlinien und Geschäftskontingente. ## Uppy einmal innerhalb einer Client Component einbinden Uppy benötigt Browser-APIs. Daher befindet sich der Dateiuploader hinter einer `use client`-Grenze. Erstellen Sie die Uppy-Instanz mit einem verzögerten State-Initialisierer genau einmal. Wird sie während des Renderns neu erstellt, gehen ausgewählte Dateien verloren und die Zuständigkeit für den Lebenszyklus wird unterbrochen. Diese Komponente zerstört die Instanz, wenn sie für den gesamten Upload-Lebenszyklus zuständig ist. Müssen Uploads die Navigation zwischen Routen überdauern, verschieben Sie die Instanz in einen langlebigeren Client-Anbieter und zerstören Sie sie, wenn dieser Anbieter beendet wird. Die asynchrone Funktion `assemblyOptions` ruft die geschützte Route auf, während Uppy den Upload vorbereitet. Sie prüft `response.ok`, verarbeitet fehlerhaftes JSON sicher, validiert die Struktur der Antwort und zeigt Nutzern nur einen stabilen Autorisierungsfehler an. Das Dashboard von Uppy stellt die Benutzeroberfläche für Auswahl, Fortschritt, Abbruch und Fehler bereit. Das Transloadit-Plugin erstellt währenddessen die Assembly und sendet Dateien über eine fortsetzbare Upload-Infrastruktur. Der begrenzte Zeitplan für Wiederholungsversuche hilft bei vorübergehenden Fehlern, ohne diese unbegrenzt fortzusetzen. Diese Wiederholungsversuche laufen, solange diese Uppy-Instanz aktiv bleibt. Sie sorgen nicht dafür, dass die gezeigte Komponente nach dem erneuten Laden der Seite ausgewählte Dateien und den Zustand der Assembly wiederherstellt. Wenn die Wiederherstellung nach dem erneuten Laden eine Produktanforderung ist, konfigurieren und testen Sie das Golden-Retriever-Plugin oder ein anderes dokumentiertes Persistenzkonzept mit dem Transloadit-Plugin. Leiten Sie diese Funktion nicht allein aus tus oder `retryDelays` ab. Die Browser-Grenzwerte entsprechen dem Template und ermöglichen schnelles Feedback, bilden aber nicht die Sicherheitsgrenze. Ein Aufrufer kann die Komponente umgehen, und Dateimetadaten können falsch sein. Legen Sie die maßgeblichen Vorgaben für Dateianzahl, Bytegröße, Prüfungen erkannter Inhalte und Exportrichtlinien im gesperrten Template fest. Entscheiden Sie außerdem, ob ein Abbruch im Browser nur die Übertragung, die Assembly oder den Asset-Datensatz der Anwendung abbrechen soll. Testen Sie diese Entscheidung, statt anzunehmen, dass alle drei Zustände identisch sind. Eine Client Component mit abgestimmten Einschränkungen und begrenzten Wiederholungsversuchen ``` 'use client' import Uppy from '@uppy/core' import Dashboard from '@uppy/react/dashboard' import Transloadit from '@uppy/transloadit' import { type ReactNode, useEffect, useState } from 'react' import { z } from 'zod' import '@uppy/core/css/style.min.css' import '@uppy/dashboard/css/style.min.css' const assemblyOptionsSchema = z.object({ params: z.string().min(1), signature: z.string().regex(/^(sha1|sha256|sha384):[0-9a-f]+$/), }) async function fetchAssemblyOptions(): Promise> { const response = await fetch('/api/transloadit-params', { method: 'POST', headers: { Accept: 'application/json' }, }) if (!response.ok) { throw new Error('Could not authorize this upload. Try again.') } const responseBody: unknown = await response.json().catch(() => null) const parsedOptions = assemblyOptionsSchema.safeParse(responseBody) if (!parsedOptions.success) { throw new Error('Could not authorize this upload. Try again.') } return parsedOptions.data } function createUppy(): Uppy { return new Uppy({ restrictions: { allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'], maxFileSize: 50 * 1024 * 1024, maxNumberOfFiles: 5, }, }).use(Transloadit, { assemblyOptions: fetchAssemblyOptions, retryDelays: [0, 1_000, 3_000, 5_000], waitForEncoding: false, }) } export function UploadForm(): ReactNode { const [uppy] = useState(createUppy) useEffect(() => { return () => uppy.destroy() }, [uppy]) return } ``` ## Fortschritt, Wiederholungsversuche und Abschluss abgleichen Übertragungsfortschritt und Verarbeitungsfortschritt beantworten unterschiedliche Fragen. Mit `waitForEncoding: false` kann die Benutzeroberfläche den Vorgang abschließen, sobald die Bytes Transloadit erreicht haben, während Validierung, Transformation und Export fortgesetzt werden. Reagieren Sie auf `transloadit:assembly-created` und verknüpfen Sie die Assembly ID mit einem ausstehenden Anwendungsdatensatz. Eine Navigation kann dann die Beobachtung im Browser unterbrechen, ohne die für den Abgleich benötigte Identität zu verlieren. Hinterlegen Sie für den asynchronen Abschluss eine feste `notify_url` im serverseitig verwalteten Template. Der Notification Handler muss die Signatur mit dem Auth Secret prüfen, dem der Auth Key der Assembly zugeordnet ist. Anschließend muss er die Payload validieren, die Assembly ID dem erwarteten ausstehenden Datensatz zuordnen und die Ergebnisse idempotent anwenden, bevor er den Erfolg zurückgibt. Notifications können erneut zugestellt werden. Ein Duplikat muss daher den vorhandenen Endzustand bestätigen, statt ein weiteres Asset oder Veröffentlichungsereignis zu erstellen. Verwenden Sie `waitForEncoding: true` nur für kurze Workflows, bei denen der Nutzer auf der Seite bleiben soll und Browsercode die endgültigen Ergebnisse tatsächlich benötigt. Behalten Sie selbst dann einen serverseitigen Wiederherstellungspfad bei, da Tabs geschlossen werden und Verbindungen abbrechen können. Ein geplanter Abgleichvorgang kann nicht abgeschlossene Assemblies abfragen, deren Benachrichtigungen nicht eingegangen sind. Legen Sie die Wiederholungsrichtlinie je nach Fehler fest: Setzen Sie nach einer Netzwerkunterbrechung die Übertragung fort, fordern Sie neue signierte Optionen an, wenn sie vor dem Erstellen der Assembly ablaufen, und stoppen Sie nach einer Richtlinienablehnung, bis der Nutzer die Datei ändert. ### Ausgewählt Der Browser verfügt über eine ausgewählte Datei, aber noch kein vertrauenswürdiges System hat sie akzeptiert. ### Hochgeladen Der Empfänger hat die Bytes erhalten, doch die verbindliche Validierung, Verarbeitung oder der Export kann weiterhin fehlschlagen. ### Bereit Ein verifiziertes Endergebnis wurde dauerhaft gespeichert und für die vorgesehene Verwendung in der Anwendung autorisiert. ## Die Kontrollen als Angreifer und als Nutzer mit unterbrochener Verbindung testen Testen Sie den Signatur-Endpunkt ohne Sitzung, mit dem falschen Mandanten, gegebenenfalls mit einem fehlenden oder ungültigen CSRF-Token, oberhalb des Limits für die Anfragerate und nach dem Entzug von Berechtigungen. Vergewissern Sie sich, dass weder Antworten noch Protokolle das Auth Secret, Template-Zugangsdaten, einen Stacktrace oder unverarbeitete Abhängigkeitsfehler enthalten. Versuchen Sie, `template_id` zu ersetzen, `steps` hinzuzufügen, `auth.expires` zu verlängern und signierte Optionen nach ihrem Ablauf zu übermitteln. Die Signaturprüfung oder die Durchsetzung durch das Template sollte die ungültige Anfrage ablehnen. Testen Sie ein zulässiges JPEG, einen unzulässigen MIME-Typ mit einer Bilddateiendung, eine zu große Datei, zu viele Dateien, eine Datei mit null Byte, Verbindungsabbrüche an mehreren Positionen, das Neuladen des Browsers, einen Abbruch, eine abgelaufene Autorisierung, eine doppelte Benachrichtigung, eine Speicherablehnung und einen Verarbeitungsfehler nach dem Upload. Vergewissern Sie sich, dass das Verhalten beim Neuladen dem Persistenzkonzept entspricht, statt eine automatische Wiederherstellung vorauszusetzen. Prüfen Sie mit Tastatur und Hilfstechnologien, ob Fortschritts- und Fehlermeldungen barrierefrei zugänglich sind. Untersuchen Sie anschließend den temporären Speicher und die Anwendungsdatensätze auf Datenlecks oder dauerhaft ausstehende Zustände. Überwachen Sie abgelehnte Signaturen, Entscheidungen zur Begrenzung der Anfragerate, die Erstellungs- und Fehlerraten von Assemblies, die Wiederherstellung von Uploads, die Verarbeitungslatenz, das Alter von Benachrichtigungen, Speicherfehler und das Alter ausstehender Datensätze, ohne geschützte Nutzdaten zu protokollieren. Lösen Sie Warnungen bei anhaltenden Änderungen aus, nicht bei einzelnen Nutzerfehlern. Halten Sie die Template ID und die von der Anwendung verwaltete Workflow-Version in den Betriebsdaten fest, da sich ein gespeichertes Template im Laufe der Zeit ändern kann. ## Wissenswerte technische Details * Eine App-Router-Datei namens `route.ts` ist ein HTTP-Endpunkt. Daher muss sie selbst Authentifizierung, Autorisierung, Missbrauchsschutz und Eingabevalidierung durchführen, bevor sie eine Signatur zurückgibt. * Die Paketmarkierung `server-only` verursacht zur Build-Zeit einen Fehler, wenn ein geschütztes Modul in eine Client Component importiert wird. Deployment-Secrets benötigen jedoch weiterhin eine korrekte Plattformkonfiguration und Zugriffskontrollen. * Wenn der Auth Key konfiguriert ist, fügt ihn die Methode `calcSignature` des Transloadit Node SDK hinzu, serialisiert die Anfrageparameter und gibt exakt diesen `params`-String zusammen mit seiner HMAC-Signatur zurück. * Signature Authentication schützt `auth.expires` und die übrigen serialisierten Nutzdaten der Anfrage. Wird ein geschützter Wert nach dem Signieren geändert, ist die Signatur ungültig. * Ein Template kann standardmäßig Überschreibungen von Steps zur Laufzeit zulassen. Browsergesteuerte Workflows sollten daher `allow_steps_override` auf `false` setzen, sofern eine eng begrenzte und geprüfte Überschreibung nicht ausdrücklich vorgesehen ist. * Uppy-Einschränkungen liefern sofortiges Feedback im Browser. Dagegen setzen `auth.max_size` und `auth.max_number_of_files` des Templates sowie Steps zur Dateiverarbeitung die Richtlinie durch, nachdem dem Browsercode nicht mehr vertraut werden kann. * Das Transloadit-Plugin akzeptiert eine asynchrone Funktion `assemblyOptions`, erstellt eine Assembly und konfiguriert fortsetzbare Uploads zum tus-Endpunkt der Assembly. * Mit `waitForEncoding: false` schließt Uppy den Vorgang nach der Übertragung statt nach der Verarbeitung ab. Die Anwendung sollte die Assembly ID speichern und für das Endergebnis eine per Signatur verifizierte Benachrichtigung oder eine spätere Statusabfrage verwenden. * Das Beispiel mit begrenzten `retryDelays` setzt Übertragungen nach vorübergehenden Fehlern fort, solange die zugehörige Uppy-Instanz aktiv bleibt. Die Wiederherstellung nach dem Neuladen erfordert einen persistierten Uppy- und Transloadit-Status, etwa durch eine bewusst konfigurierte Golden-Retriever-Integration. * Template-Zugangsdaten sind im Workspace gespeicherte Datensätze, auf die über ihren Namen verwiesen wird. Daher erscheinen unverarbeitete geheime Speicherzugangsdaten weder in der gespeicherten Template-JSON noch im Client-Bundle oder in signierten Assembly-Parametern. Das Template enthält nur den Namen des Zugangsdaten-Eintrags. ## Ein praxisnaher Ansatz 1. 1\ Erstellen Sie ein gesperrtes Template, das eine Signatur erfordert und Upload-Limits, Prüfungen erkannter Inhalte sowie eingeschränkte Template-Zugangsdaten umfasst. 2. 2\ Fügen Sie eine ausschließlich serverseitige Signaturhilfe sowie einen authentifizierten, nicht cachebaren App-Router-Endpunkt mit einer Begrenzung der Anfragerate hinzu. 3. 3\ Binden Sie eine einzige Uppy-Instanz mit abgestimmten Einschränkungen, Wiederholungsversuchen und bereinigten Autorisierungsfehlern in eine Client Component ein. 4. 4\ Speichern Sie die Assembly ID dauerhaft, verifizieren Sie Abschlussbenachrichtigungen und testen Sie Ablehnung, Unterbrechung, Ablauf, Replay und doppelte Zustellung. Ein vierstufiger Medienworkflow ## Wann Transloadit hilfreich ist Verwenden Sie das gepflegte Transloadit-Plugin von Uppy, wenn ein Next.js-Browserablauf fortsetzbare Uploads mit anschließender verwalteter Validierung, Transformation und Export erfordert. Ein gespeichertes Template legt den zulässigen Workflow fest, Signature Authentication schützt die genehmigten Anfrageparameter und deren Ablaufzeit, und Template-Zugangsdaten halten vertrauliche Speicherzugangsdaten sowohl aus Next.js-Client-Bundles als auch aus Assembly-Parametern heraus. ## Architekturgrenze Ihre Next.js-Anwendung authentifiziert den Nutzer und entscheidet, ob sie eine kurzlebige Upload-Autorisierung ausstellt. Uppy übernimmt im Browser die Dateiauswahl, Fortschrittsanzeige und Koordination der Übertragung. Transloadit empfängt die Bytes, wendet das konfigurierte Template für Validierung und Verarbeitung an und meldet die Ergebnisse. Keine dieser Ebenen ersetzt den dauerhaften Datensatz Ihrer Anwendung für das Asset oder deren Veröffentlichungsrichtlinie. ## Häufig gestellte Fragen ### Darf der Auth Key von Transloadit in einer Next.js Client Component enthalten sein? Der Auth Key identifiziert den Workspace und darf in einer signierten Anfrage enthalten sein, das Auth Secret muss jedoch serverseitig bleiben. Verlangen Sie dennoch Signaturen und beschränken Sie das Template, da ein offengelegter Auth Key ohne diese Kontrollen unbefugte Anfragen ermöglichen kann. ### Warum sollte statt der Signierung in einer Server Component ein Route Handler verwendet werden? Uppy fordert unmittelbar vor dem Upload über Browsercode neue Assembly-Optionen an. Ein Route Handler stellt diese HTTP-Grenze bereit, muss die Anfrage aber wie jeder andere Mutationsendpunkt authentifizieren und autorisieren. Eine Server Function könnte eine ähnliche Grenze implementieren, wenn die Integration sie sicher aufruft. ### Verhindert eine signierte Anfrage für ein gesperrtes Template jede Art von Upload-Missbrauch? Nein. Sie schützt die Integrität der Anfrage und beschränkt das Verarbeitungsrezept. Sie benötigen weiterhin Anwendungsautorisierung, Limits für die Anfragerate und die Abrechnung, Begrenzungen für Dateianzahl und Byteumfang, eine Validierung erkannter Inhalte, Speicherzugriff nach dem Prinzip der geringsten Rechte sowie alle Prüfungen, Scans oder manuellen Kontrollen, die das Bedrohungsmodell des Produkts erfordert. ### Sollte `waitForEncoding` in Next.js auf true gesetzt sein? Bei langen Verarbeitungsvorgängen normalerweise nicht. Bei false wartet der Nutzer auf die Übertragung, und die Anwendung schließt die Verarbeitung über eine verifizierte Benachrichtigung ab. Setzen Sie den Wert nur dann auf true, wenn der Workflow kurz ist und der Browsercode die endgültigen Ergebnisse benötigt. Behalten Sie dabei den serverseitigen Abgleich für geschlossene Tabs und unterbrochene Verbindungen bei. ### Wo sollten S3-Zugangsdaten oder andere Speicherzugangsdaten hinterlegt werden? Speichern Sie sie nach dem Prinzip der geringsten Berechtigung als Transloadit Template-Zugangsdaten und referenzieren Sie den benannten Eintrag aus dem gespeicherten Template. Legen Sie die ungeschützten Zugangsdaten des Anbieters weder in öffentlichen Next.js-Umgebungsvariablen noch im Clientcode, in signierten Anfragefeldern, Logs oder Ergebnismetadaten ab. ### Reichen die Dateibeschränkungen von Uppy zur Validierung von Uploads aus? Nein. Sie verbessern das Feedback für kooperative Nutzer. Wiederholen Sie die Byte- und Anzahlbegrenzungen im Template und prüfen Sie erkannte Dateieigenschaften mit vertrauenswürdigen Verarbeitungs-Steps, da Aufrufende Browser-JavaScript umgehen können und Deklarationen irreführend sein können. ## Erstellen Sie den Workflow Entwickeln Sie das Konzept mithilfe der Robot-Dokumentation und funktionsfähiger Demos zu einer getesteten Assembly weiter. * [Lesen Sie die API-Dokumentation](/de/docs.md) * [Entdecken Sie funktionsfähige Demos EN (English)](/demos.md) * [Kostenlosen Workspace erstellen](/c/signup/) Uploads und Frontend-Integration ## Mit verwandten Leitfäden fortfahren * [React-Datei-Uploads mit Uppy: fortsetzbare Uploads, Vorschauen, Validierung und Verarbeitung](/de/guides/react-file-uploads-with-uppy.md)\ React-Dateiuploader mit Uppy bauen: Vorschau, Validierung, barrierefreier Fortschritt, Abbruch, fortsetzbarer Upload und Übergabe zur Transloadit-Verarbeitung. * [Die besten JavaScript-Bibliotheken für Datei-Uploads: Uppy vs. FilePond vs. Dropzone](/de/guides/best-javascript-file-upload-libraries.md)\ Vergleichen Sie Uppy, FilePond und Dropzone nach Protokoll, Schnittstellenmodell, Wiederherstellung, Integration und langfristiger Verantwortung. * [Große Uploads trotz Verbindungsabbruch zuverlässig annehmen](/de/guides/resumable-uploads-for-large-files.md)\ Nehmen Sie Multi-Gigabyte-Uploads über tus an, setzen Sie sie nach Verbindungsabbrüchen fort und halten Sie die Assembly bis zum Abschluss aktiv. * [Leitfaden zur File Upload API: Architektur, Sicherheit und Anbieterauswahl](/de/guides/file-upload-api-guide.md)\ Eine File Upload API anhand von Architektur, Wiederaufnahme, direkter Cloud-Übertragung, Sicherheit, Speichergrenzen und Anbietern auswählen und implementieren.