docs/admin_guide.md aktualisiert

docs/admin_guide.md

@@ -1,7 +1,7 @@
 # Mindnet v2.2 – Admin Guide
 **Datei:** `docs/mindnet_admin_guide_v2.2.md`
-**Stand:** 2025-12-07
+**Stand:** 2025-12-08
-**Status:** **FINAL** (Konsolidiert WP02–WP04a)
+**Status:** **FINAL** (Konsolidiert WP02–WP04c)
 **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.
@@ -11,15 +11,13 @@
 ## 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:
+Wir unterscheiden strikt zwischen:
-* Die Verfügbarkeit der Dienste (Qdrant, API).
+* **Production (Port 8001):** Stabiler `main` Branch.
-* Die Datensicherheit (Backups).
+* **Development (Port 8002):** Experimentelle Feature-Branches.
-* Die Integrität des Imports (Sync zwischen Vault und DB).
-* Die Governance (wer darf zugreifen).
 
 ---
 
-## 2. Initial Setup
+## 2. Initial Setup & Installation
 
 ### 2.1 Systemvoraussetzungen
 * **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS.
@@ -29,10 +27,10 @@ Als Admin bist du verantwortlich für:
     * RAM: Min. 4GB (abhängig von der Vault-Größe und Qdrant-Index).
     * Disk: SSD empfohlen für Qdrant-Performance.
 
-### 2.2 Installation
+### 2.2 Installation (Code)
     # 1. Repository klonen
-    git clone <repo-url> /opt/mindnet
+    git clone <repo-url> /home/llmadmin/mindnet
-    cd /opt/mindnet
+    cd /home/llmadmin/mindnet
     
     # 2. Umgebung einrichten
     python3 -m venv .venv
@@ -40,7 +38,7 @@ Als Admin bist du verantwortlich für:
     pip install -r requirements.txt
     
     # 3. Verzeichnisse anlegen
-    mkdir -p logs qdrant_storage
+    mkdir -p logs qdrant_storage data/logs
 
 ### 2.3 Qdrant Setup (Docker)
 Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
@@ -59,132 +57,114 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Diese Variablen steuern das Verh
     QDRANT_API_KEY=""  # Leer lassen für lokale Instanzen ohne Auth
     
     # Mindnet Core Settings
-    COLLECTION_PREFIX="mindnet"
+    COLLECTION_PREFIX="mindnet" # "mindnet_dev" für Dev-Umgebung
     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)
+    # Import-Strategie
-    # Body: Nur Textänderungen triggern Update (Standard)
-    # Full: Auch Frontmatter-Änderungen (z.B. Tags) triggern Update
     MINDNET_HASH_COMPARE="Body" 
     MINDNET_HASH_SOURCE="parsed"
 
+### 2.5 Deployment via Systemd (Standard ab v2.2.1)
+Mindnet wird nicht mehr manuell gestartet, sondern als Systemdienst.
+
+**Production Service (`/etc/systemd/system/mindnet-prod.service`):**
+* Läuft auf Port 8001.
+* Autostart (`enabled`).
+* Restart Policy: `always` (heilt Abstürze automatisch).
+
+**Development Service (`/etc/systemd/system/mindnet-dev.service`):**
+* Läuft auf Port 8002.
+* Getrennter Ordner (`~/mindnet_dev`).
+
 ---
 
 ## 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.
+Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden.
 
 **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
+    0 * * * * cd /home/llmadmin/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.
+* `--purge-before-upsert`: Entfernt Fragmente gelöschter Textstellen.
-* `--sync-deletes`: Wichtig, um Notizen aus dem Index zu entfernen, die im Vault gelöscht wurden.
+* `--sync-deletes`: Entfernt Notizen aus dem Index, 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:**
+**System Status:**
-    curl -f http://localhost:8000/health || echo "API Down"
+    sudo systemctl status mindnet-prod
 
 **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 --url http://localhost:8001/query
-    python3 scripts/test_retriever_smoke.py --mode hybrid
 
