> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/push-und-live-abgleich.md).

# Push und Live-Abgleich

So übertragen Sie Ihre Produkte per Push, welche Hintergrundverarbeitung dafür laufen muss und wie der Live-Abgleich Änderungen innerhalb von etwa zwei Minuten in die Suche bringt.

Beim Push sendet Ihr Shop die Produkte selbst an unser Suchsystem. Das ist der Weg für Entwicklungs- und Stage-Umgebungen, die von außen nicht erreichbar sind. Diese Seite zeigt, wann Sie Push brauchen, wie ein Lauf abläuft, was auf dem Server laufen muss und wie Sie Änderungen an Preis und Lagerbestand schnell in die Suche bringen.

Die Seite richtet sich auch an Agenturen und Administratoren. Technische Begriffe sind beim ersten Auftreten kurz erklärt, Befehle stehen in Codeblöcken.

## Wann Push, wann Pull?

Es gibt zwei Wege, die Produkte in die Suche zu bringen:

|                            | Pull (Feed)                                                             | Push                                                                          |
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Wer holt oder sendet?      | Unser Suchsystem ruft den Produkt-Feed Ihres Shops ab                   | Ihr Shop sendet die Produkte selbst                                           |
| Shop von außen erreichbar? | Ja, die Feed-Adresse muss öffentlich und ohne Anmeldung erreichbar sein | Nein, nicht nötig                                                             |
| Geeignet für               | Live-Shops                                                              | Entwicklungs- und Stage-Umgebungen, Shops hinter Passwortschutz oder Firewall |
| Zeitpunkt                  | Einmal täglich zur eingestellten Uhrzeit, jederzeit manuell             | Täglich durch eine geplante Aufgabe, jederzeit manuell                        |
| Live-Abgleich              | Nicht verfügbar                                                         | Verfügbar                                                                     |
| Hintergrundverarbeitung    | Nur für Statistik-Meldungen                                             | Zwingend nötig                                                                |

Den Weg wählen Sie im Einrichtungsassistenten bei der Indexierungsart: „Push: Das Plugin sendet die Produkte (für DEV/Stage)“. Beim Push legt das Plugin keinen Produktvergleichs-Verkaufskanal und keinen Produktexport an. Stattdessen speichert es die Einstellungen (Verkaufskanal, Domain, Kundengruppe, dynamische Produktgruppe, Sprache, Währung) im Shop selbst.

{% hint style="info" %}
Wie Sie einen Pull-Feed einrichten und prüfen, lesen Sie unter [Installation und Einrichtung](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/installation-und-einrichtung.md). Für Stage-Umgebungen mit Passwortschutz ist Push der richtige Weg, siehe [Stage und Live](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/stage-und-live.md).
{% endhint %}

## Ablauf eines Push-Laufs

1. **Registrieren:** Das Plugin legt den Push-Index in unserem Suchsystem an, mit Verkaufskanal, Domain und Kundengruppe. So bekommen gleichnamige Konfigurationen für verschiedene Kanäle jeweils einen eigenen Index.
2. **Starten:** Ein Lauf beginnt im Einrichtungsassistenten, mit „Produktdaten neu einlesen“ im Bereich „Quellen“ oder durch die tägliche geplante Aufgabe. Das Plugin prüft Zugangsdaten und Einstellungen und zählt die Produkte. Gibt es kein passendes Produkt, startet der Lauf nicht („Keine Produkte gefunden“). Danach zerlegt das Plugin die Produkte in **Pakete zu je 50 Produkten**.
3. **Pakete senden:** Die Pakete werden im Hintergrund abgearbeitet. Für jedes Paket lädt das Plugin die Produkte (nach Verkaufskanal, Sichtbarkeit „Suche“ oder „Alle“, Aktiv-Status, dynamischer Produktgruppe, Währung, Sprache und Kundengruppe) und sendet sie. Im Bereich „Quellen“ sehen Sie den Fortschritt mit Prozentwert, geschätzter Restzeit und Durchsatz (Produkte pro Sekunde).
4. **Abschließen:** Sind alle Pakete verarbeitet, meldet das Plugin den Lauf als beendet. Unser Suchsystem baut den Suchindex danach fertig auf.
5. **Abbrechen oder neu starten:** Mit „Abbrechen“ beenden Sie einen laufenden Lauf nach einer Rückfrage („Laufende Indexierung wirklich abbrechen?“). Danach starten Sie mit „Neu starten“ von vorn.

