mindnet/docs/04_Operations/04_admin_operations.md

---
doc_type: operations_manual
audience: admin, devops
scope: deployment, maintenance, backup, edge_registry, moe, lazy_prompts, agentic_validation
status: active
version: 4.5.8
context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v4.5.8 inklusive WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und WP-24c Phase 3 Agentic Edge Validation Konfiguration."
---

# Admin Operations Guide

## 1. Installation & Setup

### 1.1 Voraussetzungen
* **OS:** Ubuntu 22.04+ (empfohlen).
* **Tools:** Python 3.10+, Docker, Ollama.
* **Hardware:** Min. 8GB RAM, 4 CPU Cores (für Async Import).

### 1.2 Qdrant (Docker)
Startet die Vektor-DB mit persistentem Storage auf Port 6333.

dockercompose.yaml 
```bash
services:
  qdrant:
    image: qdrant/qdrant
    container_name: qdrant
    ports:
      - "6333:6333"
    volumes:
      - ./qdrant_data:/qdrant/storage

    ulimits:
       nofile:
         soft: 65535
         hard: 65535
    restart: unless-stopped

```
```bash
docker compose up -d
```


Um Abstürze der Vektordatenbank bei einer hohen Anzahl an Collections (z. B. durch viele Notiz-Typen oder Dev-Umgebungen) zu vermeiden, müssen die System-Limits für den Container angepasst werden.
Hintergrund: Qdrant öffnet für jedes Segment einer Collection mehrere Dateien. Ohne diese Erhöhung führt das Standard-Linux-Limit (1024) zum Absturz mit dem Fehler os error 24 (Too many open files).

### 1.3 Ollama (Modelle)
**Wichtig:** Seit v2.4 ist `nomic-embed-text` Pflicht für Embeddings. Seit WP-25a wird die Modell-Konfiguration zentral über `llm_profiles.yaml` gesteuert.

```bash
# Modelle laden
ollama pull phi3:mini
ollama pull nomic-embed-text

# Testen
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'
```

**WP-25a: LLM-Profil-Konfiguration**
Die LLM-Steuerung erfolgt nun primär über `config/llm_profiles.yaml` statt ENV-Variablen:
* **Zentrale Registry:** Alle Experten-Profile (Synthese, Validierung, Kompression) sind in einer Datei definiert
* **Fallback-Kaskade:** Automatische Resilienz bei Provider-Fehlern
* **ENV-Variablen:** `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback

Siehe [Konfigurations-Referenz](../03_Technical_References/03_tech_configuration.md#6-llm-profile-registry-llm_profilesyaml-v130) für Details.

---

## 2. Deployment (Systemd Services)

Wir unterscheiden strikt zwischen **Prod** (Port 8001/8501) und **Dev** (Port 8002/8502).

### 2.1 Backend Service (`/etc/systemd/system/mindnet-prod.service`)

```ini
[Unit]
Description=Mindnet API Prod (8001)
After=network.target

