Dokumentation

Diese Dokumentation richtet sich an Administratoren, die Wanmory auf einem NAS, Heimserver oder eigenen Rechner selbst hosten. Sie behandelt Installation, Konfiguration, den Betrieb des KI-Dienstes, die tägliche Nutzung, Systemeinstellungen und Wartung. Systemdesign und Algorithmen finden Sie unter Architektur.

Wanmory ist eine quelloffene, selbst gehostete private KI-Fotobibliothek. Sie besteht aus vier Containern: dem Go-Backend (server), dem Python-KI-Inferenzdienst (ml), der Datenbank PostgreSQL + pgvector (postgres) und mdns, das die LAN-Domain bekannt gibt. Alle Fotos, Metadaten, Vektoren und die Job-Warteschlange werden lokal gespeichert, ohne Abhängigkeit von einem Cloud-Dienst.

• Fotoverwaltung: nach Monaten gruppierte Zeitleiste, Alben und intelligente Alben, Bereinigung von Serien- und ähnlichen Fotos, Reisekarte, Diashows.
• KI-Funktionen: Gesichtserkennung und -gruppierung, Suche in natürlicher Sprache (Chinese-CLIP), Texterkennung (PP-OCR), Ästhetikbewertung (KI-Auswahl).
• Mehrere Mitglieder: eigene Konten, Löschrechte nach Eigentümerschaft, Anmeldeverlauf.

Variante 1: Installationsskript (empfohlen)

Auf einem 64-Bit-Rechner mit Docker ausführen:

curl -fsSL https://wanmory.com/install.sh | bash

Das Skript erledigt nacheinander Folgendes:

• Umgebungsprüfung: CPU-Architektur (amd64 / arm64) und 64-Bit-Userland, Verfügbarkeit von Docker und Docker Compose v2, freier Arbeitsspeicher und Speicherplatz.
• Interaktive Konfiguration: Installationsverzeichnis (Standard ~/wanmory), Port (Standard 8080, auf Belegung geprüft), LAN-Domain (Standard wanmory.local), Datenbankpasswort (standardmäßig zufällig) und Speicherort der Datenbank (standardmäßig das Docker-Volume pgdata, alternativ ein Verzeichnis auf einer lokalen Festplatte) sowie Zeitzone (Stadt oder Region eingeben und suchen, etwa shanghai, tokyo oder 北京; bei mehreren Treffern per Nummer wählen).
• Speicherorte: Datenverzeichnis (Vorschaubilder, Vorschauen und hochgeladene Fotos, Standard ./data) und KI-Modellverzeichnis (Standard ./models).
• Abfragen und Ausgaben des Skripts sind auf Englisch, damit sie in jedem NAS-Terminal korrekt angezeigt werden.
• Vorhandene Fotoordner: beliebig viele Ordner nacheinander hinzufügen, jeweils schreibgeschützt (empfohlen) oder mit Schreibzugriff eingebunden.
• Schreibt .env (Rechte 600); werden Fotoordner angegeben, zusätzlich docker-compose.override.yml, die Docker Compose automatisch einbezieht.
• Lädt die offizielle docker-compose.yml herunter (bei nicht erreichbarem GitHub automatisch von Gitee), prüft die Konfiguration, zieht die Images, startet die Dienste und gibt die Adresse aus, sobald alles bereit ist.

# Beispiel: nicht interaktiv nach /opt/wanmory installieren, Port 9000, NAS-Fotoordner einbinden
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

Variante 2: Manuelle Installation

1. 1
   Verzeichnis anlegen und Compose-Datei holen

   Legen Sie ein Verzeichnis für Compose-Datei, Daten und Modelle an und laden Sie die offizielle docker-compose.yml herunter:

   bashKopieren

   mkdir -p ~/wanmory && cd ~/wanmory
   curl -fsSLO https://raw.githubusercontent.com/i-dj/wanmory/main/docker/docker-compose.yml

2. 2
   (Optional) .env anlegen

   Erstellen Sie im selben Verzeichnis eine .env, um Standardwerte zu überschreiben. Ändern Sie im Produktivbetrieb unbedingt das Datenbankpasswort:

   .envKopieren

   WANMORY_DB_PASSWORD=durch-zufaellige-zeichenfolge-ersetzen
   WANMORY_PORT=8080
   WANMORY_TZ=Europe/Berlin
   WANMORY_VERSION=latest

