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
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>
125 lines
5.9 KiB
Markdown
125 lines
5.9 KiB
Markdown
# 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.
|