Cron und Hintergrundverarbeitung

Zweck

ADP Car Market Hub hängt bei fast allem, was keine direkte Benutzeraktion ist, von geplanten Hintergrundaufgaben ab: Es importiert Fahrzeuge aus jeder verbundenen Connections-Quelle (AutoScout24, mobile.de, carcuro, einem automatischen Feed und E-Mail-Import) nach einem zentralen Zeitplan, verarbeitet Bilder asynchron, bereinigt Analytics-Daten, aktualisiert die Preisanalyse und führt tägliche Datenqualitäts-Scans durch. Dieses Dokument erklärt die Cron-Mechanismen, die das Plugin verwendet, die Unterschiede zwischen dem in WordPress integrierten Scheduler und einem echten Server-Cron, die wiederkehrenden Jobs, die das Plugin plant, und die zu überwachenden Betriebssignale.

Wann dieses Dokument zu verwenden ist

Verwenden Sie dieses Dokument, wenn Sie:

• Sich bei einer neuen Garagen-Website zwischen WP-Cron und einem externen Server-Cron entscheiden.
• Den Cron-Modus, die Häufigkeit und das geheime Token im Tab "Import & Limits" konfigurieren.
• Einen externen Scheduler (Linux-Cron, Hosting-Cron-UI oder einen Remote-Pinger) mit dem REST-Cron-Endpunkt des Plugins verbinden.
• Untersuchen, warum Importe nicht nach Zeitplan laufen oder warum sich die Bildverarbeitung verzögert.
• Überprüfen, welche wiederkehrenden Jobs das Plugin registriert und wie lange deren Daten aufbewahrt werden.

Übersicht

Das Hintergrundverarbeitungsmodell des Plugins besteht aus drei Ebenen:

1. Eine Trigger-Ebene, die entscheidet, wann die Arbeit beginnen soll. Dies kann der Pseudo-Cron von WordPress sein (gesteuert durch Website-Besuche auf wp-cron.php) oder ein externer Server-Cron, der entweder wp-cron.php direkt oder den mit einem Token gesicherten REST-Endpunkt des Plugins unter /wp-json/as24ci/v1/cron-import aufruft.
2. Eine Scheduler-Ebene, die die wiederkehrenden Jobs verwaltet. Das Plugin registriert benutzerdefinierte Intervalle (alle 5 Minuten, alle 6 Stunden sowie ein konfigurierbares Intervall "alle N Minuten" mit einer Untergrenze von 15 Minuten) und eine kleine Anzahl von WP-Cron-Hooks für Importe, die Bildwarteschlange, die AI-Generierungswarteschlange, die Analytics-Bereinigung, die Preisanalyse und den täglichen Taxonomie-Scan.
3. Eine Worker-Ebene, die die eigentliche Arbeit erledigt. Jeder WP-Cron-Hook ist an eine Klassenmethode gebunden (Importer, Bildwarteschlange, Analytics-Bereinigung usw.), die auf Transients basierende Sperren verwendet, um überschneidende Ausführungen zu verhindern, und Status-/Heartbeat-Optionen schreibt, die der Tab "System & Hilfe / Status" und das Dashboard-Widget auslesen.

Alle drei Importpfade – der geplante WP-Cron-Hook, der REST-Cron-Endpunkt und die Admin-Schaltfläche "Jetzt ausführen" – rufen denselben gemeinsamen Runner auf, sodass das Verhalten und die Sperrung unabhängig vom Trigger identisch sind.

WordPress-Cron vs. Server-Cron

Der Tab "Import & Limits" bietet zwei Trigger-Modi; beide werden unterstützt, weisen jedoch sehr unterschiedliche Zuverlässigkeitsprofile auf.

WordPress-Cron (Standard)

• Gesteuert durch den Besucherverkehr. Jede Anfrage an eine WordPress-Seite kann im Hintergrund wp-cron.php auslösen.
• Funktioniert auf jedem Host ohne Serverzugriff.
• Wird auf Websites mit wenig Traffic unzuverlässig: Ohne Besucher gibt es keine Cron-Ausführungen.
• Das Plugin installiert dennoch alle seine Hooks; verpasste Ausführungen sammeln sich einfach bis zum nächsten Besuch an.

Server-Cron (empfohlen für den Live-Betrieb)

