Caches vorwärmen: eine Site aufwärmen, bevor Besucher kommen #

Diese Anleitung erklärt das Vorladen von Caches in Exponential: Setup > Vorladen (/setup/preload) und den Befehl php bin/php/preload.php --apply. Beide sind derselbe Lauf. Er ruft die Seiten einer Site so ab, wie es ein anonymer Besucher täte, damit die Caches warm sind, bevor der erste Besucher kommt, und er listet die defekten Links mit den Seiten auf, die auf sie verweisen.

Sie richtet sich an Administratoren und Betreiber. Jede Seite, jedes Feld, jede Option und jede Datei unten wurde am 6. Oktober 2026 am Code dieses Repositorys geprüft; die Dateien sind unter Quellen genannt.

Anleitungen · Siehe auch: Betrieb einer Site · Cronjobs · Bereitstellung · Vorladen des Site-Caches (Upgrade-Hinweise)

Kurz gesagt #

• Ein Lauf beginnt bei den Bereichsseiten einer Site (ihrer Wurzel und den Bereichen aus site.ini [SiteSettings] URLTranslationKeyword) und folgt dann den Links der Site, bis zu einem Seitenlimit und einer Link-Tiefe.
• Er wärmt vor, was das Rendern einer Seite erzeugt: den Seitenansichts-Cache, die Bildvarianten, die die Seite zeigt, und die kompilierten Templates. Das sind Dateien der Installation, die Apache mit PHP-FPM und Exponential Velocity gemeinsam nutzen.
• Immer nur ein Lauf. Ein Lauf hält eine Sperre, solange er läuft, ob er von der Seite, der Shell oder per Cron gestartet wurde. Ein zweiter wird abgewiesen und sagt das.
• Von der Seite aus läuft ein Lauf nie innerhalb der Web-Anfrage: Er wird im Hintergrund gestartet, und die Seite verfolgt ihn.
• Jeder Lauf wird protokolliert: Dauer, vorgewärmte Seiten, erzeugte Bildvarianten, defekte Links mit ihren Adressen, Statuscodes und den Seiten, die auf sie verweisen. Die Seite listet die letzten Läufe auf, gleich ob sie von der Seite, aus der Shell oder per Cron kamen.
• Ein Probelauf zeigt die Adresse, die Startseiten und die Grenzen und ruft nichts ab.

1. Die Seite #

Öffnen Sie Setup > Seiten vorladen (/setup/preload). Die Seite enthält von oben nach unten:

Die Seite funktioniert ohne JavaScript: Starten, Probelauf und Anhalten senden das Formular, und Aktualisieren zeigt, wie ein Lauf steht. Mit JavaScript verfolgt die Seite einen Lauf von selbst, einmal pro Sekunde, und Sie können sie verlassen und zurückkehren: Ein laufender Lauf wird wieder aufgegriffen, wenn die Seite geöffnet wird.

Das Formular #

Nur ein Siteaccess, den die Installation ausliefert, kann gewählt werden, und die Grenzen sind ganze Zahlen innerhalb ihres Bereichs; sonst gelangt nichts aus dem Formular in eine Kommandozeile. Der Befehl wird mit einer Argumentliste gestartet, nie über eine Shell.

2. Was ein Lauf vorwärmt, und auf welchem Server #

Ein Lauf ruft jede Seite unter der Adresse der Site ab: SiteURL des Siteaccess, mit dem Präfix, das auf diesem Host den Siteaccess auswählt (Abschnitt 4). Der Server, der diese Adresse beantwortet, rendert die Seite: auf dem Demonstrationsserver Apache mit PHP-FPM.

