Dokumentation · Integrationshandbuch

Einrichtung des Server-Cronjobs

Dieses Dokument erklärt, warum ein echter Server-Cronjob die empfohlene Methode ist, um Importe für das ADP Car Market Hub-Plugin in der Produktionsumgebung auszuführen, wie dies mit dem integrierten WP-Cron-Scheduler zusammenhängt und welche betrieblichen Prüfungen eingerichtet werden sollten, sobald er läuft.

Wann Sie dieses Dokument verwenden sollten

Verwenden Sie dieses Dokument, wenn Sie:

Eine Produktionsbereitstellung vorbereiten und entscheiden, wie geplante Importe ausgelöst werden sollen.
Von WP-Cron auf einen serverseitigen Cronjob migrieren, weil Importe auf einer Website mit wenig Traffic unzuverlässig sind.
Einen Host betreiben, der aus Leistungsgründen DISABLE_WP_CRON empfiehlt oder erfordert.
Überprüfen, warum Importe verspätet starten, nur zu Spitzenzeiten ausgeführt werden oder überhaupt nicht starten.

Die Zielgruppe ist ein WordPress-Administrator mit Zugriff auf die Cron-Einrichtung des Servers (beispielsweise über cPanel, Plesk, das Hosting-Control-Panel oder Shell-Zugriff auf eine Linux-Crontab).

Übersicht

WordPress wird mit einem integrierten Scheduler namens WP-Cron ausgeliefert. WP-Cron läuft nicht kontinuierlich im Hintergrund – es wird überprüft, wenn jemand eine Seite auf der Website aufruft. Auf einer stark besuchten Website ist dies normalerweise in Ordnung, hat jedoch einige bekannte Einschränkungen:

Auf einer Website mit wenig Traffic werden geplante Aufgaben verspätet oder überhaupt nicht ausgeführt, da kein Besucher WP-Cron auslöst.
WP-Cron läuft innerhalb einer normalen HTTP-Anfrage, sodass es sich das PHP-Memory-Limit und die Ausführungszeit der Anfrage teilt.
Mehrere Besucher, die gleichzeitig eintreffen, können um die Ausführung derselben geplanten Aufgabe konkurrieren, was verschwenderisch ist, selbst wenn das Plugin intern vor Doppelstarts schützt.

Aus diesen Gründen ist die empfohlene Produktionskonfiguration, WP-Cron zu deaktivieren und es über einen echten Server-Cronjob auszulösen. Das Plugin bietet speziell für diesen Zweck einen dedizierten, durch ein Token gesicherten REST-Endpunkt, sodass der Cronjob einen Import direkt auslöst, ohne von einem Besucher abhängig zu sein.

Das Plugin bietet zwei Cron-Modi, die Sie unter Car Market Hub → Import & Limits (auf der Automatisierungs-Karte) auswählen können:

WP-Cron-Modus (Standard). Der WP-Cron-Zeitplan des Plugins (stündlich, alle 6 Stunden, zweimal täglich, täglich oder benutzerdefiniert mit einem Minimum von 15 Minuten) steuert die Importe. Geeignet für Entwicklung, Evaluierung und kleine Websites mit regelmässigem Traffic.
Server-Cron-Modus. Der WP-Cron-Zeitplan ist deaktiviert und der Import wird durch einen Server-Cronjob ausgelöst, der den REST-Endpunkt des Plugins aufruft. Empfohlen für die Produktion.

In beiden Modi wird die eigentliche Importarbeit vom selben gemeinsamen Runner innerhalb des Plugins ausgeführt – der einzige Unterschied besteht darin, was ihn auslöst.

Warum Server-Cron in der Produktion empfohlen wird

