Statisches Veröffentlichen #

Diese Seite ist für Administratoren und Entwickler, die eine öffentliche Kopie einer Exponential-Website möchten, die jeder statische Host ausliefern kann: GitHub Pages, die Pages eines anderen Git-Hosts oder ein einfacher Webserver ganz ohne PHP. Statisches Veröffentlichen macht aus einem Front-Siteaccess einen Ordner mit HTML-Seiten und Dateien, in dem jeder Link umgeschrieben ist, sodass der Ordner für sich allein funktioniert, an der Wurzel einer Domain oder unterhalb eines Pfads wie /meine-site/. Redakteure arbeiten weiter in Exponential; die öffentliche Website ist eine Kopie.

Es ist neu in Exponential 6.0.15. Diese Seite beschreibt die Build-Engine, das Veröffentlichen nach Git, ihre Befehle und die Seiten unter Setup > Statisches Veröffentlichen. Die Einrichtung bei GitHub kommt hinzu, sobald sie erscheint.

Funktionen von 6.0 · Verwandt: Generator für den statischen Cache, Statische Websites auf GitHub Pages hosten mit Exponential 6.0.15+, Das Build-Format

Was Sie bekommen #

• Ziele in staticcache.ini: Jeder Block [Target_<id>] nennt einen Front-Siteaccess, oder mehrere, die sich über ihr URI-Präfix einen Host teilen (SiteAccessList[], eine Kopie mit dem DefaultSiteAccess im Stamm und den anderen in ihren Ordnern: Statisches Veröffentlichen für Multisite-Installationen), wie seine Links geschrieben werden und wohin die Kopie gehen soll. Eine Installation kann viele Ziele haben.
• exp:static:build <ziel>: durchläuft den Siteaccess als anonymer Benutzer, nimmt heraus, was eine öffentliche Kopie nicht tragen darf, schreibt die Links um, kopiert die Dateien, die die Seiten brauchen, und schreibt die Zusatzdateien, die ein statischer Host erwartet.
• exp:static:serve <ziel>: eine lokale Vorschau des Builds, unterhalb des Basispfads des Ziels ausgeliefert, so wie GitHub Pages eine Projekt-Website ausliefert.
• exp:static:diff <ziel>: was der letzte Build geändert hat, ob der Ordner noch zu ihm passt, und eine Linkprüfung jeder Seite und Datei.
• exp:static:targets: jedes Ziel mit geprüften Einstellungen.
• exp:static:publish <ziel>: committet den Build im eigenen Git-Repository des Ziels, taggt ihn static/<ziel>/<n> und pusht ihn, nie erzwungen, angemeldet mit einem Token oder einem SSH-Deploy-Key, die nie auf eine Befehlszeile oder in ein Log gelangen. Dazu gehören exp:static:rollback, exp:static:push, exp:static:keys und exp:static:status.

Wie ein Build abläuft #

1. Als anonymer Benutzer durchlaufen. Der Build nutzt den Crawler des Generators für den statischen Cache in einem Exportmodus. Er sendet kein Cookie, also ist jede Seite das, was ein nicht angemeldeter Besucher sieht. Er beginnt auf der Startseite, folgt nur den Links, die die Website selbst schreibt, und lässt Modulansichten wie die Suche, die Anmeldung und die Bearbeitungsseiten aus. Ein Ziel kann von einer internen Adresse (CrawlURL) statt von der öffentlichen SiteURL abrufen.
2. Herausnehmen, was nicht öffentlich sein darf. Jede Seite verliert ihre Debug-Ausgabe, Formular-Token (ezxform_token-Felder und die csrf-token-Tags), Sitzungskennungen in Adressen und Nonces der Content Security Policy.
3. Ablehnen, was sich nicht bereinigen lässt. Eine Seite, deren Antwort ein Sitzungs-Cookie gesetzt hat oder die noch Debug-Ausgabe oder ein Formular-Token trägt, wird abgelehnt. Der Build schlägt dann fehl, und der Ordner des Ziels bleibt unverändert. Seiten, die es nur mit einem Query-String gibt (/blog?page=2), und Pfade, die nicht auf jedem System ein Dateiname sein können, werden übersprungen und gemeldet.
4. Die Dateien sammeln. Jede Datei, die die Seiten und ihre Stylesheets nennen, wird kopiert: Stylesheets, Skripte, Schriften und Bilder der Designs, die gepackten Dateien in var/<site>/cache/public, Bild-Aliase und Downloads. Dateien, die der Webserver direkt ausliefert, werden aus der Installation gelesen (var/ über den Cluster-Dateihandler, sodass auch die Dateien eines Clusters gefunden werden). Alles andere wird bei der Website abgerufen, wie es ein Besucher täte: ein Download, ein Bild-Alias, der noch nicht erzeugt wurde (die Anfrage erzeugt ihn), eine gepackte Datei, die noch nicht geschrieben wurde. Mit Assets=referenced-and-storage wird zusätzlich jedes Bild in var/<site>/storage/images kopiert, das zur veröffentlichten Version von Inhalten gehört, die der anonyme Benutzer lesen darf, ob eine Seite darauf verlinkt oder nicht.
5. Die Links umschreiben. Siehe Links unten.
6. Die Zusatzdateien und das Manifest schreiben. .nojekyll, CNAME, 404.html, robots.txt und sitemap.xml, wie das Ziel es verlangt, und .static-publish/manifest.json, das jede Datei mit SHA-256, Größe und, bei einer Seite, ihrem Knoten und dem Zeitpunkt der letzten Änderung ihres Inhalts aufführt.
7. Vergleichen, prüfen und ersetzen. Der Build entsteht zuerst in einem Staging-Ordner. Er wird mit dem Ordner des Ziels verglichen (der Diff), und seine Links werden geprüft. Ist es kein Probelauf, ersetzt er dann den Inhalt des Ordners: neue und geänderte Dateien werden kopiert, Dateien, die das letzte Manifest aufführte und dieses nicht, werden entfernt, und sonst wird im Ordner nichts angefasst. Ein .git-Ordner oder eine README, die Sie hinzugefügt haben, bleibt.