3. 3
   Dienste starten

   Der erste Start lädt die Images und führt die Datenbankmigrationen automatisch aus:

   bashKopieren

   docker compose up -d
   docker compose ps        # prüfen, ob alle vier Dienste running / healthy sind

4. 4
   Aufrufen und einrichten

   Öffnen Sie http://wanmory.local:8080 (oder http://<Host-IP>:8080) im Browser, legen Sie wie angezeigt das Admin-Konto an und laden Sie dann unter „Systemeinstellungen → KI“ die Modelle herunter. Danach kommen vorhandene Fotos automatisch in die KI-Warteschlange.

Die offizielle Compose-Datei definiert vier Dienste: die Datenbank postgres, das App-Backend server, den LAN-Domain-Dienst mdns und den integrierten KI-Dienst ml. Was jede Einstellung bewirkt, steht direkt in der Datei:

# Offizielle Wanmory-Compose-Datei: im Verzeichnis dieser Datei docker compose up -d ausführen
# Variablen der Form ${VAR:-Standard} werden aus .env im selben Verzeichnis gelesen; ohne Wert gilt der Standard
services:
  # ── Datenbank: PostgreSQL 17 + pgvector ──────────────────────────
  # Speichert Foto-Metadaten, Personen, Alben, Einstellungen, Job-Warteschlange und Vektoren (HNSW-Index)
  # Kein Port veröffentlicht; nur im internen Compose-Netzwerk erreichbar
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # im Produktivbetrieb unbedingt in .env ändern
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # standardmäßig Named Volume pgdata; mit WANMORY_DB_DIR in diesem Verzeichnis. In Sicherungen aufnehmen
    healthcheck:                             # server wartet auf diesen Healthcheck und startet erst, wenn die DB bereit ist
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── App-Backend: Go-Programm mit eingebetteter Web-App ───────────
  # Zuständig für API, Uploads (tus), Job-Steuerung, Vorschaubilder und Rechte; führt beim Start DB-Migrationen aus
  server:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    environment:
      DATABASE_URL: postgres://wanmory:${WANMORY_DB_PASSWORD:-wanmory}@postgres:5432/wanmory
      WANMORY_ML_URL: http://ml:3003         # Adresse des integrierten KI-Dienstes; ein entfernter KI-Dienst wird unter „KI-Einstellungen“ eingetragen
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # Zeitzone, wenn EXIF keine enthält
      WANMORY_MDNS: "off"                    # im Bridge-Netz kommt kein Multicast an; die Domain gibt der mdns-Dienst unten bekannt
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # in der Web-App angezeigter Port, passend zur Portfreigabe
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # anfängliche LAN-Domain; nach Änderung in den Web-Einstellungen gilt diese
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # Host-Port:Container-Port
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ enthält hochgeladene Originale, thumbs/ Vorschaubilder und 1440px-Vorschauen
      # Vorhandene Fotoordner als Unterverzeichnisse von /photos einbinden, beliebig viele; :ro = schreibgeschützt; Scan alle 15 Minuten
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/kamera:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── LAN-Domain bekannt geben (mDNS) ──────────────────────────────
  # Gleiches Image wie server, startet nur den Unterbefehl mdns; gibt wanmory.local bekannt (in der Web-App änderbar)
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # Host-Netzwerk ist nötig, um LAN-Multicast zu senden und zu empfangen
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # fragt server regelmäßig nach der aktuellen Domain
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # wird bekannt gegeben, solange server nicht erreichbar ist
    depends_on:
      - server
    restart: unless-stopped
  # ── Integrierter KI-Dienst: FastAPI + ONNX Runtime, nur CPU ──────
  # Zustandslos; empfängt Vorschauen von server und liefert Gesichter, Vektoren und Text; kein Port veröffentlicht
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # bewahrt Modelldateien auf, sodass ein neu erstellter Container nichts erneut lädt
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # kein automatischer Download; ein Admin bestätigt zuvor Lizenzen und Speicherbedarf in der Web-App
    restart: unless-stopped
volumes:
  pgdata:

.env (Compose-Variablen)

Diese Variablen werden in docker-compose.yml verwendet; tragen Sie sie in die .env im selben Verzeichnis ein:

Container server (optional)

