Shopware Message Queue: Worker im Produktivbetrieb

Der Shop nimmt Bestellungen an, im Admin stehen sie vollständig in der Liste - aber die Bestellbestätigung erreicht den Kunden erst Stunden später. Der Suchindex zeigt Produkte unter alten Namen, die Sitemap ist zwei Tage alt, der Newsletter-Versand kommt nicht vom Fleck. Diese Symptome gehören zusammen, und sie haben in Shopware 6 meist dieselbe Ursache: Die Shopware Message Queue wird vom Admin-Worker im Browser-Tab abgearbeitet statt von echten CLI-Workern auf dem Server. Shopware setzt für die asynchrone Verarbeitung auf die Symfony-Messenger-Komponente; im Auslieferungszustand liegen die Nachrichten in der Datenbank und werden über den Browser verarbeitet, solange jemand in der Administration angemeldet ist - laut Hersteller eine einfache und schnelle Methode für die Entwicklung, für Produktivsysteme aber ausdrücklich nicht empfohlen (Shopware Developer Documentation, Message Queue). Dieser Beitrag ist ein Betriebsleitfaden: was über die Queue läuft, wie Worker als Systemdienst betrieben werden, wie Transporte und Queues getrennt werden, woran sich Rückstau erkennen lässt und ab welcher Queue-Länge ein Alarm sinnvoll ist. Für Shops in unserem Hosting und Wartung gehört genau dieses Setup zum Standardumfang.

Die Symptome: verspätete Mails, alter Index, tote Sitemap

Die Beschwerden, mit denen Betreiber in solchen Fällen ankommen, klingen nach vier verschiedenen Problemen - und sind eines. Alles, was in Shopware 6 nicht unmittelbar im Request erledigt wird, wandert in die Message Queue. Steht deren Verarbeitung still, fallen zuerst die Aufgaben auf, die Kunden sehen, danach die, die Google sieht, und zuletzt die, die der Buchhaltung fehlen.

• Bestellbestätigungen kommen verzögert oder gebündelt, sobald sich jemand in der Administration anmeldet. Der Versand über die Queue ist konfiguriert, der Verbraucher fehlt.
• Der Suchindex hinkt hinterher. Preis- und Namensänderungen sind im Frontend erst nach einem manuellen Reindex sichtbar, weil die Indexing-Nachrichten unbearbeitet liegen bleiben - ein Effekt, der sich leicht mit schlechter Suchrelevanz im Shop verwechseln lässt.
• Die Sitemap ist veraltet. Ihre Erzeugung hängt am Scheduled Task shopware.sitemap_generate mit einem Standardintervall von 86.400 Sekunden (shopware/docs, scheduled-task.md) - der ohne laufenden Worker gar nicht erst ausgeführt wird.
• Produkt-Exportfeeds bleiben stehen.product_export_generate_task ist mit 60 Sekunden das kürzeste Standardintervall im Auslieferungszustand (shopware/docs, scheduled-task.md) und fällt entsprechend schnell auf.
• Newsletter- und Serienmails hängen, weil der Mailversand über den Message-Bus läuft, sobald framework.mailer.message_bus gesetzt ist (Shopware Developer Documentation, Message Queue).
• Die Cache-Invalidierung verzögert sich. Der Task shopware.invalidate_cache steht mit 20 Sekunden Intervall in der Standardliste (shopware/docs, scheduled-task.md) und entscheidet mit darüber, wann geänderte Inhalte im Frontend ankommen.

Bei der Bestellbestätigung ist die Verzögerung nicht nur ein Servicethema. § 312i Absatz 1 Satz 1 Nummer 3 BGB verpflichtet Unternehmer im elektronischen Geschäftsverkehr, den Zugang der Bestellung unverzüglich auf elektronischem Wege zu bestätigen (Bundesministerium der Justiz, § 312i BGB). Eine Bestätigung, die erst am nächsten Morgen den Server verlässt, weil sich dann jemand im Admin anmeldet, lässt sich schwer als unverzüglich einordnen. Dazu kommt der betriebswirtschaftliche Teil: Jede ausbleibende Bestätigung erzeugt erfahrungsgemäß eine Rückfrage im Support - und zwar in dem Moment, in dem der Kunde gerade bezahlt hat und unsicher ist, ob die Bestellung überhaupt angekommen ist (Projekterfahrung). Das kostet doppelt: einmal Bearbeitungszeit, einmal Vertrauen.

