Piwigo_Bratonien_Tools/CURRENT_STATUS.md

Aktueller Entwicklungsstand

Stand: 17.08.2026

Plugin

• Aktuelle Plugin-Version: 0.9.3.16
• Aktueller Entwicklungsblock: NC Connector – Verbindungsverwaltung / laufende Optimierung
• NC Connector ist Feature 10 und noch nicht vollständig abgeschlossen.
• Solange dieser Optimierungsblock läuft, bleibt die Version im Bereich 0.9.3.x.

Aktueller GitHub-Stand

Der lokale NC Connector ist für den aktuellen Bratonien-Einsatz inzwischen End-to-End funktionsfähig.

Erfolgreich umgesetzt und getestet:

• Nextcloud-Freigaben vom Typ folder und file werden aus der Source-View gelesen.
• Das Manifest führt beide Freigabetypen korrekt.
• Ordnerfreigaben werden als Verzeichnisbaum im Shadow Tree gespiegelt.
• Einzeldateifreigaben werden als Symlink direkt im Galerie-Root angelegt.
• Einzeldateien werden anschließend als echte Piwigo-Orphans ohne Albumzuordnung registriert.
• Entfernte Einzeldateifreigaben werden beim normalen Connector-Lauf aus dem Shadow Tree und aus Piwigo entfernt.
• Das Nextcloud-Original bleibt bei allen Löschvorgängen unangetastet.
• Der normale Connector-Lauf führt klassischen Piwigo-Dateisync und Orphan-Abgleich automatisch hintereinander aus.
• Der gemeinsame systemd-Timer bratonien-nc-connector.timer kann wieder produktiv verwendet werden.
• Connector-getriggerte neue physische Alben werden standardmäßig privat angelegt, damit neu importierte Inhalte nicht ungeordnet öffentlich erscheinen.

Architektur NC Connector

• Nextcloud bleibt die einzige dauerhafte Quelle der Originalbilder.
• Piwigo erhält nur die für die Galerie benötigte Verzeichnis-/Symlink-Struktur und erzeugt daraus seine Derivate und Cache-Dateien.
• Der Connector arbeitet mit einem PostgreSQL-Leser und den Views piwigo_showcase_sources und piwigo_showcase_activity.
• Laufzeitdaten liegen unter /var/lib/bratonien-tools/nc-connector/....
• Verbindungs-Konfigurationen liegen unter /etc/bratonien-tools/nc-connector/connection-*.conf.
• Der Shadow Tree enthält Verzeichnisse und Symlinks, keine Kopien der Originaldateien.
• Alle aktivierten Verbindungen werden über runtime/run-all.sh gemeinsam verarbeitet.

Nextcloud-Freigabemodell

Der Connector unterstützt zwei Fälle:

1. komplette Ordner werden geteilt;
2. einzelne Bilder werden direkt geteilt.

Verarbeitung:

• folder -> Verzeichnisstruktur spiegeln und über Piwigos klassische Dateisynchronisierung als physische Albumstruktur einlesen;
• file -> Symlink direkt im Galerie-Root und anschließende Registrierung als Piwigo-Orphan.

Für einzelne Dateien wird kein künstlicher Unterordner erzeugt.

Manifest / Shadow Tree

runtime/lib/build_manifest.py unterstützt zwei View-Schemata:

• modern: share_id, item_type, display_name, storage_id, source_path;
• legacy: share_id, display_name, storage_id, source_path.

Bei einer Legacy-View wird der Typ nach Auflösung des Storage-Pfads über Datei oder Verzeichnis bestimmt.

Das Manifest führt danach in beiden Fällen:

share_id, item_type, display_name, source_path

runtime/lib/shadow_tree.py verarbeitet daraus:

• folder -> Verzeichnisstruktur spiegeln;
• file -> Symlink direkt im Galerie-Root.

Activity-Gate

Das Activity-Gate berücksichtigt neben dem Nextcloud-Aktivitätsstand auch die Signatur der aktuell sichtbaren Freigaben.

Damit werden Strukturänderungen an den Shares auch dann erkannt, wenn sie nicht zuverlässig durch einen reinen Maximalwert der Nextcloud-Aktivität abgebildet werden.

Weiterhin vorhanden:

• Quiet-Time;
• maximale Wartezeit;
• periodischer Full-Sync;
• Verbindungsspezifischer State.

Piwigo-Synchronisation

Physische Alben

runtime/lib/piwigo-db-sync.pl meldet sich an Piwigo an und löst die normale Dateisynchronisierung für die physischen Albumverzeichnisse aus.

Connector-getriggerte Neuanlagen werden dabei mit privatem Standardstatus verarbeitet.

Root-Dateien / Orphans

Piwigos klassische Dateisynchronisation kann Dateien direkt unter dem Galerie-Root nicht als neues Element einem physischen Album zuordnen.

Deshalb verarbeitet bratonien.nc.syncOrphans diese Dateien separat.

Für neue Root-Dateien:

• wird ein normaler Eintrag in piwigo_images angelegt;
• storage_category_id bleibt NULL;
• es wird kein Eintrag in piwigo_image_category erzeugt;
• Metadaten und Piwigo-Aktivität werden über vorhandene Piwigo-Funktionen aktualisiert;
• die Datei erscheint im Batch Manager unter With no album / Orphans.

Für entfernte Root-Dateien wird nur der Piwigo-Datenbankeintrag entfernt. Das Nextcloud-Original bleibt unberührt.

API-Weg

Es existieren zwei eigene Webservice-Endpunkte:

• bratonien.nc.sync – vollständiger read-only Paritätstest des klassischen Piwigo-Syncs;
• bratonien.nc.syncOrphans – dedizierte Root-Orphan-Synchronisation mit Simulation und produktivem Modus.

Beide Wege sind aktuell für Piwigo 16.4.0 freigegeben.

Erfolgreiche Live-Tests

Bestätigt wurden:

• Ordnerfreigaben werden korrekt eingelesen.
• Eine einzelne Nextcloud-Dateifreigabe wurde im Manifest als file erkannt.
• Der zugehörige Symlink wurde direkt im Galerie-Root erzeugt.
• Die Orphan-Simulation erkannte die Datei als new_orphans = 1 ohne Datenbankschreibzugriff.
• Der produktive Lauf registrierte die Datei als echtes Piwigo-Orphan.
• Die Piwigo-Fotoanzahl stieg dabei entsprechend an.
• Nach Entfernen der Nextcloud-Freigabe meldete der normale Connector-Lauf files = 0 und Piwigo-Orphans synchronisiert: +0 / -1.
• Der Root-Symlink wurde entfernt.
• Ein anschließender Orphan-Abgleich fand keine Restdatei mehr.
• Der automatische Timer kann wieder regulär laufen.

Sicherheit / Betriebsmodell

• Nextcloud bleibt Eigentümer der Originaldateien.
• Der Connector löscht keine Originaldateien aus den Storage-Mounts.
• Zugangsdaten werden nicht in das Repository geschrieben.
• Aktive Verbindungen verwenden getrennte Konfigurations-, Secret- und State-Dateien.
• Der Piwigo-Sync wird nur für aktivierte Connector-Verbindungen ausgeführt.
• Neue Connector-Alben werden privat angelegt, bevor sie regulär einsortiert oder freigegeben werden.

Bekannte offene Punkte

Der lokale Connector-Grundbetrieb ist abgeschlossen. Offen bleiben vor allem die nächsten Ausbauschritte:

• Remote-Nextcloud-Adapter;
• weitere Bereinigung und Vereinfachung der Verbindungsverwaltung im Admin-UI;
• endgültige Entscheidung, welche Legacy-/Migrationshilfen nach stabiler Betriebsphase noch im Plugin verbleiben sollen;
• weitere Komfortfunktionen für Status, Diagnose und Administration.

Repository-Fallback

Während der Entwicklung bleibt GitHub das führende Repository. Zusätzlich existiert auf dem privaten Gitea-System ein Pull-Mirror als Ausfall-/Fallback-Ebene.