Lars
d1a065fec8
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
181 lines
5.1 KiB
Markdown
181 lines
5.1 KiB
Markdown
---
|
|
doc_type: operations_manual
|
|
audience: admin, devops
|
|
scope: deployment, maintenance, backup, edge_registry
|
|
status: active
|
|
version: 2.7.0
|
|
context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v2.7."
|
|
---
|
|
|
|
# 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.
|
|
|
|
```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"}'
|
|
```
|
|
|
|
---
|
|
|
|
## 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.3 Troubleshooting Guide
|
|
|
|
**Fehler: "Registry Initialization Failure" (Neu in v2.7)**
|
|
* **Symptom:** API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log.
|
|
* **Lösung:** Prüfen Sie `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein und auf eine existierende Markdown-Tabelle zeigen.
|
|
|
|
**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
|
|
```
|
|
|
|
**Fehler: "Vector dimension error: expected 768, got 384"**
|
|
* Ursache: Alte DB (v2.2), neues Modell (v2.4).
|
|
* Lösung: **Full Reset** (siehe Kap. 4.2).
|
|
|
|
**Fehler: Import sehr langsam**
|
|
* Ursache: Smart Edges sind aktiv und analysieren jeden Chunk.
|
|
* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren.
|
|
|
|
**Fehler: UI "Read timed out"**
|
|
* Ursache: Backend braucht für Smart Edges länger als 60s.
|
|
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen (oder im Systemd Service).
|
|
|
|
---
|
|
|
|
## 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
|
|
``` |