# 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=` 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.