Shopware 6
Diese Anleitung beschreibt die Integration von smoxy mit Shopware 6. Sie gilt für Shopware 6.7 und 6.6, die beiden Versionsreihen, die Shopware mit Stand November 2026 pflegt. Wo sich die Versionen unterscheiden, sind beide Varianten aufgeführt.
INFO
Voraussetzungen: Zuerst die Erste Schritte-Anleitung abschließen. Die Shop-Domain muss über smoxy geroutet werden.
Zonen-Einstellungen
Am schnellsten führt das Preset Online-Shop mit dem Shop-System Shopware zu einer passend konfigurierten Zone. Beides steht beim Anlegen einer Zone zur Auswahl. Das Preset setzt folgende Einstellungen:
| Einstellung | Wert | Warum Shopware sie braucht |
|---|---|---|
| Dynamischer Cache | Aktiviert | Cacht das HTML des Shops am Edge |
| Origin-Cache-Control berücksichtigen | Aktiviert | Shopware kennzeichnet Seiten, die nicht geteilt werden dürfen, mit private und legt die Cache-Dauer am Edge per s-maxage fest |
| Request-Hostname im Cache-Key | Aktiviert | Die Domains mehrerer Sales Channels auf derselben Zone liefern unter demselben Pfad unterschiedliche Seiten aus |
| Cookie-Wert im Cache-Key | sw-cache-hash, sw-currency | Trennt die Cache-Varianten, die Shopware je nach Kundenzustand anlegt (siehe unten) |
| Cache-Tag-Header aus Antworten entfernen | Aktiviert | Der xkey-Header von Shopware kann größer werden, als manche Clients akzeptieren |
| Conditional Rule | Cache-Bypass für /admin, /api und /store-api | Administration und APIs müssen immer den Live-Shop erreichen |
Darüber hinaus aktiviert das Preset die verwalteten ignorierten URL-Parameter, den Stale-Cache und die Bildoptimierung. Außerdem legt es eine Regel an, die Bilder nur anhand ihrer URI cacht.
Bei Zonen, die ohne Preset angelegt wurden, sind diese Einstellungen von Hand zu setzen. Der Eintrag xkey in den Cache-Tag-Headern der Zone muss erhalten bleiben (er ist standardmäßig vorhanden): Aus diesem Header liest smoxy die Tags in den Purge-Anfragen von Shopware.
WARNING
Warum sw-cache-hash in den Cache-Key gehört: Ab Shopware 6.8 cacht Shopware auch Seiten für eingeloggte Kunden und gefüllte Warenkörbe. Unter Shopware 6.7.6 und neuer schaltet das Feature-Flag CACHE_REWORK dieses Verhalten schon jetzt ein. Von der Gastversion unterscheiden sich diese Seiten nur durch das Cookie sw-cache-hash. smoxy bildet den Cache-Key aus den Einstellungen der Zone und nicht aus dem Vary-Header, den Shopware mitsendet. Fehlt sw-cache-hash im Cache-Key, kann eine Seite, die für einen bestimmten Kunden samt dessen Preisen erzeugt wurde, bei anderen Besuchern landen.
Cache-Tagging (Surrogate Keys)
Shopware 6 versieht jede cachebare Antwort im xkey-Header mit Surrogate Keys. Ändern sich Inhalte, teilt Shopware smoxy mit, welche Tags zu purgen sind. So werden nur die betroffenen Seiten gelöscht und nicht der gesamte Cache.
Reverse-Proxy-Modus aktivieren
Die Reverse-Proxy-Konfiguration gehört in die Datei config/packages/shopware.yaml.
Shopware 6.7:
shopware:
http_cache:
reverse_proxy:
enabled: true
hosts: ["https://smoxy:<token>@example.com"]Shopware 6.6:
shopware:
http_cache:
reverse_proxy:
enabled: true
hosts: ["https://smoxy:<token>@example.com"]
use_varnish_xkey: trueexample.com durch die Shop-Domain ersetzen und <token> durch das Purge-Token der Zone.
INFO
Upgrade auf Shopware 6.7: Shopware 6.7 arbeitet immer mit xkey-Tags, die Option use_varnish_xkey hat dort keine Wirkung mehr. Beim Upgrade die Option entfernen: Sie ist als veraltet markiert, und Shopware 6.8 streicht sie ganz. Dasselbe gilt für ban_method, ban_headers und purge_all.
INFO
Shopware 6.5 und älter verwenden den Konfigurationsschlüssel storefront.reverse_proxy statt shopware.http_cache.reverse_proxy. Der Schlüssel hat sich mit Shopware 6.6.0 geändert.
INFO
Cloudflare-Nutzer: Beim Einsatz von Cloudflare muss eine separate Subdomain für die Cache-Invalidierung eingerichtet werden. Siehe Cloudflare Setup.
Umgebungsvariablen
Diese Variablen gehören in die .env-Datei des Shops (oder in .env.local):
SHOPWARE_HTTP_CACHE_ENABLED=1
SYMFONY_TRUSTED_PROXIES=REMOTE_ADDRSHOPWARE_HTTP_CACHE_ENABLED ist standardmäßig aktiv. Steht die Variable auf 0, kennzeichnet Shopware keine Seite mehr als cachebar, und smoxy hat nichts zu cachen.
SYMFONY_TRUSTED_PROXIES sorgt dafür, dass Shopware den Headern X-Forwarded-For und X-Forwarded-Proto von smoxy vertraut. Erst dann sieht Shopware die IP-Adresse des Besuchers und erkennt, dass die Anfrage per HTTPS eingegangen ist. REMOTE_ADDR vertraut der Adresse, die sich direkt mit Shopware verbindet. Sitzt zwischen smoxy und Shopware noch ein Load Balancer, gehören stattdessen dessen Adressen in die Variable. Die ältere Variable TRUSTED_PROXIES wertet Shopware seit Version 6.6 nicht mehr aus. Hintergründe dazu unter Client-IP am Origin.
Cache-Hit-Rate optimieren (nur Shopware 6.6)
Unter Shopware 6.6 lässt sich die Cache-Tag-Fragmentierung verringern, indem die Tags pro Eintrag für Config, Snippets und Theme-Config deaktiviert werden:
shopware:
cache:
tagging:
each_config: false
each_snippet: false
each_theme_config: falseDas reduziert die Anzahl der Tags pro Seite, was zu weniger unnötigen Cache-Invalidierungen und einer höheren Cache-Hit-Rate führt.
WARNING
Diesen Block vor dem Upgrade auf Shopware 6.7 entfernen. Shopware 6.7 hat diese Tags pro Eintrag abgeschafft und mit ihnen die Optionen unter shopware.cache.tagging. Steht der Block noch in der Konfiguration, bricht Shopware 6.7 mit dem Konfigurationsfehler „Unrecognized option“ ab.
Wann Änderungen bei smoxy ankommen
Shopware 6.6 schickt Invalidierungen sofort an smoxy. Shopware 6.7 verzögert sie standardmäßig: Die betroffenen Tags werden gesammelt und gebündelt über den Scheduled Task shopware.invalidate_cache verschickt, standardmäßig alle 5 Minuten. Bis eine in der Administration gespeicherte Änderung im Shop sichtbar wird, können daher bis zu fünf Minuten vergehen. smoxy selbst purgt, sobald die Anfrage eintrifft.
- Die Scheduled Tasks müssen laufen (
bin/console scheduled-task:runzusammen mit einem Message-Queue-Worker). Sonst verlassen die verzögerten Invalidierungen Shopware nie. - Admin-API-Anfragen, deren Änderungen sofort sichtbar sein müssen, können den Header
sw-force-cache-invalidate: 1mitsenden. bin/console cache:clear:delayedverschickt alle ausstehenden Invalidierungen sofort.
Den gesamten Cache leeren
Um den kompletten HTTP-Cache zu leeren, schickt Shopware eine BAN-Anfrage ohne weitere Header an den konfigurierten Host. smoxy behandelt diese Anfrage als Flush URL für /. bin/console cache:clear:http und bin/console cache:clear:all leeren in smoxy deshalb nur die Startseite. Seit Shopware 6.7 lässt bin/console cache:clear den HTTP-Cache ganz außen vor.
Um das gesamte gecachte HTML zu löschen, etwa als letzten Schritt eines Deployments, geht eine Flush Content Class-Anfrage direkt an smoxy:
curl -X BAN -H "secret: <token>" -H "type: html" https://example.com/type: html löscht alle gecachten HTML-Dokumente, Bilder und übrige Assets bleiben im Cache. Die Schnellaktion Cache nach Typ leeren im Hub erledigt dasselbe ohne Token. Flush All ist nur dann das Mittel der Wahl, wenn tatsächlich der gesamte Cache geleert werden soll.
Mehrere Sales Channels
Wenn die Shopware-6-Installation mehrere Sales Channels mit verschiedenen Domains verwendet (z. B. länderspezifische Shops), muss nur eine Domain in der Reverse-Proxy-hosts-Einstellung konfiguriert werden. Shopware weiß selbst, welche Caches für welchen Sales Channel geleert werden müssen, und übermittelt diese Information automatisch an smoxy.
Zusätzlich muss Request-Hostname Teil des Cache-Keys der Zone sein (das Shopware-Preset aktiviert diese Option). Andernfalls teilen sich die Sales Channels die Cache-Einträge für denselben Pfad, und Besucher einer Domain bekommen womöglich eine Seite einer anderen ausgeliefert.
WARNING
Wichtig: Alle Sales Channels derselben Shopware-Installation müssen dieselbe smoxy-Zone verwenden.