Ein Build der Demo-Website, 560 Seiten und 3.547 Dateien (485 MB, das meiste Speicherbilder), dauerte auf einer Kopie ihrer Installation rund drei Minuten; den größten Teil braucht das Durchlaufen, das jede Seite einmal rendert. Die Linkprüfung dieses Builds fand unter 18.534 Links und Dateien keinen defekten, an der Wurzel und unterhalb von /<repository>/.

Links #

Relative Links funktionieren überall, wo der Ordner ausgeliefert wird, unter / und unterhalb jedes Pfads. Links=base-path schreibt jeden Link unterhalb von BasePath, wie es eine Website braucht, die immer an einer Stelle ausgeliefert wird. 404.html verlinkt immer unterhalb von BasePath: GitHub Pages liefert sie für jede fehlende Adresse in jeder Tiefe aus, wo relative Links an die falsche Stelle zeigen würden.

Das Siteaccess-Präfix (/site/about-us bei einer per URI zugeordneten Website) und index.php werden aus jeder Seitenadresse entfernt. Adressen in Skripten (außer strukturierten Daten) und Kommentaren bleiben unverändert.

Einstellungen #

Alle Einstellungen stehen in staticcache.ini, neben [CacheSettings] des statischen Caches. Tragen Sie Ihre in settings/override/staticcache.ini.append.php ein.

[StaticPublishSettings]:

[Target_<id>] (der mitgelieferte Block [Target_example] ist eine Vorlage mit jeder Einstellung; er wird nicht gebaut):

Die erzeugte Referenz führt jede Einstellung mit ihrem Kommentar auf: staticcache.ini [StaticPublishSettings] und [Target_example].

exp:static:targets prüft jedes Ziel: Der Siteaccess existiert und ist ein Front-Siteaccess, BasePath hat die Form /name/, Adressen sind http oder https, Remote enthält kein Passwort und kein Token, Credential nennt ein Geheimnis, statt eines zu enthalten, die Listen enthalten bekannte Werte. Fehler sind Fehler; zweifelhafte Kombinationen (eine PublicURL, deren Pfad nicht BasePath ist, eine Sitemap ohne PublicURL) sind Warnungen.

In der Administration #

Setup > Statisches Veröffentlichen (das Modul staticpublish) tut, was die Befehle tun, mit Seiten: ein Assistent, der Ziele anlegt und ändert (über den INI-Editor in settings/override/staticcache.ini.append.php geschrieben), ein im Hintergrund gestarteter Build, dessen Fortschritt live verfolgt wird, eine Vorschau des Builds (was sich ändert, mit Größen, der Bericht des Builds, die Größe gegenüber den Grenzen des Hosts, die Kopie hinter einem signierten Link ausgeliefert) mit Veröffentlichen und Verwerfen, der Verlauf mit der Rücknahme, die Seite jedes Auftrags und der Deploy-Key. Ein Dashboard-Block listet die Ziele mit ihren veralteten Seiten und ihrer letzten Veröffentlichung auf, und Setup > Cache verlinkt darauf. Die Richtlinien staticpublish/read, build, publish und setup nehmen eine Einschränkung nach Ziel (Target); Veröffentlichen, Zurücknehmen, das Speichern eines Ziels und der Deploy-Key fragen „Bestätigen Sie, dass Sie es sind“. Das Hilfehandbuch: Statisches Veröffentlichen.

