Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
78d8ab11ed
mindnet/docs/admin_guide.md
Lars f5104008c2
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Details
docs/admin_guide.md hinzugefügt
2025-12-07 12:11:51 +01:00

7.4 KiB
Raw Blame History

Mindnet v2.2 – Admin Guide

Datei: docs/mindnet_admin_guide_v2.2.md Stand: 2025-12-07 Status: FINAL (Konsolidiert WP02–WP04a) Quellen: Handbuch.md, mindnet_v2_implementation_playbook.md, mindnet_technical_architecture.md, Programmplan_V2.2.md.

Dieses Handbuch richtet sich an Administratoren. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz.

1. Zielgruppe & Scope

Mindnet ist als Single-Node System konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft. Als Admin bist du verantwortlich für:

  • Die Verfügbarkeit der Dienste (Qdrant, API).
  • Die Datensicherheit (Backups).
  • Die Integrität des Imports (Sync zwischen Vault und DB).
  • Die Governance (wer darf zugreifen).

2. Initial Setup

2.1 Systemvoraussetzungen

  • OS: Linux (Ubuntu 22.04+ empfohlen) oder macOS.
  • Runtime: Python 3.10+, Docker (für Qdrant).
  • Hardware:
    • CPU: 2+ Cores.
    • RAM: Min. 4GB (abhängig von der Vault-Größe und Qdrant-Index).
    • Disk: SSD empfohlen für Qdrant-Performance.

2.2 Installation

# 1. Repository klonen
git clone <repo-url> /opt/mindnet
cd /opt/mindnet

# 2. Umgebung einrichten
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Verzeichnisse anlegen
mkdir -p logs qdrant_storage

2.3 Qdrant Setup (Docker)

Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig. docker run -d
--name mindnet_qdrant
--restart always
-p 6333:6333
-v $(pwd)/qdrant_storage:/qdrant/storage
qdrant/qdrant

2.4 Konfiguration (ENV)

Erstelle eine .env Datei im Root-Verzeichnis. Diese Variablen steuern das Verhalten der Skripte und der API.

# Qdrant Verbindung
QDRANT_URL="http://localhost:6333"
QDRANT_API_KEY=""  # Leer lassen für lokale Instanzen ohne Auth

# Mindnet Core Settings
COLLECTION_PREFIX="mindnet"
MINDNET_TYPES_FILE="./config/types.yaml"
MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"

# Embedding Settings (Default: all-MiniLM-L6-v2)
VECTOR_DIM=384

# Import-Strategie (Performance vs. Gründlichkeit)
# Body: Nur Textänderungen triggern Update (Standard)
# Full: Auch Frontmatter-Änderungen (z.B. Tags) triggern Update
MINDNET_HASH_COMPARE="Body" 
MINDNET_HASH_SOURCE="parsed"

3. Betrieb im Alltag

3.1 Regelmäßige Importe

Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob oder Trigger) nach Qdrant synchronisiert werden. Das Skript erkennt Änderungen automatisch.

Cronjob-Beispiel (stündlich): 0 * * * * cd /opt/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1

  • --purge-before-upsert: Wichtig, um Fragmente gelöschter Textstellen zu entfernen.
  • --sync-deletes: Wichtig, um Notizen aus dem Index zu entfernen, die im Vault gelöscht wurden.

3.2 Health-Checks

Prüfe regelmäßig, ob die API und der Retriever korrekt arbeiten.

API Status Check: curl -f http://localhost:8000/health || echo "API Down"

Logischer Smoke-Test: Führt eine echte Hybrid-Suche durch und prüft, ob Scores berechnet werden. python3 scripts/test_retriever_smoke.py --mode hybrid

3.3 Umgang mit Fehlern im Importer

Falls der Importer abbricht oder Dateien ignoriert:

  1. Diagnose: Nutze scripts/diagnose_changed.py, um zu sehen, warum eine Datei als "unchanged" gilt. python3 -m scripts.diagnose_changed --vault ./vault --note-id "MeineProblemnote"
  2. Schema-Validierung: Prüfe mit scripts/payload_dryrun.py, ob eine spezifische Datei das JSON-Schema verletzt.
  3. Erzwingen: Nutze touch <filename> im Vault, um den Zeitstempel zu aktualisieren und Hash-Checks zu umgehen, oder nutze --force (Vorsicht: Performance).

