Piwigo_Bratonien_Tools/CURRENT_STATUS.md

Aktueller Entwicklungsstand

Stand: 18.08.2026

Plugin

• Aktuelle Plugin-Version: 0.9.5.5
• Aktueller Entwicklungsblock: NC Connector – WebDAV-basierter Quellenweg bei vollständigem Erhalt des bestehenden produktiven Wegs
• GitHub ist das führende Repository.
• Das private Gitea-System bleibt Mirror/Fallback.

Produktiver Stand

Der bestehende lokale NC Connector bleibt vollständig erhalten und ist weiterhin der produktive Referenzweg.

Aktuell vorhandene Quellenmodi:

• legacy-view
• user-shares
• selected-fileids

Diese Modi dürfen durch die neue WebDAV-Entwicklung weder automatisch migriert noch deaktiviert, überschrieben oder in ihrer Laufzeitlogik verändert werden.

Der bestehende Connector kann weiterhin:

• Nextcloud-Quellen in einen Shadow Tree überführen;
• Ordner als physische Piwigo-Alben synchronisieren;
• Root-Dateien als Orphans registrieren;
• entfernte Quellen aus Piwigo entfernen, ohne Nextcloud-Originale zu löschen;
• neue Connector-Alben privat anlegen;
• Piwigo API-first synchronisieren und bei Bedarf auf einen verbindungseigenen Login-Fallback zurückfallen;
• mehrere aktive Verbindungen über die gemeinsame Runtime verarbeiten.

0.9.5.4

• Neuer experimenteller Builder runtime/lib/build_webdav_placeholder_source.py hinzugefügt.
• Der Builder liest eine Nextcloud-Quelle rekursiv über WebDAV und erzeugt eine lokale Platzhalterstruktur sowie ein Mapping.
• Es werden keine Originalbilder heruntergeladen.
• Platzhalter sind extrem klein; der derzeitige Builder verwendet ein 1x1-GIF mit wenigen Dutzend Byte.
• Der bestehende produktive Sync wurde dafür nicht umgeschaltet.

0.9.5.5

Das Löschen von Connector-Verbindungen wurde gegen unterschiedliche Dateibesitzer zwischen Webserver und Runtime abgesichert.

Vorher konnte das Löschen scheitern, wenn PHP keinen Tombstone im Connector-Statusverzeichnis anlegen durfte. Jetzt gilt:

• das Löschen der Verbindung darf nicht von Schreibrechten auf Runtime-Dateien abhängen;
• die Verbindung wird aus der Piwigo-Datenbank entfernt;
• verwaiste Runtime-Dateien werden beim nächsten Connector-Lauf vor der Synchronisierung bereinigt;
• andere bestehende Verbindungen bleiben unangetastet.

Architektur – unverändert produktiver Weg

• Nextcloud ist Quelle der Originalbilder.
• Piwigo verwendet einen Shadow Tree unter dem Galeriepfad.
• Der bisherige Weg arbeitet mit lokalen, bereits vorhandenen Speicherpfaden und Symlinks auf die Originale.
• PostgreSQL-/View-/Storage-Mapping-Logik bleibt für bestehende Verbindungen erhalten.
• Runtime-Konfigurationen: /etc/bratonien-tools/nc-connector/connection-*.conf
• State: /var/lib/bratonien-tools/nc-connector/connection-ID
• Öffentlicher Admin-Status: Piwigo _data/bratonien-tools/nc-connector-status/
• Runner: runtime/run-all.sh
• Einzelverbindung: runtime/sync.sh
• Shadow Tree: runtime/lib/shadow_tree.py

Neuer WebDAV-Weg – Zielbild

Der neue Weg soll als zusätzlicher eigener Quellenmodus entstehen, zum Beispiel:

• webdav-placeholder

Er wird ausdrücklich neben den bestehenden Modi entwickelt.

Rahmenbedingungen

Der neue Weg darf nur Dinge voraussetzen, die bei einer normalen Piwigo-Installation und der bereits erforderlichen Linux-/PHP-Umgebung vorhanden sind.

Nicht als Voraussetzung zulässig:

• Rootzugriff des Betreibers;
• zusätzliche Host-Mounts;
• FUSE;
• davfs;
• rclone;
• zusätzliche Systempakete nur für den Connector;
• PostgreSQL-Zugriff auf die Nextcloud-Datenbank;
• occ-Adminzugriff;
• Wissen über Nextcloud-Storage-IDs oder Backend-Pfade.

Benötigt werden sollen nur:

• Nextcloud-Adresse;
• normaler Nextcloud-Benutzer bzw. App-Passwort;
• WebDAV-Zugriff auf genau die Inhalte, die dieser Benutzer sehen darf;
• Piwigo selbst und das Plugin.

Grundidee

WebDAV wird nicht in einen Linux-Dateipfad umgewandelt.

Stattdessen:

1. Das Plugin liest die ausgewählten Nextcloud-Verzeichnisse per WebDAV/PROPFIND.
2. Es erfasst Ordner, Dateinamen, Datei-ID, MIME-Typ, Größe, ETag und WebDAV-Pfad.
3. Für jedes Bild wird nur ein winziger lokaler Platzhalter bereitgestellt.
4. Der Shadow Tree behält seine Rolle als Piwigo-Quelle und enthält die reale Ordner-/Dateinamensstruktur.
5. Die Shadow-Tree-Einträge verweisen auf Platzhalter statt auf das Nextcloud-Original.
6. Ein separates Mapping verknüpft Shadow-Tree-Pfad mit Nextcloud-Verbindung, Datei-ID und WebDAV-Pfad.
7. Piwigo soll die Bilder dadurch zunächst als vorhandene physische Einträge erkennen können.
8. Für echte Bilddaten muss das Plugin bei Bedarf das Original über WebDAV lesen.

Anzeige und Derivate

Ziel ist nicht, Originale dauerhaft nach Piwigo zu kopieren.

Vorgesehener Ablauf:

• Piwigo kennt Album und Bild über Shadow Tree/Platzhalter.
• Wenn ein Piwigo-Derivat noch fehlt, wird das Original einmal über WebDAV gelesen.
• Piwigo erzeugt daraus sein normales lokales Derivat in _data/i/.
• Weitere Aufrufe verwenden den vorhandenen Piwigo-Derivat-Cache.
• Das Nextcloud-Original bleibt ausschließlich in Nextcloud.
• Beim tatsächlichen Abruf eines Originals muss die Quelle erneut über WebDAV gelesen werden.

Gemessene WebDAV-Performance

Realer Test vom Piwigo-System auf ein Nextcloud-Bild mit 16.091.204 Byte:

Interne Nextcloud-Adresse:

• Zeit: 1,829 s
• Geschwindigkeit: 8.796.915 Byte/s

Externe Nextcloud-Adresse:

• Zeit: 1,865 s
• Geschwindigkeit: 8.627.524 Byte/s

Die externe Verbindung war damit in diesem Test nur ungefähr 2 % langsamer als die interne Verbindung.

Folgerung für den Plan:

• WebDAV ist für bedarfsweisen Zugriff auf Originale performant genug, um den Ansatz weiterzuverfolgen.
• Entscheidend ist, dass Piwigo-Derivate normal lokal gecacht werden und WebDAV nicht bei jedem Thumbnail-Aufruf erneut angesprochen wird.

Bereits vorhandener WebDAV-Baustein

runtime/lib/build_webdav_placeholder_source.py

Aufgabe:

• WebDAV rekursiv lesen;
• keine Originalbilder herunterladen;
• lokale Platzhalterquelle erzeugen;
• Manifest und WebDAV-Mapping erzeugen.

Dieser Builder ist aktuell nur ein Baustein. Er ist noch nicht als vollständiger Connection-Modus in Wizard, Secret-Speicherung, Reconcile und Runtime integriert.

Noch notwendige Umsetzung für webdav-placeholder

1. Verbindungstyp rückwärtskompatibel ergänzen

• neuer eigener SOURCE_MODE;
• bestehende drei Modi bleiben unverändert;
• keine automatische Migration alter Verbindungen.

2. Nextcloud-Zugang verbindungseigen speichern

Der aktuelle Wizard benutzt Nextcloud-Zugangsdaten bereits für WebDAV-Verzeichnisabfragen, speichert sie aber nicht in einer Form, die die spätere Runtime für WebDAV verwenden kann.

Das Secret-Format muss rückwärtskompatibel erweitert werden um:

• nextcloud_user
• nextcloud_password

Bestehende Secrets müssen weiterhin lesbar bleiben.

3. Wizard-Abschluss für WebDAV-Verbindungen

Eine neue WebDAV-Verbindung darf keine PostgreSQL- oder Storage-Mount-Pflicht haben.

Gespeichert werden müssen mindestens:

• Connection-Name;
• Nextcloud-Basis-URL;
• Nextcloud-Benutzer;
• verschlüsseltes Nextcloud-Passwort/App-Passwort;
• ausgewählte WebDAV-Wurzeln;
• Piwigo-Galeriepfad;
• Piwigo-Authentifizierung für den Sync, sofern benötigt;
• source_mode=webdav-placeholder.

4. Reconcile und Runtime

runtime/reconcile.php muss WebDAV-Verbindungen gesondert behandeln:

• keine PostgreSQL-Konfiguration verlangen;
• keine Storage-Mappings verlangen;
• WebDAV-Zugang sicher in eine verbindungseigene Runtime-Datei überführen;
• bestehende lokale Verbindungstypen unverändert lassen.

runtime/sync.sh muss einen eigenen Zweig für webdav-placeholder erhalten.

5. Shadow Tree

Der bestehende Shadow Tree bleibt erhalten.

Der neue Builder muss nur eine Quelle erzeugen, die vom bestehenden shadow_tree.py verarbeitet werden kann. Ein kompletter Umbau des Shadow Trees ist nicht vorgesehen.

6. Piwigo-Erkennung testen

Erster PoC:

• kleine neue WebDAV-Testverbindung anlegen;
• einen kleinen ausgewählten Ordner verwenden;
• Platzhalterquelle bauen;
• bestehenden Shadow Tree erzeugen;
• Piwigo synchronisieren;
• prüfen, ob Albumstruktur und Bilder korrekt registriert werden.

Der bestehende produktive Connector bleibt währenddessen aktiv und unverändert.

7. Echte Bilddaten statt Platzhalter ausliefern

Erst wenn Piwigo die Platzhalterstruktur korrekt registriert, wird der zweite Teil umgesetzt:

• Piwigo-Anforderung einem WebDAV-Mapping zuordnen;
• echtes Original bei Bedarf über WebDAV lesen;
• Piwigo-Derivate aus der echten Quelle erzeugen;
• normale Piwigo-Derivate weiterverwenden;
• keine dauerhafte Originalkopie in Piwigo.

8. Lastverhalten absichern

Vor einer produktiven Umstellung muss geprüft werden:

• Verhalten bei vielen gleichzeitig noch ungecachten Bildern;
• parallele WebDAV-Abfragen;
• Derivat-Erzeugung;
• Fehlerfall bei nicht erreichbarer Nextcloud;
• geänderte oder gelöschte Remote-Dateien;
• Cache-Invalidierung bei geändertem ETag.

Migrationsregel

Der bisherige Weg bleibt so lange vollständig erhalten, bis der WebDAV-Weg funktional vollständig ist.

Es gibt bis dahin keine automatische Migration bestehender Verbindungen.

Erst nach erfolgreichem End-to-End-Test von:

• Verbindungsanlage;
• Verzeichnisauswahl;
• Shadow Tree;
• Piwigo-Registrierung;
• echter Bildausgabe;
• Derivat-Cache;
• Änderungserkennung;
• Löschen/Deaktivieren;
• Fehlerbehandlung

kann über eine freiwillige Migration bestehender Verbindungen entschieden werden.

Sicherheit und Datenhaltung

• Nextcloud-Originale werden nicht gelöscht.
• Nextcloud-Originale werden im neuen WebDAV-Weg nicht dauerhaft nach Piwigo kopiert.
• Lokale Piwigo-Derivate sind ausdrücklich erlaubt und Teil des normalen Piwigo-Caches.
• Connector-Zugangsdaten werden verschlüsselt gespeichert.
• Wizard-Secrets bleiben serverseitig.
• Bestehende Verbindungen bleiben während der Entwicklung unangetastet.
• Mutierende Admin-Aktionen verwenden Post/Redirect/Get.
• Self-Updates sind an einen konkreten Commit und SHA-256 gebunden.

Nächster konkreter Entwicklungsschritt

Rückwärtskompatible Verbindungsschicht für webdav-placeholder bauen:

1. Secret-Format um verbindungseigenen Nextcloud-Zugang erweitern.
2. neuen Source-Modus in Datenmodell/Reconcile/Runtime ergänzen.
3. Wizard so erweitern, dass eine WebDAV-Verbindung ohne PostgreSQL und ohne Storage-Mapping abgeschlossen werden kann.
4. danach eine neue Testverbindung anlegen und den Platzhalter-PoC durch den bestehenden Shadow Tree und Piwigo-Sync schicken.