Uploads und Ergebnisse speichern, ohne einen Bucket einzurichten

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Wer verarbeitete Dateien behalten möchte, muss den Speicher oft separat einrichten: einen S3-Bucket anlegen, eine IAM-Richtlinie schreiben und Zugangsdaten zu einem Template hinzufügen. Das ist zusätzliche Arbeit, bevor Sie sich dem Problem widmen können, das Sie eigentlich lösen wollten.

Transloadit Storage bietet zugelassenen Workspaces eine Alternative. Der Robot /transloadit/store legt Dateien im Speicher Ihres Workspaces ab, und eine signierte Smart-CDN-URL liefert das Original oder ein bei Bedarf erzeugtes Derivat aus. Die Dateibibliothek der Console und ein S3-kompatibler Endpunkt bieten Möglichkeiten, diese Dateien zu verwalten, sofern die Dateibibliothek für Ihren Workspace aktiviert ist.

Transloadit Storage befindet sich in der privaten Vorschau. Wenn Sie es vor der allgemeinen Verfügbarkeit ausprobieren möchten, fragen Sie uns nach Zugang für Ihren Workspace. Für dieses Tutorial benötigen Sie außerdem Zugriff auf die Dateibibliothek, den unser Team separat freischaltet. Die Aktivierung von Storage allein gewährt diesen Zugriff nicht.

Dieses Tutorial bringt eine Datei in vier kurzen Schritten mit Node.js und dem offiziellen SDK von Ihrer Festplatte in Transloadit Storage und über das Smart CDN wieder heraus. Dabei wird zu keinem Zeitpunkt ein Bucket angelegt.

Was Sie benötigen

• Node.js 22 oder neuer.
• Einen Workspace, der für die Storage-Vorschau zugelassen ist und für den der Zugriff auf die Dateibibliothek aktiviert ist.
• Zwei Auth Keys aus Zugangsdaten in der Console: einen API-Schlüssel mit assemblies:write, dam:read, templates:read und templates:write für die folgenden Beispiele sowie einen separaten Smart-CDN-Signierschlüssel. Wählen Sie für diesen zweiten Schlüssel Neuer Auth Key und Private Bildauslieferung (Smart-CDN-Signierung); damit wird Smart CDN aktiviert und nur smart_cdn:sign ausgewählt. Für direkte Uploads über S3 ist zusätzlich dam:write erforderlich.
• Die AWS CLI für die optionalen S3-Befehle in Schritt 2.
• Den Slug Ihres Workspaces – den Teil nach /c/ in der Console-URL, zum Beispiel mytransloadit-toystory-app.

Assemblies, die mit assemblies:write autorisiert sind, können Dateien über Storage-Robots speichern und importieren. Die Scopes dam:read und dam:write steuern den direkten S3-Zugriff, nicht diese Assembly-Vorgänge.

Die Aktivierung von Smart CDN für einen Schlüssel schränkt nicht ein, was er sonst noch kann; das tun seine Berechtigungen. Mit nur smart_cdn:sign kann der Schlüssel weder eigenständige Assemblies erstellen noch Storage verwalten. Wer sein Auth Secret besitzt, kann jedoch weiterhin URLs signieren, die über Ihr Konto Transformationen ausführen und Ihre gespeicherten Dateien ausliefern. Bewahren Sie es daher wie jedes andere Auth Secret auf Ihrem Server auf. Falls es offengelegt wird, löschen Sie den Schlüssel und erstellen Sie einen neuen.

Legen Sie ein Projekt und eine Datei .env an:

mkdir zero-config-storage && cd zero-config-storage
npm init -y && npm pkg set type=module
npm install @transloadit/node @transloadit/utils
curl --fail --location --output photo.jpg https://demos.transloadit.com/inputs/chameleon.jpg

TRANSLOADIT_KEY=your-api-auth-key
TRANSLOADIT_SECRET=your-api-auth-secret
TRANSLOADIT_CDN_KEY=your-smart-cdn-auth-key
TRANSLOADIT_CDN_SECRET=your-smart-cdn-auth-secret
TRANSLOADIT_WORKSPACE=your-workspace-slug

