Cron und Hintergrundverarbeitung

Zweck

ADP Car Market Hub ist für fast alles, was keine direkte Benutzeraktion ist, auf geplante Hintergrundaufgaben angewiesen: Es importiert Fahrzeuge von AutoScout24, verarbeitet Bilder asynchron, bereinigt Analysedaten, aktualisiert die Preisanalyse und führt tägliche Datenqualitäts-Scans 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 sowie 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 planmässig ausgeführt werden 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 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 mit einem 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 Untergrenze von 15 Minuten) und eine kleine Anzahl von WP-Cron-Hooks für Importe, die Bildwarteschlange, die KI-Generierungswarteschlange, die Analysebereinigung, die Preisanalyse und den täglichen Taxonomie-Scan.
3. Eine Worker-Schicht, die die eigentliche Arbeit erledigt. Jeder WP-Cron-Hook ist an eine Klassenmethode gebunden (Importer, Bildwarteschlange, Analysebereinigung usw.), die auf Transients basierende Sperren verwendet, um überschneidende Ausführungen zu verhindern, und Status-/Heartbeat-Optionen schreibt, die vom Tab "System & Hilfe / Zustand" und dem Dashboard-Widget ausgelesen werden.

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 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 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 an, bis der nächste Besuch erfolgt.

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 Zustandsprüfungen des Plugins für einen "vollständig bereiten" Live-Status gefordert.
• 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 andere wiederkehrende Jobs (Bildwarteschlange, Analysebereinigung, Preisgestaltung 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, Analysebereinigung, Preisgestaltung, Bildwarteschlange, 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 Triggerpfaden 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 gegeneinander antreten.
• Verarbeitung pro Garage. Der Runner geht jede konfigurierte Seller ID durch und ruft nacheinander den Importer für jede einzelne auf.
• Fahrzeuge pro Durchlauf. Der Tab "Import & Limits" bietet eine Begrenzung für "Fahrzeuge pro Durchlauf" (0 = kein Limit). Das Absenken dieses Werts 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 Triggerquelle (wp-cron, rest, manuell) und den Zählungen pro Garage aktualisiert. Das Dashboard-Widget und der Tab "System & Hilfe" lesen diese Optionen aus, um Informationen zum letzten Durchlauf anzuzeigen.
• Optionale Vollsynchronisation. Wenn die Option "Vollsynchronisation" 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 Systemanforderungen).

Der Batch-Wizard in der Admin-Oberflä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ührungszeitlimits 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 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 Warteschlangen-Grössenlimit in Scheduler) begrenzt, wie gross die Warteschlange werden darf, bevor das Plugin eine Warnung protokolliert und Einträge erzwungen bereinigt.

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 Analysedaten. Analytics::cleanup_old_data() (Hook as24ci_daily_cleanup) löscht Analysezeilen, die älter sind als der in der Einstellung Aufbewahrungstage für Analysedaten festgelegte Wert. Der Standardwert ist 180 Tage; das im Code erzwungene Minimum beträgt 7 Tage.
• 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 wird bei jedem Log-Schreibvorgang ausgeführt.
• Token-Cache. OAuth-Zugriffstoken werden in einem Transient zwischengespeichert, bis kurz vor ihrem angegebenen expires_in. Für Diagnosezwecke ist ein Tool "Token-Cache leeren" vorhanden.
• Fahrzeuglöschungen. Wenn das Plugin ein Fahrzeug entfernt (Vollsynchronisation oder manuelles Löschen), bereinigt es die zugehörigen Medienanhänge und Metadaten über einen zentralen Löschpfad.

REST-Cron-Endpunkt

Der mit einem Token gesicherte Trigger-Endpunkt wird durch Cron_Endpoint registriert:

• Route: GET /wp-json/as24ci/v1/cron-import
• Authentifizierung: Ein zufälliges, 32 Zeichen langes 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 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 kopierfertige 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 hält die Nicht-Import-WP-Cron-Hooks (Bildwarteschlange, Analysebereinigung, Preisgestaltung usw.) am Laufen, wenn DISABLE_WP_CRON auf true gesetzt ist.

Betriebsüberwachung

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

• Tab "System & Hilfe / Zustand". 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 Karte, 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 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.

Eine einfache Live-Einrichtung umfasst:

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

---

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 wenig Traffic den Cron möglicherweise überhaupt nicht aus – wechseln Sie zum 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 Transient as24ci_cron_import_running, wenn ein vorheriger PHP-Prozess abgestürzt ist, ohne die Sperre freizugeben. Verringern Sie die Fahrzeuge pro Durchlauf, um die einzelnen Durchläufe deutlich unter der Lock-TTL zu halten.
• Die Bildwarteschlange wächst, ohne kleiner zu werden. Bestätigen Sie, 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 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 regenerieren. 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