DATABASE_URL, WANMORY_ML_URL, WANMORY_MDNS und WANMORY_HTTP_PUBLIC_PORT sind in der Compose-Datei bereits mit Zweckangabe gesetzt. Die folgenden Variablen stehen nicht in der Standarddatei; fügen Sie sie bei Bedarf zum environment von server hinzu:

Fotos, die schon auf einem NAS oder einer externen Festplatte liegen, müssen nicht hochgeladen werden. Binden Sie den Ordner als Unterverzeichnis von /photos im Container ein; er wird alle 15 Minuten gescannt, neue Dateien werden an Ort und Stelle importiert (weder kopiert noch verschoben) und anschließend wie hochgeladene Fotos mit Metadaten, Vorschaubildern und KI verarbeitet.

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro bindet schreibgeschützt ein
      - /media/usb/kamera:/photos/usb:ro
      - /home/ich/Bilder:/photos/pictures     # Einbindung mit Schreibzugriff

Führen Sie danach docker compose up -d aus. Der erste Scan beginnt etwa 20 Sekunden nach dem Neustart des Containers.

• Schreibgeschützte Einbindung (:ro) empfohlen: Das System schreibt nichts in diese Ordner. Löschen in der App verschiebt ein Foto nur nach „Zuletzt gelöscht“, endgültiges Löschen entfernt nie die Originaldatei, und spätere Scans importieren sie nicht erneut. Bei Ordnern mit Schreibzugriff löscht endgültiges Löschen auch die Originaldatei.
• Inhaltlich identische Dateien werden nur einmal importiert (Abgleich per SHA-1-Prüfsumme), auch bereits hochgeladene Dateien und Duplikate über mehrere Ordner hinweg.
• Versteckte Ordner und NAS-Systemordner (.xxx, @eaDir, #recycle usw.) werden automatisch übersprungen.
• Aus Fotoordnern importierte Fotos gehören keinem Mitglied; nur Admins können sie löschen.

Der Dienst mdns läuft im Host-Netzwerkmodus und gibt die Zugriffsdomain im LAN bekannt (Standard wanmory.local). macOS, iOS, iPadOS und Windows 10 oder neuer erreichen sie ohne Router-Konfiguration unter http://wanmory.local:8080. Die Domain lässt sich unter „Systemeinstellungen → Zugriffsdomain“ ändern und muss auf .local enden.

Web-Uploads nutzen das fortsetzbare Protokoll tus (/api/uploads/) mit 16-MB-Blöcken. Hinter einem Reverse Proxy müssen Sie die Begrenzung der Anfragegröße aufheben und das Request-Buffering abschalten. Nginx-Beispiel:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/uploads/ {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 0;          # keine Größenbegrenzung (mindestens 20m)
    proxy_request_buffering off;     # durchreichen statt auf der Platte des Proxys zwischenspeichern
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Der KI-Dienst ist ein zustandsloser HTTP-Dienst: Er empfängt Vorschauen mit 1440 Pixeln vom Backend und liefert Gesichter, Vektoren und erkannten Text zurück. Er greift nie auf die Datenbank zu und speichert keine Dateien. Das Backend kennt zwei Betriebsarten, umschaltbar unter „Systemeinstellungen → KI → KI-Betriebsart“:

Ist der KI-Dienst nicht verfügbar, bleiben KI-Jobs in der Warteschlange und werden nicht mehr geholt, sodass keine Wiederholungen verbraucht werden; sobald der Dienst zurück ist, geht es automatisch weiter. Durchsuchen, Uploads und andere Funktionen sind nicht betroffen.

Variante 1: Direkt auf einem Mac oder GPU-Rechner (empfohlen)

Direkt ausgeführt nutzt der Dienst Hardwarebeschleunigung: Auf Apple Silicon verwenden die Gesichtsmodelle CoreML und Chinese-CLIP MPS; auf NVIDIA-GPUs läuft Chinese-CLIP per CUDA in halber Genauigkeit (etwa 1,9 GB VRAM / Arbeitsspeicher). Installieren Sie zuerst uv.

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # PyTorch-Abhängigkeiten installieren (GPU-beschleunigte semantische Suche)
# Zugangstoken erzeugen; Backend und KI-Dienst verwenden denselben Wert
export WANMORY_ML_TOKEN=$(openssl rand -hex 24)
echo $WANMORY_ML_TOKEN
WANMORY_FACE_MODEL_PRELOAD=1 uv run --extra torch python -m wanmory_ml
# lauscht standardmäßig auf 0.0.0.0:3003; änderbar mit WANMORY_ML_HOST / WANMORY_ML_PORT

Variante 2: Docker-Image auf einem anderen Rechner

Für einen leistungsstärkeren x86-Rechner ohne nutzbare GPU; das Image verwendet nur die CPU:

docker run -d --name wanmory-ml --restart unless-stopped \
  -p 3003:3003 \
  -e WANMORY_ML_TOKEN=<Zugangstoken> \
  -v $PWD/models:/models \
  ghcr.io/i-dj/wanmory-ml:latest

Entfernten Dienst im Backend aktivieren

1. 1
   KI-Einstellungen öffnen

   Öffnen Sie als Admin „Systemeinstellungen → KI → KI-Betriebsart“ und wählen Sie „Entfernter Dienst“.

2. 2
   Adresse und Token eintragen

   Die Adresse sieht etwa so aus: http://192.168.1.20:3003; als Token den im vorigen Schritt erzeugten Wert. Vor dem Speichern wird die Verbindung getestet und Latenz sowie Dienstversion angezeigt.

3. 3
   Stufe und Modelle bestätigen

   Nach erfolgreicher Verbindung wird eine Stufe „Automatisch“ anhand der Hardware des entfernten Rechners neu empfohlen; laden Sie unter „Modellstufe“ die benötigten Modelle herunter.

Die Stufe bestimmt, welche Modelle für Gesichter und semantische Suche verwendet werden. Mit „Automatisch“ empfiehlt das System eine Stufe anhand der Hardware des Rechners, auf dem der KI-Dienst läuft: mit nutzbarer GPU „Hohe Genauigkeit“; nur mit CPU und weniger als 6 GB Arbeitsspeicher „Leicht“, sonst „Ausgewogen“.

• Die Texterkennung nutzt PP-OCRv6 (RapidOCR); ihre Modelle kommen mit den Abhängigkeiten und brauchen keinen eigenen Download.
• Nach einem Stufenwechsel werden für alle Fotos die Gesichter mit den neuen Modellen neu erkannt und die semantischen Vektoren neu berechnet; die Suche nutzt so lange die alten Vektoren, benannte Personen bleiben erhalten.
• Modelle werden in das eingebundene Verzeichnis ./models geladen; nicht mehr genutzte Modelle lassen sich löschen, um Platz zu schaffen (das aktive Modell nicht).
• Die InsightFace-Gesichtsmodelle sind nur für nicht kommerzielle Nutzung freigegeben; vor kommerzieller Nutzung ersetzen oder eine Lizenz erwerben.

1. 1
   Admin anlegen

   Beim ersten Aufruf erkennt das System, dass noch kein Konto existiert, und führt durch das Anlegen eines Admins. Admins können Mitglieder hinzufügen und Systemeinstellungen ändern.

2. 2
   Modelle herunterladen

   Öffnen Sie „Systemeinstellungen → KI“, bestätigen Sie die Modellstufe und laden Sie die Modelle herunter. Bis sie bereit sind, warten KI-Jobs in der Warteschlange.

3. 3
   Fotos importieren

   Laden Sie über die Web-App hoch oder binden Sie die Fotos auf Ihrem NAS wie unter Vorhandene Fotoordner einbinden beschrieben ein.

4. 4
   Mitglieder hinzufügen

   Legen Sie unter „Systemeinstellungen → Mitglieder“ Konten für weitere Personen an und wählen Sie die Rolle „Mitglied“ oder „Admin“.

• Web-Uploads unterstützen Fotos, Videos, HEIC, RAW (etwa DNG) und mehr, mit Mehrfachauswahl; hochgeladen wird in Blöcken über das tus-Protokoll, fortsetzbar nach Verbindungsabbruch oder Neuladen der Seite.
• Hochgeladene Dateien werden nach Jahr und Monat im Upload-Verzeichnis abgelegt (Standard data/upload). Das Verzeichnis lässt sich unter „Systemeinstellungen → Upload-Verzeichnis“ ändern; das gilt nur für neue Uploads.
• Nach dem Import laufen nacheinander: Metadaten lesen (ExifTool) → Vorschaubilder und 1440-Pixel-Vorschau erzeugen (libvips / FFmpeg) → semantische Vektoren, Gesichter und Text erkennen (KI-Dienst) → Reverse Geocoding.
• Die Anzeige der Hintergrundaufgaben oben in der Seitenleiste zeigt Fortschritt und geschätzte Restzeit für „Fotos importieren“ und „KI-Erkennung“, gezählt in Fotos.

Personeninformationen (Namen, Zusammenführungen) teilen sich alle Mitglieder; Fotoanzahl, Titelbilder und Personenseiten werden aus den Fotos berechnet, die das jeweilige Mitglied sehen kann, und ausgeblendete Fotos sieht nur ihr Eigentümer.

• Mitglieder: Beim Hinzufügen Namen, Startpasswort (mindestens 4 Zeichen) und Rolle festlegen; Passwörter lassen sich zurücksetzen und Mitglieder entfernen.
• Anmeldeverlauf: Erfasst Zeit, Gerät und IP jeder Anmeldung, der Standort wird offline aus der IP geschätzt (ip2region); die letzten sechs Monate bleiben erhalten. Nur für Admins sichtbar.
• Unter „Mein Konto“ kann jedes Mitglied Passwort und Avatar ändern und die angemeldeten Geräte sehen.

Oben auf der Karte steht live der Status der KI (läuft oder Grund der Pause). Änderungen wirken sofort, ohne Neustart.

„Systemeinstellungen → Systemupdate“ zeigt die aktuellen Versionen von Backend und KI-Dienst und meldet neue Versionen. Zum Aktualisieren im Verzeichnis mit der docker-compose.yml ausführen:

docker compose pull && docker compose up -d

Datenbankmigrationen laufen beim Start von server automatisch. Haben Sie mit WANMORY_VERSION eine Version festgelegt, ändern Sie zuerst das Tag in der .env.

Drei Arten von Daten sollten gesichert werden:

# Datenbank exportieren
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# In eine neue Installation zurückspielen (zuerst docker compose up -d postgres ausführen)
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

Vergisst ein Mitglied sein Passwort, setzt ein Admin es unter „Systemeinstellungen → Mitglieder“ zurück. Vergisst der Admin sein eigenes, führen Sie auf dem Host, auf dem die App läuft, im Verzeichnis mit der docker-compose.yml aus:

docker compose exec server wanmory reset-password            # Konten auflisten und eines wählen
docker compose exec server wanmory reset-password <Name>      # Konto direkt angeben

• Der Befehl listet alle Konten (Name, Rolle, Erstellungszeit, letzte Anmeldung); per Nummer wählen und das neue Passwort zweimal eingeben.
• Nach dem Zurücksetzen ist das Konto auf allen Geräten abgemeldet; Fotos und Alben bleiben unberührt.
• Das geht nur auf dem Host, in der Web-App gibt es dafür keinen Zugang. Ohne Docker wanmory reset-password mit denselben Umgebungsvariablen wie der Server ausführen, etwa DATABASE_URL.

Die Logs der Dienste zeigen docker compose logs -f server und docker compose logs -f ml. Besteht das Problem weiter, melden Sie es auf der Seite Problem melden mit Versionsnummer und den relevanten Logs.

Führen Sie auf dem Host, auf dem Wanmory läuft, das Deinstallationsskript aus:

curl -fsSL https://wanmory.com/uninstall.sh | bash

Das Skript liest zuerst die .env im Installationsverzeichnis und listet Container, Datenbank, Datenverzeichnis und KI-Modelle samt Speicherbedarf sowie die eingebundenen Fotoordner auf. Danach stoppt und entfernt es Container und Netzwerk und fragt für jeden Punkt einzeln, ob er gelöscht werden soll (standardmäßig bleibt alles erhalten):

• Eingebundene vorhandene Fotoordner (NAS, externe Festplatten) werden nie gelöscht.
• Wer Datenbank oder Datenverzeichnis löschen möchte, muss zur Bestätigung DELETE eingeben.
• Werden nur die Container entfernt und die Daten behalten, stellt ein erneutes install.sh im selben Verzeichnis alles wieder her; löschen Sie die .env, behalten aber die Datenbank, notieren Sie vorher das darin enthaltene WANMORY_DB_PASSWORD.