Node liest sie mit --env-file ein, sodass keine Abhängigkeit von dotenv nötig ist. Laden Sie sie für die Shell-Befehle in Schritt 2 mit set -a; . ./.env; set +a und verwenden Sie anschließend dasselbe Terminal. Während der Vorschau haben Sie von uns möglicherweise auch Endpunkt-Überschreibungen erhalten (TRANSLOADIT_ENDPOINT, TRANSLOADIT_STORAGE_S3_ENDPOINT, TRANSLOADIT_SMART_CDN_BASE_URL, TRANSLOADIT_SMART_CDN_EXTRA_PARAMS); die folgenden Skripte übernehmen diese, sofern vorhanden, und greifen andernfalls auf die Standardwerte der Produktionsumgebung zurück. Setzen Sie Werte mit Leerzeichen oder Shell-Zeichen wie & in .env in Anführungszeichen, damit sich die Datei auch mit dem Shell-Befehl sicher laden lässt.

Schritt 1: Eine Datei mit /transloadit/store speichern

/transloadit/store ist ein speichernder Robot wie /s3/store, benötigt aber weder Zugangsdaten noch einen Bucket: Er schreibt in den Speicher Ihres Workspaces. path legt fest, wo die Datei landet; Ordner werden bei Bedarf angelegt, und ${file.name} wird für jede Datei einzeln ersetzt.

import { Transloadit } from '@transloadit/node'

const client = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
  endpoint: process.env.TRANSLOADIT_ENDPOINT,
})

const assembly = await client.createAssembly({
  files: { photo: './photo.jpg' },
  params: {
    steps: {
      stored: {
        robot: '/transloadit/store',
        use: ':original',
        path: 'uploads/${file.name}',
        // Uploading the same name again creates a new version instead of failing.
        conflict_strategy: 'overwrite',
      },
    },
  },
  waitForCompletion: true,
})

// Storing Robots do not add a result key of their own: they annotate the file they stored,
// which is still listed under the step that produced it — here the upload, `:original`.
const [stored] = assembly.results[':original']
console.log(`Stored ${stored.path} (${stored.size} bytes, asset ${stored.asset_id})`)

node --env-file=.env store.js
# Stored uploads/photo.jpg (9309370 bytes, asset 8kLg…)

Das ist der gesamte Teil „Speicher einrichten“ dieses Tutorials. Die Datei liegt nun unter uploads/photo.jpg in Ihrem Workspace. Wenn Sie erneut unter demselben Pfad speichern, erhalten Sie eine neue Version (conflict_strategy: 'overwrite'). Eine frühere Version können Sie abrufen, solange sie aufbewahrt wird; die Versionierung ist weder eine Zusage dauerhafter Aufbewahrung noch ein Ersatz für Ihre Backup-Strategie.

Schritt 2: Ansehen – in der Console oder mit Ihren vorhandenen S3-Tools

Die Dateibibliothek muss von unserem Team für Ihren Workspace aktiviert werden. Anschließend kann ein Workspace-Inhaber, ein Admin oder ein reguläres Mitglied sie öffnen, ein Billing Admin dagegen nicht. Die Aktivierung von Storage allein schaltet weder die Seite noch ihren S3-Endpunkt frei.

