Unifi-Voucher-Tool/updater/README.md
Friederich Loheide 25b8c51362
Some checks failed
CI / PHP Lint-1 (push) Successful in 43s
CI / PHP Lint (push) Successful in 45s
CI / PHP Lint (pull_request) Successful in 38s
CI / Unit Tests & Static Analysis (push) Failing after 43s
CI / PHP Lint-1 (pull_request) Successful in 40s
CI / Unit Tests & Static Analysis (pull_request) Failing after 41s
Selbst-Updater neu gebaut, Diagnoseseiten abgesichert
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>
2026-09-25 19:49:59 +00:00

5.9 KiB
Raw Permalink Blame History

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 until wird 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

  1. CHANGELOG.md: neuen Abschnitt ## MAJOR.MINOR.PATCH – Datum ergänzen
  2. Updater\Version::RELEASE und die Datei VERSION anheben (Patch = Fehlerbehebung, Minor = Funktion) – ein Test wacht darüber, dass beide übereinstimmen
  3. Tests grün (composer test), statische Analyse grün (composer stan)
  4. 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.