From 9d3fd21c88eafa44e4e26a733495b436db34a077 Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 8 Dec 2025 09:07:34 +0100 Subject: [PATCH] docs/admin_guide.md aktualisiert --- docs/admin_guide.md | 144 +++++++++++++++++++------------------------- 1 file changed, 62 insertions(+), 82 deletions(-) diff --git a/docs/admin_guide.md b/docs/admin_guide.md index 0981dde..801c490 100644 --- a/docs/admin_guide.md +++ b/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 -**Status:** **FINAL** (Konsolidiert WP02–WP04a) +**Stand:** 2025-12-08 +**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: -* 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). +Wir unterscheiden strikt zwischen: +* **Production (Port 8001):** Stabiler `main` Branch. +* **Development (Port 8002):** Experimentelle Feature-Branches. --- -## 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 /opt/mindnet - cd /opt/mindnet + git clone /home/llmadmin/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) - # Body: Nur Textänderungen triggern Update (Standard) - # Full: Auch Frontmatter-Änderungen (z.B. Tags) triggern Update + # Import-Strategie 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. -* `--sync-deletes`: Wichtig, um Notizen aus dem Index zu entfernen, die im Vault gelöscht wurden. +* `--purge-before-upsert`: Entfernt Fragmente gelöschter Textstellen. +* `--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:** - curl -f http://localhost:8000/health || echo "API Down" +**System Status:** + 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 + python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query -### 3.3 Umgang mit Fehlern im Importer -Falls der Importer abbricht oder Dateien ignoriert: +### 3.3 Logs & Monitoring +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. - 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). +* **Technische Fehler (Live):** + `journalctl -u mindnet-prod -f` +* **Fachliche Logs (Data Flywheel):** + `/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:** - 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). +3. **Dienst neustarten (Zwingend!):** + sudo systemctl restart mindnet-prod +4. **Schema-Migration (falls nötig):** + 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. -* **Strategie:** Git-Repository, rsync auf NAS, oder Cloud-Sync. -* **Restore:** Einfach Dateien zurückkopieren und Import laufen lassen. +Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS). ### 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):** +Für schnelle Wiederherstellung des Suchindex. 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: +### 5.3 Log-Daten (Priorität 3) +Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden. +### 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 -* **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.1 Zugriffsschutz +Mindnet hat aktuell **keine integrierte Authentifizierung**. +* **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik) mit Basic Auth laufen, wenn sie im Netzwerk freigegeben wird. +* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein. -### 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 +### 6.2 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 +* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen. \ No newline at end of file