Medien in Payload CMS mit Hetzner S3 Object Storage hosten

In diesem Beitrag werden wir uns eingehend damit beschäftigen, wie man Hetzner Object Storage verwendet, um Mediendateien in Payload CMS zu hosten, indem wir sein flexibles Speicheradapter-System nutzen.

Egal, ob Sie ein benutzerdefiniertes CMS oder eine produktionsbereite Plattform mit Asset-Management-Funktionen erstellen, die Integration von Hetzners kostengünstigem S3-kompatiblem Storage mit Payload ist eine leistungsstarke und erschwingliche Lösung.

Einrichten des Storage Buckets

Melden Sie sich beim Hetzner Cloud Console an.
Erstellen Sie ein neues Projekt (oder wählen Sie ein bestehendes aus).
Fügen Sie innerhalb des Projekts einen neuen Speicherbucket hinzu.
Navigieren Sie zum Abschnitt Access Keys und generieren Sie ein neues Schlüsselpaar.
Kopieren Sie die Access Key ID und den Secret Access Key in die .env-Datei Ihres Payload-Projekts.
Kopieren Sie auch den Namen Ihres Speicherbuckets.

Ihre .env-Datei sollte die folgenden Variablen enthalten:

HETZNER_BUCKET="bucket-name"
HETZNER_ACCESS_KEY_ID="access-key-id"
HETZNER_SECRET_ACCESS_KEY="secret-access-key"

Payload-Konfiguration

Um Payload CMS mit Hetzner Object Storage zu verbinden, verwenden Sie das @joneslloyd/payload-storage-hetzner -Plugin. Dieser von der Community entwickelte Adapter ermöglicht eine nahtlose Integration mit Hetzners S3-API.

Hier ist eine grundlegende Plugin-Konfiguration in Ihrem Payload-Setup:

import hetznerStorage from '@joneslloyd/payload-storage-hetzner';

export default buildConfig({
  /* your config */
  plugins: [
    hetznerStorage({
      collections: {
        media: true,
      },
      bucket: process.env.HETZNER_BUCKET!,
      region: 'nbg1',
      credentials: {
        accessKeyId: process.env.HETZNER_ACCESS_KEY_ID!,
        secretAccessKey: process.env.HETZNER_SECRET_ACCESS_KEY!,
      },
      acl: 'public-read',
    }),
  ],
});

Für vollständige Konfigurationsoptionen siehe die npm-Dokumentation .

Unterstützung von Client-seitigen Uploads (Wichtig für Vercel)

Beim Bereitstellen von Payload auf Vercel , können Sie auf Upload-Beschränkungen stoßen, die auf das 4.5 MB Body-Größenlimit von Vercel zurückzuführen sind.

Um dies zu umgehen, können Sie Client-seitige Uploads aktivieren. Dadurch können Mediendateien direkt vom Browser zu Hetzner hochgeladen werden, wodurch die API-Schicht von Payload umgangen wird.

Um Client-Uploads zu aktivieren, setzen Sie clientUploads: true in der Plugin-Konfiguration.

CORS-Konfiguration für Hetzner

Client-seitige Uploads erfordern ordnungsgemäß konfigurierte CORS (Cross-Origin Resource Sharing)-Regeln für Ihren Hetzner Object Storage-Bucket. Wenn sie nicht konfiguriert sind, stoßen Sie auf diesen häufigen Fehler:

Access to fetch at '<hetzner-url>' from origin '<your-domain>' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Schritt-für-Schritt: CORS über AWS CLI einrichten

Leider bietet Hetzner derzeit keine Benutzeroberfläche zur Bearbeitung der CORS-Einstellungen. Stattdessen verwenden wir die AWS CLI, um sie zu konfigurieren.

1. Fügen Sie eine CORS-Datei hinzu

Erstellen Sie eine s3-cors.json-Datei in Ihrem Payload-Projekt:

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://your-domain.com"],
      "AllowedHeaders": ["*"],
      "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
      "MaxAgeSeconds": 3000
    }
  ]
}

Damit können Sie Ihre CORS-Konfiguration in der Versionskontrolle verfolgen.

2. Installieren Sie die AWS CLI
Befolgen Sie die AWS CLI Installationsanleitung .

3. Erstellen Sie ein AWS CLI-Profil
Fügen Sie im .aws-Ordner Ihres Systems (z. B. ~/.aws oder C:\Users\<your-user>\.aws), Folgendes hinzu:

credentials

[<bucket-name>]
aws_access_key_id = <access-key-id>
aws_secret_access_key = <secret-access-key>

config

[profile <bucket-name>]
region = eu-central-1
output = json
endpoint_url = https://<bucket-region>.your-objectstorage.com

4. Wenden Sie die CORS-Konfiguration an

Führen Sie aus dem Verzeichnis Ihres Payload-Projekts den folgenden Befehl aus:

aws s3api put-bucket-cors \
  --bucket <your-bucket-name> \
  --cors-configuration file://./s3-cors.json \
  --endpoint-url https://<bucket-region>.your-objectstorage.com \
  --profile <bucket-name>

Fazit
Mit dieser Einrichtung ist Ihr Payload CMS nun vollständig in Hetzners Object Storage integriert - und bereit für effizientes, skalierbares Medienschalten. Egal, ob Sie eine Marketingseite, ein internes Dashboard oder ein benutzerdefiniertes CMS erstellen, diese Kombination bietet Leistung und Flexibilität ohne hohe Kosten.

Danke fürs Lesen! Wenn Sie Fragen, Feedback oder Verbesserungsvorschläge haben, können Sie sich gerne melden.