psa-orderform/docs/UPDATE_AND_BACKUP.md

Update und Backup

Überblick

Updates und Backups laufen über den Manage-Client in manage-client/. Der Client holt Releases von einem zentralen Manage-Server, rollt sie über die Installation aus und lädt Backups der Betriebsdaten dorthin hoch.

Der Client ist ein fertiges Paket und wird pro Projekt gepflegt. Seine vollständige Dokumentation liegt unter https://manage.med0.de/client-docs/ (maschinenlesbar: llms.php); dieses Dokument beschreibt nur, wie er in diesem Projekt eingebunden ist.

Er ersetzt die früheren Komponenten includes/backup.php, admin/updater.php, backup-server/ und update-server/, die vollständig entfernt wurden.

Bestandteile im Projekt

Pfad	Zweck
manage-client/lib/	die Bibliothek; lib/client.php ist der einzige Einstiegspunkt
manage-client/bin/manage-client.php	Kommandozeile für Cron und Shell
manage-client/ui/panel.php	die Oberfläche, eingebunden von admin/manage.php
manage-client/config.php	Serveradresse, Instanz, Token, Backup-Quellen — nicht im Repository, nicht im Release-Paket
manage-client/config.sample.php	Vorlage dafür
admin/manage.php	Adminseite „Update & Backup“ (prüft den Login, bindet dann das Panel ein)
includes/after-update.php	Post-Update-Hook (psaAfterUpdate)
includes/manage-activity.php	Cron-Ersatz: Backup und Statusmeldung durch Adminaktivität
migrations/	einmalige Migrationsskripte, die mit einem Release ausgeliefert werden
scripts/create-release-zip.sh	baut das Release-ZIP

Laufzeitdaten liegen unter data/manage/ (backups/, updates/, work/, migrations.json, manage-client.log, activity.json) und sind über die .htaccess im Projektwurzelverzeichnis nicht über das Web erreichbar.

Konfiguration (manage-client/config.php)

Die drei Verbindungswerte stammen aus dem Manage-Server; der Token wird beim Anlegen der Instanz einmalig angezeigt:

define("MANAGE_SERVER_URL", "https://manage.med0.de");
define("MANAGE_INSTANCE",   "psa-...");
define("MANAGE_TOKEN",      "...");

Projektspezifisch gesetzt sind außerdem:

Konstante	Wert in diesem Projekt
MANAGE_VERSION_FILE / MANAGE_VERSION_CONSTANT	includes/version.php mit APP_VERSION
MANAGE_UPDATE_PROTECTED_PATHS	config.php, data/, .git/, manage-client/config.php
MANAGE_UPDATE_SANITY_PATHS	index.php, includes/functions.php
MANAGE_UPDATE_POST_HOOK	includes/after-update.php → psaAfterUpdate()
MANAGE_BACKUP_SOURCES	data/*.json, data/uploads/**, data/manage/migrations.json
MANAGE_BACKUP_DATABASE	null — reines Flat-File-Projekt
MANAGE_BACKUP_LOCAL_RETENTION	4 lokale Archive
MANAGE_BACKUP_AUTO_INTERVAL_SECONDS	604800 (wöchentlich)
MANAGE_HTTP_TIMEOUT	5 Sekunden — die Einstellungsseite ruft das Manifest beim Rendern ab

config.php der Anwendung enthält keine Update- oder Backup-Konstanten mehr.

Bedienung im Admin

• Einstellungen zeigt Version, Update-Verfügbarkeit, letztes Backup und offene Migrationen und verlinkt auf die Vollansicht.
• Update & Backup (admin/manage.php) bietet: Backup erstellen, Update ausrollen, Migrationen nachholen, Status melden, lokale Backups herunterladen.
• Das Dashboard (admin/index.php) stößt die periodischen Aufgaben an, siehe unten.

Ohne Cron: Auslösung durch Adminaktivität

Auf dieser Installation steht in der Regel kein Cron zur Verfügung. Die beiden Aufgaben, die sonst geplant laufen würden, hängen deshalb an der Adminaktivität: admin/index.php ruft beim Aufruf manageActivityRunDueTasks() aus includes/manage-activity.php auf. Der Login leitet immer auf das Dashboard, jede Adminsitzung kommt also dort vorbei.

Aufgabe	Intervall	Konstante
Automatisches Backup	wöchentlich	MANAGE_BACKUP_AUTO_INTERVAL_SECONDS
Statusmeldung (Heartbeat)	stündlich	MANAGE_ACTIVITY_HEARTBEAT_INTERVAL

Ist das Intervall noch nicht abgelaufen, passiert nichts. Nach einem frisch erstellten Backup wird die Statusmeldung unabhängig vom Intervall gesendet, damit der Manage-Server nicht bis zu eine Stunde lang ein veraltetes „letztes Backup“ anzeigt.

Der Zeitstempel der letzten Statusmeldung steht in data/manage/activity.json und wird vor dem Request geschrieben: ein nicht erreichbarer Manage-Server kostet dadurch einen Versuch pro Intervall, nicht einen pro Seitenaufruf. Keine der beiden Aufgaben kann die Seite abbrechen — Fehler landen im Client-Log (data/manage/manage-client.log), ein fehlgeschlagenes Backup zusätzlich als Hinweis auf dem Dashboard.

Die Update-Prüfung braucht keine eigene Auslösung: die Einstellungsseite und admin/manage.php holen das Manifest beim Rendern.

Cron

Nur relevant, wenn auf einer Installation doch Cron zur Verfügung steht - dann sind die Kommandos der zuverlässigere Weg und die Auslösung durch Adminaktivität greift nur noch selten ein:

20 3 * * * /usr/bin/php /pfad/zum/projekt/manage-client/bin/manage-client.php backup --trigger=cron --quiet
7  * * * * /usr/bin/php /pfad/zum/projekt/manage-client/bin/manage-client.php heartbeat --quiet
0  8 * * 1-5 /usr/bin/php /pfad/zum/projekt/manage-client/bin/manage-client.php check --quiet

Exitcodes: 0 Erfolg, 1 Fehler, 2 Update verfügbar (nur check). Updates werden bewusst nicht automatisch installiert.

Release bauen und veröffentlichen

./scripts/create-release-zip.sh v1.3.15

Das Skript schreibt die Version nach includes/version.php, packt alle von Git verwalteten Dateien abzüglich der Ausschlussliste (config.php, manage-client/config.php, data/, build/, scripts/) nach build/releases/psa-orderform-vX.Y.Z.zip und gibt SHA-256 und Größe aus. Das ZIP wird im Manage-Server unter Releases hochgeladen; Prüfsumme und Größe berechnet der Server selbst.

Die Wurzel des ZIP ist das Anwendungsverzeichnis — kein zusätzlicher Oberordner.

Migrationen

Migrationen liegen in migrations/ und werden mit dem Release ausgeliefert. Sie laufen in Dateinamenreihenfolge, jeweils genau einmal; der Stand steht in data/manage/migrations.json.

<?php

return function (array $context): void {
    $file = $context["app_root"] . "/data/products.json";
    // ... idempotent umbauen ...
};

Der Kontext enthält app_root, instance, from_version, to_version, backup_dir, run_id und migration_id. Migrationen müssen idempotent sein: eine mittendrin abgebrochene Migration gilt nicht als angewendet und läuft beim nächsten Lauf von vorn.

Nach einem Fehler:

php manage-client/bin/manage-client.php migrate --dry-run
php manage-client/bin/manage-client.php migrate

Grenzen

• Kein Restore. Backups werden erstellt und übertragen, aber nie zurückgespielt. Die vom Update überschriebenen Dateien liegen als Kopie unter data/manage/updates/, ausschließlich für manuelle Wiederherstellung.
• Gelöschte Dateien verschwinden nicht. Ein Update legt sich über den Bestand; was ein Release nicht mehr enthält, bleibt liegen. Entfernen gehört in eine Migration.
• Kein Wartungsmodus. Die Anwendung bleibt während des Ausrollens erreichbar.
• Backups enthalten personenbezogene Daten aus data/orders.json. Für den Manage-Server gelten dieselben Anforderungen wie für diese Anwendung. Zugangsdaten gehören nicht ins Backup — config.php ist deshalb keine Backup-Quelle.