Was in Shopware über die Message Queue läuft

Shopware nutzt Symfony Messenger und Enqueue, um Nachrichten asynchron zu verarbeiten - Aufgaben laufen im Hintergrund und damit unabhängig von Timeouts einzelner Requests oder Systemabbrüchen (Shopware Developer Documentation, Message Queue). Im Auslieferungszustand existieren drei Transporte: async für den Regelbetrieb, low_priority für nachrangige Aufgaben und ein Failure-Transport für Nachrichten, die ihre Zustellversuche aufgebraucht haben. Konfiguriert werden sie über die Umgebungsvariablen MESSENGER_TRANSPORT_DSN, MESSENGER_TRANSPORT_LOW_PRIORITY_DSN und MESSENGER_TRANSPORT_FAILURE_DSN (Shopware Developer Documentation, Message Queue). Wer den E-Commerce-Betrieb plant, sollte diese drei Namen kennen - an ihnen hängt der halbe Tagesablauf des Shops.

Die Standard-Scheduled-Tasks decken einen weiten Intervallbereich ab: shopware.invalidate_cache läuft mit 20 Sekunden, product_export_generate_task mit 60 Sekunden, die meisten Aufräumaufgaben täglich mit 86.400 Sekunden, product_keyword_dictionary.cleanup wöchentlich mit 604.800 Sekunden und product_download.media.cleanup mit 2.628.000 Sekunden etwa monatlich (shopware/docs, scheduled-task.md). Eingeplant werden sie durch bin/console scheduled-task:run; seit Shopware 6.5.5.0 gibt es dafür die Option --no-wait, mit der sich der Aufruf sauber in einen Cron-Eintrag alle fünf Minuten setzen lässt, statt einen dauerhaft wartenden Prozess zu halten (Shopware Developer Documentation, Scheduled Task).

Warum der Admin-Worker im Browser-Tab keine Betriebslösung ist

Der Admin-Worker ist ein Mechanismus der Administration: Die Oberfläche hält einen Request offen, arbeitet die konfigurierten Transporte ab, und nach Ablauf des Poll-Intervalls endet der Request, woraufhin die Administration einen neuen startet. Der dokumentierte Standardwert für dieses Intervall liegt bei 30 Sekunden, die abzuarbeitenden Transporte werden explizit aufgeführt (Shopware Developer Documentation, Message Queue):

# config/packages/shopware.yaml
shopware:
    admin_worker:
        enable_admin_worker: true
        poll_interval: 30
        transports: ["async", "low_priority"]

Daraus ergeben sich drei Betriebsprobleme. Erstens wird nur verarbeitet, solange jemand angemeldet ist - nachts, am Wochenende und in Betriebsferien steht die Queue. Zweitens erzeugt jede geöffnete Administration einen dauerhaft laufenden PHP-Request; bei mehreren gleichzeitig angemeldeten Mitarbeitenden führt das laut Hersteller zu hoher CPU-Last und stört die saubere Ausführung von PHP-FPM (Shopware Developer Documentation, Message Queue). Drittens hängt die Verarbeitungsleistung am Nutzerverhalten statt an einer Kapazitätsplanung: Wer den Admin-Tab schließt, hält die Hintergrundverarbeitung an, ohne es zu merken.

# config/packages/shopware.yaml
shopware:
    admin_worker:
        enable_admin_worker: false

Worker als Systemdienst: Limits, Instanzen, geordneter Neustart

Der empfohlene Weg ist der CLI-Worker (Shopware Developer Documentation, Message Queue). Der Befehl messenger:consume verarbeitet einen oder mehrere Transporte und beendet sich nach definierten Grenzen. Das ist gewollt: Ein langlebiger PHP-Prozess sammelt über die Laufzeit Speicher an, deshalb wird er regelmäßig ersetzt statt endlos weiterbetrieben. Zeit- und Speichergrenze sind damit keine Notbremse, sondern die Betriebsart.