• Der Seitenansichts-Cache (var/<var dir>/cache/content), die Bildvarianten (var/<var dir>/storage/images) und die kompilierten Templates sind Dateien der Installation. Apache/PHP-FPM und Velocity nutzen sie gemeinsam, daher wärmt ein Lauf sie für beide vor, gleich welcher Server antwortet.
• Exponential Velocity hat einen eigenen Antwort-Cache vor seinen Workern. Er behält eine anonyme Seite velocity.ini [CacheSettings] DefaultTtl Sekunden lang (standardmäßig 30), daher hält ein Vorwärmen vor den Besuchern nicht an. Die Seite sagt, wenn Velocity läuft und wie lange sein Cache eine Seite behält.
• Seiten für angemeldete Benutzer werden nicht vorgewärmt: Der Lauf ist ein anonymer Besucher.
• Nur das eigene Markup der Seite wird gelesen: Links und Bilder innerhalb von <script>, <template>, <style> oder Kommentaren sowie Werte, die ein Anführungszeichen, einen JavaScript- oder Template-Ausdruck oder Leerraum enthalten, sind keine Adressen und werden übersprungen.
• Anfragen an Adressen außerhalb der Site werden nie gestellt: Links zu einem anderen Host oder zu einem anderen Siteaccess auf demselben Host werden nicht verfolgt, ebenso wenig Modul-Views (/content/edit, /setup, /user/login ...), das eigene Panel von Velocity (/Q/...) oder Dateien (Bilder, Skripte, Dokumente).

Erzeugte Bildvarianten ist die Zahl der Bilddateien, die während des Laufs im Speicher erschienen sind: die Varianten, die die gerenderten Seiten erzeugt haben. Sie wird auf der Festplatte gezählt, daher wird sie bei einem geclusterten Datei-Handler (file.ini [ClusteringSettings] FileHandler anders als eZFSFileHandler oder eZFS2FileHandler) als nicht gezählt angezeigt. Eine Site, die bereits warm war, erzeugt keine.

3. Aus der Shell und per Cron #

# what a run would do, without requesting anything
php bin/php/preload.php --siteaccess=site --dry-run

# warm the site of the siteaccess "site"
php bin/php/preload.php --apply --siteaccess=site

# a small run: the starting pages and the pages they link to, at most 20
php bin/php/preload.php --apply --siteaccess=site --max-pages=20 --max-depth=1

# with the image check
php bin/php/preload.php --apply --siteaccess=site --images

Der Befehl gibt jede Seite aus, während sie abgerufen wird, und am Ende die defekten Links. Seine letzten drei Zeilen sagen, was der Lauf getan hat, für ein Protokoll, das nur sein Ende behält:

Preload finished in 182.4s: run 1c9f49b30d7a51ac, listed in Setup > Preload.
Pages warmed 167, broken 0, denied 0, skipped 3.
Image aliases made 480.

Exit-Codes: 0, wenn der Lauf beendet oder angehalten wurde (defekte Links sind ein Befund, kein Fehler), 1, wenn er fehlgeschlagen ist (keine SiteURL, ein unbekannter Siteaccess, ein Fehler), 2, wenn bereits ein anderes Vorladen lief und dieses nicht gestartet wurde.

Für Cron, zum Beispiel nach dem nächtlichen Leeren der Caches:

30 4 * * * cd /path/to/exponential && php bin/php/preload.php --apply --siteaccess=site -q

Die Seite zeigt diese Zeile für die Auswahl in ihrem Formular. Der Befehl braucht die PHP-Kommandozeile und die curl-Extension; er braucht weder wget noch das Programm curl mehr und schreibt nichts nach /tmp.

4. Die Adresse eines Siteaccess #

Ein Lauf muss den gewählten Siteaccess erreichen, nicht nur dessen Host. Die Adresse wird allein aus site.ini ermittelt, so wie eine Anfrage zugeordnet wird (expPreloadAddress):

1. Die Basis ist SiteURL des Siteaccess (seine eigene settings/siteaccess/<name>/site.ini.append.php, sonst die globale), mit vorangestelltem https://, wenn sie kein Schema hat.
2. Zuerst wird die Adresse ohne Präfix versucht. Dann jedes Präfix, das die Zuordnung anbietet: /<name> für URIMatchType=element, die URI eines Eintrags URIMatchMapItems[] für URIMatchType=map, die URI eines Eintrags HostUriMatchMapItems[].
3. Jede Adresse wird so zugeordnet, wie es eine Anfrage würde: der Reihe nach die Methoden aus [SiteAccessSettings] MatchOrder, dann DefaultAccess. Die erste Adresse, die den Siteaccess erreicht, wird verwendet.

