# Piwigo Bratonien Tools Modular aufgebautes Piwigo-Plugin mit erweiterten Werkzeugen fuer Administration, Bildverarbeitung, Nextcloud-Anbindung und Frontend-Funktionen. Das Projekt ist aus der Bratonien-Piwigo-Installation entstanden, wird aber bewusst so entwickelt, dass die einzelnen Funktionen moeglichst neutral und auch ausserhalb dieser Installation nutzbar bleiben. Aktuelle Plugin-Version: **0.14.3** ## Funktionsumfang ### NC Connector Der NC Connector verwaltet Nextcloud-Quellen fuer Piwigo und fuehrt den regelmaessigen Abgleich mit einer Plugin-eigenen Sync-Runtime aus. Aktuell vorhanden: - mehrere Connector-Verbindungen im eigenen Datenmodell - lokale Verbindungen direkt in Bratonien Tools anlegen - verschluesselte Speicherung von PostgreSQL- und Piwigo-Sync-Zugangsdaten - lokaler Nextcloud-Adapter ueber PostgreSQL-Reader und explizite Storage-Mounts - Verifikation von PostgreSQL-Verbindung, Source-View, Activity-View und Storage-Mounts - native Aktivierung einer verifizierten Verbindung ohne vorherige Legacy-Installation - eigener State pro Verbindung unter `/var/lib/bratonien-tools/nc-connector/connection-ID` - gemeinsame Runtime-Konfiguration unter `/etc/bratonien-tools/nc-connector/` - Multi-Connection-Runner unter `runtime/run-all.sh` - gemeinsame Zeitsteuerung ueber `bratonien-nc-connector.timer` - Verbindungen koennen kontrolliert deaktiviert und danach geloescht werden - Anzeige von Timer-Status, letztem Lauf, letztem Ergebnis und naechstem geplanten Lauf - Plugin-eigene Sync-Runtime unter `runtime/` - Activity-Gate mit Quiet-Time, Max-Wartezeit und periodischem Full-Sync - Shadow Tree fuer Piwigo ohne Kopie der Originaldateien - Originalbilder bleiben an ihrer Nextcloud-/Storage-Quelle - lokale Piwigo-Derivate und Caches bleiben davon getrennt und koennen jederzeit neu erzeugt werden Die Runtime baut aus den freigegebenen Nextcloud-Quellen einen Piwigo-kompatiblen Shadow Tree. Dateien werden dabei nicht in eine zweite permanente Originalbibliothek kopiert, sondern ueber Symlinks auf die vorhandenen Storage-Mounts referenziert. #### Neuinstallation Eine frische Piwigo-Installation benoetigt keinen vorher vorhandenen `piwigo-sync` mehr. Der vorgesehene Ablauf ist: 1. lokale Nextcloud-Verbindung in Bratonien Tools anlegen 2. PostgreSQL, Views und Storage-Mounts pruefen 3. die angezeigte Root-Aktivierung ausfuehren 4. der Installer legt Runtime-Konfiguration, Secrets, State-Verzeichnis sowie systemd-Service und -Timer an 5. vor der Aktivierung wird ein echter Lauf mit der Plugin-Runtime getestet Der gemeinsame Service verarbeitet alle aktivierten `connection-*.conf`-Dateien nacheinander. Dadurch koennen mehrere Verbindungen mit einer gemeinsamen Zeitsteuerung betrieben werden. #### Migration bestehender Installationen Fuer bestehende Installationen, die zuvor den separaten `piwigo-sync` aus `Proxmox_Scripts` verwendet haben, existiert weiterhin ein kontrollierter Migrationsweg: - bestehende Verbindung einmalig importieren - Connector-Kopie unabhaengig verifizieren - kontrollierten Cutover vorbereiten - Connector-Timer aktivieren und Legacy-Timer deaktivieren - Runtime vom bisherigen `/opt/piwigo-sync` auf die Plugin-eigene Runtime umstellen - Legacy-Bestand entfernen - den verbliebenen Laufzeit-State anschliessend mit `nc-connector-normalize.php` in die native Struktur unter `/var/lib/bratonien-tools/nc-connector/` ueberfuehren Nach abgeschlossener Migration werden `/opt/piwigo-sync`, `/etc/piwigo-sync`, `piwigo-sync.service` und `piwigo-sync.timer` nicht mehr benoetigt. ### Bildcache - Piwigo-Bildcache gezielt leeren - vorhandene Bildderivate neu erzeugen - Cache-Aufbau als Worker-Prozess starten und abbrechen - Worker-Einstellungen verwalten - Originalbilder bleiben unangetastet ### Wasserzeichenverwaltung Erweiterte Wasserzeichenverwaltung als Alternative zur einfachen Piwigo-Standardkonfiguration. Unter anderem vorhanden: - eigene Wasserzeichendateien - Wasserzeichenprofile - Standardprofil - albumbezogene Regeln - getrennte Einstellungen fuer Positionierung und Verarbeitung - eigener Runtime-Filter fuer Piwigo-Bildderivate - Aktivierung und Deaktivierung der erweiterten Wasserzeichen-Engine Beim Aktivieren wird die bisherige Piwigo-Wasserzeichenkonfiguration gesichert und nicht dauerhaft ueberschrieben. Beim Deaktivieren kann sie wiederhergestellt werden. ### Bilddateien & Pfade Verwaltung eigener Bilddateien fuer die Piwigo-Installation. - Upload nach `local/bratonien/assets/` - Vorschau vorhandener Dateien - Anzeige von Dateiname, Pfad, Abmessungen und Dateigroesse - Dateien loeschen - konfigurierbare PHP-Uploadgrenzen ueber `.user.ini` - Validierung von `upload_max_filesize` und `post_max_size` ### Oeffentliche Bildauswahl fuer Batch Downloader Erweitert Albumseiten um die Moeglichkeit, einzelne Bilder fuer einen Download auszuwaehlen. - Auswahlmodus direkt in der Albumansicht - einzelne Bilder markieren - alle Bilder auswaehlen oder Auswahl aufheben - nur die ausgewaehlten Bilder an Batch Downloader uebergeben - vorhandene Piwigo- und Batch-Downloader-Berechtigungen bleiben wirksam - getrennte Freigabe fuer Gaeste, registrierte Benutzer und Gruppen **Abhaengigkeit:** Das Piwigo-Plugin Batch Downloader muss installiert und aktiv sein. Die ZIP-Erstellung wird nicht dupliziert. Bratonien Tools uebergibt lediglich die berechtigten Bild-IDs an Batch Downloader. ### Fortlaufende Bildtitel in der Stapelverarbeitung Erweitert Piwigos globale Stapelverarbeitung um die Aktion **Fortlaufende Bildtitel**. - arbeitet ausschliesslich mit der aktuellen Piwigo-Auswahl - frei waehlbares Titelpraefix - frei waehlbare Startnummer - einstellbare Stellenzahl mit fuehrenden Nullen - direkte Vorschau des resultierenden Titelformats - wahlweise alle ausgewaehlten Titel ueberschreiben oder nur leere beziehungsweise typische Kamera-/Importtitel ersetzen - Reihenfolge nach Dateiname, Aufnahmedatum oder aktueller Albumreihenfolge - vorhandene individuelle Titel koennen gezielt geschuetzt werden - physische Dateinamen werden nicht veraendert Beispiel: `Samt 2026 - 001`, `Samt 2026 - 002`, `Samt 2026 - 003`. Die Albumreihenfolge steht nur zur Verfuegung, wenn die Stapelverarbeitung auf genau ein Album ohne rekursive Unteralben gefiltert ist. ### Albumzugriff verwalten In der Administrationsoberflaeche koennen Alben direkt zwischen **oeffentlich** und **privat** umgeschaltet werden. - Albumliste mit Suchfeld - paginierte Darstellung - Umschalten des Zugriffs direkt aus Bratonien Tools - Verwendung nativer Piwigo-Icons fuer den Zugriffsstatus - beim Sperren eines Albums behaelt der aktuell handelnde Benutzer automatisch direkten Zugriff Der Schutz vor versehentlichem Selbstaussperren greift auch dann, wenn ein Album ueber Piwigos eigene Album-Zugriffsverwaltung von oeffentlich auf privat gesetzt wird. ### Geschuetzte Albumfreigaben Private Alben koennen direkt mit Bratonien Tools geteilt werden. ShareAlbum oder ein anderes Freigabe-Plugin ist dafuer nicht erforderlich. - eigener individueller Freigabelink pro Freigabe - Passwort **optional**; ohne Passwort reicht der nicht erratbare Link - Passwoerter werden nur als Hash gespeichert - integrierter Generator fuer sichere Passwoerter - erzeugte Passwoerter koennen angezeigt und kopiert werden - optionales Ablaufdatum - optionaler Freigabe-Tag, um mehrere Freigaben desselben Albums auseinanderzuhalten - eigener technischer Piwigo-Benutzer pro Freigabe - der technische Benutzer erhaelt nur Zugriff auf das freigegebene private Album - aktive Freigabelinks werden in der Administration angezeigt und koennen direkt kopiert werden - bei aelteren, nicht rekonstruierbaren Links kann ein neuer Link erzeugt werden; der bisherige Link wird dabei ungueltig - Freigaben koennen einzeln widerrufen werden - beim Widerruf wird der technische Benutzer samt Sitzungen und Albumrecht entfernt - wird das Album geloescht, werden zugehoerige Freigaben automatisch bereinigt Freigabe-Tokens werden nicht im Klartext gespeichert. Fuer aktuelle Freigaben kann der Link deterministisch aus dem technischen Freigabebenutzer, dem Album und einem lokal gespeicherten Secret rekonstruiert werden; in der Datenbank liegt nur der Hash des Tokens. ### Erweiterte Bildnavigation Auf der Bilddetailseite werden die vorhandenen Piwigo-Image-Maps weiterverwendet und responsiv neu aufgeteilt. Die Bildflaeche besteht aus vier Navigationszonen: - links: vorheriges Bild - rechts: naechstes Bild - oben mittig: zurueck zur Vorschau beziehungsweise Albumansicht - Mitte: PhotoSwipe / Vollbildansicht Die Zonen werden anhand der aktuell dargestellten Bildgroesse berechnet und bei Groessenaenderungen neu gesetzt. Fuer die sichtbaren Hover-Elemente werden neutrale CSS-Klassen bereitgestellt. Das Plugin enthaelt bewusst kein Bratonien-spezifisches Farbschema. Individuelles Branding kann ueber Theme- oder Custom-CSS erfolgen. ### Selbstaktualisierung Bratonien Tools kann den aktuellen Stand des GitHub-Repositories pruefen und sich aus der Administration heraus aktualisieren. - Versionspruefung gegen `main.inc.php` im GitHub-Repository - Update-Pruefung wird kurzzeitig zwischengespeichert - Updates duerfen nur vom Piwigo-Webmaster ausgefuehrt werden - Download des aktuellen `main`-Branches als ZIP - Pruefung auf `ZipArchive` und Schreibrechte des Plugin-Verzeichnisses - detailliertere Downloadfehler - Status wird nach Update-Pruefungen und Aktionen neu eingelesen ## Architektur Das Plugin ist modular aufgebaut. Administrative Werkzeuge werden getrennt implementiert und ueber eine zentrale Registry eingebunden. Frontend-, Runtime- und Piwigo-Integrationen liegen ebenfalls in eigenen Modulen. Wichtige Bestandteile: - `main.inc.php` - Plugin-Einstieg, Runtime-Module und Admin-Menue - `admin.php` - zentraler Admin-Controller - `include/tool_registry.inc.php` - Registry der administrativen Aktionen - `include/nc_connector.inc.php` - Connector-Datenmodell, Legacy-Import und gemeinsame Low-Level-Funktionen - `include/nc_connector_manage.inc.php` - native Connection-Verwaltung und Verifikation - `include/nc_connector_takeover.inc.php` - kontrollierte Legacy-Uebergabe - `include/nc_connector_system.inc.php` - Timer- und Laufzeitstatus ueber alle aktiven Verbindungen - `runtime/sync.sh` - Plugin-eigene Sync-Runtime einer Verbindung - `runtime/run-all.sh` - gemeinsamer Runner fuer alle installierten Verbindungen - `runtime/lib/activity_gate.py` - Activity-Gate und zeitgesteuerte Reconciliation - `runtime/lib/build_manifest.py` - Aufloesung der Nextcloud-Quellen auf konfigurierte Storage-Mounts - `runtime/lib/shadow_tree.py` - Aufbau des Piwigo-kompatiblen Shadow Trees ohne Kopieren der Originale - `runtime/lib/piwigo-db-check.php` - Konsistenzpruefung vorhandener Piwigo-Alben - `runtime/lib/piwigo-db-sync.pl` - Ausloesen der Piwigo-Dateisynchronisierung - `nc-connector-install.php` - native Aktivierung einer verifizierten Verbindung - `nc-connector-disable.php` - kontrollierte Deaktivierung einer aktiven Verbindung - `nc-connector-normalize.php` - Ueberfuehrung einer migrierten aktiven Verbindung in den nativen State- und Multi-Connection-Aufbau - `nc-connector-migrate.php` - einmaliger Migrationshelfer fuer bestehende Legacy-Installationen - `nc-connector-cutover-v2.php` - kontrollierter Legacy-Cutover - `nc-connector-runtime-switch.php` - Umstellung einer aktiven Legacy-Verbindung auf die Plugin-eigene Runtime - `nc-connector-legacy-cleanup.php` - kontrollierte Entfernung alter Sync-Scripts und systemd-Units - `include/public_selection.inc.php` - oeffentliche Fotoauswahl und Batch-Downloader-Anbindung - `include/picture_navigation.inc.php` - Einbindung der erweiterten Bildnavigation - `include/batch_titles.inc.php` - fortlaufende Titelvergabe in Piwigos Stapelverarbeitung - `include/album_lock.inc.php` - Laden und Umschalten des Album-Zugriffsstatus - `include/album_shares.inc.php` - Albumfreigaben, Freigabetokens und Schutz vor Selbstaussperren bei privaten Alben - `include/cache_worker_settings.inc.php` - Einstellungen fuer den Cache-Worker - `include/dependencies.inc.php` - Abhaengigkeitspruefungen - `include/watermark_*.inc.php` - Wasserzeichen-Engine und Runtime - `include/self_update.inc.php` - Versionspruefung und Selbstaktualisierung - `tools/album_rules.inc.php` - albumbezogene Regeln - `tools/asset_manager.inc.php` - Verwaltung eigener Bilddateien - `tools/image_cache.inc.php` - Cache-Verwaltung - `tools/watermark*.inc.php` - administrative Wasserzeichenmodule - `main-cache-build.php` - Cache-Aufbau im Worker-Prozess - `main-cache-status.php` - Statusschnittstelle fuer den Cache-Worker - `js/` - Frontend- und Admin-JavaScript - `css/` - strukturelles Plugin-CSS - `template/` - Admin- und Frontend-Templates - `maintain.class.php` - Piwigo-Lifecycle ## Neues administratives Tool hinzufuegen 1. Neue Implementierung unter `tools/` anlegen. 2. Datei in `include/tool_registry.inc.php` laden. 3. Handler in `bratonien_tools_get_tools()` registrieren. 4. Benoetigte Darstellung in der gemeinsamen Administrationsoberflaeche ergaenzen. Funktionen sollten moeglichst eigenstaendig bleiben und keine Bratonien-spezifische Gestaltung voraussetzen. ## Sicherheit Administrative Aktionen pruefen Piwigo-Berechtigungen und verwenden fuer schreibende Aktionen Piwigos CSRF-Schutz. Weitere Schutzmechanismen sind funktionsabhaengig, unter anderem: - verschluesselte Speicherung der Connector-Zugangsdaten mit einem lokalen Connector-Secret - PostgreSQL-Reader mit minimalen Leserechten fuer lokale Nextcloud-Verbindungen - explizite Storage-Zuordnungen statt automatischer Freigabe beliebiger Dateipfade - Verifikation von Datenbank, Views und Mounts vor einer Aktivierung - Runtime-Test vor der nativen Aktivierung - Root-only-Hilfsprogramme fuer systemd-, Secret- und State-Aenderungen - getrennte State-Verzeichnisse pro Connector-Verbindung - Originalbilder werden vom NC Connector nicht in eine zweite permanente Bibliothek kopiert - Validierung von Cache- und Dateipfaden - Filterung ausgewaehlter Bild-IDs gegen die aktuell berechtigte Bildmenge - Nutzung der von Piwigos Stapelverarbeitung validierten Auswahl fuer die fortlaufende Titelvergabe - gehashte Passwoerter und gehashte Freigabetokens fuer Albumfreigaben - nicht erratbare Freigabelinks auf Basis eines lokal erzeugten Secrets - eigene technische Benutzer mit minimalem Albumzugriff fuer Freigaben - automatische Bereinigung widerrufener und geloeschter Albumfreigaben - automatischer Erhalt des eigenen Zugriffs beim Umschalten eines Albums auf privat - Beibehaltung bestehender Piwigo- und Plugin-Berechtigungen - kontrollierte Uploadziele und Uploadgrenzen - kein Zugriff auf Originalbilder beim Leeren des Bildcaches - Webmaster-Pruefung, Schreibbarkeitspruefung und kontrolliertes temporaeres Arbeitsverzeichnis bei Selbstupdates ## Styling und Anpassung Bratonien Tools soll Funktion und Gestaltung voneinander trennen. Plugin-eigene Styles dienen daher nur der technischen Darstellung und Positionierung. Farben, Schatten, Hover-Effekte und individuelles Branding sollten ueber das aktive Piwigo-Theme oder Custom CSS umgesetzt werden. ## Entwicklungsstand Das Plugin befindet sich weiterhin in aktiver Entwicklung. Der NC Connector ist in Version 0.14.3 von der migrationsorientierten Uebergangsstruktur auf einen nativen Mehrverbindungs-Aufbau erweitert worden. Der Remote-Adapter ist der naechste noch offene Connector-Ausbauschritt.