• Gesteuert durch das Betriebssystem oder den Scheduler des Hosting-Control-Panels.
• Unabhängig vom Website-Traffic, vorhersehbar und von den Statusprüfungen des Plugins für einen "vollständig bereiten" Live-Status vorausgesetzt.
• Empfohlene Einrichtung: 1. Setzen Sie define( 'DISABLE_WP_CRON', true ); in wp-config.php, damit der besuchergesteuerte Cron deaktiviert wird. 2. Fügen Sie einen Server-Cron-Eintrag hinzu, der den REST-Endpunkt des Plugins mit dem geheimen Token aufruft. 3. Fügen Sie einen zweiten Eintrag hinzu, der wp-cron.php selbst ausführt, damit wiederkehrende Jobs, die keine Importe sind (Bildwarteschlange, Analytics-Bereinigung, Preise usw.), weiterhin ausgeführt werden.

Das Umschalten auf Server-Cron im Tab "Import & Limits" blendet die WP-Cron-Zeitplanfelder aus und zeigt die REST-Trigger-URL, das geheime Token und kopierfertige Beispielbefehle an.

Vom Plugin registrierte wiederkehrende Jobs

Die folgenden WP-Cron-Hooks werden vom Plugin geplant (einige nur, wenn die entsprechende Funktion konfiguriert ist). Der Tab "System & Hilfe" listet ihre nächste geplante Ausführungszeit auf, sodass sie jederzeit überprüft werden können.

Die Aktivierung registriert die wiederkehrenden Jobs, die immer vorhanden sein sollten (Importe, Analytics-Bereinigung, Preise, Bildwarteschlange, AI-Warteschlange falls zutreffend). Die Deaktivierung entfernt die WP-Cron-Einträge des Plugins über wp_clear_scheduled_hook() für jeden der oben genannten Hooks.

---

---

Wiederkehrende Importe

Der Import-Runner wird von allen drei Trigger-Pfaden gemeinsam genutzt und verhält sich wie folgt:

• Sperrung (Locking). Bevor der Runner Arbeit verrichtet, setzt er ein Transient (as24ci_cron_import_running) mit einer Gültigkeit (TTL) von etwa 40 Minuten. Nachfolgende Durchläufe, die eintreffen, während die Sperre aktiv ist, werden sauber beendet und melden, dass bereits ein Import läuft. Dies verhindert, dass WP-Cron und ein Server-Cron gegeneinander antreten (Race Condition).
• Verarbeitung pro Garage. Der Runner durchläuft jede konfigurierte Seller ID und ruft nacheinander den Importer für jede einzelne auf.
• Fahrzeuge pro Durchlauf. Der Reiter "Import & Limits" bietet eine Begrenzung für "Fahrzeuge pro Durchlauf" (0 = kein Limit). Die Senkung dieses Wertes ist der wichtigste Hebel für die Stabilität auf Shared Hosting und bei sehr grossen Beständen; empfohlene Werte sind 50–80 für grosse Kataloge.
• Status-Persistenz. Nach jedem Durchlauf werden die Optionen mit dem Zeitstempel des letzten Durchlaufs, der Trigger-Quelle (wp-cron, rest, manuell) und den Zählern pro Garage aktualisiert. Das Dashboard-Widget und der Reiter "System & Hilfe" lesen diese Optionen aus, um Informationen zum letzten Durchlauf anzuzeigen.
• Optionaler Vollabgleich (Full Sync). Wenn die Option "Full Sync" aktiviert ist, kann der Runner Fahrzeuge, die in der neuesten API-Antwort fehlen, als gelöscht markieren; dies ist dauerhaft, weshalb eine getestete Backup-Strategie erforderlich ist (siehe Hosting-Anforderungen).

Der Batch-Wizard in der Admin-Benutzeroberfläche verwendet denselben Importer, verarbeitet jedoch ein Fahrzeug pro Schritt aus einer Warteschlangenliste (Transient as24ci_batch_queue), was für sehr grosse Erstimporte auf ressourcenbeschränkten Hosts nützlich ist.

Bildwarteschlange und asynchrone Worker

Wenn Bildwarteschlange aktivieren eingeschaltet ist (empfohlen für bildintensive Importe):