Gut zu wissen:

* Pro Installation läuft immer nur **ein** Push-Lauf gleichzeitig. Ein zweiter Start wird abgewiesen.
* Ein Lauf ohne Lebenszeichen seit 15 Minuten gilt als tot und darf neu gestartet werden.
* Produkte, die nur in der Suche sichtbar sind (Shopware-Sichtbarkeit „nur Suche“), werden übertragen und erscheinen nicht auf Kategorieseiten.
* Varianten ohne eigene Kategorie übernehmen die Kategorien des Hauptprodukts.
* Ein Push wird nie automatisch wiederholt. Ein fehlgeschlagener Lauf wird mit „Erneut versuchen“ oder „Neu starten“ von Hand gestartet.
* Manuell ausgelöste Läufe sind jederzeit möglich, solange die Datenquelle nicht durch InsightSearch gesperrt ist und nicht schon ein Lauf aktiv ist.

## Hintergrundverarbeitung (Worker)

Push läuft nicht direkt beim Klick, sondern über die **Message Queue** von Shopware. Das ist eine Warteschlange, in die der Shop Aufträge stellt. Ein **Worker** ist ein dauerhaft laufender Prozess, der diese Aufträge abarbeitet. Ohne Worker bleibt ein Push-Lauf einfach stehen. Auch die Meldungen zu Warenkorb, Bestellung und Zahlstatus für die Statistik laufen über diese Warteschlange.

Im Bereich „Quellen“ weist das Plugin selbst darauf hin: Die Hintergrundverarbeitung von Shopware muss dauerhaft laufen, entweder mit aktivem Admin-Worker oder mit `messenger:consume` als Dienst.

### Worker starten

Für den Dauerbetrieb eignet sich ein Worker als Dienst, den Supervisor oder systemd nach einem Beenden neu starten:

```bash
bin/console messenger:consume async low_priority --time-limit=3600 --memory-limit=512M
```

* `async` ist die Warteschlange, die das Plugin nutzt. Nehmen Sie `low_priority` dazu, wie es Shopware empfiehlt, damit keine Nachrichten liegen bleiben.
* `--time-limit=3600` beendet den Worker nach einer Stunde sauber, der Dienst startet ihn neu.
* `--memory-limit=512M` begrenzt den Speicher des Workers. Die genauen Werte richten sich nach Ihrem Server und der Shopware-Dokumentation.

Der **Admin-Worker** von Shopware läuft nur, solange ein Administrator den Admin im Browser geöffnet hat. Er reicht für einen Test, nicht für den Dauerbetrieb.

### Speicherlimit

Große Kataloge brauchen beim Verarbeiten der Pakete viel Arbeitsspeicher. Das Plugin schützt den Worker davor, hart abzustürzen:

| Situation                                                                                | Reaktion                                                                           |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Der Worker belegt mindestens 70 % des PHP-Speicherlimits und weniger als 64 MB sind frei | Er beendet sich nach der aktuellen Nachricht sauber, ein frischer Worker übernimmt |
| Der Worker belegt 80 % oder mehr und weniger als 48 MB sind frei                         | Ein neues Paket beginnt nicht mehr, der Worker beendet sich zuerst                 |
| Das Speicherlimit ist unbegrenzt (`-1`)                                                  | Der Schutz greift nicht                                                            |

Im Protokoll steht dann „\[WorkerMemoryGuard] Worker wird wegen Speicherverbrauch beendet und neu gestartet“. Damit der Neustart klappt, muss ein Dienst wie Supervisor oder systemd den Worker wieder starten. Das Speicherlimit gilt für PHP auf der Kommandozeile (CLI), nicht für das Limit der Webseiten.

{% hint style="warning" %}
Bricht ein Worker hart ab, zum Beispiel durch einen PHP-Fehler wegen zu wenig Speicher, bleibt die Nachricht in der Warteschlange unsichtbar. Sie kommt erst nach einer Stunde zurück. Das war die Ursache für einen Lauf, der bei 96 Prozent stehen blieb.
{% endhint %}