Die Reihenfolge der Transporte im Aufruf ist eine Prioritätsentscheidung: Der Worker arbeitet den ersten Transport ab und wechselt erst dann zum nächsten, wenn dort nichts mehr wartet (Symfony Documentation, Messenger). messenger:consume async low_priority bedeutet also Mails und Indexierung zuerst, nachrangige Aufgaben danach. Damit der Prozess nach Erreichen seiner Grenzen wieder startet, gehört er unter einen Prozessmanager - systemd oder Supervisor; ein Cron-Aufruf ist die schwächere Alternative (Shopware Developer Documentation, Message Queue). Shopware liefert eine Vorlage für eine instanziierbare systemd-Unit mit:

[Unit]
Description=Shopware Message Queue Consumer, instance %i
PartOf=shopware_consumer.target

[Service]
Type=simple
User=www-data
Restart=always
WorkingDirectory=/var/www/html
ExecStart=php /var/www/html/bin/console messenger:consume --time-limit=60 --memory-limit=512M async low_priority

[Install]
WantedBy=shopware_consumer.target

Mit systemctl enable shopware_consumer@{1..3}.service werden daraus drei parallele Instanzen, die über ein gemeinsames Target gestartet werden (Shopware Developer Documentation, Message Queue). Die Vorlage arbeitet mit --time-limit=60 und --memory-limit=512M: Der Prozess beendet sich nach 60 Sekunden oder bei 512 MB Speicherverbrauch und wird durch Restart=always sofort neu gestartet. Wer Supervisor bevorzugt, steuert die Instanzzahl über numprocs, erlaubt mit startretries mehrere Startversuche und räumt dem Prozess über stopwaitsecs eine Frist ein, die laufende Nachricht noch zu beenden - in der Symfony-Dokumentation beispielhaft mit 20 Sekunden angegeben (Symfony Documentation, Messenger).

Nach jedem Deployment müssen die Worker neu starten, sonst arbeiten sie mit dem Code, der beim Prozessstart geladen wurde. Symfony sieht dafür bin/console messenger:stop-workers vor: Der Befehl setzt eine Markierung im Cache, jeder Worker beendet die laufende Nachricht und danach sich selbst, der Prozessmanager startet ihn mit dem neuen Code neu (Symfony Documentation, Messenger). Der Aufruf gehört hinter Code-Rollout und Cache-Aufwärmung. Zwei Details entscheiden über den Erfolg: Läuft die Anwendung auf mehreren Hosts, muss der Cache ein gemeinsam genutzter Adapter sein, damit die Markierung alle Prozesse erreicht (Symfony Documentation, Messenger). Und wer opcache.validate_timestamps=0 gesetzt hat - eine Empfehlung aus den Shopware-Performance-Hinweisen -, muss den OPcache beim Deployment aktiv leeren, sonst laufen Web-Prozesse und Worker weiter auf altem Bytecode (Shopware Developer Documentation, Performance Tweaks).

Transport-Wahl: Datenbank als Standard, Redis oder AMQP unter Last

Standardmäßig nutzt Shopware den Doctrine-Transport, der die Nachrichten in der Datenbank ablegt. Der Hersteller bezeichnet das als einfache Lösung, die für die Entwicklung gut geeignet ist, für Produktivsysteme aber nicht empfohlen wird, und verweist auf spezialisierte Broker, die die Datenbank entlasten (Shopware Developer Documentation, Message Queue). In der Praxis trägt die Datenbank kleinere Shops mit überschaubarem Nachrichtenaufkommen trotzdem zuverlässig - der Wechsel lohnt sich, sobald mehrere Worker parallel arbeiten, Massenimporte zur Routine gehören oder die Datenbank ohnehin an ihrer Schreibgrenze läuft.