[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet
# Startet Uvicorn (Async Server)
# Hinweis: Die .env muss MINDNET_VOCAB_PATH für die Edge Registry enthalten.
ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

### 2.2 UI Service (`/etc/systemd/system/mindnet-ui-prod.service`)

```ini
[Unit]
Description=Mindnet UI Prod (8501)
After=mindnet-prod.service

[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet

# Environment für Streamlit Port & API-Ziel
Environment="MINDNET_API_URL=http://localhost:8001"
Environment="MINDNET_API_TIMEOUT=300"
Environment="STREAMLIT_SERVER_PORT=8501"
Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
Environment="STREAMLIT_SERVER_HEADLESS=true"

# WICHTIG: Pfad zur neuen Router-Datei (ui.py)
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

---

## 3. Wartung & Monitoring

### 3.1 Regelmäßiger Import (Cron)
Führt den Sync stündlich durch. Nutzt `--purge-before-upsert` für Sauberkeit.

```bash
# Crontab Eintrag (user: llmadmin)
0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
```

### 3.2 Monitoring der Edge Registry (WP-22)
Administratoren sollten regelmäßig das Log für unbekannte Kanten-Typen prüfen.
* **Pfad:** `data/logs/unknown_edges.jsonl`.
* **Aktion:** Wenn neue Typen häufig auftreten, sollten diese als Alias in die `01_edge_vocabulary.md` aufgenommen werden.

### 3.2.1 Logging begrenzen (Dateigröße / Zeilen)
Das Hauptlog liegt unter `logs/mindnet.log`. Bei sehr langen Logs (z. B. >80.000 Zeilen) kannst du die Ausgabe eingrenzen:

| Umgebungsvariable | Bedeutung | Default |
|-------------------|-----------|---------|
| **`LOG_LEVEL`** | `INFO`, `WARNING`, `ERROR` oder `DEBUG` | `INFO` (bzw. `DEBUG` wenn `DEBUG=true`) |
| **`LOG_MAX_BYTES`** | Max. Größe einer Log-Datei in Bytes vor Rotation | `1048576` (1 MB) |
| **`LOG_BACKUP_COUNT`** | Anzahl rotierter Backup-Dateien | `2` |

**Empfehlung bei zu langen Logs:**
* **`LOG_LEVEL=INFO`** (oder **`WARNING`**) in `.env` setzen – reduziert die Zeilen deutlich gegenüber `DEBUG`.
* Uvicorn-, HTTP- und Qdrant-Logs werden intern auf WARNING gedrosselt, sodass weniger Framework-Zeilen anfallen.
* Kleinere **`LOG_MAX_BYTES`** (z. B. `524288` = 512 KB) führt zu häufigerer Rotation und kürzeren Einzeldateien.

### 3.3 Troubleshooting Guide

Dieser Abschnitt hilft bei häufigen Problemen und deren Lösung.

#### Allgemeine Diagnose-Schritte

Bevor du spezifische Fehler behebst, führe diese Checks durch:

1. **Service-Status prüfen:**
   ```bash
   systemctl status mindnet-prod
   systemctl status mindnet-ui-prod
   docker ps | grep qdrant
   ```

2. **Logs analysieren:**
   ```bash
   journalctl -u mindnet-prod -n 50 --no-pager
   journalctl -u mindnet-ui-prod -n 50 --no-pager
   docker logs qdrant --tail 50
   ```

3. **API-Verfügbarkeit testen:**
   ```bash
   curl http://localhost:8001/health
   curl http://localhost:8001/query -X POST -H "Content-Type: application/json" -d '{"query": "test", "top_k": 1}'
   ```

#### Häufige Fehler & Lösungen

**Fehler: "Registry Initialization Failure" (Neu in v2.7)**
* **Symptom:** API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log.
* **Diagnose:** Prüfe die Logs auf `EdgeRegistry`-Fehler.
* **Lösung:** 
  1. Prüfe `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein.
  2. Stelle sicher, dass die Datei `01_edge_vocabulary.md` existiert und eine gültige Markdown-Tabelle enthält.
  3. Prüfe Dateiberechtigungen: `ls -l $MINDNET_VOCAB_PATH`

**Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"**
* **Ursache:** Alte Dependencies oder falsches Paket installiert.
* **Lösung:** Environment aktualisieren.
  ```bash
  source .venv/bin/activate
  pip uninstall streamlit-cytoscapejs
  pip install st-cytoscape
  pip install -r requirements.txt  # Vollständige Synchronisation
  ```

**Fehler: "Vector dimension error: expected 768, got 384"**
* **Ursache:** Alte DB (v2.2), neues Modell (v2.4) oder falsches Embedding-Modell.
* **Diagnose:** Prüfe die Collection-Konfiguration in Qdrant.
* **Lösung:** **Full Reset** (siehe Kap. 4.2) oder Collection neu erstellen:
  ```bash
  python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes
  python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply --force
  ```

**Fehler: Import sehr langsam**
* **Ursache:** Smart Edges sind aktiv und analysieren jeden Chunk mit LLM-Calls.
* **Diagnose:** Prüfe `MINDNET_LLM_BACKGROUND_LIMIT` und LLM-Provider-Status.
* **Lösung:** 
  1. Erhöhe `MINDNET_LLM_BACKGROUND_LIMIT` in `.env` (Standard: 2)
  2. Oder deaktiviere Smart Edges temporär in `types.yaml` für bestimmte Typen
  3. Prüfe, ob Ollama/Cloud-Provider erreichbar ist

**Fehler: UI "Read timed out"**
* **Ursache:** Backend braucht für Smart Edges länger als das Timeout-Limit.
* **Diagnose:** Prüfe Backend-Logs auf langsame LLM-Calls.
* **Lösung:** 
  1. Erhöhe `MINDNET_API_TIMEOUT=300.0` in `.env` (oder im Systemd Service)
  2. Prüfe `MINDNET_LLM_TIMEOUT` für einzelne LLM-Requests
  3. Erwäge, Smart Edges für große Imports zu deaktivieren

**Fehler: "Qdrant connection refused"**
* **Ursache:** Qdrant-Container läuft nicht oder falsche URL.
* **Lösung:**
  ```bash
  docker ps | grep qdrant  # Prüfe Container-Status
  docker start qdrant      # Starte Container falls gestoppt
  docker logs qdrant       # Prüfe Container-Logs
  # Prüfe QDRANT_URL in .env
  ```

**Fehler: "Ollama model not found"**
* **Ursache:** Modell nicht geladen oder falscher Modellname.
* **Lösung:**
  ```bash
  ollama list              # Zeige geladene Modelle
  ollama pull phi3:mini    # Lade fehlendes Modell
  ollama pull nomic-embed-text
  # Prüfe MINDNET_LLM_MODEL und MINDNET_EMBEDDING_MODEL in .env
  ```

**Fehler: "Too many open files" (Qdrant)**
* **Ursache:** System-Limit für offene Dateien zu niedrig (besonders bei vielen Collections).
* **Lösung:** Erhöhe `ulimits` im Docker-Compose (siehe Kap. 1.2) oder systemweit:
  ```bash
  # Temporär
  ulimit -n 65535
  # Permanently: /etc/security/limits.conf
  ```

**Fehler: "Unknown edge type" in Logs**
* **Ursache:** Neue Kanten-Typen im Vault, die nicht in `edge_vocabulary.md` definiert sind.
* **Diagnose:** Prüfe `data/logs/unknown_edges.jsonl`.
* **Lösung:** 
  1. Füge fehlende Typen als Aliase in `01_edge_vocabulary.md` hinzu
  2. Oder verwende kanonische Typen aus der Registry

**Fehler: "Phase 3 Validierung schlägt fehl" (WP-24c v4.5.8)**
* **Symptom:** Links in `### Unzugeordnete Kanten` werden nicht validiert oder abgelehnt.
* **Diagnose:** Prüfe Logs auf `🚀 [PHASE 3]` und `🚫 [PHASE 3] REJECTED`.
* **Lösung:**
  1. Prüfe `MINDNET_LLM_VALIDATION_HEADERS` in `.env` (Standard: `Unzugeordnete Kanten,Edge Pool,Candidates`)
  2. Prüfe `MINDNET_LLM_VALIDATION_HEADER_LEVEL` (Standard: `3` für `###`)
  3. Prüfe `llm_profiles.yaml` - `ingest_validator` Profil muss existieren
  4. Prüfe LLM-Verfügbarkeit (Ollama/OpenRouter)
  5. **Hinweis:** Transiente Fehler (Netzwerk) erlauben die Kante, permanente Fehler lehnen sie ab

**Fehler: "Note-Scope Links werden nicht erkannt" (WP-24c v4.2.0)**
* **Symptom:** Links in `## Smart Edges` Zonen werden nicht als Note-Scope behandelt.
* **Diagnose:** Prüfe Logs auf Note-Scope Extraktion.
* **Lösung:**
  1. Prüfe `MINDNET_NOTE_SCOPE_ZONE_HEADERS` in `.env` (Standard: `Smart Edges,Relationen,Global Links`)
  2. Prüfe `MINDNET_NOTE_SCOPE_HEADER_LEVEL` (Standard: `2` für `##`)
  3. Header-Namen müssen exakt (case-insensitive) übereinstimmen

#### Performance-Optimierung

**Problem: Langsame Chat-Antworten**
* Prüfe LLM-Provider (Cloud vs. lokal)
* Reduziere `top_k` in Query-Requests
* Prüfe Qdrant-Performance (Anzahl Collections, Index-Größe)

**Problem: Hoher Speicherverbrauch**
* Reduziere `MINDNET_LLM_BACKGROUND_LIMIT`
* Prüfe Qdrant-Speicherverbrauch: `docker stats qdrant`
* Erwäge, alte Collections zu archivieren

#### Weitere Hilfe

Für detaillierte Informationen zu:
- **Server-Betrieb:** Siehe [Server Operations Manual](04_server_operation_manual.md)
- **Entwicklung:** Siehe [Developer Guide](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners)
- **Konfiguration:** Siehe [Configuration Reference](../03_Technical_References/03_tech_configuration.md)

---

## 4. Backup & Restore

### 4.1 Qdrant Snapshot
Sichert den Vektor-Index.

```bash
docker stop mindnet_qdrant
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
docker start mindnet_qdrant
```

### 4.2 Notfall-Rebuild (Clean Slate)
Wenn alles inkonsistent ist oder Dimensionen sich ändern:

```bash
# 1. DB löschen
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes

# 2. Neu importieren (Force Hash recalculation)
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```

**Wichtig (v2.9.1 Migration):**
Nach dem Update auf v2.9.1 (Section-basierte Links, Multigraph-Support) ist ein vollständiger Re-Import erforderlich, um "Phantom-Knoten" zu beheben und die neue Edge-Struktur zu konsolidieren:
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```
Dies stellt sicher, dass alle bestehenden Links korrekt in `target_id` und `target_section` aufgeteilt werden.