Zuverlässiges Timing. Ein Server-Cronjob läuft nach einem festen Zeitplan, unabhängig davon, ob in diesem Moment jemand die Website besucht.
Keine Beeinträchtigung der Ladezeit. Importe verlangsamen den Seitenaufbau eines echten Besuchers nicht, da sie in ihrem eigenen PHP-Prozess laufen.
Vorhersehbarer Ressourcenverbrauch. Ein Server-Cronjob läuft einmal pro geplantem Zeitpunkt, anstatt opportunistisch von jedem Besucher angestossen zu werden.
Einfachere Überwachung. Cron-Läufe hinterlassen einen klaren Audit-Trail (in den Protokollen des Cron-Dienstes und in den Protokollen des Plugins) und können mit externen Uptime-Prüfungen kombiniert werden.
Kompatibel mit Hosts, die WP-Cron drosseln oder deaktivieren. Einige Managed-Hosts schränken ein, wie oft wp-cron.php intern ausgeführt wird; ein externer Trigger umgeht dies.

Der Server-Cron lässt sich auch gut mit der Bildwarteschlange des Plugins kombinieren: Ein zweiter Cronjob, der wp-cron.php in kurzem Intervall aufruft, sorgt dafür, dass die normale Aufgabenwarteschlange von WordPress (einschliesslich der Bildverarbeitung) in einem vorhersehbaren Rhythmus läuft.

Voraussetzungen

Bestätigen Sie vor dem Wechsel zum Server-Cron Folgendes:

Das Plugin ist installiert, aktiviert und die API-Verbindung funktioniert. Siehe Einrichtung der API-Zugangsdaten und Verbindungstest.
Die Hosting-Umgebung bietet Zugriff auf die Cron-Einrichtung des Servers (cPanel-Cronjobs, geplante Aufgaben in Plesk, Hosting-Control-Panel-Cron oder eine Linux-Crontab über SSH).
Die Website kann vom Cronjob über HTTPS erreicht werden. Bei den meisten Hosts läuft der Cron-Befehl auf demselben Server und kann curl verwenden, um die Website aufzurufen.
Sie können wp-config.php bearbeiten (dies ist erforderlich, um DISABLE_WP_CRON zu setzen).
Die allgemeinen Anforderungen an das Hosting und an Cron und Hintergrundverarbeitung sind erfüllt.

Schritt-für-Schritt-Anleitung

Die Automatisierungs-Karte des Plugins zeigt die genaue REST-Trigger-URL und Beispielbefehle für die aktuelle Installation an. Verwenden Sie diese Werte, anstatt URLs aus der Dokumentation zu kopieren.

Wechseln Sie das Plugin in den Server-Cron-Modus. Öffnen Sie Car Market Hub → Import & Limits. Wählen Sie auf der Cron-Modus-Karte Server-Cron und speichern Sie. Das Plugin blendet die WP-Cron-Zeitplansteuerungen aus und zeigt eine Karte Server-Cron-Einrichtung mit der REST-Trigger-URL, dem geheimen Token und Beispielbefehlen an.
Deaktivieren Sie den integrierten Cron von WordPress. Fügen Sie die folgende Zeile in wp-config.php ein, irgendwo oberhalb des Kommentars /* That's all, stop editing! */:

   define( 'DISABLE_WP_CRON', true );

Ohne diese Zeile versuchen sowohl WP-Cron als auch der Server-Cronjob, Importe zu planen, was verschwenderisch ist, selbst wenn die interne Sperre des Plugins Doppelstarts verhindert.

Kopieren Sie die REST-Trigger-URL. Die Karte für die Server-Cron-Einrichtung zeigt die URL in der Form https://<your-site>/wp-json/as24ci/v1/cron-import?token=<secret> an. Verwenden Sie die Schaltfläche Kopieren, damit die URL wortgetreu kopiert wird. Behandeln Sie das Token als Geheimnis – jeder, der es besitzt, kann einen Import auslösen.
Fügen Sie den Import-Cronjob hinzu. Erstellen Sie in der Cron-Einrichtung Ihres Servers einen Job, der die Trigger-URL im gewünschten Rhythmus aufruft. Das Plugin füllt ein Beispiel vor wie:

   */15 * * * * curl -s "https://<your-site>/wp-json/as24ci/v1/cron-import?token=<secret>" > /dev/null

