Eigener Speicher + eigenes CDN

Verfügbar in: den API-Tarifen Velocity und Momentum. Nicht verfügbar in Ignite (ohne CDN), in der Entwickler-Sandbox (Sandbox-Dateien sind temporär) und in den WordPress-Tarifen (sie nutzen das verwaltete smallPict CDN).

Kurz gesagt: Im BYO-Modus schreibt smallPict Ihre Originale und optimierten Bilder in Ihren Bucket, und Ihr CDN liefert sie aus. Speicher und CDN werden immer gemeinsam verbunden: Das eine lässt sich nicht ohne das andere einbinden.

Was BYO ist

Velocity und Momentum haben zwei Auslieferungsmodi. Sie wählen einen unter Dashboard → CDN & Speicher.

• Verwaltet (Standard): smallPict bewahrt Ihre Originale in seinem verschlüsselten Speicher auf (nach 90 Tagen in ein Langzeitarchiv verschoben) und liefert optimierte Bilder über cdn.smallpict.app aus. Keine Einrichtung nötig.
• Eigener Speicher + eigenes CDN (BYO): Sie verbinden einen S3-kompatiblen Bucket in Ihrem eigenen Konto und ein CDN in Ihrem eigenen Konto. Jeder neue Job schreibt das Original und die optimierte Datei in Ihren Bucket, und die API gibt URLs auf Ihrer CDN-Domain zurück.

Die Kopplung gibt es, weil smallPict beide Hälften der Auslieferung übernehmen muss: Dateien schreiben und veraltete Kopien aus dem Cache entfernen. Ein Bucket ohne CDN ließe Cache-Purges ins Leere laufen; ein CDN ohne Bucket hätte nichts auszuliefern.

Verwaltet vs. BYO

Unterstützte Anbieter

Speicher (bereits verfügbar): Amazon S3, Cloudflare R2, Google Cloud Storage (S3-Interoperabilität), Alibaba Cloud OSS, Tencent Cloud COS, DigitalOcean Spaces, SumoPod Storage, MinIO sowie jeder andere S3-kompatible Dienst über einen benutzerdefinierten Endpoint (zum Beispiel Hetzner, Vultr oder Wasabi).

CDN (bereits verfügbar): Cloudflare und Amazon CloudFront.

Geplant: Azure Blob Storage und weitere CDNs. Frühen Zugang können Sie auf der Seite Cloud-Anbieter anfordern.

Bevor Sie beginnen

1. Sie nutzen API Velocity oder Momentum und sind als Konto-Administrator angemeldet.
2. Sie haben einen Bucket und ein CDN, das Dateien aus diesem Bucket über HTTPS ausliefert.
3. Der Speicher-Endpoint ist aus dem Internet über HTTPS erreichbar. Private, interne und reine HTTP-Endpoints werden abgelehnt.
4. Sie haben eng begrenzte Schlüssel für smallPict erstellt (siehe Minimale Berechtigungen unten). Verwenden Sie nicht die Root- oder Admin-Schlüssel Ihres Kontos.

Öffnen Sie dann Dashboard → CDN & Speicher, wählen Sie Eigener Speicher + eigenes CDN, füllen Sie beide Teile aus und klicken Sie auf Speicher + CDN speichern. smallPict führt die Verbindungsprüfung aus (siehe unten) und schaltet nur dann auf BYO um, wenn sie bestanden ist.

Einrichtungsanleitungen

A. Amazon S3 + Amazon CloudFront