Unabhängig vom gewählten Transport gibt es einen Detailpunkt, der unter Last spürbar wird: Symfony Messenger prüft bei jeder Verbindung, ob die Queue existiert, und legt sie bei Bedarf an. Shopware empfiehlt, das über ?auto_setup=false an der Verbindungs-URL abzuschalten und die Queues stattdessen einmalig beim Deployment mit bin/console messenger:setup-transports anzulegen (Shopware Developer Documentation, Performance Tweaks). Wenn Redis ohnehin im Spiel ist, lohnt der Blick auf die übrigen Einsatzfelder - zusammengefasst im Beitrag zu Redis-Caching für Shopware.

Queues trennen, damit der Massenimport nicht den Mailversand blockiert

Der wichtigste Betriebsschritt nach dem Abschalten des Admin-Workers ist die Trennung der Queues. Der Grund ist schnell erzählt: Ein Katalogimport mit 50.000 Positionen erzeugt in wenigen Minuten sehr viele Indexing-Nachrichten. Liegen Bestellmails in derselben Queue, stehen sie hinter diesem Berg - der Kunde wartet auf die Bestätigung, während der Worker Produktdaten indexiert. Shopware weist ausdrücklich darauf hin, dass es sinnvoll sein kann, Nachrichten auf einen anderen Transport zu leiten, um die Worker-Zahl für einen bestimmten Nachrichtentyp zu begrenzen, Datenbanksperren zu vermeiden oder den Mailversand zu priorisieren (Shopware Developer Documentation, Message Queue).

# config/packages/framework.yaml
framework:
    messenger:
        transports:
            async: "%env(MESSENGER_TRANSPORT_DSN)%"
            entity_indexing: "%env(MESSENGER_TRANSPORT_INDEXING_DSN)%"
        routing:
            '*': async

# config/packages/shopware.yaml
shopware:
    messenger:
        routing_overwrite:
            'Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexingMessage': entity_indexing

shopware.messenger.routing_overwrite überschreibt - anders als die reine Symfony-Routing-Konfiguration - eine bestehende Zuordnung, statt eine weitere hinzuzufügen. Genau das braucht man für Indexing-Nachrichten, die standardmäßig über das AsyncMessageInterface auf async geleitet werden. Die Option wurde mit Shopware 6.6.4.0 und 6.5.12.0 eingeführt (Shopware Developer Documentation, Message Queue). Die Umsetzung eigener Nachrichtentypen und Handler gehört in die individuelle Entwicklung und sollte zusammen mit dem Betriebskonzept entstehen, nicht danach.

1. Dienst 1 - Mail und Regelbetrieb:messenger:consume async, zwei bis drei Instanzen, kurze Zeitlimits. Zielgröße ist die Wartezeit bis zur Bestellbestätigung.
2. Dienst 2 - Indexierung:messenger:consume entity_indexing, begrenzte Instanzzahl, höheres Speicherlimit. Zielgröße ist Durchsatz ohne Sperrenstau in der Datenbank.
3. Dienst 3 - Nachrangiges:messenger:consume low_priority, eine Instanz. Aufräumarbeiten und alles, was eine Verzögerung von Stunden verträgt.
4. Dienst 4 - Failure-Transport: ein eigener Verbraucher mit längerem Intervall. Ohne ihn bleiben fehlgeschlagene Nachrichten unbearbeitet liegen - darauf weist die Herstellerdokumentation ausdrücklich als Warnung hin (Shopware Developer Documentation, Message Queue).

Die eigentliche Frage ist nicht, wie viele Worker ein Shop braucht, sondern welche Nachricht hinter welcher anderen warten darf.

XICTRON Entwicklungsteam

Skalierung: Worker-Zahl bestimmen und Rückstau erkennen

Auf die Frage nach der richtigen Worker-Zahl gibt Shopware bewusst keine pauschale Antwort: Sie hängt von der Menge der eingereihten Nachrichten und ihrem Typ ab - Produktindexierung ist eher langsam, andere Nachrichten werden sehr schnell verarbeitet; der Hersteller empfiehlt, die Queue zu beobachten und die Zahl entsprechend anzupassen (Shopware Developer Documentation, Message Queue). Das ist keine Ausflucht, sondern die einzige belastbare Antwort - und sie setzt voraus, dass der Rückstau überhaupt gemessen wird.