Einträge der Host-Zuordnung werden mit ihrem optionalen dritten Feld gelesen, HostMatchMapItems[]=host;siteaccess;method, wobei die Methode strict, start, end oder part ist, und HostMatchMethod (standardmäßig strict) gilt für einen Eintrag ohne Methode. So schickt example.com;site;start einen Testhost example.com.test.local für das Vorladen genauso zu site wie für einen Besucher.

Erreicht keine Adresse den Siteaccess, verwendet der Lauf wie bisher /<name> (wenn uri in MatchOrder steht), und der Probelauf und die Ausgabe warnen, dass die vorgewärmten Seiten die eines anderen Siteaccess sein können. Prüfen Sie die SiteURL und die Zuordnungseinstellungen dieses Siteaccess.

Eine SiteURL, die bereits auf das Präfix endet (demo.example/site), erhält es nicht noch einmal. Die Site, in der ein Lauf bleibt, ist alles unterhalb des Pfads von SiteURL plus Präfix (dort /site/..., /bold/... für ein URI-Präfix, der ganze Host außer den Präfixen anderer Siteaccesses für eine über den Host zugeordnete Site); Links zu /admin/... und zu anderen Siteaccesses werden nicht verfolgt.

Die Bereichsseiten aus Phase 1 sind die Wurzel, die Bereiche aus URLTranslationKeyword und die Seiten der obersten Ebene, auf die die Startseiten verweisen (/site/fitness, /fitness).

5. Läufe, die Sperre und die Dateien #

Läufe werden in var/<var dir>/preload/ aufbewahrt:

Die letzten 20 Läufe werden aufbewahrt; ein laufender Lauf wird nie entfernt. Die Sperre hängt am Prozess: Ein Lauf, der abstürzt, hinterlässt keine Sperre, und nichts muss von Hand entfernt werden. Ein Lauf, dessen Prozess verschwunden ist, wird als Ohne Abschluss beendet aufgeführt, und einer, dessen Prozess nie gestartet ist, nach einer Minute als Fehlgeschlagen.

Zustände: Startet, Läuft, Abgeschlossen, Angehalten (von der Seite aus), Fehlgeschlagen (mit dem Grund) und Ohne Abschluss beendet.

6. Zugriff #

Geben Sie einer Rolle die Richtlinie setup / preload. Die Views sind setup/preload (die Seite), setup/preloadjob (das JSON, das die Seite liest: Fortschritt und Status eines Laufs, die Liste der Läufe sowie Start, Anhalten und Probelauf für Skripte) und setup/preloadstream (der ältere Fortschrittsdatenstrom, beibehalten; er startet nichts). Jedes POST trägt das Formular-Token.

setup/preloadjob antwortet:

7. Wenn sich etwas nicht wie erwartet verhält #

Quellen #

• kernel/classes/exppreloadjob.php (expPreloadJob): das Starten eines Laufs im Hintergrund, der Lauf selbst (execute()), der Probelauf (plan()), die angebotenen Sites, die Zählung der Bildvarianten, die Server.
• kernel/classes/exppreloadaddress.php (expPreloadAddress): Adresse und Präfix eines Siteaccess, die Zuordnung, die Startseiten.
• kernel/classes/exppreloadlock.php (expPreloadLock), kernel/classes/exppreloadhistory.php (expPreloadHistory): die Sperre und die Läufe.
• kernel/setup/exppreloadrunner.php (expPreloadRunner): der Crawler, den auch der Generator des statischen Caches verwendet.
• kernel/private/classes/views/setup/preload.php, preloadjob.php, preloadstream.php: die Views.
• kernel/private/classes/commands/preload.php, preloadjob.php: bin/php/preload.php und der Lauf im Hintergrund.
• design/admin/templates/setup/preload.tpl und stylesheets/modules/setup.css (und dasselbe in design/admin4).
• Tests: tests/tests/kernel/classes/preload/ (keine Datenbank), expPreloadRunnerLinksTest, ExpPreloadStartUrlsTest.