Sobald der Zugriff aktiviert ist, öffnen Sie die Console, wählen Ihren Workspace aus und gehen zu Dateibibliothek (https://transloadit.com/c/<workspace-slug>/file-library/). Dort finden Sie den Ordner uploads mit photo.jpg darin. Hier können Sie Ihre gespeicherten Dateien durchsuchen und verwalten.

Lieber im Terminal? Transloadit Storage ist S3-kompatibel, und Ihr Auth Key und Ihr Auth Secret dienen als Zugangsdaten. Der Slug Ihres Workspaces ist der Bucket:

set -a; . ./.env; set +a
export AWS_ACCESS_KEY_ID="$TRANSLOADIT_KEY" AWS_SECRET_ACCESS_KEY="$TRANSLOADIT_SECRET"
export AWS_DEFAULT_REGION=us-east-1
aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
  s3 ls "s3://$TRANSLOADIT_WORKSPACE/uploads/"
# 2026-08-31 10:12:04    9309370 photo.jpg

Die folgenden Beispiele verwenden S3-Auflistungen und versionierte Downloads. Prüfen Sie, welche Operationen und Berechtigungen Ihr Client benötigt, statt davon auszugehen, dass jede AWS-S3-Funktion verfügbar ist. Nachdem Sie store.js zweimal ausgeführt haben, können Sie beide Versionen über die S3-API auflisten:

aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
  s3api list-object-versions --bucket "$TRANSLOADIT_WORKSPACE" --prefix uploads/photo.jpg \
  --query 'Versions[?Key==`uploads/photo.jpg`].[VersionId,IsLatest,LastModified]' --output text
# 9G2…   True    2026-08-31T10:12:04+00:00
# 7Kq…   False   2026-08-31T10:05:41+00:00

Nachdem Sie zweimal unter denselben Pfad hochgeladen haben, rufen Sie die frühere Version über ihre Versions-ID ab. Der Filter auf den exakten Schlüssel verhindert, dass eine andere Datei ausgewählt wird, deren Name mit uploads/photo.jpg beginnt:

if PREVIOUS=$(aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
  s3api list-object-versions --bucket "$TRANSLOADIT_WORKSPACE" --prefix uploads/photo.jpg \
  --query 'Versions[?Key==`uploads/photo.jpg` && IsLatest==`false`] | [0].VersionId' --output text); then
  if [ -n "$PREVIOUS" ] && [ "$PREVIOUS" != None ]; then
    aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
      s3api get-object --bucket "$TRANSLOADIT_WORKSPACE" --key uploads/photo.jpg \
      --version-id "$PREVIOUS" photo-previous.jpg
  else
    printf '%s\n' 'No previous version exists. Upload the same path again first.'
  fi
else
  printf '%s\n' 'Could not list object versions; no download was attempted.' >&2
fi

Schritt 3: Über das Smart CDN ausliefern

Halten Sie das Verzeichnis uploads/ aus diesem Tutorial privat. Um eine Datei an einen Browser zu übergeben, signieren Sie eine Smart-CDN-URL für das integrierte Template builtin/storage-serve@0.0.1, das die Datei aus Ihrem Speicher liest und ausliefert. Die Signatur enthält einen Ablaufzeitpunkt, der begrenzt, wie lange Transloadit diese Signatur akzeptiert. Der Ablauf kann jedoch keine Bytes zurückholen, die ein Empfänger bereits heruntergeladen oder zwischengespeichert hat.

import { getSignedSmartCdnUrl } from '@transloadit/utils/node'

const url = getSignedSmartCdnUrl({
  workspace: process.env.TRANSLOADIT_WORKSPACE,
  template: 'builtin/storage-serve@0.0.1',
  input: 'uploads/photo.jpg',
  authKey: process.env.TRANSLOADIT_CDN_KEY,
  authSecret: process.env.TRANSLOADIT_CDN_SECRET,
  expiresAt: Date.now() + 60 * 60 * 1000, // valid for one hour
  // Preview environments only; omit in production.
  baseUrl: process.env.TRANSLOADIT_SMART_CDN_BASE_URL,
  urlParams: Object.fromEntries(
    new URLSearchParams(process.env.TRANSLOADIT_SMART_CDN_EXTRA_PARAMS ?? ''),
  ),
})

console.log(url)

curl --fail --silent --show-error --output photo-served.jpg "$(node --env-file=.env serve.js)"

Die URL hat die Form https://your-workspace-slug.tlcdn.com/builtin%2Fstorage-serve%400.0.1/uploads%2Fphoto.jpg?auth_key=…&exp=…&sig=sha256%3A…. Behandeln Sie sie wie Zugangsdaten: Wer sie besitzt, kann ihre Autorisierung nutzen. Leiten Sie sie daher per Pipe an curl weiter oder übergeben Sie sie an einen Browser, statt sie zu protokollieren. Dieselbe URL ohne die Parameter auth_key, exp und sig wird für dieses private Verzeichnis abgelehnt, unabhängig von der Einstellung für Signature Authentication in Ihrem Workspace. Storage unterstützt außerdem explizit veröffentlichte Präfixe sowie separate Built-ins für die öffentliche Auslieferung. Dieses Tutorial veröffentlicht kein Präfix; veröffentlichen Sie private Dateien nicht nur, um das Signieren von URLs zu umgehen.

Damit wird das Original ausgeliefert – alle 9,3 MB, auch an ein Smartphone. Schritt 4 zeigt, wie Sie stattdessen eine verkleinerte Version ausliefern; auf einer echten Seite würden Sie diese für alles verwenden, was größer als ein Thumbnail ist.

Schritt 4 (optional): Derivate bei Bedarf erzeugen

builtin/storage-serve liefert das Original aus. Für Thumbnails, Wasserzeichen oder Formatkonvertierungen erstellen Sie ein eigenes Template mit /transloadit/import, einem verarbeitenden Robot und /file/serve. Dieses Template verwendet /image/resize, um die Datei auf eine in der URL übergebene Breite zu skalieren:

import { Transloadit } from '@transloadit/node'

const client = new Transloadit({
  authKey: process.env.TRANSLOADIT_KEY,
  authSecret: process.env.TRANSLOADIT_SECRET,
  endpoint: process.env.TRANSLOADIT_ENDPOINT,
})

const name = 'storage-thumb'
const template = {
  steps: {
    imported: { robot: '/transloadit/import', path: '${fields.input}' },
    resized: { robot: '/image/resize', use: 'imported', width: '${fields.w}', imagemagick_stack: 'v3.0.0' },
    served: { robot: '/file/serve', use: 'resized' },
  },
}

// Search every page so rerunning the script also works in Workspaces with many Templates.
let existing
for await (const item of client.streamTemplates()) {
  if (item.name === name) {
    existing = item
    break
  }
}
if (existing) {
  await client.editTemplate(existing.id, { name, template })
  console.log(`Template ${name} updated`)
} else {
  await client.createTemplate({ name, template })
  console.log(`Template ${name} created`)
}

Eine URL dafür signieren Sie mit demselben Aufruf, nur mit dem Namen Ihres eigenen Templates und der Breite als URL-Parameter:

import { getSignedSmartCdnUrl } from '@transloadit/utils/node'

const url = getSignedSmartCdnUrl({
  workspace: process.env.TRANSLOADIT_WORKSPACE,
  template: 'storage-thumb',
  input: 'uploads/photo.jpg',
  authKey: process.env.TRANSLOADIT_CDN_KEY,
  authSecret: process.env.TRANSLOADIT_CDN_SECRET,
  expiresAt: Date.now() + 60 * 60 * 1000,
  baseUrl: process.env.TRANSLOADIT_SMART_CDN_BASE_URL, // preview environments only
  urlParams: {
    w: 300,
    ...Object.fromEntries(new URLSearchParams(process.env.TRANSLOADIT_SMART_CDN_EXTRA_PARAMS ?? '')),
  },
})

console.log(url)

node --env-file=.env create-template.js && \
  curl --fail --silent --show-error --output photo-thumb.jpg "$(node --env-file=.env serve-thumb.js)"
# Template storage-thumb created

Das Smart CDN liefert eine 300 Pixel breite Version von uploads/photo.jpg.

Auch der Step /transloadit/import des eigenen Templates erfordert authentifizierten Zugriff. Wenn Sie Signature Authentication für den Workspace deaktivieren, wird dieser private Import nicht öffentlich. Lesen Sie bei anderen Templates die Dokumentation zur Authentifizierung, bevor Sie eine unsignierte Nutzung zulassen.

Referenz: die beiden Robots

• /transloadit/store akzeptiert optional path mit dem Standardwert ${file.url_name}. Bei bereits vorhandenen Zielen schlägt der Vorgang fehl, sofern Sie nicht overwrite oder rename wählen. Speichern Sie aus dem Ergebnis des erzeugenden Steps die zurückgegebenen Werte workspace, asset_id und version_id sowie den finalen Wert path. Alle Optionen finden Sie in der Referenz zum Storage-Robot.
• /transloadit/import akzeptiert für eine Datei oder einen Ordner den Wert path oder alternativ asset_id, optional zusammen mit version_id, um aufbewahrte Bytes auszuwählen. Ordnerimporte umfassen nur direkte Unterelemente, sofern recursive: true nicht gesetzt ist. Die Ausgabe ist eine normale Datei, die ein anderer Robot per use verwenden kann. Informationen zu Authentifizierung und Selektoren finden Sie in der Referenz zum Import-Robot.

Was gerade passiert ist

• Ein einziger Robot, /transloadit/store, hat die Datei im Speicher Ihres Workspaces abgelegt. Kein Bucket, kein IAM, keine Zugangsdaten in Templates.
• Eine aktivierte Dateibibliothek in der Console und die unterstützten S3-Operationen machen dieselben gespeicherten Dateien zugänglich.
• Eine signierte Smart-CDN-URL liefert das Original aus, und ein kleines eigenes Template liefert Derivate.

Wie es weitergeht

• Für Upload-Oberflächen im Browser lohnt sich ein Blick auf Uppy. Bewahren Sie Auth Secrets und die Signierbeispiele aus diesem Artikel auf Ihrem Server auf, nicht im Browser-Code.
• Verwenden Sie /transloadit/import mit einem Ordnerpfad und recursive: true, um Unterordner einzubeziehen, wenn Sie eine Sammlung erneut verarbeiten, etwa um neue Thumbnails für eine ganze Kampagne zu erstellen.