Die aussagekräftigste Kennzahl ist dabei nicht die Anzahl wartender Nachrichten, sondern ihr Alter. Eine Queue mit 5.000 Einträgen, die in vier Minuten abgearbeitet ist, ist unauffällig. Eine Queue mit 40 Einträgen, von denen der älteste seit zwei Stunden wartet, ist ein Störungsfall. Beim Doctrine-Transport lässt sich beides aus der Tabelle messenger_messages ablesen: die Zeilenzahl je queue_name und der älteste available_at-Zeitpunkt ohne gesetztes delivered_at. Bei Redis oder einem AMQP-Broker liefern die Bordmittel des jeweiligen Dienstes dieselben beiden Werte.

Beim Erhöhen der Instanzzahl gibt es eine natürliche Grenze: Ab einem gewissen Punkt konkurrieren die Worker um dieselben Datenbanksperren, und der Durchsatz steigt nicht mehr proportional zur Prozesszahl. Das ist der Moment, in dem entweder der Transport gewechselt oder ein Nachrichtentyp auf einen eigenen Transport gelegt wird - nicht der Moment für den vierten und fünften Worker auf derselben Queue. Wie sich die übrigen Stellschrauben im System zueinander verhalten, ordnet der Beitrag zur Shopware-6-Performance-Optimierung ein.

Fehlerbehandlung: Failure-Transport, Wiederholungen und Alarme

Scheitert die Verarbeitung einer Nachricht, wird sie in den Failure-Transport verschoben. Die Standardkonfiguration wiederholt die Zustellung dreimal; scheitert sie erneut, wird die Nachricht gelöscht (Shopware Developer Documentation, Message Queue). In Symfony ist die Wiederholungsstrategie parametrisiert: max_retries steht auf 3, die erste Wartezeit auf 1.000 Millisekunden, der Multiplikator auf 2 - die Abstände wachsen also exponentiell, und max_delay deckelt sie bei Bedarf (Symfony Documentation, Messenger). Für einen kurzen Ausfall des Mailservers ist das genau richtig; für einen Ausfall über mehrere Minuten reicht es nicht.

Symfony bringt für den Umgang mit dem Failure-Transport eigene Befehle mit: messenger:failed:show listet die Einträge und zeigt mit -vv den vollständigen Fehler, messenger:failed:retry stellt einzelne oder alle Nachrichten erneut zu, messenger:failed:remove entfernt sie (Symfony Documentation, Messenger). Sinnvoll ist außerdem --failure-limit am Verbraucher: Der Worker beendet sich nach einer definierten Zahl von Fehlern, statt in einer Schleife dieselbe kaputte Nachricht zu verarbeiten (Symfony Documentation, Messenger). In Verbindung mit Restart=always entsteht daraus ein sauberer Selbstheilungsmechanismus für vorübergehende Störungen.

• Kein Worker-Prozess aktiv - Alarm nach 60 Sekunden. Dieser eine Alarm erklärt die Mehrzahl aller Symptome aus dem ersten Abschnitt.
• Alter der ältesten wartenden Nachricht über 5 Minuten in der Mail-Queue, über 30 Minuten in der Indexing-Queue. Schwellen je Queue getrennt setzen, sonst ist der Alarm entweder taub oder lästig.
• Queue-Länge über einem definierten Wert - der Wert ergibt sich aus dem gemessenen Durchsatz, nicht aus dem Bauchgefühl.
• Zuwachs im Failure-Transport - jeder neue Eintrag ist ein Ereignis, kein Betriebszustand.
• Scheduled Task ohne Ausführung im erwarteten Intervall - eine Aufgabe mit 60-Sekunden-Intervall, die seit einer Stunde nicht lief, zeigt einen stehenden Planer an.

Kennzahlen fürs Monitoring und typische Fallstricke

