Aktualisierung per Klick im Administrationsbereich, ohne Zugang zum Server. Der bisherige Updater lud ein ZIP und entpackte es ungeprüft über die Produktion; das ist vollständig ersetzt. Neu in updater/: - Version: Release-Version als Konstante, installierter Commit-SHA in storage/.version (Datei, nicht Datenbank - der Updater muss den Stand auch bei hängender Datenbank lesen können) - Progress: Fortschrittsdatei mit eigenem Fehlerzustand (pct = -1) und Verfallszeit, damit ein abgestürzter Lauf den nächsten nicht blockiert - Maintenance: Wartungsmarkierung mit Ablauf, die sich beim Prüfen selbst aufräumt - ProxyClient: nur HTTPS, Zertifikatsprüfung an, begrenzte Weiterleitungen, 503 mirror_pending/not_released als Bitte um Geduld - Updater: Prüfsumme gegen X-Content-Sha256, zweistufiger ZIP-Slip-Schutz, geschützte Pfade, atomares Schreiben je Datei, nie löschen - AutoMigrate: zieht Migrationen beim ersten Seitenaufruf nach, nur bei geändertem Fingerabdruck und mit Sperre gegen Parallellauf - guard.php: Wartungs-Wächter für die Einstiegsseiten, JSON für die Schnittstellen; ausgenommen bleiben Update-Seite, Anmeldung und Health-Check - Changelog: zerlegt CHANGELOG.md und rendert Markdown ohne unsichere Links Oberfläche: Seite "Aktualisierung" mit Stand, Kanal, Suche, Fortschritt, Migrationsliste und Versionsgeschichte. Der Datenschutzhinweis steht dauerhaft neben der Schaltfläche, nicht in einem Dialog. Fehlt changelog_preview in der Antwort, bleibt es bei "neue Fassung verfügbar" - kein leerer Kasten, kein erfundener Ersatztext. Commit-Texte werden nirgends angezeigt. Außerdem (Punkt 2 der Liste): - cron_test.php entfernt: ohne jede Anmeldung erreichbar, meldete Datenbankfehler samt Meldung und die Spalten der vouchers-Tabelle - test.php verweigert ohne config.php die Auskunft; bisher lief die Diagnose auf einer frisch entpackten Installation ohne Anmeldung PHPStan prüft jetzt den gesamten updater/-Ordner. 18 neue Tests (93 Tests, 243 Assertions), Ablauf gegen den echten Update-Dienst durchgespielt. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.9 KiB
Selbst-Updater
Aktualisiert eine laufende Installation per Klick im Administrationsbereich – ohne Zugang zum Server. Quellcode und Datenbank-Migrationen kommen über einen Update-Dienst, der den aktuellen Stand eines Branches als ZIP bereitstellt.
[diese Installation] ←HTTPS→ [Update-Dienst] ←pull→ [Git-Repository]
Es gibt keine Tags und keine Releases: gezählt wird der Stand des Branches, und die Identität eines Stands ist sein Commit-SHA. „Ein Stand zurück“ heißt also ein Commit zurück, nicht eine Versionsnummer.
Dateien
| Datei | Aufgabe |
|---|---|
Version.php |
Release-Version (Konstante) und installierter Commit-SHA (storage/.version) |
Progress.php |
Fortschrittsdatei storage/.update-progress, inklusive Fehlerzustand |
Maintenance.php |
Wartungsmarkierung storage/.maintenance, läuft von allein aus |
ProxyClient.php |
HTTP-Client für den Update-Dienst, nur HTTPS |
Updater.php |
Kern: prüfen, laden, entpacken, übernehmen, migrieren |
UpdaterFactory.php |
Kanalwahl, persistiert in storage/updater-settings.json |
AutoMigrate.php |
zieht Migrationen beim ersten Seitenaufruf nach einem Update nach |
MigrationRunner.php |
führt die SQL-Dateien aus migrations/ aus |
Changelog.php |
zerlegt die CHANGELOG.md und rendert Markdown |
AuditLogger.php |
schreibt jeden Lauf in die Tabelle audit_log |
guard.php |
Wartungs-Wächter für die Einstiegsseiten |
UpdateController.php |
die JSON-Endpunkte |
templates/maintenance.php |
eigenständige Wartungsseite |
Ablauf einer Aktualisierung
| Fortschritt | Schritt |
|---|---|
| 0 % | Wartungsmodus aktivieren |
| 5 % | GET /version – Ziel-Stand ermitteln |
| 20 % | GET /zip?ref=<sha> in eine Datei streamen, gegen X-Content-Sha256 prüfen |
| 50 % | nach storage/.update-staging entpacken, gemeinsamen Deckel-Ordner strippen |
| 65 % | über die Produktion legen, geschützte Pfade auslassen |
| 80 % | ausstehende Migrationen ausführen |
| 90 % | Zwischenspeicher und Bytecode-Cache leeren |
| 100 % | neuen Stand speichern, Audit-Eintrag schreiben, aufräumen |
Der Wartungsmodus wird im finally immer wieder abgebaut. Scheitert ein
Schritt, steht die Fortschrittsdatei auf pct = -1, step = error samt
Meldung – das ist eindeutig von „0 % erledigt“ unterscheidbar.
Sicherheitseigenschaften
- ZIP-Slip, zweistufig. Eintragsnamen werden vorab abgelehnt (absolute
Pfade, Laufwerksbuchstaben,
..-Segmente, Null-Bytes); nach dem Schreiben wird der aufgelöste Pfad geprüft und alles außerhalb des Arbeitsverzeichnisses sofort gelöscht. Die zweite Stufe fängt ab, was die erste übersieht. - Geschützte Pfade (
Updater::PROTECTED_PATHS) werden nie überschrieben:config.php,.env,.git/,uploads/,vendor/,node_modules/,composer.lock,package-lock.json,updater/storage/,data/. - Atomar je Datei. Erst daneben schreiben, dann umbenennen. Ein Abbruch mittendrin hinterlässt sonst eine halbe PHP-Datei, die den nächsten Aufruf mit einem Parse-Fehler abwürgt.
- Nur überschreiben und ergänzen, nie löschen. Eine im neuen Stand fehlende Datei bleibt liegen: etwas unaufgeräumter, aber ein Fehler in der Pfadberechnung nimmt so keine Nutzdaten mit.
- Prüfsumme. Der Dienst nennt die SHA-256 des Pakets im Kopf
X-Content-Sha256; stimmt sie nicht, bricht der Lauf ab. - Nur HTTPS, Zertifikatsprüfung an, Weiterleitungen begrenzt.
- Selbstheilender Wartungsmodus. Ein abgelaufenes
untilwird beim Prüfen entfernt – ohne das legt ein Absturz die Installation dauerhaft lahm. - Nur Administratoren dürfen prüfen, aktualisieren und den Kanal wechseln; alle schreibenden Endpunkte verlangen ein CSRF-Token.
Kanäle
| Kanal | Adresse |
|---|---|
stable |
https://update.loheide.cloud/unifivouchertool |
development |
https://update.loheide.cloud/unifivouchertool-development |
Der aktive Kanal liegt in storage/updater-settings.json – nicht in der
Datenbank, damit der Updater ihn auch bei hängender Datenbank lesen kann.
Automatische Migration
Ohne Serverzugang ist der erste Seitenaufruf nach einem Update der einzige
verlässliche Zeitpunkt, zu dem neue Migrationen laufen können. AutoMigrate
hängt deshalb an Database::getInstance(). Zwei Vorkehrungen:
- ein Fingerabdruck über die Migrationsdateien; nur wenn er sich geändert hat, wird überhaupt migriert – sonst liefe der Migrator bei jedem Aufruf,
- eine Sperrdatei gegen Parallellauf, denn nach einem Update treffen oft mehrere Aufrufe gleichzeitig ein.
Fehler werden protokolliert, nicht geworfen: eine fehlgeschlagene Nachführung darf nicht jede Seite unbenutzbar machen.
Endpunkte
Dieses Projekt hat kein Routing-System – die Zuordnung steht in routes.php:
POST /admin/update/check -> admin/update_api.php?action=check
POST /admin/update/install -> admin/update_api.php?action=install
GET /admin/update/progress -> admin/update_api.php?action=progress
POST /admin/update/channel -> admin/update_api.php?action=channel
POST /admin/update/migrations -> admin/update_api.php?action=migrations
Neue Fassung veröffentlichen
CHANGELOG.md: neuen Abschnitt## MAJOR.MINOR.PATCH – DatumergänzenUpdater\Version::RELEASEund die DateiVERSIONanheben (Patch = Fehlerbehebung, Minor = Funktion) – ein Test wacht darüber, dass beide übereinstimmen- Tests grün (
composer test), statische Analyse grün (composer stan) - Commit und Merge nach
main– der Update-Dienst liefert den Stand aus, sobald er gespiegelt ist
Kompilierte Assets gehören mit ins Repository: beim Anwender läuft kein Build.
Rückbau
updater/ löschen, admin/update.php und admin/update_api.php entfernen,
die require-Zeile des Wächters aus den Einstiegsseiten nehmen und den Aufruf
von AutoMigrate in includes/Database.php streichen.