Cron-Jobs und Hintergrundverarbeitung

Zweck

ADP Car Market Hub ist bei fast allen Aktionen, die keine direkte Benutzeraktion darstellen, auf geplante Hintergrundaufgaben angewiesen: Es importiert Fahrzeuge von AutoScout24, verarbeitet Bilder asynchron, bereinigt Analytics-Daten, aktualisiert die Preisanalyse und führt tägliche Datenqualitätsprüfungen durch. Dieses Dokument erklärt die vom Plugin verwendeten Cron-Mechanismen, die Unterschiede zwischen dem in WordPress integrierten Scheduler und einem echten Server-Cron, die vom Plugin geplanten wiederkehrenden Jobs und die zu überwachenden Betriebssignale.

Wann dieses Dokument zu verwenden ist

Verwenden Sie dieses Dokument, wenn Sie:

• sich bei einer neuen Autohaus-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 planmäßig ausgeführt werden oder warum sich die Bildverarbeitung verzögert.
• prüfen, welche wiederkehrenden Jobs das Plugin registriert und wie lange deren Daten aufbewahrt werden.

Übersicht

Das Hintergrundverarbeitungsmodell des Plugins besteht aus drei Schichten:

1. Eine Trigger-Schicht, 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 token-gesicherten REST-Endpunkt des Plugins unter /wp-json/as24ci/v1/cron-import aufruft.
2. Eine Scheduler-Schicht, 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 Mindestgrenze von 15 Minuten) und eine kleine Anzahl von WP-Cron-Hooks für Importe, die Bild-Warteschlange, die KI-Generierungswarteschlange, die Analytics-Bereinigung, die Preisanalyse und die tägliche Taxonomie-Prüfung.
3. Eine Worker-Schicht, die die eigentliche Arbeit verrichtet. Jeder WP-Cron-Hook ist an eine Klassenmethode gebunden (Importer, Bild-Warteschlange, Analytics-Bereinigung usw.), die auf Transients basierende Sperren verwendet, um überschneidende Ausführungen zu verhindern, und Status-/Heartbeat-Optionen schreibt, die vom Tab „System & Hilfe / Health“ und dem Dashboard-Widget ausgelesen werden.

Alle drei Importpfade – der geplante WP-Cron-Hook, der REST-Cron-Endpunkt und die Admin-Schaltfläche „Jetzt starten“ – rufen denselben gemeinsamen Runner auf, sodass Verhalten und Sperren 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 Besucher-Traffic. Jeder Aufruf einer WordPress-Seite kann im Hintergrund wp-cron.php auslösen.
• Funktioniert auf jedem Host ohne Serverzugriff.
• Wird auf Websites mit geringem 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 Produktivbetrieb)

• Gesteuert durch das Betriebssystem oder den Scheduler des Hosting-Control-Panels.
• Unabhängig vom Website-Traffic, vorhersehbar und von den Health-Prüfungen des Plugins für einen „vollständig bereiten“ Produktivstatus vorausgesetzt.
• Empfohlene Einrichtung: 1. Setzen Sie define( 'DISABLE_WP_CRON', true ); in wp-config.php, damit der besuchergesteuerte Cron deaktiviert ist. 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 andere wiederkehrende Jobs (Bild-Warteschlange, 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 existieren sollten (Importe, Analytics-Bereinigung, Preise, Bild-Warteschlange, ggf. KI-Warteschlange). 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). Vor jeder Arbeit setzt der Runner ein Transient (as24ci_cron_import_running) mit einer Gültigkeitsdauer (TTL) von etwa 40 Minuten. Nachfolgende Ausführungen, 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 miteinander in Konflikt geraten.
• Verarbeitung pro Anbieter. Der Runner durchläuft jede konfigurierte Seller ID und ruft nacheinander den Importer für jede ID auf.
• Fahrzeuge pro Durchlauf. Der Tab „Import & Limits“ bietet eine Begrenzung für „Fahrzeuge pro Durchlauf“ (0 = kein Limit). Die Reduzierung dieses Werts ist der wichtigste Hebel für die Stabilität auf Shared-Hosting-Umgebungen und bei sehr großen Beständen; empfohlene Werte liegen bei 50–80 für große 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ählungen pro Anbieter aktualisiert. Das Dashboard-Widget und der Tab „System & Hilfe“ lesen diese Optionen aus, um Informationen zum letzten Durchlauf anzuzeigen.
• Optionaler vollständiger Abgleich (Full Sync). Wenn die Option „Vollständiger Abgleich“ 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-Assistent 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 große Erstimporte auf ressourcenbeschränkten Hosts nützlich ist.

Bild-Warteschlange und asynchrone Worker

Wenn Bild-Warteschlange 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ührungszeitlimits abgeschlossen wird.
• Die verbleibenden Bild-URLs werden an die Bild-Warteschlange (eine WordPress-Option) angehängt und alle 5 Minuten in Batches durch den Hook as24ci_image_queue_process verarbeitet.
• Der Worker verwendet eine eigene Transient-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ößen-Limit in Scheduler) begrenzt, wie groß 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

