Cache-Invalidierung
smoxy cached Inhalte am Edge, um die Last auf dem Origin-Server zu reduzieren. Wenn sich Inhalte ändern, muss die gecachte Version invalidiert werden, damit Besucher das Update sehen. smoxy bietet mehrere Methoden dafür - vom Löschen einer einzelnen URL bis zum Flushen ganzer Tag-Gruppen.
Alle Invalidierungsanfragen verwenden die HTTP-Methode BAN und erfordern das im Proxy der Zone festgelegte Cache-Token.
Diese BAN-Anfragen (der Edge akzeptiert PURGE als gleichwertige Methode) gehen direkt an den Edge von smoxy und werden durch das Purge-Token der Zone authentifiziert - das Core-System führt die Invalidierung selbst durch, ganz ohne Aufruf der Hub-API. Das hält Framework-Integrationen einfach: Ein Cache-Invalidator im Stil von Symfony/FOSHttpCache muss lediglich BAN-Anfragen an den Hostnamen senden. Die Cache-Löschendpunkte der Hub-API sind eine zusätzliche Erleichterung auf Basis desselben Mechanismus.
INFO
Cloudflare-Nutzer: Cloudflare kann BAN/PURGE-Requests blockieren. Siehe Cloudflare Setup für die empfohlene Lösung.
Methoden
Flush URL
Löscht den Cache für eine bestimmte URL.
curl -X BAN -H "secret: <token>" -H "url: /" https://www.example.com/Die URL lässt sich auch als Request-Ziel übergeben:
curl -X BAN -H "secret: <token>" https://www.example.com/products/my-productFlush Tags
Löscht alle gecachten Inhalte, die mit einem oder mehreren Cache-Tags versehen sind. Tags werden über den x-cache-tags-Header der Origin-Antworten gesetzt (siehe Cache für die Tag-Konfiguration).
Einen einzelnen Tag flushen:
curl -X BAN -H "secret: <token>" -H "tags: smartphones" https://www.example.com/Mehrere Tags gleichzeitig flushen (kommagetrennt):
curl -X BAN -H "secret: <token>" -H "tags: smartphones,accessories" https://www.example.com/Wann Tags verwenden: Tags sind der effizienteste Weg, Gruppen zusammengehöriger Inhalte zu invalidieren. Wenn ein Shop beispielsweise Produktseiten mit ihrem Kategorienamen taggt, lassen sich alle „Samsung"-Produkte mit einem einzigen Request flushen, anstatt jede URL einzeln zu purgen.
Gängige Tagging-Strategien:
| Strategie | Tag-Beispiel | Anwendungsfall |
|---|---|---|
| Nach Kategorie | smartphones, laptops | Neue Produkte in einer Kategorie |
| Nach Marke | samsung, apple | Markenweite Preisaktualisierung |
| Nach Produkt-ID | product-123 | Einzelnes Produkt geändert |
| Nach Seitentyp | listing, detail, home | Template- oder Layout-Änderung |
Flush File
Löscht eine bestimmte Cache-Datei anhand ihres Cache-Hashs. Nützlich, wenn der genaue Cache-Eintrag bekannt ist, der invalidiert werden soll.
curl -X BAN -H "secret: <token>" -H "cache-file: 469640790ad5bda4d1cc6a19f6770214.html" https://www.example.com/INFO
Tipp: Der Cache-Datei-Hash wird als Response-Header zurückgegeben, wenn Debug-Header aktiviert sind.
Flush Content Class
Löscht alle gecachten Inhalte einer ganzen Klasse mit einer einzigen Anfrage - Bilder, HTML-Dokumente oder statische Assets. smoxy versieht jedes gecachte Objekt automatisch mit seiner Inhaltsklasse, es ist also keine Konfiguration am Origin nötig.
curl -X BAN -H "secret: <token>" -H "type: images" https://www.example.com/type | Löscht |
|---|---|
html | Alle gecachten HTML-Dokumente |
images | Alle gecachten Bilder |
assets | Alle übrigen gecachten statischen Dateien (CSS, JavaScript, Fonts, ...) |
Nützlich, wenn sich eine Art von Inhalt komplett ändert - zum Beispiel images nach dem Neugenerieren von Thumbnails flushen, ohne das gecachte HTML anzutasten. Ein type-Header lässt sich mit einem tags-Header in derselben Anfrage kombinieren; beide werden angewendet. Die Singularformen image und asset werden ebenfalls akzeptiert.
Dieselbe Klassen-Invalidierung ist auch ohne BAN-Token möglich: über die Schnellaktion Cache nach Typ leeren im Hub oder über die Hub-API mit POST /api/zones/{zoneId}/cache/clear und action auf html, images oder assets:
curl -X POST https://api.smoxy.eu/api/zones/{zoneId}/cache/clear \
-H "X-API-TOKEN: <token>" \
-H "Content-Type: application/json" \
-d '{"action": "images"}'Das Feld cdnCleared in der Antwort gibt an, ob auch der zugehörige CDN-Cache geleert wurde. Der Endpunkt ist auf einen Clear pro Zone alle 5 Sekunden begrenzt (siehe Rate-Limiting).
Flush All
Löscht den gesamten Cache der Zone. Nur als letzten Ausweg verwenden - es zwingt jede Anfrage, frisch vom Origin abgerufen zu werden, bis der Cache wieder aufgewärmt ist.
curl -X BAN -H "secret: <token>" -H "type: all" https://www.example.com/INFO
type: flushall ist die frühere Schreibweise dieser Anfrage und funktioniert weiterhin.
Die richtige Methode wählen
| Methode | Umfang | Geschwindigkeit | Origin-Last |
|---|---|---|---|
| Flush URL | Einzelne URL | Sofort | Minimal |
| Flush Tags | Gruppe verwandter Seiten | Sofort | Moderat |
| Flush File | Einzelner Cache-Eintrag | Sofort | Minimal |
| Flush Content Class | Alle Bilder, HTML-Dokumente oder Assets | Sofort | Moderat bis hoch |
| Flush All | Gesamter Zonen-Cache | Sofort | Hoch (Cache-Kaltstart) |
Mit der gezielten Methode beginnen. Flush URL für einzelne Seiten verwenden, Flush Tags für Gruppen, Flush Content Class für eine ganze Inhaltsart und Flush All nur wenn nötig.
Rate-Limiting
BAN/PURGE-Anfragen werden am Edge gedrosselt. Bis zu 5 Anfragen pro Sekunde werden sofort verarbeitet; oberhalb dieser Rate wird jede weitere Anfrage um 100 ms verzögert. Anfragen werden nie abgelehnt - sie werden lediglich verlangsamt.
Der Cache-Clear-Endpunkt der Hub-API - auf dem auch die Schnellaktionen im Dashboard aufbauen - hat ein eigenes Limit: ein Cache-Clear pro Zone alle 5 Sekunden. Anfragen darüber werden mit 429 Too Many Requests und einem Retry-After-Header abgelehnt, der den nächsten möglichen Zeitpunkt nennt.
TIP
Den gesamten Cache nicht mit einer BAN/PURGE-Anfrage pro URL leeren - große Mengen laufen in die Drosselung. Um alles zu invalidieren, genügt eine einzelne Flush-All-Anfrage (oder die Schnellaktion Gesamten Cache leeren im Dashboard) - sie leert den gesamten Zonen-Cache mit einem Request.
Flush All außerdem nicht bei jedem Request oder jeder Änderung auslösen, sondern nur, wenn eine vollständige Invalidierung wirklich nötig ist: am Ende von Sync-Prozessen (z. B. Preis- und Bestandsupdates in einem Onlineshop) oder nach dem Release einer neuen App-Version, wenn der Cache für alle URLs der App geleert werden muss.
Schnellaktionen
Der Cache lässt sich auch ohne Code über die Schnellaktionen im Dashboard leeren:
- Gesamten Cache leeren - entspricht Flush All
- Cache nach URL leeren - entspricht Flush URL
- Cache nach Tag leeren - entspricht Flush Tags
- Cache nach Typ leeren - alle gecachten HTML-Dokumente, Bilder oder Assets in einem Schritt purgen (entspricht Flush Content Class)