- Python 87.9%
- Svelte 5.4%
- HTML 3.2%
- TypeScript 2.4%
- CSS 0.8%
- Other 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .github/workflows | ||
| benchmarks | ||
| config | ||
| datasets/reference-v1 | ||
| docs | ||
| frontend | ||
| scripts | ||
| src | ||
| tests | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| AGENTS.md | ||
| BETA_READINESS.md | ||
| compose.ml.yaml | ||
| compose.omv.registry.yaml | ||
| compose.omv.yaml | ||
| compose.source-write.yaml | ||
| compose.yaml | ||
| Dockerfile | ||
| Dockerfile.ml | ||
| facet-integration-plan.md | ||
| pyproject.toml | ||
| README.md | ||
| requirements.txt | ||
| setup_facet.py | ||
| setup_facet_install.py | ||
| uv.lock | ||
Family Photo Manager Beta
Family Photo Manager bereitet große Familien-Fotoarchive für Immich, PhotoPrism und andere Fotoverwaltungen vor. Bestehende Ordner lassen sich erfassen, Duplikate prüfen, Bilder bewerten und konkrete Dateiaktionen nachvollziehbar planen. Die WebUI ist der bevorzugte Bedienweg; eine CLI bleibt für Administration und Automatisierung verfügbar.
Aktuelle Beta: 0.4.0b1 (Docker-Tag 0.4.0-beta.1). Ein früherer Stand wurde mit
etwa 17.000 Fotos erprobt. Das ist kein Nachweis für beliebige Archive mit 500.000
Dateien oder jedes NAS-Dateisystem. Aktuelle Prüfergebnisse und nach Schwere
geordnete Grenzen stehen in BETA_READINESS.md.
Was die Beta kann
- Read-only Inventar mit vollständigem BLAKE3, ExifTool-Metadaten und wiederholbaren, inkrementellen Scans; Unterbrechungen markieren nicht erreichte Dateien nicht als fehlend.
- Familien und Quellen, exakte Duplikate, optionale dHash/pHash-Ähnlichkeit, RAW/JPEG-/Sidecar-Beziehungen, Lightroom-Schutz und Datumsprobleme.
- Webprüfung mit Vorschauen, menschlichen Sternen, konkreter/festgeschriebener Auswahl, getrennten Analyseergebnissen und persistenten Aufträgen.
- Gespeicherte Pläne, Dry-run, verifizierte Kopien, separat freigegebene Moves und geprüfte Löschlisten. Export der Dateiaktionen als JSONL-Manifest.
- Optionale technische Bewertung und ausdrücklich konfigurierte lokale Modelle für Gesichter/Ästhetik. Familienvorschläge benötigen bestätigte Personen und eine Benutzerentscheidung; sie ändern keine Quellenzugehörigkeit.
Nicht enthalten: dauerhafte Galerie, Foto-Backup, Metadateneditor, automatische Foto-Reparatur, Modelltraining oder mitgelieferte Modellgewichte. Ein direkter Upload/Import in Immich oder PhotoPrism ist nicht implementiert. Geschlossene Augen, semantische Suche und eine allgemeine „bestes Serienbild“-Auswahl sind keine zugesicherten Betafunktionen. Der vorhandene Immich-ML-Adapter ist experimentell und auf Immich 3.3.0 festgelegt. Gesichts-/CLIP-Inferenz wurde mit einem echten GPU-Dienst geprüft; Testbericht.
Schutz der Originale
Für wertvolle Fotos ist weiterhin ein separates, geprüftes Backup erforderlich. Beginne mit einer unabhängigen Testdatenbank und einem kleinen Testbestand. Quellen sind im Standard-Compose read-only. Alle Dateiaktionsfreigaben sind aus. Ein Score, Ähnlichkeit oder eine Auswahl führt niemals selbst zu einer Löschung.
Moves entfernen Quellen erst nach vollständiger BLAKE3-Prüfung und dauerhafter Zielveröffentlichung der übertragenen Gruppe. Unbekannte Ziele werden nicht überschrieben. Jeder Ausführungsversuch braucht einen frischen Dry-run und eine Bestätigung. Ein Journal dokumentiert die Operation; Löschen hat keinen Undo. Während freigegebener Dateiaktionen dürfen keine anderen Programme die beteiligten Quellen/Ziele verändern. POSIX-Sperren koordinieren unsere Prozesse, nicht externe Editoren, SMB-Clients oder Sync-Werkzeuge.
Docker starten — neue Testinstallation
Für die Bedienung über die OMV-Weboberfläche: OMV-Compose-Plugin.
Die eigenständige compose.omv.yaml verwendet Environment-Variablen für LAN-Zugriff,
Ersteinrichtung und Kopierfreigabe; keine TOML-Datei erforderlich.
compose.omv.registry.yaml bezieht das geprüfte AMD64-Image aus
git.maxbuelk.de/vibe/photo-manager:0.4.0-beta.1-omv (Pull → Up im Plugin).
Die manuelle OMV-Testanleitung bleibt als Alternative verfügbar.
Benötigt werden Docker Engine und Compose v2-kompatible CLI auf einem Linux-Host.
Intel-/AMD-Systeme einschließlich Ryzen 3200G verwenden linux/amd64. Node und uv
werden auf dem NAS nicht benötigt; das Image baut die WebUI in einer eigenen Stufe.
Das geprüfte Beta-Image ist in der Forgejo-Registry verfügbar; Zugang und Digest
sind in der OMV-Anleitung beschrieben. Alternativ
lokal bauen oder ein geprüftes Image über docker load übernehmen.
Im ausgecheckten Repository:
test -e .env || cp .env.example .env
In .env echte vorhandene Hostpfade eintragen:
FPM_IMAGE=family-photo-manager:0.4.0-beta.1
FPM_SOURCE=/srv/fotos/testarchiv
FPM_OUTPUT=/srv/foto-ausgabe/test
FPM_UID=1000
FPM_GID=1000
Die Beispielpfade müssen ersetzt werden. Eine nicht erreichbare Fotofreigabe wiederherstellen, niemals durch einen leeren Ordner ersetzen. Ein Ausgabeordner kann bewusst separat angelegt werden und muss außerhalb registrierter Quellen liegen. Bind-Mounts erstellen fehlende Hostpfade nicht automatisch.
config/docker/app.toml prüfen. Die neuen Container sehen das Quellarchiv unter
/sources/archive, die Ausgabe unter /output. UID/GID 1000 besitzen die neu
angelegten Image-Verzeichnisse /data und /cache. Diese IDs müssen die Quellen
lesen und das gewählte Ausgabeziel schreiben dürfen. Bei abweichenden IDs zuerst
auch die Eigentümer der Anwendungsvolumes passend einrichten; ein geänderter
Wert allein ändert keine Dateirechte. Keine rekursive Rechteänderung an Fotos und
kein App-/Worker-Betrieb als root.
docker compose config --quiet
docker compose build app
# Bei einem bereits geladenen fertigen Image entfällt der Build.
docker compose run --rm --no-deps app --db /data/inventory.sqlite init
docker compose run --rm --no-deps app --db /data/inventory.sqlite setup-account
docker compose up -d --wait --wait-timeout 120
docker compose ps
Alternativ zur manuellen Ersteinrichtung kann der App-Container mit FPM_INIT=1
eine fehlende Datenbank samt Zugangscode anlegen. Vorhandene Inventare werden
weder automatisch migriert noch zurückgesetzt; der Worker wartet auf die gesunde App.
Der Code steht beim ersten Start im App-Log.
Den einmaligen Zugangscode privat aufbewahren. Im Browser genau
http://localhost:8765 öffnen, Code eingeben und ein Passwort wählen.
127.0.0.1 ist eine andere Origin und wird mit der Standardkonfiguration abgewiesen.
Der Port ist nur an Host-Loopback gebunden. Bei einem entfernten NAS kannst du
den SSH-Tunnel aus der OMV-Anleitung
verwenden oder eine exakte LAN-/Proxy-Origin konfigurieren;
Details unter Betrieb und Zugang. Nicht einfach den Port
öffentlich freigeben. Es gibt ein lokales Administratorkonto; Familien sind keine
voneinander abgeschotteten Benutzerkonten.
Bestehende Installation: Die obigen init-/setup-account-Schritte sind kein
Upgrade-Rezept. Zuerst App/Worker stoppen, konsistentes SQLite-Backup erstellen,
an einem neuen Pfad wiederherstellen und explizit migrieren. Historische Quellpfade
müssen im Container erhalten bleiben oder administrativ neu gebunden werden.
Auch ein neuer Compose-Projektname kann andere, leere Volumes auswählen: bisherigen
Projektnamen mit docker compose -p NAME beibehalten. Siehe
Migration und Update.
Der Workflow in der WebUI
- Bibliothek: Familie und konkrete Quelle registrieren, dann „Erfassen“.
Bestehende Ordner müssen vorher nicht umsortiert werden. Datenbank/Cache und
90_Systemdürfen nicht Teil einer registrierten Fotoquelle sein. - Analysieren: Basisanalyse starten, optional Ähnlichkeit/technische Bewertung. Einzelne fehlende RAW-Vorschauen sind kein Nachweis beschädigter Originale.
- Prüfen / Bewertungen: Duplikate und Varianten vergleichen, Keeper/Ablehnung ausdrücklich entscheiden, Sterne vergeben und konkrete Dateien auswählen.
- Anwenden: Auswahl als Plan speichern, Positionen und Ziele prüfen, Dry-run
ausführen und erst dann die Aktion bestätigen. Standardmäßig bleibt Ausführung
gesperrt. Für Kopieren zuerst
allow_copy = truesetzen und beide Dienste neu erstellen. Move/Delete benötigen separate Fähigkeiten und bewusste schreibbare Worker-Mounts; zunächst nur mit synthetischen Testbeständen erproben. - Ergebnis kontrollieren: Auftrag/Dateifortschritt und Zielbestand prüfen, JSONL-Manifest herunterladen. Den geprüften Dateisystemexport anschließend im gewünschten Fotosystem importieren.
Die Übersicht nennt den nächsten Schritt und dessen Begründung. „Aufträge“ zeigt Fortschritt, Probleme und neue Versuche. Browser-/API-Neustart beendet den Worker nicht. Unterbrochene Worker-Aufträge setzen sich nicht automatisch fort.
Was dauerhaft gespeichert wird
| Speicher | Inhalt und Verantwortung |
|---|---|
app-data → /data |
SQLite inklusive Benutzerzugang, Entscheidungen, Plänen, Job- und Ausführungsjournalen; auf lokalem Datenträger sichern |
preview-cache → /cache |
Regenerierbare Vorschauen, standardmäßig 1 GiB Budget; Worker schreibt, API liest |
./config/docker → /config:ro |
Geprüfte Startkonfiguration; separat sichern |
FPM_SOURCE → /sources/archive:ro |
Bestehende Fotos als Bind-Mount; werden nicht in ein Anwendungsvolume importiert |
FPM_OUTPUT → /output |
Bewusst gewählter Export; nur Worker hat einen schreibbaren Mount |
| Docker-Logs | Rotierendes stdout/stderr, maximal 3 × 10 MiB pro Dienst |
Backups der laufenden SQLite-Hauptdatei ohne WAL sind nicht ausreichend. Verwende
nach sicherem Stoppen die Backup-Funktion. docker compose down --volumes ist
kein Update-Schritt. Nach ausgeführten Moves/Löschungen ist eine alte Datenbank
allein kein sicherer Rollback.
Fehler melden
Version, Betriebssystem/Architektur, Dateisystem/Mountart, betroffene Aktion, Reproduktionsschritte und Erwartung angeben. Nur synthetische oder ausdrücklich freigegebene Dateien teilen. Diagnose lokal sammeln:
docker compose run --rm --no-deps app --version
docker compose ps
docker compose logs --no-color --since 30m app worker > family-photo-manager-beta.log
Auftragsbezogene Ereignisse lassen sich in der WebUI unter „Auftrag & technische
Details“ herunterladen. Logs, Fehler und Manifeste können private Dateipfade und
Namen enthalten. Vor einem Bugreport prüfen/anonymisieren. Keine Datenbank,
.env, Passwörter, Zugangscodes, Cookies oder ML-Tokens veröffentlichen. HTTP-
Zugriffslogs sind standardmäßig aus; Validierungsfehler spiegeln keine Eingaben.
Lokale Entwicklung und Kompatibilität
uv sync --locked --dev --group analysis --group decoders
uv run family-photo-manager --help
uv run --group analysis --group decoders pytest -q
uv run ruff check .
cd frontend
npm ci
npm run check
npm run build
npx playwright test
Python ≥3.12; geprüft wird 3.12. ExifTool ist für Scans nötig, FFmpeg für Video- Poster. Node wird nur für Entwicklung/Build benötigt. Docker verwendet Node 22.16.0. Weitere Betriebsbefehle, lokale Konfiguration und ML-Grenzen: Operations, Architektur, Projektziel, Repository-Struktur.
Der Anzeigename lautet Family Photo Manager, Distribution/CLI/Image heißen
family-photo-manager, das neue Python-Kommando ist python -m family_photo_manager.
Der bisherige CLI-Name photo-manager bleibt ein Alias. photo_manager bleibt die
bestehende Python-Implementierung, damit Imports, globale Sperren und Klassen nicht
verdoppelt werden. ~/.config/photo-manager, Cookie photo_manager, gespeicherte
Browserauswahl, Datenbankschema und Modell-/Rezeptkennungen behalten ihre Identität.
Compose akzeptiert bisherige PM_*-/PHOTO_*-Variablen als Fallback; neue FPM_*
Werte haben Vorrang. Vorhandene Hostordner und Inventarpfade werden nicht umbenannt.
Geplante Plattform- und Performance-Erweiterungen
Native macOS-Unterstützung, AMD64-/ARM64-Docker-Images, ressourcenabhängige Verarbeitung und wählbare schnelle/genaue ML-Profile sind im Plattform- und Performance-Plan beschrieben. Die automatische Ressourcensteuerung und die ML-Profilauswahl sind noch nicht implementiert. Der Plan ergänzt das verbindliche Projektziel.