-### 3.3 Umgang mit Fehlern im Importer
+### 3.3 Logs & Monitoring
-Falls der Importer abbricht oder Dateien ignoriert:
+Seit v2.2.1 werden technische Logs im Systemd Journal und fachliche Logs in JSONL-Dateien gespeichert.
 
-1.  **Diagnose:** Nutze `scripts/diagnose_changed.py`, um zu sehen, warum eine Datei als "unchanged" gilt.
+* **Technische Fehler (Live):**
-        python3 -m scripts.diagnose_changed --vault ./vault --note-id "MeineProblemnote"
+    `journalctl -u mindnet-prod -f`
-2.  **Schema-Validierung:** Prüfe mit `scripts/payload_dryrun.py`, ob eine spezifische Datei das JSON-Schema verletzt.
+* **Fachliche Logs (Data Flywheel):**
-3.  **Erzwingen:** Nutze `touch <filename>` im Vault, um den Zeitstempel zu aktualisieren und Hash-Checks zu umgehen, oder nutze `--force` (Vorsicht: Performance).
+    `/home/llmadmin/mindnet/data/logs/search_history.jsonl`
+    `/home/llmadmin/mindnet/data/logs/feedback.jsonl`
+
+> **Hinweis:** Die JSONL-Logs wachsen endlos ("Append Only"). Richte bei Bedarf `logrotate` ein oder archiviere alte Logs. Lösche sie nicht, da sie die Basis für WP08 (Self-Tuning) sind.
 
 ---
 
 ## 4. Update-Prozess
 
-Wenn neue Versionen der Mindnet-Software (z.B. Schema-Updates in WP05) ausgerollt werden:
+Wenn neue Versionen ausgerollt werden (Deployment):
 
 1.  **Code aktualisieren:**
+        cd /home/llmadmin/mindnet
         git pull origin main
 2.  **Dependencies prüfen:**
+        source .venv/bin/activate
         pip install -r requirements.txt
-3.  **Schema-Migration:**
+3.  **Dienst neustarten (Zwingend!):**
-    Mindnet nutzt oft "Rebuild" statt komplexer Migrationen, da der Vault die Source of Truth ist.
+        sudo systemctl restart mindnet-prod
-    * Prüfe `CHANGELOG.md` auf "Breaking Changes".
+4.  **Schema-Migration (falls nötig):**
-    * Bei Schema-Änderungen: Führe einen **Full Rebuild** durch (siehe 5.3).
+    Bei Änderungen an `types.yaml` oder Index-Strukturen:
+        python3 -m scripts.import_markdown ... --apply
 
 ---
 
 ## 5. Backup & Restore
 
-Datensicherheit ruht auf zwei Säulen: Dem Vault (Original) und Qdrant (Index).
+Datensicherheit ruht auf drei Säulen: Vault (Source), Qdrant (Index), JSONL-Logs (Lern-Daten).
 
 ### 5.1 Vault-Backup (Priorität 1)
-Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden.
+Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS).
-* **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).
+Für schnelle Wiederherstellung des Suchindex.
-
-**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):**
+### 5.3 Log-Daten (Priorität 3)
-Siehe Qdrant Dokumentation (Snapshot API).
+Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden.
-
-**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:
 
+### 5.4 Notfall-Wiederherstellung (Rebuild)
+Wenn die Datenbank korrupt ist:
     # 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. Governance & Sicherheit
 
-### 6.1 Log-Quellen
+### 6.1 Zugriffsschutz
-* **Importer:** Schreibt nach STDOUT/STDERR. Sollte im Cronjob in eine Datei (z.B. `/var/log/mindnet_import.log`) umgeleitet werden.
+Mindnet hat aktuell **keine integrierte Authentifizierung**.
-* **API (Uvicorn):** Standard Access-Logs.
+* **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik) mit Basic Auth laufen, wenn sie im Netzwerk freigegeben wird.
-* **Qdrant:** Docker Logs (`docker logs mindnet_qdrant`).
+* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.
 
-### 6.2 Wichtige Metriken (Log-Parsing)
+### 6.2 Typen-Governance
-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.