### Nach Updates neu starten

Nach einem Plugin-Update oder einer Konfigurationsänderung sollten laufende Worker den neuen Code laden:

```bash
bin/console messenger:stop-workers
```

Supervisor oder systemd starten sie danach neu.

## Geplante Aufgaben des Plugins

Das Plugin nutzt die **geplanten Aufgaben** (Scheduled Tasks) von Shopware. Diese müssen dauerhaft laufen, zum Beispiel per Cron oder als Dienst mit `scheduled-task:run`. Ohne sie gibt es keinen täglichen Push, keine Überwachung hängender Läufe, keine Verbindungsprüfung, kein Nachholen von Bestellungen und keinen Live-Abgleich.

| Aufgabe                     | Zweck                                                                                                      | Takt            |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------- |
| Täglicher Push              | Überträgt alle Produkte aller Push-Indizes komplett. Überspringt einen Index, dessen Lauf schon aktiv ist. | alle 24 Stunden |
| Überwachung hängender Läufe | Prüft Läufe ohne Fortschritt, reiht Pakete neu ein oder schließt einen Lauf ab (siehe unten)               | alle 10 Minuten |
| Verbindungsprüfung          | Meldet ein Lebenszeichen, gleicht gebuchte Zusatzfunktionen und die Liste der Indizes ab                   | stündlich       |
| Live-Abgleich               | Überträgt vorgemerkte Produktänderungen, nur wenn der Schalter an ist                                      | jede Minute     |
| Nachholen von Bestellungen  | Holt Bestellungen der letzten 7 Tage nach, die unser Suchsystem noch nicht kennt                           | alle 6 Stunden  |

Der tägliche Push hat keine einstellbare Uhrzeit. Er läuft alle 24 Stunden ab dem letzten Lauf. Die Einstellung „Automatische Indexierung (Uhrzeit)“ im Bereich „Quellen“ gilt nur für Pull.

Aufgaben registrieren und starten Sie mit den Shopware-Befehlen, die auf der Seite [Befehle](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/befehle.md) beschrieben sind.

## Wenn der Push bei 96 Prozent hängt

Ein Lauf kann stehen bleiben, etwa weil ein Worker abgestürzt ist oder gar keiner läuft. Das Plugin überwacht das und hilft sich selbst. Die Überwachung läuft alle 10 Minuten und rechnet ab dem letzten Fortschritt:

| Zeit ohne Fortschritt                           | Was passiert                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ab ca. 4 Minuten                                | Offene Pakete werden automatisch neu eingereiht, bis zu 3 Mal je Paket und höchstens 50 Pakete je Durchlauf, ohne doppelt zu senden oder zu zählen. Im Bereich „Quellen“ erscheint: „Seit einigen Minuten gibt es keinen Fortschritt. Hängende Pakete werden automatisch neu eingereiht, danach läuft die Indexierung weiter.“ |
| 10 Minuten                                      | Die Anzeige warnt, dass seit über 10 Minuten kein Fortschritt mehr erkennbar ist                                                                                                                                                                                                                                               |
| 15 Minuten, keine Pakete mehr neu einreihbar    | Der Lauf gilt als fehlgeschlagen („Indexierung hängt (keine Fortschritte). Bitte erneut starten.“) und lässt sich neu starten                                                                                                                                                                                                  |
| 1 Stunde, wenn gar kein Worker läuft            | Der Lauf gilt als fehlgeschlagen und lässt sich neu starten                                                                                                                                                                                                                                                                    |
| Alle Pakete fertig, Abschluss fehlt (5 Minuten) | Die Überwachung schließt den Lauf selbst ab                                                                                                                                                                                                                                                                                    |

### Das können Sie prüfen

1. Läuft ein Worker? Prüfen Sie den Status von Supervisor oder systemd, oder ob ein Admin im Browser offen ist.
2. Ist das PHP-Speicherlimit des Worker-Prozesses (CLI) ausreichend? Bei sehr großen Katalogen erhöhen Sie es.
3. Läuft `scheduled-task:run`? Ohne die geplanten Aufgaben läuft die Überwachung nicht.
4. Steht im Bereich „Quellen“ der Hinweis zum automatischen Neu-Einreihen?
5. Schauen Sie ins Protokoll des Plugins unter `var/log` (Datei `cogi_insightsearch-<Datum>.log`) nach Einträgen mit „\[PushIndexing]“, „\[PushFinalize]“ und „\[WorkerMemoryGuard]“.
6. Starten Sie den Lauf danach mit „Neu starten“.