Für die Messseite braucht es keine große Werkzeugkette. Shopware liefert seit 6.7.8.0 einen eigenen Endpunkt für Queue-Statistiken: GET /api/_info/message-stats.json ersetzt das ältere GET /api/_info/queue.json, das gemeinsam mit der incrementbasierten Statistik als veraltet markiert und für 6.8.0.0 zur Entfernung vorgesehen ist. Der Hersteller begründet den Wechsel damit, dass die alten Werte durch fest verdrahtete Multiplikatoren und fehlende Dekremente in Randfällen oft ungenau waren (Shopware Release Notes 6.7.8.0). Wer bisher gegen queue.json alarmiert hat, sollte die Umstellung einplanen - inklusive der ebenfalls als veraltet markierten Optionen shopware.admin_worker.enable_queue_stats_worker und shopware.increment.message_queue (Shopware Release Notes 6.7.8.0).

• Wartende Nachrichten je Queue - getrennt nach async, low_priority, eigenen Transporten und dem Failure-Transport
• Alter der ältesten wartenden Nachricht je Queue - die eigentliche Führungsgröße im Betrieb
• Durchsatz in Nachrichten pro Minute, ebenfalls je Transport
• Anzahl laufender Worker-Prozesse und ihre Laufzeit seit dem letzten Neustart
• Zuwachs im Failure-Transport pro Stunde als eigener Zähler
• Zeit von der Bestellung bis zum Versand der Bestätigung als fachliche Kennzahl - die einzige Zahl aus dieser Liste, die auch außerhalb der IT jeder versteht

Wie diese Kennzahlen in ein durchgängiges Bild aus Verfügbarkeit, Antwortzeiten und Fehlerraten passen, beschreibt der Beitrag zum Shop-Monitoring für Verfügbarkeit und Performance. Zwei weitere Betriebsthemen greifen direkt in die Queue: die Invalidierung des HTTP-Caches, die an einem Scheduled Task hängt und die wir im Beitrag zum Cache-Rework und HTTP-Cache in Shopware einordnen, sowie die Absicherung der Schnittstellen, über die viele dieser Nachrichten überhaupt erst entstehen - dazu passt der Beitrag zum Absichern der Store API im Headless-Shop.

Die Queue gehört in den Betrieb, nicht in den Browser-Tab

Die asynchrone Verarbeitung ist in Shopware 6 kein Randthema, sondern der Pfad, über den Bestellbestätigungen, Suchindex, Sitemap, Feeds und Aufräumaufgaben laufen. Der Auslieferungszustand mit Admin-Worker und Datenbank-Transport ist für die Entwicklung gedacht - der Hersteller sagt das selbst (Shopware Developer Documentation, Message Queue). Der Übergang in den Produktivbetrieb besteht aus wenigen, klar benennbaren Schritten: Admin-Worker aus, Worker als Dienst mit Zeit- und Speichergrenze, getrennte Queues für Mail, Indexierung und Nachrangiges, ein eigener Verbraucher für den Failure-Transport, ein geordneter Neustart nach jedem Deployment und zwei Kennzahlen im Monitoring. Keiner dieser Schritte ist aufwendig - aufwendig ist der Zustand davor.

XICTRON richtet dieses Setup für Shopware-Shops ein und übernimmt den laufenden Betrieb: Wir deaktivieren den Admin-Worker, legen die Worker als Systemdienste mit passenden Limits an, trennen die Queues nach fachlicher Dringlichkeit, hängen den Failure-Transport an eine Alarmierung und binden den geordneten Neustart in das Deployment ein. Ob der Datenbank-Transport ausreicht oder ein eigener Broker sinnvoll ist, entscheiden wir anhand des gemessenen Nachrichtenaufkommens statt nach Schema. Sprechen Sie uns über die Kontaktseite an, lassen Sie den Bestand im Rahmen einer Beratung aufnehmen oder sehen Sie sich an, was unser Hosting und Wartung abdeckt. Für Anpassungen im Shop selbst - eigene Nachrichtentypen, Handler, Routing - steht unsere Shopware-Entwicklung bereit.

Häufige Fragen zur Shopware Message Queue