2025-12-14 20:47:49 +01:00

3.9 KiB

Raw Blame History

doc_type	audience	scope	status	version	context
operations_manual	admin, devops	deployment, maintenance, backup	active	2.6	Installationsanleitung, Systemd-Units und Wartungsprozesse.

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.

docker run -d \
  --name mindnet_qdrant \
  --restart always \
  -p 6333:6333 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant

1.3 Ollama (Modelle)

Wichtig: Seit v2.4 ist nomic-embed-text Pflicht für Embeddings.

# 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`)

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

[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet
# Startet Uvicorn (Async Server)
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`)

[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 & Cronjobs

3.1 Regelmäßiger Import (Cron)

Führt den Sync stündlich durch. Nutzt --purge-before-upsert für Sauberkeit.

# 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 Troubleshooting Guide

Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"

Ursache: Alte Dependencies oder falsches Paket installiert.

Lösung: Environment aktualisieren.

source .venv/bin/activate
pip uninstall streamlit-cytoscapejs
pip install st-cytoscape
# Oder sicherheitshalber:
pip install -r requirements.txt

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.

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:

# 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

3.9 KiB Raw Blame History