Diese Seite ist eine maschinelle Übersetzung der englischen Seite, die maßgeblich ist. Englische Seite lesen
Ein CDN vor die Medienauslieferung setzen
Ein CDN vor dem Server (Cloudflare, Google Cloud CDN, CloudFront und so weiter) kann Medien ausliefern (/media/ und /media/proxy/).
Anfragen, die aus dem CDN-Cache beantwortet werden, brauchen weder CPU noch Transfervolumen des Servers.
Diese Anleitung behandelt den Aufbau, in dem der Server der Origin des CDN ist (Origin Pull). Sie gilt für jeden Blob-Speicher: Mit blob = s3 oder blob = gcs liest der Server
die Dateien aus dem privaten Bucket und liefert sie unter /media/ aus wie mit blob = fs, der Bucket ist also nie die Origin des CDN.
Wenn der ganze Server hinter dem CDN liegt, kann er außerdem Anfragen ablehnen, die nicht über das CDN kamen.
Einrichten
Abschnitt betitelt „Einrichten“Setze media_origin (MY_MEDIA_ORIGIN) auf den Hostnamen des CDN (zum Beispiel media.example.org).
MY_MEDIA_ORIGIN=https://media.example.org- Der Wert ist nur eine Origin (
scheme://host[:port]), ohne Pfad, Query oder abschließenden Schrägstrich.httpsist Pflicht, undhttpist nur für Loopback-Hosts wielocalhosterlaubt. Ein ungültiger Wert lässt den Start fehlschlagen. - Ist er nicht gesetzt, werden Medien von der eigenen Origin des Servers ausgeliefert (
https://{host}). - Diese URLs verwenden diese Origin:
{media_origin}/media/...für lokale Medien und{media_origin}/media/proxy/...für den Proxy entfernter Medien. Erfasst ist jede URL, die die Client-API, ActivityPub (attachment,icon,imageund dasiconeigener Emojis) und Link-Vorschauen (OGP) ausgeben. - Die Content-Security-Policy des Webclients fügt diese Origin zu
img-srcundmedia-srchinzu. - Föderierte URIs, etwa die
ideines ActivityPub-Objekts, bleiben unterhttps://{host}/, was auch immermedia_originist. Es ändert sich nur der Ort, an dem Dateien ausgeliefert werden, nicht die Bezeichner. - URLs werden bei jedem Lesen neu gebildet und nicht in der Datenbank gespeichert, eine Änderung von
media_originändert also auch die URLs vorhandener Medien. Alte URLs, die entfernte Server gespeichert haben, funktionieren weiter, solange/media/auf der alten Origin weiter ausliefert.
Das CDN auf den Server richten
Abschnitt betitelt „Das CDN auf den Server richten“- Mache den öffentlichen Hostnamen des Servers (
https://{host}) zur Origin (zum Backend). Das CDN muss vom Server nur Pfade unter/media/abrufen. - Der Server beschränkt
/media/und/media/proxy/nicht nach Hostnamen. Er liefert aus, welchenHostdas CDN auch sendet. /media/braucht keine Authentifizierung, und Authorized Fetch gilt dafür nicht. Der Server beantwortet unsignierte Anfragen des CDN, wie sie sind.- Bei entfernten Medien (
/media/proxy/{id}/{variant}?sig=...) istsigTeil der URL. Nimm den Query-String in den Cache-Schlüssel auf. Sonst teilen sich URLs mit verschiedenen Signaturen einen Eintrag. - Lass das
Cache-Controlder Origin bestimmen, wie lange gecacht wird (überschreibe es nicht im CDN).
| Pfad | Cache-Control |
|---|---|
/media/{...} (lokale Medien) |
public, max-age=31536000, immutable (ein Jahr) |
/media/proxy/{...} (entfernte Medien) |
public, max-age= die Sekundenzahl der Servereinstellung remote_media_cache_ttl_seconds |
Beide werden mit Cross-Origin-Resource-Policy: cross-origin zurückgegeben, damit Seiten anderer Origins sie lesen können.
Auf Cloud Run richtet ingress-cloudflare-media das mit OpenTofu ein: siehe Auf Cloud Run bereitstellen.
Wer Medien-URLs öffnen kann
Abschnitt betitelt „Wer Medien-URLs öffnen kann“Medien-URLs sind nicht zugriffsgeschützt. Jede Person, die die URL einer Datei hat, kann sie ohne Anmeldung öffnen, unabhängig von der Sichtbarkeit des Beitrags, an den sie angehängt ist. Das gilt mit und ohne CDN und schließt die Anhänge von Beiträgen nur für Follower und von Direktnachrichten sowie die Proxy-URLs entfernter Medien ein.
- Die URLs sind schwer zu erraten: Die URL einer lokalen Datei enthält Bezeichner mit einem zufälligen Anteil, und eine Proxy-URL trägt eine Signatur. Eine bekannte URL verrät keine anderen.
- Wer einen Beitrag gesehen hat, kann seine Medien-URLs weitergeben, und die URLs funktionieren für andere weiter.
- Antworten sind als
publicmarkiert, sodass das CDN und jeder gemeinsame Cache zwischen Server und Leser eine Kopie behalten dürfen (wie lange, steht in der Tabelle oben). Genau das lässt ein CDN Medien ausliefern, ohne den Server zu fragen.
Sag deinen Nutzern, dass ein nicht öffentlicher Beitrag zwar einschränkt, wer den Beitrag sieht, aber niemanden daran hindert, die Datei zu öffnen, wenn er den Link einer angehängten Datei hat.
Löschen und der Cache
Abschnitt betitelt „Löschen und der Cache“Nachdem du Medien gelöscht hast, behält der Cache des CDN sie für max-age. Eine gelöschte Datei kann bei lokalen Medien bis zu einem Jahr sichtbar bleiben, beim Proxy bis zu remote_media_cache_ttl_seconds.
Der Server leert den Cache des CDN nicht. Wenn etwas direkt nach einem Löschen oder einer Moderationsaktion verschwinden muss, leere ihn von Hand in der Konsole oder API des CDN.
Service Worker
Abschnitt betitelt „Service Worker“Der Service Worker des Webclients cacht keine Medien einer anderen Origin und überlässt sie der Netzwerkverarbeitung des Browsers, sodass nur der Cache des CDN gilt.
Anfragen ablehnen, die nicht über das CDN kamen
Abschnitt betitelt „Anfragen ablehnen, die nicht über das CDN kamen“Ein CDN schützt den Server nur vor den Anfragen, die durch es hindurchgehen. Ist die Origin zusätzlich unter ihrer eigenen Adresse erreichbar, wie *.run.app auf Cloud Run mit Verkehr aus dem Internet, kann jeder sie direkt aufrufen, an WAF und Cache vorbei.
Stehen die Adressen des CDN in trusted_proxies, verbindet sich auch ein Aufrufer auf der Serverless-Plattform des CDN selbst (etwa ein eigener Cloudflare Worker) von einer vertrauenswürdigen Adresse und kann die Client-IP wählen, die die Rate Limits sehen.
Die drei Einstellungen unten schließen das. Das CDN fügt jeder Anfrage, die es weiterleitet, einen geheimen Header hinzu, und der Server antwortet auf jede Anfrage ohne ihn mit 403, bevor er irgendetwas anderes mit ihr tut.
- Browser und Apps (Seiten, die Client-API, OAuth und Medien-URLs) und andere Server (ActivityPub-Zustellungen und -Abrufe)
erreichen das CDN unter
hostund unter dem Host vonmedia_origin. Das CDN beantwortet gecachte/media/-Dateien selbst und setztorigin_secret_headerbei jeder Anfrage, die es an den Server weiterleitet, auforigin_secret. - Die Plattform (Health-Probes, Uptime-Monitore, Cloud Tasks und Cloud Scheduler) und alle anderen, etwa ein Skript oder ein eigener Webhook, erreichen die eigene Adresse des Servers direkt, ohne den Header.
- Die Origin-Prüfung läuft im Server zuerst. Sie lässt eine Anfrage durch, die den Header einmal mit
origin_secretoderorigin_secret_previousträgt, und ohne den Header nurGETundHEADder Health-Checks undPOSTauf/_internal/. Sie entfernt den Header aus jeder Anfrage und lehnt den Rest mit403ab. - Eine Anfrage, die durchkommt, erreicht den Webclient, die Client-API, OAuth, ActivityPub, die Health-Checks oder
/_internal/oder/media/und/media/proxy/, die den Medienspeicher lesen (blob = fs,s3odergcs) oder die Datei eines anderen Servers weiterreichen. Eine abgelehnte Anfrage erhält403mitCache-Control: no-storeund erhöhtmy.http.origin_refused.
Nutze es, wenn der Server eine öffentliche Adresse hat, die die Plattform nicht für alles außer dem CDN schließen kann. Du brauchst es nicht, wenn eine Firewall oder die Plattform bereits einschränkt, wer sich verbinden kann, zum Beispiel bei einem Server, der nur in einem privaten Netzwerk hinter deinem Load Balancer lauscht.
Auch nicht, wenn dieser Load Balancer den Header des CDN selbst prüft und nur die Adressen des CDN zulässt, wie es ein AWS Application Load Balancer hinter CloudFront mit einer Listener-Regel und der verwalteten Präfixliste com.amazonaws.global.cloudfront.origin-facing kann. Trage dann sowohl die Adressen des Load Balancers als auch die des CDN in trusted_proxies ein, da jeder an X-Forwarded-For anhängt.
Es hilft nicht, wenn eine eigene Funktion der Plattform den Verkehr weiterleitet und keinen Header hinzufügt, den du kontrollierst, etwa ein Cloud-Run-Domain-Mapping. Nur ein CDN oder Load Balancer, der einen Request-Header hinzufügen kann, hilft.
| Einstellung | Was sie enthält |
|---|---|
origin_secret (MY_ORIGIN_SECRET) |
Der Wert, mindestens 32 Bytes sichtbares ASCII. Ein Geheimnis, gelesen aus der Umgebung oder aus MY_ORIGIN_SECRET_FILE |
origin_secret_header (MY_ORIGIN_SECRET_HEADER) |
Der Name des Headers, dein eigener. Pflicht zusammen mit origin_secret. Namen, die ein CDN nicht setzen darf oder die der Server oder ein Proxy liest, etwa solche mit dem Anfang cf- oder x-cf-, sind ungültig |
origin_secret_previous (MY_ORIGIN_SECRET_PREVIOUS) |
Ein zweiter akzeptierter Wert, nur während einer Rotation |
Ist keine davon gesetzt, wird nichts geprüft, und der Server verhält sich, als gäbe es diesen Abschnitt nicht.
Was ohne den Header durchkommt
Abschnitt betitelt „Was ohne den Header durchkommt“| Anfrage | Warum |
|---|---|
GET oder HEAD von /healthz, /readyz, /health/live, /health/ready, /api/v1/instance/health |
Die Probes der Plattform und Uptime-Monitore rufen sie direkt auf |
POST an Pfade unter /_internal/ |
Cloud Tasks und Cloud Scheduler rufen sie unter der eigenen URL des Servers auf. Sie tragen ihr eigenes signiertes Token |
Alles andere braucht den Header, auch im Wartungsmodus: der Webclient und seine Assets, /media/, die Client-API, OAuth und ActivityPub, einschließlich der Zustellungen anderer Server.
Alles, was den Server direkt unter seiner eigenen Adresse statt über das CDN aufruft, wird daher abgelehnt: ein eigener Webhook, ein Sprach-Medienserver, ein Skript. Richte es auf den Hostnamen des CDN.
Der Metriken-Port (metrics_listen) ist ein separater Listener, der nicht öffentlich ist und nicht geprüft wird.
Eine Anfrage, die das Geheimnis nicht trägt, hat beim Rest der Verarbeitung nichts mitzureden, auch wenn sie durchkommt: Ihre Client-IP ist die Gegenstelle der Verbindung, was auch immer X-Forwarded-For sagt, und ihre traceparent und X-Request-Id werden ignoriert.
Einrichten
Abschnitt betitelt „Einrichten“Jeder Hostname, den das CDN an den Server weiterleitet, braucht den Header: host, der Host von media_origin und eine separate account_domain, wenn das CDN sie ausliefert. Ein Medien-Host hinter demselben CDN setzt ihn ebenfalls, da /media/ wie alles andere abgelehnt wird.
-
Erzeuge den Wert und wähle einen Namen, den nichts anderes verwendet:
Terminal-Fenster openssl rand -hex 32 -
Setze den Header zuerst im CDN. Der Server ignoriert einen Header, den er nicht kennt, dieser Schritt ändert also noch nichts.
- Cloudflare: eine Transform Rule für Anfrage-Header (Rules, dann Transform Rules, dann Modify Request Header), bei jedem Tarif. Wähle alle eingehenden Anfragen der Zone und wähle Set static mit deinem Namen und Wert. Sie ersetzt einen Wert, den ein Client gesendet hat. Eine Regel nur für manche Hostnamen sperrt die anderen aus.
- Amazon CloudFront: ein benutzerdefinierter Origin-Header am Origin jeder Distribution. Er ersetzt ebenfalls den Wert eines Betrachters.
- Google-Cloud-Load-Balancer: ein benutzerdefinierter Anfrage-Header am Backend-Dienst.
- Jedes andere CDN oder jeder andere Proxy: Der Header muss bei jeder Anfrage an den Server gesetzt, nicht angehängt werden.
-
Setze
MY_ORIGIN_SECRETundMY_ORIGIN_SECRET_HEADERund stelle bereit.my config checkvalidiert sie und wiederholt, was geprüft wird, kann aber das CDN nicht sehen. -
Prüfe von außen, mit der Adresse des Origins selbst:
Terminal-Fenster curl -s -o /dev/null -w '%{http_code}\n' https://<host>/ # 200: through the CDNcurl -s -o /dev/null -w '%{http_code}\n' https://<origin address>/ # 403: directlycurl -s -o /dev/null -w '%{http_code}\n' https://<origin address>/health/live # 200: a health check
Liste außerdem die Adressen des CDN in trusted_proxies auf, sonst sieht der Server einen einzigen Client, und alle Anfragen teilen sich die Ratenlimits des CDN; my config check warnt davor.
Eine abgelehnte Anfrage erhält dasselbe 403-Problemdokument wie jede andere verbotene Anfrage, mit Cache-Control: no-store, wie auch immer der Header falsch war. Nichts in der Antwort nennt den Header.
Wenn alle ausgesperrt sind
Abschnitt betitelt „Wenn alle ausgesperrt sind“Eine falsche Einrichtung lehnt jede Anfrage ab, während die Health-Checks 200 bleiben, sodass die Plattform einen gesunden Server sieht und ein Uptime-Monitor von /health/live nichts bemerkt. Die Anzeichen sind:
403für jede Seite über das CDN.- Die Metrik
my.http.origin_refusedsteigt, während die Anfragen vonhttp.server.request.durationaufhören. - Zeilen
http requestim Log mit dem Status403und ohnehttp.route. Das Log und die Traces enthalten nie den Header, seinen Namen oder seinen Wert. Eine abgelehnte Anfrage erzeugt keinen Trace-Span.
Stelle zur Wiederherstellung ohne die Prüfung bereit: Entferne MY_ORIGIN_SECRET und MY_ORIGIN_SECRET_HEADER. Andere Server wiederholen ihre Zustellungen, aber die Leute konnten den Server in der Zwischenzeit nicht erreichen.
Vergleiche dann den Namen und den Wert im CDN mit den Einstellungen, prüfe, dass die Regel jeden Hostnamen abdeckt, und setze sie erneut.
Den Wert rotieren
Abschnitt betitelt „Den Wert rotieren“CDN und Server können sich nicht im selben Moment ändern, und jedes Replikat des Servers startet in seinem eigenen Tempo neu. Mit nur einem akzeptierten Wert würde eine Änderung den Verkehr ablehnen, solange sie sich unterscheiden. Der Server akzeptiert deshalb während einer Rotation zwei Werte:
- Setze
MY_ORIGIN_SECRETauf den neuen Wert undMY_ORIGIN_SECRET_PREVIOUSauf den alten und stelle bereit. Beide Werte kommen durch. - Ändere den Wert im CDN und warte, bis die Änderung alle seine Standorte erreicht hat.
- Entferne
MY_ORIGIN_SECRET_PREVIOUSund stelle bereit.my config checkwarnt, solange er gesetzt ist.
Der Name des Headers lässt sich so nicht rotieren. Um ihn zu ändern, wiederhole die Einrichtung bei kurz abgeschalteter Prüfung des Servers, oder setze den neuen Namen im CDN neben dem alten, bevor du ihn bereitstellst.
Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt