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

125 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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