4. Update-Prozess

Wenn neue Versionen der Mindnet-Software (z.B. Schema-Updates in WP05) ausgerollt werden:

  1. Code aktualisieren: git pull origin main
  2. Dependencies prüfen: pip install -r requirements.txt
  3. Schema-Migration: Mindnet nutzt oft "Rebuild" statt komplexer Migrationen, da der Vault die Source of Truth ist.
    • Prüfe CHANGELOG.md auf "Breaking Changes".
    • Bei Schema-Änderungen: Führe einen Full Rebuild durch (siehe 5.3).

5. Backup & Restore

Datensicherheit ruht auf zwei Säulen: Dem Vault (Original) und Qdrant (Index).

5.1 Vault-Backup (Priorität 1)

Der Markdown-Vault ist die Single Source of Truth. Er muss klassisch gesichert werden.

  • Strategie: Git-Repository, rsync auf NAS, oder Cloud-Sync.
  • Restore: Einfach Dateien zurückkopieren und Import laufen lassen.

5.2 Qdrant-Snapshots (Priorität 2)

Für schnelle Wiederherstellung des Suchindex ohne stundenlangen Re-Import (bei großen Vaults).

Backup erstellen (Volume-Level): docker stop mindnet_qdrant tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage docker start mindnet_qdrant

Alternativ: API-Snapshot (Zero-Downtime): Siehe Qdrant Dokumentation (Snapshot API).

Restore:

  1. Container stoppen.
  2. Inhalt von qdrant_storage löschen.
  3. Backup entpacken.
  4. Container starten.

5.3 Notfall-Wiederherstellung (Rebuild)

Wenn die Datenbank korrupt ist oder Indizes defekt sind, ist der sauberste Weg ein Rebuild:

# 1. DB komplett leeren (Wipe)
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes

# 2. Alles neu importieren
python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply

6. Monitoring & Logging

6.1 Log-Quellen

  • Importer: Schreibt nach STDOUT/STDERR. Sollte im Cronjob in eine Datei (z.B. /var/log/mindnet_import.log) umgeleitet werden.
  • API (Uvicorn): Standard Access-Logs.
  • Qdrant: Docker Logs (docker logs mindnet_qdrant).

6.2 Wichtige Metriken (Log-Parsing)

Achte in den Import-Logs auf folgende Muster:

  • edges_created: Sollte bei neuen Inhalten > 0 sein.
  • chunks_created: Sollte plausibel zur Anzahl neuer/geänderter Notizen sein.
  • unresolved_references: Ein hoher Anstieg deutet auf tote Links oder Tippfehler im Vault hin.
  • ERROR / WARNING: Parsing-Fehler (z.B. ungültiges YAML).

7. Governance & Sicherheit

7.1 Zugriffsschutz

Mindnet hat aktuell keine integrierte Authentifizierung (By Design für lokalen Betrieb).

  • API: Muss hinter einem Reverse Proxy (Nginx, Traefik, Caddy) mit Basic Auth oder OAuth laufen, wenn sie im Netzwerk freigegeben wird.
  • Qdrant: Sollte nicht öffentlich erreichbar sein (Firewall auf Port 6333, 127.0.0.1 Bindung).

7.2 Datenschutz & Sichtbarkeit

  • Interne Nutzung: Standardmäßig sind alle Inhalte im Index "internal".
  • Trennung: Wenn du öffentliche und private Daten hast, nutze unterschiedliche COLLECTION_PREFIX (z.B. mindnet_public, mindnet_private) und getrennte Import-Jobs/Vault-Ordner, oder warte auf die WP05-ACL-Implementierung (Filterung auf API-Ebene).

7.3 Typen-Governance

Änderungen an der types.yaml (z.B. neue Gewichte) wirken global.

  • Prozess: Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.
  • Review: Prüfe, ob neue Typen (type: xyz) auch Chunking-Profile haben, sonst fallen sie auf Defaults zurück.