diff --git a/docs/admin_guide.md b/docs/admin_guide.md new file mode 100644 index 0000000..0981dde --- /dev/null +++ b/docs/admin_guide.md @@ -0,0 +1,190 @@ +# 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 /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 ` 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. \ No newline at end of file