Passen Sie den Zeitplanausdruck (*/15 * * * * bedeutet alle 15 Minuten) an die Bedürfnisse der Garage an. Importe überspringen unveränderte Fahrzeuge dank der Änderungserkennung, sodass häufige Durchläufe in der Regel ressourcenschonend sind.

Fügen Sie einen zweiten Cronjob hinzu, um die Aufgabenwarteschlange von WordPress am Laufen zu halten. Da DISABLE_WP_CRON auch die Warteschlange deaktiviert, die vom Bild-Worker des Plugins und von anderen WordPress-Funktionen verwendet wird, fügen Sie einen zweiten Cronjob hinzu, der wp-cron.php direkt in einem kurzen Intervall ausführt. Das Beispiel des Plugins verwendet den absoluten Pfad der WordPress-Installation:

   */5 * * * * php /path/to/wordpress/wp-cron.php > /dev/null 2>&1

Der Pfad wird auf der Automatisierungs-Karte basierend auf der aktuellen WordPress-Installation angezeigt. Ersetzen Sie ihn durch den dort angezeigten Wert.

Überprüfen Sie dies mit einem manuellen Durchlauf. Rufen Sie von einer Workstation aus die REST-Trigger-URL einmal mit curl auf (oder fügen Sie sie in einen Browser ein). Ein erfolgreicher Durchlauf gibt eine JSON-Antwort zurück, die das Importergebnis beschreibt. Ein 403-Fehler mit "Invalid or missing token" bedeutet, dass die URL falsch kopiert wurde.
Überprüfen Sie den nächsten geplanten Durchlauf. Warten Sie auf den nächsten geplanten Cron-Takt, öffnen Sie dann Car Market Hub → System & Hilfe und bestätigen Sie, dass Letzter externer Cron-Lauf einen aktuellen Zeitstempel anzeigt.

Für eine alternative Authentifizierungsmethode, die das Token aus der URL (und somit aus den Zugriffsprotokollen und Prozesslisten) heraushält, akzeptiert der Endpunkt auch einen Authorization: Bearer <token>-Header. Zum Beispiel:

*/15 * * * * curl -s -H "Authorization: Bearer <secret>" "https://<your-site>/wp-json/as24ci/v1/cron-import" > /dev/null

Beide Methoden sind gleichwertig; die Header-Methode wird bevorzugt, wenn die Cron-Umgebung benutzerdefinierte Header unterstützt.

Konfigurationsreferenz

Die Einstellungen, die den Server-Cron-Modus betreffen, befinden sich unter Car Market Hub → Import & Limits (Automatisierungs-Karte).

Einstellung	Zweck
Cron-Modus	Wechselt zwischen WP-Cron und Server-Cron. Im Server-Cron-Modus ist der WP-Cron-Zeitplan deaktiviert und die Karte für die Server-Cron-Einrichtung wird angezeigt.
REST-Trigger-URL	Die vollständige URL, die der Server-Cronjob aufrufen soll. Enthält das geheime Token als Query-Parameter. Generiert aus der aktuellen Website-URL und dem gespeicherten Token.
Geheimes Token	Ein zufälliges Token mit 32 Zeichen, das den REST-Trigger authentifiziert. Wird bei der ersten Verwendung automatisch generiert. Verwenden Sie die Schaltfläche Token neu generieren, um ein neues auszustellen (der bestehende Cronjob muss dann mit der neuen URL aktualisiert werden).
Beispiel-Cron-Befehle	Vorausgefüllte Beispielbefehle unter Verwendung der aktuellen Trigger-URL und des absoluten Pfads zu `wp-cron.php`. Verwenden Sie die Schaltflächen Kopieren, um sie wortgetreu zu kopieren.
Max. Fahrzeuge pro Cron-Lauf	Begrenzt, wie viele Fahrzeuge ein einzelner Importlauf verarbeitet. `0` bedeutet unbegrenzt. Nützlich als Sicherheitsgrenze auf Shared-Hosts.
Bildwarteschlangen-Modus	Wenn aktiviert, laden geplante Importe sofort nur das erste Bild pro Fahrzeug herunter und reihen den Rest für die asynchrone Verarbeitung in die Warteschlange ein. Empfohlen in der Produktion.

