Cache
smoxy bietet eine CDN-Caching-Schicht, die Kopien der Inhalte am Edge speichert. Diese Anleitung behandelt die für die Zone verfügbare Caching-Konfiguration -- Caching-Verhalten, TTL, Cache-Key-Zusammensetzung, Cache-Tags, Edge-Verarbeitung und Stale-Cache-Verhalten. Wo die Cache-Entscheidung im gesamten Anfrageablauf steht, zeigt der Lebenszyklus einer Anfrage.
Dynamischer Cache
Der Schalter Dynamischer Cache aktiviert das Caching der text/html-Antworten der Zone auf den Edge-Servern von smoxy, was die Origin-Last reduziert und die Performance verbessert. Statische Assets werden unabhängig von dieser Einstellung gecacht.
Gut geeignet für HTML-Caching: Produkt- und Kategorieseiten, Blogbeiträge, Landingpages, Dokumentation -- jede Seite, deren HTML sich nicht pro Besucher ändert. Nicht geeignet: personalisierte Seiten (Benutzer-Dashboards, Warenkörbe), Seiten mit Echtzeitdaten und dynamische API-Antworten. Für gemischte Seiten (z. B. eine Produktseite mit personalisiertem Warenkorb-Widget) können SSI/ESI die statischen Teile getrennt von den dynamischen Fragmenten cachen.
Ändert sich der HTML-Inhalt, sollte der Cache invalidiert werden, damit Besucher die aktuelle Version sehen (Cache-Invalidierung). Die konfigurierte TTL gilt für HTML wie für alle anderen gecachten Inhalte; variiert das HTML nach Cookie (Sprache, Login-Status), sollte die Cookie-Komponente entsprechend konfiguriert werden. Eine Steuerung pro Anfrage -- Caching nur für bestimmte Pfade oder keines für eingeloggte Benutzer -- ist über Conditional Rules möglich.
Cache-Control berücksichtigen
Der Schalter Origin-Cache-Control berücksichtigen -- standardmäßig aktiviert -- überlässt dem Origin die Steuerung des Cachings pro Antwort über dessen Cache-Control-Header. Wenn aktiviert, cacht smoxy keine Antworten, die mit no-cache, private oder max-age=0 gekennzeichnet sind, sodass diese Anfragen weiterhin den Origin erreichen.
s-maxage hat Vorrang. Als Shared Cache wertet smoxy die s-maxage-Direktive vor max-age aus. Eine Antwort mit Cache-Control: max-age=0, s-maxage=3600 wird daher gecacht -- max-age=0 untersagt nur dem Browser das Caching, während s-maxage>0 Proxy-Caches wie smoxy das Speichern ausdrücklich erlaubt. Nur ohne positives s-maxage führt max-age=0 zu einem Bypass. Diese Kombination ist in Frameworks üblich, die Browser- und Proxy-Caching trennen, etwa Shopware 6 oder Symfony HttpCache.
| Einstellung | Standard |
|---|---|
| Origin-Cache-Control berücksichtigen | Aktiviert |
Wenn deaktiviert, verwendet smoxy die konfigurierte TTL für alle cachebaren Antworten, unabhängig vom Cache-Control-Header des Origins.
Cache-TTL (Time-to-Live)
Die Standard-TTL bestimmt, wie lange smoxy die Inhalte zwischenspeichert, bevor eine frische Kopie vom Origin-Server angefordert wird. Das Dropdown befindet sich in der Karte Origin-Cache-Control berücksichtigen und bietet feste Vorgaben:
5 Minuten · 15 Minuten · 30 Minuten · 1 Stunde · 6 Stunden · 12 Stunden · 1 Tag · 2 Tage · 3 Tage · 7 Tage
Der Standard ist 7 Tage (604.800 Sekunden).
Browser-Cache-TTL
Die Browser-Cache-TTL bestimmt, wie lange Browser die vom CDN ausgelieferten Antworten zwischenspeichern -- gesendet an die Clients als Cache-Control-Direktive max-age. Während die Standard-TTL regelt, wie lange smoxy Inhalte am Edge vorhält, regelt diese Einstellung die Kopie im Browser der Besucher.
| Option | Verhalten |
|---|---|
| Von smoxy verwaltet (Standard) | Browser folgen dem serverseitigen Cache-Ablauf |
| Kein Browser-Caching | Weist Browser an, nicht zu cachen |
| Feste Vorgabe | Überschreibt die vom Origin zurückgegebene max-age und die Standard-TTL der Zone |
Die festen Vorgaben reichen von 5 Minuten bis 1 Jahr:
5 Minuten · 15 Minuten · 30 Minuten · 1 Stunde · 6 Stunden · 12 Stunden · 1 Tag · 7 Tage · 30 Tage · 1 Jahr
Über die API ist die Einstellung als Zonen-Feld cacheControlPublicMaxAgeOverride verfügbar und akzeptiert jeden Wert zwischen 0 und 31536000 Sekunden (1 Jahr) oder -1 für Von smoxy verwaltet. Ein Wert, der keiner Vorgabe entspricht, erscheint im Dropdown als Benutzerdefiniert (Ns).
Cache-Key
Der Cache-Key bestimmt, wie smoxy eindeutige gecachte Antworten identifiziert. Zwei Anfragen mit demselben Cache-Key liefern denselben gecachten Inhalt. Das Verständnis des Cache-Keys ist wichtig, um zu vermeiden, dass veralteter oder falscher Inhalt ausgeliefert wird.
Komponenten
Standardmäßig wird der Cache-Key aus der Request-URI und dem Query-String gebildet. Vier optionale Komponenten lassen sich ergänzen -- alle standardmäßig deaktiviert:
| Komponente | Steuerung | Standard | Beschreibung |
|---|---|---|---|
| Request-URI | Immer enthalten | -- | Der Anfragepfad ist immer Teil des Cache-Keys |
| Request-Hostname | Schalter | Deaktiviert | Bezieht den Anfrage-Hostnamen ein, sodass verschiedene Hostnamen getrennt cachen |
| Land | Schalter | Deaktiviert | Bezieht das Land des Besuchers (per GeoIP) ein, sodass verschiedene Länder getrennt cachen |
| Cookie-Wert | Schalter | Deaktiviert | Variiert den Cache anhand bestimmter Cookie-Werte |
| Header-Wert | Schalter | Deaktiviert | Variiert den Cache anhand bestimmter Request-Header-Werte |
Request-Hostname
Wenn Request-Hostname aktiviert ist, erzeugen Anfragen an verschiedene Hostnamen auf derselben Zone separate Cache-Einträge. Dies ist wichtig, wenn mehrere Hostnamen auf derselben Zone unterschiedliche Inhalte für denselben Pfad ausliefern.
Beispiel: Mit dieser Aktivierung werden www.example.com/about und shop.example.com/about separat gecacht.
Land
Wenn Land aktiviert ist, bezieht smoxy das Land des Besuchers in den Cache-Key ein, sodass Besucher aus verschiedenen Ländern separat gecachte Antworten erhalten. Das Land wird per GeoIP-Lookup aus der IP-Adresse des Besuchers ermittelt.
Beispiel: Damit werden ein Besucher aus Deutschland (DE) und einer aus Österreich (AT) für dieselbe URL getrennt gecacht. Diese Option sollte nur aktiviert werden, wenn der Origin tatsächlich länderspezifische Inhalte für denselben Pfad ausliefert -- andernfalls fragmentiert sie den Cache und senkt die Trefferrate.
Cookie-Wert
Wenn Cookie-Wert aktiviert ist, bezieht smoxy bestimmte Cookie-Werte in den Cache-Key ein. Dies ist nützlich, um unterschiedliche Inhalte basierend auf Benutzereinstellungen wie Sprache oder Region auszuliefern.
Welche Cookies variiert werden, lässt sich unter Cookie-Namenswerte angeben -- eine Liste von Cookie-Namen.
Beispiel: Wird auf language variiert, erhalten ein Besucher mit language=en und ein Besucher mit language=de separat gecachte Antworten.
Header-Wert
Wenn Header-Wert aktiviert ist, bezieht smoxy die Werte bestimmter Request-Header in den Cache-Key ein. Das ist nützlich, wenn der Origin je nach Request-Header unterschiedliche Inhalte ausliefert -- etwa Accept-Language für lokalisierte Seiten oder einen eigenen X-Device-Type-Header.
Welche Header variiert werden, lässt sich unter Header-Namenswerte angeben -- eine Liste von Request-Header-Namen.
Beispiel: Wird auf Accept-Language variiert, erhalten ein Besucher mit Accept-Language: en und einer mit Accept-Language: de separat gecachte Antworten.
Normalisierung und Deduplizierung. Beim Speichern trimmt smoxy jeden Eintrag, verwirft leere Einträge und entfernt Duplikate ohne Berücksichtigung der Groß-/Kleinschreibung, wobei - und _ als dasselbe Zeichen gelten. Accept-Language, accept-language und Accept_Language fallen zu einem einzigen Eintrag zusammen -- die zuerst eingegebene Schreibweise bleibt erhalten.
Header-Namen mit Bindestrich schreiben. Also Accept-Language, nicht Accept_Language: Request-Header, deren Name Unterstriche enthält, werden verworfen, bevor sie smoxy erreichen, und tragen daher nie zum Cache-Key bei.
Verwaltete ignorierte URL-Parameter
smoxy pflegt eine kuratierte Liste von Query-Parametern, die den Seiteninhalt bekanntermaßen nicht beeinflussen -- Klick-IDs von Werbenetzwerken (gclid, fbclid, ttclid, ...), UTM-Kampagnen-Tags sowie Tracking-Parameter gängiger Analyse-, E-Mail-Marketing- und Affiliate-Plattformen. Ist Verwaltete ignorierte URL-Parameter aktiviert, wird jeder Parameter dieser Liste vor der Berechnung des Cache-Keys aus der URL entfernt -- zusätzlich zu den eigenen ausgeschlossenen Query-Parametern.
Die Liste wird von smoxy gepflegt und zentral aktualisiert -- neue Parameter wirken automatisch auf die Zone, ohne dass eine Konfiguration nötig ist. Ein Klick auf Parameter anzeigen in der Karte zur Cache-Key-Anpassung zeigt die aktuelle Liste mit einer Beschreibung jedes Eintrags.
| Einstellung | Standard |
|---|---|
| Verwaltete ignorierte URL-Parameter | Aktiviert für neue Zonen. Zonen, die vor Juli 2026 erstellt wurden, bleiben deaktiviert, bis die Option eingeschaltet wird |
Aktuell verwaltete Parameter (Juli 2026)
| Quelle | Parameter |
|---|---|
| Google Analytics / Ads | _ga, _gl, gclid, gclsrc, gbraid, wbraid, gad_source, gad_campaignid, dclid, srsltid |
| UTM-Kampagnen-Tags | utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_id, utm_source_platform, utm_creative_format, utm_marketing_tactic |
| Social Ads | fbclid (Meta), ttclid (TikTok), twclid (X/Twitter), li_fat_id (LinkedIn), epik (Pinterest) |
| Microsoft / Yandex | msclkid, yclid |
| Adobe | ef_id, s_kwcid |
| Matomo / Piwik | matomo_campaign, matomo_cid, matomo_kwd, mtm_campaign, mtm_cid, mtm_content, mtm_group, mtm_keyword, mtm_kwd, mtm_medium, mtm_placement, mtm_source, piwik_campaign, piwik_keyword, piwik_kwd, pk_campaign, pk_cid, pk_keyword, pk_kwd, pk_medium, pk_source |
| etracker | etcc_bky, etcc_cmp, etcc_ctv, etcc_grp, etcc_med, etcc_mty, etcc_ori, etcc_plc, etcc_var |
| E-Mail-Marketing | _hsenc, _hsmi (HubSpot), mc_cid, mc_eid (Mailchimp), sc_eh, sc_lid, sc_llid, sc_src, sc_uid, sfmc_sub (Salesforce Marketing Cloud), em_cmp |
| Affiliate-Netzwerke | awc (AWIN), tduid (Tradedoubler), wgu, wgexpiry (Webgains) |
| Retargeting & Werbung | cto_pld (Criteo), rtbhc (RTB House), trc_gad_id, trc_gag_id, trc_gcmp_id (Taboola), padico, styCampaignId, styProUuid, stySource |
| E-Commerce-Analytics | klar_adid, klar_cpid, klar_source (Klar), channable (Channable) |
| Cache-Buster | sucurianticache (Sucuri), uptime_kuma_cachebuster (Uptime Kuma) |
Die verbindliche, stets aktuelle Liste wird im Hub angezeigt und ist über die API abrufbar: GET /api/zones/{zoneId}/cache/managed-ignored-url-params.
Eine Steuerung pro Anfrage ist über Conditional Rules möglich: Die Einstellung Managed Ignored URL Params erzwingt die verwaltete Liste für passenden Traffic oder schaltet sie dort ab.
Ausgeschlossene Query-Parameter
Standardmäßig ist der vollständige Query-String Teil des Cache-Keys. Bestimmte Query-Parameter lassen sich ausschließen, die das Caching nicht beeinflussen sollen -- typischerweise Tracking-Parameter, die den Seiteninhalt nicht verändern.
Konfiguriert wird eine kommagetrennte Liste von Parameternamen zum Ausschließen.
Häufige Ausschlüsse: utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid -- all diese sind bereits durch die verwaltete Liste abgedeckt, wenn sie aktiviert ist; die eigene Liste dient für seitenspezifische Parameter darüber hinaus.
Parameternamensregeln: Nur alphanumerische Zeichen und Bindestriche sind erlaubt.
Cache-Tags
Cache-Tags ermöglichen es, gecachte Inhalte zu gruppieren und selektiv zu invalidieren. Der Origin-Server sendet Cache-Tag-Werte in HTTP-Response-Headern, und smoxy verwendet diese, um gecachte Inhalte mit Tags zu verknüpfen. Beim Purgen eines Tags werden alle damit verknüpften gecachten Inhalte invalidiert.
Konfiguration
Es lassen sich bis zu 4 Cache-Tag-Header konfigurieren. Jeder Header hat einen Namen und ein Trennzeichen.
| Einstellung | Beschreibung |
|---|---|
| Header-Name | Der HTTP-Response-Header, der die Tag-Werte enthält |
| Trennzeichen | Das Zeichen, das mehrere Tags innerhalb des Headers trennt -- eines von Leerzeichen, ,, ; oder | |
Header-Namensregeln: Nur alphanumerische Zeichen und Bindestriche sind erlaubt.
Standards
smoxy ist mit zwei Cache-Tag-Headern vorkonfiguriert:
| Header | Trennzeichen | Beispiel |
|---|---|---|
x-cache-tags | , (Komma) | x-cache-tags: product-123,category-shoes |
xkey | (Leerzeichen) | xkey: product-123 category-shoes |
Diese Standards decken die gängigsten Cache-Tagging-Konventionen ab. Eine Anpassung nach Bedarf oder das Hinzufügen weiterer Header ist möglich.
Cache-Tag-Header entfernen
Standardmäßig werden die vom Origin gesendeten Cache-Tag-Header an die Besucher durchgereicht. Der Schalter Cache-Tag-Header aus Antworten entfernen -- standardmäßig deaktiviert -- entfernt jeden oben konfigurierten Header (z. B. x-cache-tags, xkey) aus den Antworten an den Client, auf jedem Pfad: bei Cache-Hits, Misses und Bypasses gleichermaßen.
Das ist nützlich, wenn außergewöhnlich große Tag-Header sonst von nachgelagerten Anwendungen abgelehnt würden -- der xkey-Header von Shopware etwa kann größer werden, als manche Proxys und Clients akzeptieren.
Ein unter eigenen Response-Headern explizit gesetzter Header gewinnt gegenüber dem Entfernen; der Abgleich der Header-Namen ignoriert die Groß-/Kleinschreibung (xkey entfernt auch XKey). Eine Steuerung pro Anfrage ist über Conditional Rules möglich: Die Überschreibung erzwingt das Verhalten für passenden Traffic oder schaltet es dort ab.
Über die API ist die Einstellung als Zonen-Feld stripCacheTagHeaders verfügbar.
Cache-Tag-Ignorier-Liste
Eine Liste von Tag-Mustern lässt sich konfigurieren, die ignoriert werden sollen. Tags, die diesen Mustern entsprechen, werden nicht gespeichert, was den Cache-Metadaten-Overhead für Tags reduziert, die nie invalidiert werden sollen.
Einzugeben ist eine kommagetrennte Liste von Tag-Namen oder -Mustern.
Erlaubte Zeichen: Alphanumerisch, Klammern, geschweifte Klammern, eckige Klammern, Bindestriche, Unterstriche, Punkte, Schrägstriche und Sternchen.
SSI & ESI
smoxy unterstützt Server Side Includes (SSI) und Edge Side Includes (ESI) zum Zusammensetzen von Seiten aus mehreren Fragmenten am Edge.
| Feature | Beschreibung |
|---|---|
| SSI | Verarbeitet <!--#include -->-Direktiven in HTML-Antworten |
| ESI | Verarbeitet <esi:include>-Tags für Edge-seitiges Seitenzusammensetzen |
INFO
Hinweis: ESI kann nur aktiviert werden, wenn SSI ebenfalls aktiviert ist.
Diese Features sind nützlich für Sites, die Seiten aus cachebaren Fragmenten mit unterschiedlichen TTLs zusammensetzen (z. B. ein statischer Header der stundenlang gecacht wird und ein dynamisches Warenkorb-Widget das sekündlich gecacht wird).
Stale-Cache
Die Stale-Cache-Steuerung erlaubt es smoxy, veraltete Inhalte aus dem CDN-Cache auszuliefern, statt zu scheitern oder auf den Origin zu warten. Zwei unabhängige Schalter:
| Schalter | Verhalten |
|---|---|
| Bei Nichterreichbarkeit | Liefert gecachte Inhalte aus, wenn der Origin nicht erreichbar ist |
| Während der Aktualisierung | Liefert gecachte Inhalte aus, während im Hintergrund eine frische Kopie geholt wird |
INFO
Hinweis: Stale-Cache ist nur mit CDN verfügbar.
Fehlerantworten cachen
Wenn aktiviert, werden Fehlerantworten (HTTP 300+) des Origins kurz gecacht -- etwa 5 Sekunden --, um ihn vor wiederholten Upstream-Ausfällen zu schützen.
INFO
Hinweis: Das Cachen von Fehlerantworten ist nur mit CDN verfügbar.
Purge-Token
Jede Zone verfügt über ein automatisch generiertes Purge-Token, das Anfragen zur Cache-Invalidierung (Purge) an die API von smoxy authentifiziert. Es wird auf der Cache-Seite neben der Karte „Dynamischer Cache“ angezeigt und kann nicht manuell gesetzt werden. Das Token ist standardmäßig maskiert -- ein Klick auf Token anzeigen blendet es ein. Es wird in den Purge-Anfragen mitgesendet, um sie zu autorisieren.
Siehe Cache-Invalidierung zum Senden von Purge-Anfragen.
Der s-cache Response-Header
Wenn Dynamischer Cache oder Optimierung aktiviert ist, fügt smoxy jeder Antwort einen s-cache-Response-Header hinzu, der mitteilt, wie die Anfrage bedient wurde. Er dient zum Debuggen der Cache-Trefferrate, zur Überprüfung des Regelverhaltens und zur Bestätigung, dass die Cache-Control-Direktiven des Origins respektiert werden.
HIT
Die Ressource wurde im Cache von smoxy gefunden und direkt vom Edge ausgeliefert - keine Origin-Anfrage.
MISS
Die Ressource war nicht im Cache und wurde vom Origin geholt. Um zu verhindern, dass Browser die Miss-Antwort cachen, setzt smoxy cache-control: no-cache, no-store, must-revalidate auf der Antwort - das garantiert, dass die nächste Anfrage als HIT bedient werden kann, sobald smoxy den Inhalt gespeichert hat.
BYPASS
smoxy hat den Cache absichtlich übersprungen. Dies passiert, wenn:
- Origin-Cache-Control berücksichtigen aktiviert ist und der Origin
Cache-Control: no-cache,privateodermax-age=0ohne positivess-maxagezurückgegeben hat -- ists-maxage>0vorhanden, wird die Antwort stattdessen gecacht (siehe Cache-Control berücksichtigen). - Die Anfrage einen
http-bypass-Header mit einem gültigen Token oder einer base64-kodierten Form des Hostnamens trug. - Der Content-Type der Antwort nicht für Caching geeignet ist (siehe Unterstützte MIME-Typen).
Wichtige Hinweise
- TTL-Abwägung: Eine längere TTL bedeutet weniger Origin-Traffic, aber langsamere Content-Aktualisierungen. Eine kürzere TTL bedeutet frischeren Inhalt, aber mehr Origin-Anfragen. Die Wahl richtet sich danach, wie häufig sich der Inhalt ändert.
- Auf Cookies mit Bedacht variieren: Nur auf Cookies variieren, die tatsächlich den Antwortinhalt beeinflussen. Das Variieren auf Session-IDs oder Tracking-Cookies deaktiviert das Caching effektiv, da jeder Besucher einen einzigartigen Cache-Eintrag erhält.
- Sparsam auf Header variieren: Jeder Request-Header, auf den variiert wird, vervielfacht die Anzahl der gecachten Kopien jeder URL -- eine pro eindeutiger Kombination von Header-Werten. Nur auf Header variieren, die die Antwort tatsächlich verändern, sonst sinkt die Trefferrate.
- Tracking-Parameter ausschließen: Marketing-Parameter wie UTM-Tags ändern den Seiteninhalt nicht. Das Ausschließen aus dem Cache-Key verbessert die Cache-Trefferrate erheblich. Die verwaltete Liste deckt die gängigen automatisch ab; eigene Ausschlüsse ergänzen alles Seitenspezifische.
- Cache-Tags erfordern Origin-Kooperation: Der Origin-Server muss die konfigurierten Tag-Header in seinen Antworten senden. smoxy liest diese Header und speichert die Verknüpfung - es generiert keine Tags automatisch.