portal/docs/BETRIEB.md
flessinb 1e5ce2c20c Hintergrund & Darstellung: animierte Vorlagen, eigener Verlauf, eigenes Bild
Pro Person gespeichert (users.appearance), lokal zwischengespeichert für sofortige
Anzeige. Vorlagen: Polarlicht, Ozean, Sternenhimmel, Abendrot, Lichter. Eigenes
Bild wird serverseitig mit GD neu kodiert (JPEG, max. 2560 px, ohne Metadaten)
und nur der eigenen Person ausgeliefert. Hell/Dunkel erzwingbar, Animation
abschaltbar, prefers-reduced-motion wird beachtet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 07:57:08 +01:00

6.8 KiB
Raw Permalink Blame History

Betrieb: Daten, Migrationen, Wiederherstellung, Tests

Wo liegt was?

Pfad Inhalt
/var/www/html/portal.flessinghome.de Git-Arbeitskopie; nginx liefert nur public/ aus
/var/lib/portal/users.json Benutzer: Rolle, Passwort-Hash, 2FA-Geheimnis, Favoriten, Anordnung (layout), Sitzungsversion (sv)
/var/lib/portal/areas.json Bereiche mit Sichtbarkeit
/var/lib/portal/bookmarks.json Links (geteilt: area; privat: owner)
/var/lib/portal/trash.json Papierkorb (30 Tage)
/var/lib/portal/settings.json Gästeseite: Überschrift, Text, WLAN (gilt für alle Gäste-Links)
/var/lib/portal/guests.json Gäste-Links: Name, Ablauf, Bereiche, WLAN, aktiv – Token nur als SHA-256-Hash
/var/lib/portal/config.json optional: eigene Einstellungen, siehe unten
/var/lib/portal/sessions/ Anmeldungen (PHP-Sitzungen, Rechte 700). Löschen = alle abmelden. Aufräumen nach 30 Tagen ohne Nutzung in bin/check.php
/var/lib/portal/backgrounds/ eigene Hintergrundbilder, eine JPEG-Datei je Person (neu kodiert, ohne Metadaten)
/var/lib/portal/status.sqlite Prüf-Verlauf (7 Tage) – kann gelöscht werden, wird neu angelegt
/etc/portal/android-release.jks Signaturschlüssel der App – sichern

Alle Dateien in /var/lib/portal gehören www-data:www-data und haben die Rechte 640. Schreibzugriffe laufen über eine gemeinsame Sperre (.lock). Geschrieben wird atomar: in eine temporäre Datei, danach rename.

Grenze: Ändert ein Vorgang mehrere Dateien, zum Beispiel Bereich löschen (Papierkorb, Links, Bereiche) oder Import (Bereiche, Links), wird zuerst alles geprüft und erst dann geschrieben. Die Sperre verhindert parallele Änderungen. Fällt der Server aber genau zwischen zwei Dateien aus, kann ein Zwischenstand bleiben. Für echte Transaktionen müssten die Daten nach SQLite (siehe Plan).

Einstellungen (/var/lib/portal/config.json)

Standardwerte stehen in lib/config.php. In config.json stehen nur Abweichungen. Listen werden dabei komplett ersetzt, nicht ergänzt.

{
  "check": {
    "ports": "80,443,1024-65535",
    "maxParallel": 8,
    "maxRedirects": 3,
    "staleAfter": 600,
    "internalNets": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10", "fc00::/7"],
    "internalRoles": ["admin", "erwachsene"]
  },
  "trashDays": 30
}
  • ports: Ziel-Ports, die geprüft werden dürfen.
  • denyNets: Netze, die nie geprüft werden (Loopback, Link-Local und Cloud-Metadaten, Multicast).
  • internalNets und internalRoles: Ins Heimnetz wird nur für geteilte Links geprüft und für private Links von Personen mit diesen Rollen. Private Links von Kindern werden nur ins Internet geprüft.

Datenmigrationen