Betriebliche Hinweise

Nur ein Scheduler gleichzeitig. Führen Sie den WP-Cron- und den Server-Cron-Modus nicht parallel aus. Das Wechseln zu Server-Cron im Plugin deaktiviert den WP-Cron-Zeitplan; das Hinzufügen von DISABLE_WP_CRON zu wp-config.php vervollständigt das Bild, indem verhindert wird, dass WordPress seine Cron-Warteschlange über Frontend-Anfragen ausführt.
Der gemeinsame Runner. Der REST-Endpunkt, der WP-Cron-Hook und die Admin-Schaltfläche Jetzt auslösen delegieren alle an denselben Import-Runner innerhalb des Plugins. Es gibt keinen separaten "Server-Cron-Importpfad" mit anderem Verhalten.
Sicherheit bei Gleichzeitigkeit. Der Runner verwendet eine interne, auf Transients basierende Sperre, um zu verhindern, dass zwei Importe gleichzeitig ausgeführt werden. Selbst wenn sich ein Cronjob überschneidet, wird der zweite Durchlauf abgebrochen.
Vertraulichkeit des Tokens. Das Cron-Token berechtigt zum Auslösen eines Imports. Behandeln Sie es als Geheimnis. Vermeiden Sie es, vollständige Trigger-URLs in Screenshots oder Tickets einzufügen; zensieren Sie den Teil token=..., bevor Sie ihn teilen.
Token-Rotation. Verwenden Sie Token neu generieren, wann immer Sie vermuten, dass das Token offengelegt wurde, oder im Rahmen einer regelmässigen Rotation. Aktualisieren Sie nach der Neugenerierung jeden Cronjob, der die URL verwendet – die vorherige URL wird abgewiesen.
Speicherort des Endpunkts. Der REST-Endpunkt ist die standardmässige WordPress-REST-URL …/wp-json/as24ci/v1/cron-import. Wenn sich die WordPress-Website-URL ändert (HTTPS-Migration, Domainänderung, Verschiebung bei einer Multi-Site), aktualisieren Sie den Cronjob entsprechend.
Externer Heartbeat. Jede Anfrage an die Website, die ?as24ci_cron=1 enthält, zeichnet einen Zeitstempel auf, den die Registerkarte "System & Hilfe" verwendet, um zu bestätigen, dass ein externer Scheduler aktiv ist. Dies dient rein der Information und löst an sich keinen Import aus.
Begleitjob für die Bildwarteschlange. Wenn Bilder während geplanter Importe in die Warteschlange eingereiht werden, wird die Warteschlange durch die WordPress-Aufgabenwarteschlange verarbeitet. Wenn Sie WP-Cron deaktiviert haben, sorgt der zweite Cronjob, der wp-cron.php aufruft, dafür, dass diese Warteschlange in Bewegung bleibt.
Verlassen Sie sich nicht auf browserbasiertes Testen. Das Einfügen der Trigger-URL in einen Browser funktioniert zur Überprüfung, sollte aber nicht als eigentlicher Trigger verwendet werden – das würde voraussetzen, dass jemand einen Browser geöffnet hält.

Betriebliche Prüfungen nach der Einrichtung

Gehen Sie diese Prüfungen einmal nach dem Wechsel in den Server-Cron-Modus und erneut nach jeder grösseren Änderung (Host-Migration, URL-Änderung, Token-Neugenerierung) durch:

Cron-Dienst ist aktiviert. Bestätigen Sie, dass die Cron-Einrichtung des Hosts aktiv ist und dass das Benutzerkonto, das den Job ausführt, die Berechtigung zur Ausführung des Befehls hat.
Geplanter Befehl ist korrekt. Der Zeitplanausdruck entspricht der gewünschten Häufigkeit, die URL entspricht dem auf der Automatisierungs-Karte angezeigten Wert und der zweite Job, der wp-cron.php aufruft, existiert.
DISABLE_WP_CRON ist definiert. Die Registerkarte "System & Hilfe" bestätigt, dass die Konstante gesetzt ist, wenn Sie sich im Server-Cron-Modus befinden.
Letzter externer Cron-Lauf ist aktuell. Die Registerkarte "System & Hilfe" zeigt einen Zeitstempel für den Letzten externen Cron-Lauf innerhalb des erwarteten Intervalls an.
Letzter Importlauf ist aktuell. Das Dashboard-Widget und die Registerkarte "System & Hilfe" zeigen aktuelle Aktivitäten des Importers an.
Protokolle zeigen keine wiederholten Authentifizierungsfehler. Ein Muster von 403-Antworten in den Protokollen bedeutet, dass der Cronjob ein veraltetes oder falsches Token verwendet.
Bildwarteschlange wird abgearbeitet. Die Registerkarte "Import & Limits" zeigt an, dass die Bildwarteschlange verarbeitet wird (oder leer ist).
Optionaler externer Monitor. Konfigurieren Sie einen Uptime-Monitor oder einen Alarm auf Hosting-Ebene, der Sie benachrichtigt, wenn der Importjob nicht mehr ausgeführt wird.

Überprüfen Sie diese Punkte anhand der aktuellen Plugin-Version, bevor Sie Anweisungen für Kunden veröffentlichen, da sich die UI-Labels zwischen den Versionen ändern können.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Was zu prüfen ist
Der Cron-Job läuft, aber die Antwort ist 403 mit "Invalid or missing token".	Das Token in der URL ist falsch, enthält Leerzeichen oder wurde nach der Erstellung des Cron-Jobs neu generiert.	Kopieren Sie die URL erneut aus der Automatisierungskarte und aktualisieren Sie den Cron-Befehl.
Der Cron-Job läuft, aber die Antwort ist 403 mit "Cron token not configured".	Das Token wurde noch nicht generiert.	Öffnen Sie die Automatisierungskarte, um automatisch ein Token zu generieren, und kopieren Sie dann die neue URL.
Der Cron-Job läuft erfolgreich, aber der Tab "System & Hilfe" zeigt immer noch keinen aktuellen externen Lauf an.	Der Cron-Dienst ruft einen anderen Host auf (zum Beispiel HTTP statt HTTPS, oder `www.` gegenüber dem kanonischen Hostnamen) und die Anfrage wird von WordPress wegeleitet.	Verwenden Sie die genaue URL, die auf der Automatisierungskarte angezeigt wird. Bestätigen Sie, dass der Cron-Dienst des Hosts die Website über HTTPS erreichen kann.
Importe laufen, aber Bildanhänge werden nicht mehr angezeigt.	`DISABLE_WP_CRON` ist aktiviert, aber kein Cron-Job ruft `wp-cron.php` auf, sodass der Bild-Warteschlangen-Worker nie ausgeführt wird.	Fügen Sie den zweiten Cron-Job für `wp-cron.php` wie oben beschrieben hinzu.
Importe laufen zu lange oder stossen an ein Speicherlimit.	Die PHP-CLI-Limits des Hosts sind strenger als erwartet.	Reduzieren Sie Max. Fahrzeuge pro Cron-Lauf, lassen Sie den Bild-Warteschlangenmodus aktiviert und lesen Sie Cron und Hintergrundverarbeitung.
Importe laufen zweimal kurz nacheinander ab.	Sowohl der WP-Cron-Modus als auch ein Server-Cron-Job sind aktiv.	Schalten Sie das Plugin in den Server-Cron-Modus und fügen Sie `DISABLE_WP_CRON` zu `wp-config.php` hinzu.
Der Cron-Job läuft, gibt aber immer "Another import is already running" zurück.	Ein vorheriger Lauf wurde nicht beendet (lang laufender Batch, hostseitiges Timeout). Die temporäre Sperre (Transient Lock) ist noch nicht abgelaufen.	Warten Sie, bis die Sperre abläuft, und untersuchen Sie dann den vorherigen Lauf über die Plugin-Protokolle. Siehe Cron-Fehler.