Die Administration startet ihre Aufträge als Konsolenprozesse (exp:static:build, exp:static:publish und exp:static:rollback mit --login, --run-id und --progress), sodass ein langer Build nie eine Webanfrage blockiert; die Auftragsdateien liegen in <WorkDir>/.jobs, und [StaticPublishSettings] JobHistory legt fest, wie viele aufbewahrt werden.

Befehle #

Jeder Befehl nimmt --format=json und gibt dann ein JSON-Dokument aus, Schema exp-static/1. Die Exit-Codes sind die von exp:upgrade: 0 erledigt, 1 fehlgeschlagen, 2 Aufruffehler, 3 Datenbank nicht erreichbar, 4 interner Fehler. Die erzeugten Seiten: exp:static:build, exp:static:diff, exp:static:serve, exp:static:targets, exp:static:publish, exp:static:rollback, exp:static:push, exp:static:keys, exp:static:status, exp:static:github, exp:static:dns.

Veröffentlichen nach Git #

Der Ordner des Ziels var/<site>/static-publish/<ziel>/ ist ein eigenes Git-Repository (nie im Repository der Website). exp:static:publish committet darin nur die Dateien des Builds, als einen Commit pro Veröffentlichung mit dem annotierten Tag static/<ziel>/<n>, und pusht Branch und Tags zum Remote des Ziels. Ein Push wird nie erzwungen, ein Tag nie verschoben; ein gescheiterter Push lässt den Commit lokal mit dem Push-Zustand pending, und exp:static:push oder der Cronjob-Teil staticpublish sendet ihn erneut. Zurücknehmen ist ein neuer Commit mit den Dateien eines früheren Tags, der Verlauf wächst also nur. Je Ziel läuft ein Build, eine Veröffentlichung, ein Zurücknehmen oder ein Push zur Zeit (eine Sperre pro Ziel).

Zugangsdaten sind Namen: Ein Token unter Setup > Geheimnisse oder in einer Umgebungsvariablen gelangt über GIT_ASKPASS und die Umgebung des einen git-Prozesses zu git; ein SSH-Deploy-Key, je Ziel von exp:static:keys erzeugt, über eine Datei, die nur der Prozess für die Dauer des Pushs lesen kann, und GIT_SSH_COMMAND. Keines steht je auf einer Befehlszeile, in der Remote-Adresse oder in einem Log.

Jede Veröffentlichung und jedes Zurücknehmen ist eine Zeile in exp_static_run (Zustand, Zahlen, Bytes, Commit, Tag, Push-Zustand, wer, wann), und die Seiten der letzten Veröffentlichung stehen in exp_static_page; der Upgrade-Schritt 6.0.15-static-publish-tables legt beide Tabellen auf jeder Datenbank an. Das Audit zeichnet system.staticpublish.publish, .rollback und .credential auf.

Anleitungen: Repositorys und Zugangsdaten, Verlauf und Zurücknehmen, SSH-Deploy-Keys.

GitHub #

Für ein Ziel mit Kind=github-pages und einer GitHub-Adresse nutzt das statische Veröffentlichen die REST-API von GitHub, hinter einer Funktionsprüfung (expStaticGitHub::available(): curl und openssl von PHP sowie GitHubAPI=enabled). Es meldet sich mit den eigenen Zugangsdaten des Ziels an, einem Token (token:) oder einer Installation einer GitHub App (app:), die nur im Header Authorization gesendet werden. Ein Deploy-Key oder none pusht nur.

• Einrichtung (exp:static:github setup und Auf GitHub einrichten in Schritt 4 des Assistenten): legt das Repository an, öffentlich, sofern nicht anders gewünscht, und leer, für das Konto oder eine Organisation; schaltet GitHub Pages aus dem Branch und Ordner oder aus GitHub Actions ein; setzt die eigene Domain und erzwingt HTTPS, sobald GitHub sein Zertifikat hat. Im Audit als system.staticpublish.target mit dem Verb github-setup.
• Zustand (exp:static:github status und der Kasten Auf GitHub in Verlauf und Vorschau): das Repository, GitHub Pages und der letzte Pages-Build (built, building, queued, failed), mit dem, was von den Einstellungen des Ziels abweicht.
• GitHub Actions: Mit Delivery=actions (oder Extras[]=workflow) schreibt der Build .github/workflows/static-publish-pages.yml, der die gepushten Dateien unverändert bereitstellt. Dafür muss der Build an der Wurzel des Branches liegen, und ein Token braucht die Berechtigung Workflows, um ihn zu pushen.
• Grenzen: Jeder Push eines GitHub-Pages-Ziels wird zuerst geprüft. Ein Build über MaxSiteBytes oder mit einer Datei über MaxFileBytes wird nicht gepusht (der Push bleibt pending); über 90 % der Grenze für die Website, eine Datei über 50 MB und ein privates Repository sind Warnungen.
• GitHub App: Credential=app:<installation> meldet sich mit einem Installations-Token der App an, die in GitHubAppId und GitHubAppKey gesetzt ist, erstellt mit einem JWT, das mit dem privaten Schlüssel der App signiert ist, und für den Prozess aufbewahrt, bis es abläuft; es gelangt wie ein Token über GIT_ASKPASS zu git.
• OAuth: exp:static:github signin meldet einen Benutzer mit dem Device Flow einer OAuth App an und bewahrt das Token im Geheimnisspeicher auf.
• DNS: exp:static:dns und DNS prüfen in Schritt 6 vergleichen die Einträge einer eigenen Domain mit den Adressen von GitHub Pages (expStaticDnsCheck).