Version Datum Was Nötig?
v1 → v2 2026-11-12 feste Kategorien → Bereiche (bin/migrate.php) erledigt; Sicherung unter /root/portal-data-backup-20261112-2155
v2 → v3 2026-11-12 neue optionale Felder: users.sv, users.layout, links.expect, links.insecureIntern; neue Datei trash.json keine Migration – fehlende Felder gelten als Standard
v3 → v4 2026-11-12 mehrere Gäste-Links in guests.json automatisch beim ersten Zugriff (guestLinks()): ein vorhandener Link aus settings.guest.token wird zu „Standard“ (Hash des alten Tokens → gedruckte QR-Codes gelten weiter; Bereiche = alle mit „Gäste“-Häkchen). settings.guest bleibt unverändert.
v4 → v5 2026-11-13 Sitzungen in /var/lib/portal/sessions/ statt /var/lib/php/sessions (dort löscht Debians phpsessionclean alles nach 24 min), „Angemeldet bleiben“ keine Migration; einmalig neu anmelden
v5 → v6 2026-11-13 neues optionales Feld users.appearance, Ordner backgrounds/; nginx: client_max_body_size 8m für api.php keine Migration – fehlt das Feld, gilt „Schlicht“

Rückweg von v4 auf v3: Die alte Version liest wieder settings.guest (einzelner Link) und ignoriert guests.json. Neu angelegte Gäste-Links gelten dann nicht.

Rückweg von v3 auf v2: Die alte Version ignoriert die neuen Felder. Was nach dem Rückweg gelöscht wird, landet nicht im Papierkorb. Einträge in trash.json bleiben einfach liegen.

Verhalten nach dem Update:

  • Sitzungen: Alle bisherigen Anmeldungen bleiben gültig, weil sv fehlt und deshalb als 0 zählt.
  • Statusprüfung: Die TLS-Zertifikatsprüfung ist jetzt an. Selbstsignierte Heimnetz-Dienste stehen dann auf „Zertifikat ungültig“. Lösung: im Link unter „Erweiterte Prüfung“ das Häkchen „Zertifikat der Heimnetz-Adresse nicht prüfen“ setzen. Vor dem Update gegen eine Kopie der Daten geprüft: Alle 9 Links blieben erreichbar.
  • 404: gilt nicht mehr als erreichbar, sondern als „Seite fehlt“.

Wiederherstellung

Einzelne Links oder Bereiche: ☰ → Papierkorb → „Wiederherstellen“. Die IDs bleiben erhalten, dadurch greifen Favoriten und die persönliche Anordnung wieder. Ist der Bereich eines Links selbst gelöscht, zuerst den Bereich wiederherstellen.

Ganzer Datenstand aus einer Sicherung:

B=/pfad/zur/sicherung        # enthält users.json, areas.json, bookmarks.json, …
cd /var/lib/portal
cp -a users.json areas.json bookmarks.json settings.json trash.json /root/portal-vor-restore-$(date +%F-%H%M)/ 2>/dev/null
install -o www-data -g www-data -m 640 "$B"/{users,areas,bookmarks,settings,trash}.json /var/lib/portal/

Stammt users.json aus der Sicherung, gelten deren Passwörter und 2FA. Neuere Sitzungen können ungültig werden.

Nur ein Benutzer ausgesperrt (Passwort oder 2FA verloren): Ein Admin setzt in der Oberfläche ein neues Passwort bzw. setzt die 2FA zurück. Hat kein Admin mehr Zugang, den ersten Admin anlegen wie im README beschrieben.

Empfehlung: /var/lib/portal (ohne status.sqlite) täglich mit der vorhandenen Sicherung mitnehmen, außerdem /etc/portal/.

Tests

./tests/run.sh

Das Skript startet einen eigenen PHP-Testserver mit leerem Wegwerf-Datenordner (PORTAL_DATA_DIR) und einen kleinen Ziel-Server (tests/target.php), der beliebige HTTP-Codes und Weiterleitungen liefert. Die echten Daten werden nie berührt. Geprüft werden:

  • Rechte zwischen Admin, Erwachsenen und Kindern, Trennung privater Links, CSRF
  • Sortieren der Bereiche (Rechte je Bereich, unbekannte und doppelte IDs)
  • Sitzungswiderruf mit mehreren Geräten
  • Statusbewertung und -prüfung: Zustände, erwartete Codes, gesperrte Netze und Ports, Weiterleitungen, private Kinder-Links
  • persönliche Anordnung, Papierkorb, Import (Dubletten, Rechte, kein halber Import) und Export

Update einspielen

cd /var/www/html/portal.flessinghome.de
git pull
./tests/run.sh
# Nach Änderungen an JS/CSS: ?v= in public/index.html und public/gast.html hochzählen und CACHE in public/sw.js erhöhen