Unifi-Voucher-Tool/updater
Friederich Loheide d93cbbadc2
Some checks failed
CI / PHP Lint (push) Successful in 41s
CI / PHP Lint-1 (push) Successful in 40s
CI / Unit Tests & Static Analysis (push) Failing after 39s
CI / PHP Lint (pull_request) Successful in 41s
CI / PHP Lint-1 (pull_request) Successful in 41s
CI / Unit Tests & Static Analysis (pull_request) Failing after 41s
Verweis auf das Änderungsprotokoll folgt dem eingestellten Kanal
Wurde die Vorschau gekürzt, zeigt die Oberfläche einen Verweis auf das
vollständige Änderungsprotokoll. Der zeigte fest auf den stabilen Kanal,
auch wenn die Installation auf dem Entwicklungskanal läuft.

Aufgefallen beim ersten echten Durchlauf mit Vorschau: der Dienst kennt
jetzt 3.0.0 und liefert die Abschnitte samt "complete": false.

Freigabe nach dem dokumentierten Ablauf: Changelog ergänzt, VERSION und
Version::RELEASE auf 3.0.1 angehoben.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-25 19:52:58 +00:00
..
migrations Zertifikatsprüfung als Opt-in: pro Site und für SMTP 2026-09-25 05:12:28 +00:00
storage Updater-System (OpenNIT-Modell) im isolierten updater/-Ordner 2026-06-05 18:51:51 +00:00
templates Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
AuditLogger.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
AutoMigrate.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
bootstrap.php Updater-System (OpenNIT-Modell) im isolierten updater/-Ordner 2026-06-05 18:51:51 +00:00
Changelog.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
guard.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
Maintenance.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
MigrationRunner.php Updater-System (OpenNIT-Modell) im isolierten updater/-Ordner 2026-06-05 18:51:51 +00:00
Progress.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
ProxyClient.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
README.md Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
RetryLaterException.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
routes.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
UpdateController.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
Updater.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
UpdaterFactory.php Selbst-Updater neu gebaut, Diagnoseseiten abgesichert 2026-09-25 19:49:59 +00:00
Version.php Verweis auf das Änderungsprotokoll folgt dem eingestellten Kanal 2026-09-25 19:52:58 +00:00

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.