Hilfe: Mit GitHub verbinden, Branch oder GitHub Actions, Eigene Domain verwenden, Grenzen und Bedingungen von GitHub Pages.

Was einen Server braucht #

Ein statischer Host kann nicht suchen, kein Formular annehmen und niemanden anmelden. Jeder Build findet diese Teile (expStaticDegrader) und gibt ihnen einen Ersatz; der Bericht des Builds listet sie als degraded:

• Suche (Search=enabled): Die Suchformulare der Site gehen zu search.html, das im Browser einen Index je Sprache durchsucht (expStaticSearchIndex).
• Informationssammler (Forms=endpoint): Sie senden an den Formular-Endpunkt staticpublish/form der Live-Site, der Ursprung, ein beim Build signiertes Token und eine Ratenbegrenzung prüft und den Post dann an die normale Informationssammlung übergibt. Mit Forms=hide zeigen sie einen kurzen Text mit einem Link zur Live-Seite.
• Kommentare, Warenkorb, Anmeldung: der kurze Text, oder sie fallen weg.
• Weiterleitungsseiten (Extras[]=redirects) für alte Adressen, eigene Aliase und URL-Platzhalter ohne *.
• Nachbearbeitung: minify, precompress, fingerprint.

Ein Ziel kann sich selbst veröffentlichen: Triggers[]=publish (Seiten beim Veröffentlichen von Inhalten als veraltet markiert, nach PublishDebounce gebaut) und Triggers[]=schedule (Schedule), beides im Cronjob-Teil staticpublish, danach mit der E-Mail von Notify[] und einem signierten Webhook. Einzelheiten: Dynamische Funktionen, Der Formular-Endpunkt. Das Audit zeichnet auch system.staticpublish.build und system.staticpublish.form auf.

Datenschutz #

• Builds laufen als anonymer Benutzer: Das Durchlaufen sendet kein Cookie, und die Prüfungen in der Datenbank (welche Speicherbilder kopiert werden dürfen) erfolgen für den anonymen Benutzer.
• Seiten mit Debug-Ausgabe, Formular-Token oder Sitzungskennungen werden bereinigt; eine Seite, die sich nicht bereinigen lässt oder deren Antwort ein Sitzungs-Cookie gesetzt hat, hält den Build an, bevor etwas in den Ordner des Ziels geschrieben wird.
• Speicherbilder werden nur für die veröffentlichte Version von Inhalten kopiert, die der anonyme Benutzer lesen darf. Bilder von Entwürfen (storage/images-versioned) und Dateien in storage/original werden nie aus dem Speicher kopiert; ein Download kommt nur in die Kopie, wenn eine Seite darauf verlinkt und die Website ihn einem anonymen Besucher gibt.
• ExcludePaths[] und ExcludeSections[] lassen Seiten aus.
• Lesen Sie den Diff eines Builds (exp:static:build --dry-run, exp:static:diff), bevor Sie ihn irgendwohin öffentlich übertragen.

Plattformen #

• PHP 7.4 ist nutzbar, 8.0 und neuer werden voll unterstützt.
• Jede Datenbank, auf der Exponential läuft; der Build liest nur Inhalts- und Bildtabellen.
• Apache mit PHP-FPM, Velocity und jeder andere Webserver: Der Build ruft Seiten wie ein Besucher über HTTP ab.
• Cluster-Speicher: Dateien unterhalb von var/ werden über den Cluster-Dateihandler gelesen.
• Windows: Pfade werden im Manifest auf jedem System mit / geschrieben, Seitenpfade, die unter Windows keine Dateinamen sein können (:, *, ?, CON und ähnliche), werden übersprungen und gemeldet, und der Vorschauserver wird ohne Shell gestartet.