Lars
f5104008c2
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
190 lines
7.4 KiB
Markdown
190 lines
7.4 KiB
Markdown
# 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. |