• Während des Imports wird nur das erste Bild jedes Fahrzeugs synchron heruntergeladen, sodass die Seite schnell antwortet und der Cron-Durchlauf weit innerhalb der PHP-Ausführungszeitgrenzen abgeschlossen wird.
• Die verbleibenden Bild-URLs werden an die Bildwarteschlange (eine WordPress Option) angehängt und alle 5 Minuten in Batches durch den Hook as24ci_image_queue_process verarbeitet.
• Der Worker verwendet seine eigene transiente Sperre (as24ci_image_queue_running, 10 Minuten TTL) und verarbeitet eine feste Anzahl von Bildern pro Batch.
• Ein Sicherheitslimit (die Konstante für das Warteschlangengrössen-Limit in Scheduler) begrenzt, wie gross die Warteschlange werden darf, bevor das Plugin eine Warnung protokolliert und Einträge zwangsweise dedupliziert.

Die KI-Generierungswarteschlange folgt einem ähnlichen Muster: KI-Aufrufe während des Imports werden in eine Warteschlange verschoben und von einem asynchronen Worker verarbeitet, damit die Importläufe nicht durch den verwalteten Gemini-Endpunkt blockiert werden.

Bereinigungs- und Aufbewahrungsroutinen

• Aufbewahrung von Analytics. Analytics::cleanup_old_data() (Hook as24ci_daily_cleanup) löscht Analytics-Zeilen, die älter sind als der in der Einstellung Aufbewahrungstage für Analytics festgelegte Wert. Der Standardwert beträgt 180 Tage; das im Code erzwungene Minimum liegt bei 7 Tagen.
• Log-Rotation. Plugin-Logs in wp-content/uploads/as24ci-logs/ werden rotiert, sobald eine einzelne Datei 10 MB erreicht, und rotierte Dateien werden nach 7 Tagen gelöscht. Dies ist unabhängig von WP-Cron und läuft bei jedem Log-Schreibvorgang.
• Token-Cache. OAuth-Zugriffstoken werden in einem Transient zwischengespeichert, bis kurz vor ihrem angegebenen expires_in. Für Diagnosezwecke existiert ein Tool "Token-Cache leeren".
• Fahrzeuglöschungen. Wenn das Plugin ein Fahrzeug entfernt (Full Sync oder manuelle Löschung), bereinigt es die zugehörigen Medienanhänge und Metadaten über einen zentralen Löschpfad.

REST-Cron-Endpunkt

Der durch ein Token gesicherte Trigger-Endpunkt wird durch Cron_Endpoint registriert:

• Route: GET /wp-json/as24ci/v1/cron-import
• Authentifizierung: Ein zufälliges, 32-stelliges Geheimnis, das in der Option as24ci_cron_token gespeichert ist. Der Endpunkt akzeptiert das Token auf zwei Arten:
• Bevorzugt: Authorization: Bearer <token> HTTP-Header (hält das Token aus den Server-Zugriffsprotokollen heraus).
• Fallback: ?token=<token> Query-Parameter.
• Antwortcodes: 200 bei Erfolg, 429 wenn die Sperre bereits aktiv ist (ein Import läuft bereits), 403 für fehlende/ungültige Token, 500 für nicht abgefangene Ausnahmen.
• Nebeneffekt: Jeder erfolgreiche Aufruf aktualisiert die Option as24ci_last_external_cron_run, die vom Reiter "System & Hilfe" verwendet wird, um zu bestätigen, dass der externe Cron aktiv ist.
• Ein separater, nicht authentifizierter Heartbeat wird aufgezeichnet, wann immer eine WordPress URL mit ?as24ci_cron=1 aufgerufen wird, was für einfache externe Pinger nützlich ist, die nur die Erreichbarkeit bestätigen müssen.

Der Reiter "Import & Limits" generiert kopierfertige Beispielbefehle wie:

*/15 * * * * curl -s -H "Authorization: Bearer YOUR_TOKEN" "https://example.com/wp-json/as24ci/v1/cron-import" > /dev/null
*/5  * * * * php /var/www/html/wp-cron.php > /dev/null 2>&1

Der erste Eintrag löst Importe aus; der zweite hält Nicht-Import-WP-Cron-Hooks (Bildwarteschlange, Analytics-Bereinigung, Preisgestaltung usw.) am Laufen, wenn DISABLE_WP_CRON auf true gesetzt ist.

Betriebliche Überwachung

Das Plugin stellt die Signale bereit, die Betreiber zur Überwachung ohne zusätzliche Tools benötigen:

• System & Hilfe / Reiter "Zustand". Listet jeden Plugin-Cron-Hook, seinen nächsten geplanten Lauf und die Information auf, ob die Planung derzeit von WP-Cron oder von einem externen Server-Cron verwaltet wird. Enthält eine Infokarte, die DISABLE_WP_CRON im Server-Cron-Modus als empfohlen kennzeichnet.
• Dashboard-Widget. Zeigt den jüngsten Importlauf, den nächsten geplanten Import (wenn WP-Cron verwendet wird), die Tiefe der Bildwarteschlange und den nächsten Warteschlangenlauf an.
• Plugin-Logs. wp-content/uploads/as24ci-logs/ protokolliert jeden Cron-Lauf, das Erwerben/Freigeben von Sperren, Aktivitäten in der Bildwarteschlange und alle HTTP-Fehler. Logs rotieren bei 10 MB mit einer Aufbewahrungsfrist von 7 Tagen.
• Optionen des letzten Durchlaufs. as24ci_last_external_cron_run und die entsprechenden internen Optionen können direkt über WP-CLI für skriptbasierte Alarmierungen überprüft werden.

Ein einfaches Produktions-Setup ist:

• Uptime-Check auf der öffentlichen Archiv-URL (Frontend-Verfügbarkeit).
• Uptime-Check auf /wp-json/as24ci/v1/cron-import (mit dem Authorization: Bearer Header), der einen 2xx/429 Status zurückgibt (Cron-Pfad erreichbar und authentifiziert).
• Speicherplatz-Alarmierung auf dem wp-content/uploads/ Volume (Bildwachstum und Logs).
• Optionale Log-Weiterleitung oder regelmässige Überprüfung des Plugin-Log-Verzeichnisses.

---

Fehlerbehebung

• Importe starten nie automatisch. Überprüfen Sie den Cron-Modus im Tab "Import & Limits". Wenn WP-Cron ausgewählt ist, führen Websites mit wenig Traffic Cron-Jobs möglicherweise überhaupt nicht aus – wechseln Sie zu Server-Cron. Wenn Server-Cron ausgewählt ist, überprüfen Sie, ob der curl/wget-Befehl den REST-Endpunkt tatsächlich erreicht (HTTP 200 oder 429 erwartet).
• Antworten mit "Ein Import läuft bereits" (HTTP 429). Der Lock-Transient wird noch von einem vorherigen Durchlauf gehalten. Warten Sie, bis der Durchlauf beendet ist, oder löschen Sie den as24ci_cron_import_running Transient, falls ein vorheriger PHP-Prozess abgestürzt ist, ohne den Lock freizugeben. Verringern Sie Fahrzeuge pro Durchlauf, um einzelne Durchläufe deutlich unter der Lock-TTL zu halten.
• Die Bildwarteschlange wächst, ohne kleiner zu werden. Stellen Sie sicher, dass wp-cron.php ausgeführt wird (im Server-Cron-Modus erfordert dies den zweiten oben gezeigten Cron-Eintrag), überprüfen Sie das Log-Verzeichnis auf Fehler des Queue-Workers und verifizieren Sie ausgehende HTTPS-Verbindungen zu den Bild-Hosts (siehe API-, Netzwerk- und SSL-Anforderungen).
• Analyse- oder Preisdaten werden nicht aktualisiert. Diese werden täglich über WP-Cron ausgeführt; wenn DISABLE_WP_CRON auf true gesetzt ist und kein zweiter Cron-Eintrag vorhanden ist, der wp-cron.php aufruft, werden die täglichen Jobs nie ausgeführt.
• Der Tab "System & Hilfe" zeigt an, dass das Cron-Token nicht konfiguriert ist. Öffnen Sie den Tab "Import & Limits", wechseln Sie in den Server-Cron-Modus und lassen Sie das Plugin entweder automatisch ein Token generieren oder fügen Sie Ihr eigenes ein und speichern Sie.
• Token durchgesickert oder rotiert. Klicken Sie im Tab "Import & Limits" auf Token neu generieren. Aktualisieren Sie sofort jeden externen Scheduler, da das vorherige Token nicht mehr funktioniert, sobald das neue gespeichert ist.
• Cron-Durchläufe auf Staging-Systemen beeinträchtigen Produktionsdaten. Verwenden Sie pro Umgebung ein anderes Cron-Token und ziehen Sie nach Möglichkeit einen anderen AutoScout24-Client in Betracht (siehe Hosting-Anforderungen).

Verwandte Dokumente

• Technische Systemanforderungen
• WordPress Anforderungen
• Hosting-Anforderungen
• PHP- und Datenbank-Anforderungen
• API-, Netzwerk- und SSL-Anforderungen
• Checkliste vor der Installation
• Verbindungsreferenz