From ac419ac56f3ca9783c181fe778d07661a438b2b1 Mon Sep 17 00:00:00 2001 From: Terranom674 Date: Tue, 18 Aug 2026 21:17:27 +0200 Subject: [PATCH] Bring README to current 0.9.5.5 connector architecture --- README.md | 135 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 96 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index cd893c2..a21b37c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Modulares Piwigo-Plugin für Administration, Bildverarbeitung, geschützte Freigaben, Fotoauswahl und die Anbindung von Nextcloud an Piwigo. -Aktuelle Plugin-Version: **0.9.4.4** +Aktuelle Plugin-Version: **0.9.5.5** ## Grundprinzip @@ -12,62 +12,102 @@ Für die Administration gilt: Der normale Nutzer sieht Aufgaben, Entscheidungen ## NC Connector -Der NC Connector synchronisiert ausdrücklich freigegebene Nextcloud-Inhalte mit Piwigo. +Der NC Connector synchronisiert ausdrücklich ausgewählte Nextcloud-Inhalte mit Piwigo. ### Datenmodell - Nextcloud bleibt die Quelle der Originaldateien. - Originalbilder werden nicht in eine zweite dauerhafte Bibliothek kopiert. -- Ein Shadow Tree erzeugt die für Piwigo benötigte Verzeichnisstruktur mit Symlinks. -- Ordnerfreigaben werden als physische Piwigo-Alben synchronisiert. -- Einzeldateifreigaben werden im Galerie-Root verlinkt und als echte Piwigo-Orphans ohne Albumzuordnung registriert. -- Entfernte Freigaben werden aus Shadow Tree und Piwigo entfernt, das Nextcloud-Original bleibt erhalten. +- Ein Shadow Tree erzeugt die für Piwigo benötigte Verzeichnisstruktur. +- Der bestehende produktive Weg verwendet lokale bereits vorhandene Speicherpfade und Symlinks auf die Originale. +- Ordner werden als physische Piwigo-Alben synchronisiert. +- Root-Dateien können als echte Piwigo-Orphans ohne Albumzuordnung registriert werden. +- Entfernte Quellen werden aus Shadow Tree und Piwigo entfernt, das Nextcloud-Original bleibt erhalten. - Neu importierte physische Connector-Alben werden privat angelegt. +### Bestehende produktive Quellenmodi + +Der bestehende Connector unterstützt weiterhin getrennte Quellenmodi: + +- `legacy-view` +- `user-shares` +- `selected-fileids` + +Diese Modi bleiben während der Entwicklung des neuen WebDAV-Wegs vollständig erhalten. Es gibt keine automatische Migration bestehender Verbindungen. + ### Verbindungsassistent Neue Verbindungen werden bevorzugt mit einem Endnutzer-Assistenten angelegt. -Ablauf: - -1. Nextcloud-Adresse, Benutzer und Passwort eingeben. -2. Der Assistent prüft HTTP/HTTPS, Nextcloud-Status und Anmeldung. -3. Derselbe in Schritt 1 angegebene Connector-Benutzer und dasselbe Passwort werden auch für den lesenden PostgreSQL-Zugriff verwendet; es gibt im normalen Ablauf keine zweite Benutzer-/Passwortabfrage. -4. Vorhandene passende Connector-Werte für Host, Port, Datenbank und Storage-Zuordnungen werden wiederverwendet, aber erneut mit dem aktuellen Zugang geprüft. -5. Nur wenn der übliche PostgreSQL-Weg nicht erreichbar ist, werden abweichende Datenbank-Adresse, Port und Datenbankname gezielt abgefragt. Benutzer und Passwort bleiben dabei die Angaben aus Schritt 1. -6. Nicht automatisch zuordenbare Storage-Mounts werden einzeln bestätigt. -7. Danach wird der Nextcloud-Benutzer gewählt, dessen Freigaben verwendet werden sollen. Empfohlen wird ein eigener `showcase`-Benutzer. -8. Piwigo-API-Zugang testen oder bewusst überspringen. -9. Optionaler bzw. bei übersprungener API verpflichtender Login-Fallback. -10. Erst der Abschluss legt die Verbindung dauerhaft an. +Der aktuelle Assistent kann Nextcloud per HTTP/HTTPS und OCS prüfen und Verzeichnisse per WebDAV anzeigen. Für den bestehenden produktiven lokalen Weg existieren weiterhin PostgreSQL-/View-/Storage-Mapping-Schritte, sofern sie benötigt werden. Wizard-Geheimnisse werden während der Einrichtung serverseitig in der Sitzung gehalten. Ein fehlgeschlagener Test leert die Eingaben nicht. Ein API-Test verändert die dauerhafte API-Konfiguration erst beim erfolgreichen Abschluss des Assistenten. Die vollständige technische Maske bleibt weiterhin über **Ohne Assistent anlegen** sowie bei bestehenden Verbindungen unter **Technische Einstellungen** erreichbar. -### Lokaler Adapter +### Lokaler produktiver Adapter -Der derzeit produktive Adapter verwendet: +Der derzeit produktive Adapter verwendet je nach bestehender Verbindung: -- PostgreSQL-Reader mit minimalen Leserechten; -- Source-View `piwigo_showcase_sources`; -- Activity-View `piwigo_showcase_activity`; +- PostgreSQL-Reader; +- Source-/Activity-Views; - explizite Storage-Zuordnungen auf bereits vorhandene lokale Mounts; - Plugin-eigene Runtime und getrennten State pro Verbindung. -Ein Storage-Mapping besteht aus `storage_id`, einem optionalen `source_prefix` und dem lokalen Mount. Ein leerer Prefix ist zulässig und bedeutet, dass der Mount direkt dem Storage-Root entspricht. +Dieser Weg bleibt erhalten, bis der neue WebDAV-Weg vollständig End-to-End funktioniert. + +### Neuer WebDAV-Weg + +Der geplante neue Quellenmodus wird zusätzlich zu den bestehenden Modi entwickelt, vorgesehen als `webdav-placeholder`. + +Ziel: + +- nur normale Nextcloud-Anmeldung bzw. App-Passwort und WebDAV benötigen; +- keine Nextcloud-PostgreSQL-Rechte voraussetzen; +- keine Storage-IDs oder Backend-Pfade voraussetzen; +- keine zusätzlichen Host-Mounts voraussetzen; +- kein FUSE, davfs oder rclone voraussetzen; +- keine Originalbilder dauerhaft nach Piwigo kopieren. + +Grundidee: + +1. Nextcloud-Verzeichnisse werden über WebDAV/PROPFIND gelesen. +2. Ordner, Dateinamen, Datei-ID, MIME-Typ, Größe, ETag und WebDAV-Pfad werden erfasst. +3. Für Bilder wird nur eine winzige lokale Platzhalterquelle erzeugt. +4. Der bestehende Shadow Tree bildet daraus die reale Ordner-/Dateinamensstruktur für Piwigo. +5. Ein Mapping verbindet den Piwigo-/Shadow-Tree-Pfad mit der WebDAV-Quelle. +6. Wenn Piwigo echte Bilddaten benötigt, wird das Original bei Bedarf über WebDAV gelesen. +7. Piwigo-Derivate werden normal in `_data/i/` gecacht. +8. Das Original bleibt ausschließlich in Nextcloud. + +Der erste experimentelle Baustein dafür ist: + +- `runtime/lib/build_webdav_placeholder_source.py` + +Dieser Builder ist noch kein vollständiger Connection-Modus. Die Integration in Secret-Speicherung, Wizard, Reconcile und Runtime steht noch aus. + +### Gemessene WebDAV-Performance + +Ein realer Test mit einem 16.091.204-Byte-Bild ergab vom Piwigo-System: + +- interne Nextcloud-Adresse: 1,829 s bei 8.796.915 Byte/s; +- externe Nextcloud-Adresse: 1,865 s bei 8.627.524 Byte/s. + +Damit war die externe Verbindung in diesem Test nur ungefähr 2 % langsamer. Der WebDAV-Ansatz wird deshalb weiterverfolgt. Wichtig bleibt, dass Piwigo-Derivate lokal gecacht werden und WebDAV nicht bei jedem Thumbnail-Aufruf erneut verwendet wird. ### Activity Gate -Der regelmäßige Lauf berücksichtigt: +Der bestehende regelmäßige Lauf berücksichtigt: - Nextcloud-Aktivität; -- Signatur der sichtbaren Freigaben; +- Signatur der sichtbaren Quellen; - Quiet-Time; - maximale Wartezeit; - periodischen Full-Sync; - notwendigen Reparaturlauf bei beschädigtem Shadow Tree oder fehlenden Piwigo-Alben. +Der neue WebDAV-Modus erhält später eine eigene Änderungserkennung, insbesondere über WebDAV-Metadaten wie ETag. + ### Piwigo-Synchronisierung Der produktive Lauf ist API-first: @@ -106,11 +146,25 @@ Bestehende Verbindungen können: - technisch bearbeitet, solange sie nicht aktiv sind; - deaktiviert und anschließend gelöscht werden. -Das Löschen einer Connector-Verbindung entfernt keine Nextcloud-Originale und keine Piwigo-Bilder. Erreichbare Connector-eigene Status-/State-Daten der Verbindung werden bereinigt. +Seit 0.9.5.5 hängt das Löschen einer Verbindung nicht mehr davon ab, dass der Webserver in Root-eigene Runtime-Verzeichnisse schreiben kann. Die Datenbankverbindung wird entfernt; verwaiste Runtime-Dateien werden vor einem späteren Sync bereinigt. -### Legacy-Migration +Das Löschen einer Connector-Verbindung entfernt keine Nextcloud-Originale und keine Piwigo-Bilder. -Für ältere Installationen mit dem früheren separaten `piwigo-sync` existieren weiterhin Migrations-/Cutover-Helfer. Neue Installationen sollen den nativen Connector-Weg verwenden. +### Migrationsregel für WebDAV + +Der bestehende lokale Weg bleibt so lange vollständig erhalten, bis `webdav-placeholder` End-to-End funktioniert. + +Vor einer freiwilligen Migration bestehender Verbindungen müssen mindestens erfolgreich getestet sein: + +- Verbindungsanlage; +- Verzeichnisauswahl; +- Shadow Tree; +- Piwigo-Registrierung; +- echte Bildausgabe; +- Derivat-Cache; +- Änderungserkennung; +- Löschen/Deaktivieren; +- Fehlerbehandlung. ## Bildcache @@ -187,21 +241,20 @@ Wichtige Dateien und Verzeichnisse: - `include/nc_connector.inc.php` – Datenmodell und gemeinsame Connector-Funktionen - `include/nc_connector_wizard.inc.php` – Endnutzer-Assistent und Connection-Bearbeitung - `include/nc_connector_manage.inc.php` – Credential-Format, Storage-Mappings, Verifikation und Löschen +- `include/nc_connector_connection_scope.inc.php` – verbindungseigene Authentifizierung und sichere Löschlogik - `include/nc_connector_create_api.inc.php` – API-first-Verbindungserstellung - `include/nc_connector_piwigo_api.inc.php` – API-Zugang und Fallback-Verwaltung - `include/nc_connector_system.inc.php` – Timer- und Laufzeitstatus - `include/nc_productive_ws.inc.php` – produktiver Piwigo-Dateisync - `include/nc_orphan_ws.inc.php` – Orphan-Synchronisierung - `runtime/lib/activity_gate.py` – Activity Gate -- `runtime/lib/build_manifest.py` – Auflösung der Nextcloud-Freigaben auf Storage-Mounts +- `runtime/lib/build_manifest.py` – bestehende Auflösung der Nextcloud-Quellen auf Storage-Mounts +- `runtime/lib/build_selected_manifest.py` – ausgewählte Nextcloud-Datei-IDs auf bestehende Storage-Pfade auflösen +- `runtime/lib/build_webdav_placeholder_source.py` – experimentelle WebDAV-Platzhalterquelle - `runtime/lib/shadow_tree.py` – atomarer Shadow Tree mit Rollback - `runtime/lib/piwigo-sync.php` – API-first-Piwigo-Sync mit Fallback -- `runtime/run-all.sh` – Multi-Connection-Runner +- `runtime/run-all.sh` – Multi-Connection-Runner und Bereinigung verwaister Runtime-Dateien - `runtime/sync.sh` – Ablauf einer Verbindung -- `nc-connector-install.php` – native Root-Aktivierung -- `nc-connector-disable.php` – Deaktivierung -- `nc-connector-normalize.php` – Normalisierung älterer aktiver Verbindungen -- `nc-connector-*-cleanup/switch/cutover` – Legacy-Migrationshelfer - `include/self_update.inc.php` – Self-Updater - `include/album_shares.inc.php` – geschützte Albumfreigaben - `include/public_selection.inc.php` – Fotoauswahl @@ -215,14 +268,18 @@ Wichtige Dateien und Verzeichnisse: - administrative Schreibaktionen verwenden Piwigos CSRF-Schutz; - Connector-Zugangsdaten werden verschlüsselt gespeichert; - Wizard-Geheimnisse werden nicht in Browser-Web-Storage persistiert; -- Storage-Mounts werden explizit zugeordnet und validiert; +- bestehende lokale Storage-Mounts werden explizit zugeordnet und validiert; - SQL-View-Namen werden vor Verwendung validiert; -- gefährliche technische Pfade sind nicht Teil des normalen Wizard-Happy-Paths; - produktive Piwigo-API ist versionsgebunden; - Originalbilder werden vom Connector nicht gelöscht; +- der neue WebDAV-Weg soll Originalbilder nicht dauerhaft lokal speichern; - Update-Pakete werden an Commit und Hash gebunden; -- Root-Helfer prüfen CLI-/Root-Ausführung, bevor sie Systemdienste oder `/etc`-/`/var/lib`-Daten verändern. +- bestehende Verbindungen bleiben während der WebDAV-Entwicklung unangetastet. ## Entwicklungsstand -`0.9.4.x` ist der aktuelle Entwicklungsblock. Der lokale NC Connector ist End-to-End produktiv im Einsatz. Der Verbindungsassistent und die Verwaltung werden weiter aus Endnutzersicht konsolidiert. Ein vollständig entfernter Nextcloud-Adapter ohne direkten PostgreSQL-/Storage-Zugriff ist noch nicht umgesetzt. +`0.9.5.x` ist der aktuelle Entwicklungsblock. Der bestehende lokale NC Connector bleibt produktiv und wird nicht durch den experimentellen WebDAV-Weg ersetzt. + +Der nächste konkrete Schritt ist die rückwärtskompatible Verbindungsschicht für `webdav-placeholder`: verbindungseigene Nextcloud-Zugangsdaten speichern, neuen Source-Modus in Wizard/Reconcile/Runtime ergänzen und danach eine neue Testverbindung durch den bestehenden Shadow Tree und Piwigo-Sync schicken. + +Den detaillierten aktuellen Plan enthält `CURRENT_STATUS.md`.