1. Erstellen Sie den Bucket in der gewünschten Region, zum Beispiel my-images in ap-southeast-1. Lassen Sie Block Public Access eingeschaltet.
2. Erstellen Sie eine CloudFront-Distribution mit dem Bucket als Origin. Verwenden Sie Origin access control (OAC), damit CloudFront den Bucket lesen kann, während er privat bleibt, und übernehmen Sie die Bucket-Richtlinie, die CloudFront Ihnen anbietet.
3. Optional: eigene Domain. Fügen Sie der Distribution einen alternativen Domainnamen (zum Beispiel images.example.com) und ein Zertifikat hinzu, und richten Sie einen DNS-Eintrag auf die Distribution.
4. Erstellen Sie einen IAM-Benutzer (oder eine Rolle) für den Speicher mit dieser Richtlinie:

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Action": [        "s3:PutObject",        "s3:GetObject",        "s3:DeleteObject"      ],      "Resource": "arn:aws:s3:::my-images/*"    }  ]}

5. Erstellen Sie einen IAM-Benutzer für CloudFront (es kann derselbe Benutzer sein) mit dieser Richtlinie. cloudfront:GetDistribution ist optional; damit kann smallPict die Domain der Distribution erkennen, wenn Sie das Feld für die CDN-Domain leer lassen.

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Action": [        "cloudfront:CreateInvalidation",        "cloudfront:GetDistribution"      ],      "Resource": "arn:aws:cloudfront::123456789012:distribution/E2QWRUHAPOMQZL"    }  ]}

6. Im Dashboard:
   • Speicheranbieter Amazon S3, Bucket my-images, Region ap-southeast-1, Endpoint leer (es wird der Standard-Endpoint der Region verwendet) sowie Access Key ID und Secret für den Speicher.
   • CDN Amazon CloudFront, die Distribution-ID (zum Beispiel E2QWRUHAPOMQZL), Access Key ID und Secret für CloudFront und optional die CDN-Domain (https://images.example.com). Lassen Sie die Domain leer, um die eigene *.cloudfront.net-Domain der Distribution zu verwenden.

B. Cloudflare R2 + Cloudflare

1. Erstellen Sie einen R2-Bucket, zum Beispiel my-images.
2. Verbinden Sie eine benutzerdefinierte Domain mit dem Bucket (R2 → Ihr Bucket → Settings → Custom Domains), zum Beispiel images.example.com, auf einer Zone im selben Cloudflare-Konto. Anfragen an diese Domain laufen über den Cloudflare-Cache. Verwenden Sie die Entwicklungs-URL r2.dev nicht für den Produktivbetrieb.
3. Erstellen Sie ein R2-API-Token (R2 → Manage API tokens) mit Object Read & Write, beschränkt auf diesen Bucket. Kopieren Sie die angezeigte Access Key ID und den Secret Access Key.
4. Erstellen Sie ein Cloudflare-API-Token (My Profile → API Tokens) für die Zone mit Zone → Cache Purge → Purge. Zone → Zone → Read ist optional.
5. Im Dashboard:
   • Speicheranbieter Cloudflare R2, Bucket my-images, Endpoint https://<account_id>.r2.cloudflarestorage.com (in den S3-API-Details Ihres Buckets angezeigt), Region auto sowie die R2 Access Key ID und der Secret Access Key.
   • CDN Cloudflare, die Zone-ID (Overview-Seite der Domain, Abschnitt API), das API-Token und die CDN-Domain https://images.example.com.

C. Google Cloud Storage + Cloudflare

Google Cloud Storage wird über seine S3-kompatible XML-API mit HMAC-Schlüsseln angebunden.

1. Erstellen Sie den Bucket, zum Beispiel my-images.
2. Erstellen Sie ein Dienstkonto und weisen Sie ihm Storage Object User (roles/storage.objectUser) nur für diesen Bucket zu.
3. Erstellen Sie einen HMAC-Schlüssel für das Dienstkonto: Cloud Storage → Settings → Interoperability → Create a key for a service account. Kopieren Sie Access-ID und Secret.
4. Machen Sie die optimierten Dateien für Ihr CDN lesbar. Cloudflare ruft Dateien über HTTPS aus Cloud Storage ab, daher müssen Objekte unter optimized/ öffentlich lesbar sein. Bei einheitlichem Zugriff auf Bucket-Ebene macht die Rolle Storage Object Viewer für allUsers den gesamten Bucket lesbar, originals/ eingeschlossen. Wenn Ihre Originale privat bleiben müssen, schalten Sie eine authentifizierende Schicht davor (zum Beispiel einen Cloudflare Worker, der Anfragen an den Bucket signiert).
5. Richten Sie einen proxied Cloudflare-DNS-Eintrag auf Cloud Storage, zum Beispiel images.example.com. Benennen Sie den Bucket entweder nach dem Hostnamen und verwenden Sie einen proxied CNAME auf c.storage.googleapis.com, oder nutzen Sie eine Cloudflare Origin Rule, die Anfragen an storage.googleapis.com sendet und den Bucket-Namen an den Anfang des Pfads setzt.
6. Erstellen Sie ein Cloudflare-API-Token für die Zone mit Zone → Cache Purge → Purge (Zone → Zone → Read optional).
7. Im Dashboard: Speicheranbieter Google Cloud Storage, Bucket, Endpoint https://storage.googleapis.com, Region auto, HMAC-Access-ID und Secret; CDN Cloudflare, Zone-ID, API-Token und CDN-Domain https://images.example.com.

D. MinIO oder beliebiger S3-kompatibler Speicher + Cloudflare

Dies gilt für MinIO und S3-kompatible Dienste wie Hetzner, Wasabi, Vultr, SumoPod, Alibaba Cloud OSS, Tencent Cloud COS und DigitalOcean Spaces.

1. Erstellen Sie den Bucket und einen auf diesen Bucket beschränkten Schlüssel mit Put, Get und Delete für Objekte (siehe Minimale Berechtigungen unten).
2. Machen Sie optimized/ für Ihr CDN lesbar, zum Beispiel mit einer Bucket-Richtlinie, die anonymes s3:GetObject nur auf optimized/* erlaubt. Bei MinIO:

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": {        "AWS": [          "*"        ]      },      "Action": [        "s3:GetObject"      ],      "Resource": [        "arn:aws:s3:::my-images/optimized/*"      ]    }  ]}

3. Schalten Sie Cloudflare vor den Bucket: ein proxied DNS-Eintrag für images.example.com, der auf den öffentlichen Host des Buckets zeigt. Wenn der Anbieter seinen eigenen Hostnamen in der Anfrage erwartet, fügen Sie eine Cloudflare Origin Rule hinzu, die den Host-Header umschreibt (und bei Path-Style-Hosts den Bucket-Namen in den Pfad einfügt).
4. Erstellen Sie ein Cloudflare-API-Token für die Zone mit Zone → Cache Purge → Purge (Zone → Zone → Read optional).
5. Im Dashboard: Wählen Sie den Anbieter aus der Tabelle, geben Sie Bucket, Endpoint, Region (auto, wenn der Anbieter keine hat) und Schlüssel ein; aktivieren Sie Path-Style-Anfragen, wo die Tabelle es angibt; dann CDN Cloudflare, Zone-ID, API-Token und CDN-Domain.

Minimale Berechtigungen

Geben Sie smallPict Schlüssel, die nur das können, was nötig ist, und zwar für einen einzigen Bucket.

Die Verbindungsprüfung

Bei jedem Speichern (und wenn Sie Prüfung wiederholen wählen) prüft smallPict die gesamte Verbindung, bevor es sie verwendet:

1. Speicher: schreibt eine kleine Testdatei unter .smallpict-probe/ in Ihren Bucket, liest sie zurück und löscht sie.
2. Cloudflare: sendet einen Test-Purge für eine einzelne URL an Ihre Zone.
3. CloudFront: erstellt eine Test-Invalidierung für einen Pfad /.smallpict-probe/.... Sie zählt zu Ihren CloudFront-Invalidierungspfaden des Monats.

Schlägt ein Schritt fehl, wird nichts umgeschaltet. Das Dashboard zeigt den Grund neben dem betroffenen Feld an, zum Beispiel beim Bucket-Namen oder beim API-Token. Die Verbindungsprüfung ist auf 5 Versuche pro Minute begrenzt.

Bucket-Zugriff für Ihr CDN

• optimized/ muss für Ihr CDN lesbar sein: entweder öffentlich lesbar für dieses Präfix oder über CDN-Origin-Zugriff auf einen privaten Bucket (CloudFront Origin access control oder eine benutzerdefinierte R2-Domain).
• originals/ kann privat bleiben. Ihr CDN braucht es nie.
• CORS ist nur nötig, wenn Browser die Bilder per JavaScript Cross-Origin abrufen (zum Beispiel mit fetch() oder in einem Canvas). Einfache <img>-Tags brauchen es nicht. Falls Sie es benötigen, erlauben Sie GET und HEAD vom Origin Ihrer Website.

Objektstruktur und URLs

Die CDN-Domain kann ein Pfadpräfix enthalten, zum Beispiel https://example.com/images; die URL lautet dann https://example.com/images/optimized/<job_id>.<ext>.

Cache-Header

Optimierte Dateien werden mit Cache-Control: public, max-age=31536000, immutable geschrieben. Jeder Job erhält einen eindeutigen Schlüssel, daher hat ein neues Ergebnis immer eine neue URL, und ein Purge ist selten nötig. Achten Sie darauf, dass die Caching-Regeln Ihres CDN diesen Header nicht mit einer kürzeren Dauer überschreiben.

Cache-Purge

• Purge-Anfragen über die API (POST /v1/purge) gehen gebündelt an Ihr CDN.
• Bei Cloudflare werden Dateien per URL gepurgt. „Purge all“ leert nur Ihren Auslieferungshost und Ihr Pfadpräfix, nicht Ihre gesamte Zone.
• Bei CloudFront werden Dateien mit Invalidierungen gepurgt. „Purge all“ erstellt eine Invalidierung /*. Invalidierungspfade über das monatliche Freikontingent von CloudFront hinaus stellt AWS Ihrem Konto in Rechnung.

Moduswechsel

Ein Moduswechsel verschiebt keine vorhandenen Dateien. Bereits ausgelieferte Dateien behalten ihre aktuellen URLs; nur neue Jobs nutzen den neuen Modus.

• Verwaltet → BYO: Neue Jobs landen in Ihrem Bucket und werden von Ihrem CDN ausgeliefert. Dateien, die bereits auf cdn.smallpict.app liegen, bleiben dort.
• BYO → verwaltet: Neue Jobs nutzen wieder verwalteten Speicher und das verwaltete CDN. Ihre BYO-Einstellungen und Schlüssel bleiben gespeichert, aber ungenutzt, sodass Sie ohne erneute Eingabe zurückwechseln können, bis Sie Trennen wählen.
• Trennen: löscht die gespeicherten Schlüssel und BYO-Einstellungen und bringt Sie zurück in den verwalteten Modus. Dateien in Ihrem Bucket bleiben unangetastet.

Wenn etwas fehlschlägt

• Kann smallPict nicht in Ihren Bucket schreiben, versucht es es erneut und lässt den Job dann fehlschlagen, mit einem Grund, den Sie in der API-Antwort nachlesen können.
• Das Dashboard zeigt den letzten Fehler und seinen Zeitpunkt an, zusammen mit einer Schaltfläche Prüfung wiederholen.
• Sie erhalten eine E-Mail pro Vorfall, nicht eine pro fehlgeschlagenem Job.
• smallPict weicht nie auf den verwalteten Speicher aus. Ihre Dateien werden nie an einem Ort gespeichert, den Sie nicht gewählt haben.

Sicherheit

• Schlüssel werden in einem verschlüsselten Secrets-Speicher aufbewahrt. Sie werden nie wieder angezeigt, nie von der API zurückgegeben und nie in Logs geschrieben.
• Um einen Schlüssel zu rotieren, geben Sie den neuen ein und speichern; die Verbindungsprüfung läuft mit dem neuen Schlüssel. Lassen Sie ein Schlüsselfeld leer, um den gespeicherten Schlüssel zu behalten.
• Speicher- und CDN-Endpoints müssen HTTPS verwenden. Endpoints, die auf private, Loopback-, Link-Local- oder andere interne Adressen auflösen, werden abgelehnt.
• Verwenden Sie separate, eng begrenzte Schlüssel für smallPict, und widerrufen Sie sie in der Konsole Ihres Anbieters, wenn Sie BYO nicht mehr nutzen.