• Analytics-Aufbewahrung. Analytics::cleanup_old_data() (Hook as24ci_daily_cleanup) löscht Analytics-Zeilen, die älter sind als der in der Einstellung Analytics-Aufbewahrungstage festgelegte Wert. Der Standardwert ist 180 Tage; das im Code erzwungene Minimum beträgt 7 Tage.
• Protokoll-Rotation. Plugin-Protokolle 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 geschieht unabhängig von WP-Cron und wird bei jedem Protokollschreibvorgang ausgeführt.
• Token-Cache. OAuth-Zugriffstoken werden in einem Transient zwischengespeichert, bis kurz vor ihrem angegebenen expires_in. Für Diagnosezwecke steht das Tool „Token-Cache leeren“ zur Verfügung.
• Fahrzeuglöschungen. Wenn das Plugin ein Fahrzeug entfernt (Vollständiger Abgleich oder manuelles Löschen), bereinigt es die zugehörigen Medienanhänge und Metadaten über einen zentralen Löschpfad.

REST-Cron-Endpunkt

Der token-gesicherte Trigger-Endpunkt wird durch Cron_Endpoint registriert:

• Route: GET /wp-json/as24ci/v1/cron-import
• Authentifizierung: Ein zufälliges, 32-stelliges geheimes Token, das in der Option as24ci_cron_token gespeichert ist. Der Endpunkt akzeptiert das Token auf zwei Wegen:
• Bevorzugt: Authorization: Bearer <token>-HTTP-Header (hält das Token aus den Zugriffsprotokollen fern).
• Fallback: ?token=<token>-Abfrageparameter.
• Antwortcodes: 200 bei Erfolg, 429, wenn die Sperre bereits aktiv ist (ein Import läuft bereits), 403 bei fehlenden/ungültigen Token, 500 bei nicht abgefangenen Ausnahmen.
• Nebeneffekt: Jeder erfolgreiche Aufruf aktualisiert die Option as24ci_last_external_cron_run, die vom Tab „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 Tab „Import & Limits“ generiert kopierfähige Beispielbefehle wie:

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

Der erste Eintrag löst Importe aus; der zweite sorgt dafür, dass Nicht-Import-WP-Cron-Hooks (Bild-Warteschlange, Analytics-Bereinigung, Preise usw.) ausgeführt werden, wenn DISABLE_WP_CRON auf true gesetzt ist.

Betriebliche Überwachung

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

• Tab „System & Hilfe / Health“. Listet jeden Cron-Hook des Plugins, seine nächste geplante Ausführung und die Information auf, ob die Planung derzeit von WP-Cron oder von einem externen Server-Cron übernommen wird. Enthält eine Infokarte, die DISABLE_WP_CRON im Server-Cron-Modus als empfohlen kennzeichnet.
• Dashboard-Widget. Zeigt den letzten Importlauf, den nächsten geplanten Import (wenn WP-Cron verwendet wird), die Tiefe der Bild-Warteschlange und den nächsten Warteschlangenlauf an.
• Plugin-Protokolle. wp-content/uploads/as24ci-logs/ zeichnet jeden Cron-Lauf, das Setzen/Freigeben von Sperren, Aktivitäten der Bild-Warteschlange und alle HTTP-Fehler auf. Protokolle rotieren bei 10 MB mit einer Aufbewahrungsfrist von 7 Tagen.
• Optionen für den letzten Durchlauf. 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 Setup für den Produktivbetrieb umfasst:

• Erreichbarkeitsprüfung (Uptime-Check) der öffentlichen Archiv-URL (Frontend-Verfügbarkeit).
• Erreichbarkeitsprüfung von /wp-json/as24ci/v1/cron-import?token=…, die einen 2xx/429-Status zurückgeben muss (Cron-Pfad erreichbar und authentifiziert).
• Speicherplatz-Warnung für das wp-content/uploads/-Volume (Bildwachstum und Protokolle).
• Optionale Protokollweiterleitung (Log-Shipping) oder regelmäßige Überprüfung des Plugin-Protokollverzeichnisses.

---

Fehlerbehebung

• Importe werden nie automatisch ausgeführt. Überprüfen Sie den Cron-Modus im Reiter „Import & Limits“. Wenn WP-Cron ausgewählt ist, lösen Websites mit geringem Traffic den Cron-Job möglicherweise überhaupt nicht aus – wechseln Sie zu einem Server-Cron-Job. Wenn Server-Cron ausgewählt ist, stellen Sie sicher, dass der curl/wget-Befehl den REST-Endpunkt tatsächlich erreicht (HTTP 200 oder 429 erwartet).
• Antworten mit „Ein Import wird bereits ausgeführt“ (HTTP 429). Der Lock-Transient wird noch von einem vorherigen Durchlauf gehalten. Warten Sie, bis der Durchlauf beendet ist, oder löschen Sie den Transient as24ci_cron_import_running, wenn ein vorheriger PHP-Prozess abgestürzt ist, ohne die Sperre aufzuheben. Verringern Sie den Wert für Fahrzeuge pro Durchlauf, um die einzelnen 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 oben gezeigten zweiten Cron-Eintrag), überprüfen Sie das Protokollverzeichnis auf Fehler des Queue-Workers und verifizieren Sie ausgehende HTTPS-Verbindungen zu den Bild-Hosts (siehe API-, Netzwerk- und SSL-Anforderungen).
• Analytics- 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 niemals ausgelöst.
• Der Reiter „System & Hilfe“ zeigt an, dass das Cron-Token nicht konfiguriert ist. Öffnen Sie den Reiter „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 Reiter „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-Ausführungen auf Staging-Umgebungen 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).

Zugehörige Dokumente

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