Weitere Schritte finden Sie unter [Fehlersuche](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/fehlersuche.md).

## Live-Abgleich

Ohne Live-Abgleich sehen Besucher Änderungen an Preisen, Lagerbestand oder Sichtbarkeit erst nach dem nächsten Push-Lauf, also bis zu einen Tag später. Mit dem Live-Abgleich sind sie nach **etwa zwei Minuten** in der Suche.

### Einstellung

Die Option finden Sie in der Plugin-Konfiguration in der Karte „Live-Abgleich“:

| Einstellung                                                    | Wirkung                                                                                | Standard |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------- |
| „Preis-, Lager- und Sichtbarkeitsänderungen sofort übertragen“ | Geänderte und gelöschte Produkte werden nach etwa zwei Minuten in die Suche übernommen | aus      |

{% hint style="warning" %}
Setzen Sie den Schalter unter „Alle Verkaufskanäle“. Er gilt immer für alle Verkaufskanäle. Ein Wert, den Sie für einen einzelnen Verkaufskanal setzen, wird nicht ausgewertet.
{% endhint %}

Der Live-Abgleich gilt **nur für Push-Indizes**. Im Pull-Betrieb passiert nichts: Dort bringt der nächste Abruf des Feeds die Änderungen.

### Was übertragen wird

Das Plugin merkt sich die Produkte, wenn sich Preis, Lager, Sichtbarkeit, Aktiv-Status oder Kategorien ändern, wenn eine Bestellung den Bestand verändert oder wenn ein Produkt gelöscht wird. Die geplante Aufgabe läuft jede Minute und sendet Einträge, die mindestens 20 Sekunden alt sind. So werden mehrere Änderungen am selben Produkt zusammengefasst.

* Produkte, die nicht mehr zum Umfang des Index gehören (unsichtbar, inaktiv, nicht in der dynamischen Produktgruppe), werden aus der Suche entfernt.
* Wird ein Hauptprodukt gelöscht, verschwinden seine Varianten mit.
* Ein Produkt, das gelöscht und mit derselben ID sofort neu angelegt wird (zum Beispiel bei einem ERP-Import), bleibt in der Suche.

### Pausen und Schutz

Der Live-Abgleich pausiert sich selbst, wenn etwas nicht stimmt, damit keine Last entsteht:

| Situation                              | Reaktion                                                                                                                    |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Zugangsdaten werden abgelehnt          | 1 Stunde Pause                                                                                                              |
| Sonstiger Fehler oder Serverfehler     | 5 Minuten Pause                                                                                                             |
| Zu viele Anfragen (Drosselung)         | Wartezeit nach Vorgabe, mindestens 30 Sekunden. Ist nur ein Index gesperrt, laufen die anderen weiter.                      |
| Mehr als 20.000 vorgemerkte Änderungen | Die Vormerkungen werden verworfen, der nächste vollständige Push übernimmt alles (Meldung „Zu viele Änderungen auf einmal“) |

Voraussetzung sind laufende geplante Aufgaben und ein laufender Worker.

{% hint style="info" %}
Große Importe, etwa ein Neuaufbau der Shopware-Indizes mit `dal:refresh:index`, können sehr viele Änderungen vormerken. Planen Sie solche Läufe bei aktivem Live-Abgleich bewusst ein.
{% endhint %}

## Weiterlesen

{% content-ref url="/pages/SjGrQJy19tWx34BxWnlQ" %}
[Stage und Live](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/stage-und-live.md)
{% endcontent-ref %}

{% content-ref url="/pages/CjY24FwIjTqbOmJFUGvX" %}
[Befehle](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/befehle.md)
{% endcontent-ref %}

{% content-ref url="/pages/IRaJNiR83at8tpKODJsz" %}
[Fehlersuche](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/fehlersuche.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/push-und-live-abgleich.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
