Dokumentationsaupdate
Deploy mindnet to llm-node / deploy (push) Successful in 3s

This commit is contained in:
Lars committed 2025-12-28 10:56:34 +01:00
1 parent e9532e8878
commit 5225090490
15 files changed
+2553 -17

No files matched your search

+110 -9
View File
@@ -131,30 +131,131 @@ Administratoren sollten regelmäßig das Log für unbekannte Kanten-Typen prüfe
### 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.
* **Lösung:** Prüfen Sie `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein und auf eine existierende Markdown-Tabelle zeigen.
* **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.
* **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).
* Lösung: **Full Reset** (siehe Kap. 4.2).
* **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.
* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren.
* **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 60s.
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen (oder im Systemd Service).
* **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
#### 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)
---
+474
View File
@@ -0,0 +1,474 @@
---
doc_type: operations_manual
audience: devops, deployment_engineer
scope: deployment, ci_cd, rollout, versioning
status: active
version: 2.9.1
context: "Vollständiger Deployment-Guide für Mindnet: CI/CD, Rollout-Strategien, Versionierung und Rollback."
---
# Deployment Guide
Dieses Dokument beschreibt die Deployment-Prozesse, CI/CD-Pipelines und Rollout-Strategien für Mindnet.
## 1. Deployment-Architektur
Mindnet läuft in einer **Multi-Environment-Architektur**:
| Environment | Ports | Zweck | User |
| :--- | :--- | :--- | :--- |
| **Production** | 8001 (API), 8501 (UI) | Live-System | `llmadmin` |
| **Development** | 8002 (API), 8502 (UI) | Test & Entwicklung | `llmadmin` |
**Wichtig:** Beide Environments teilen sich die gleiche Qdrant-Instanz, nutzen aber unterschiedliche Collection-Prefixes.
---
## 2. Deployment-Methoden
### 2.1 Automatisches Deployment (CI/CD)
**Tool:** Gitea Actions (`.gitea/workflows/deploy.yml`)
**Trigger:** Push auf `main` Branch
**Prozess:**
1. **Checkout:** Code wird ausgecheckt
2. **Stop API:** Graceful Stop des API-Services
3. **Deploy:** Rsync der whitelisted Verzeichnisse
4. **Dependencies:** Python venv & requirements aktualisieren
5. **Restart:** API-Service neu starten
**Deployierte Verzeichnisse:**
- `app/` - Backend-Code
- `scripts/` - Admin-Tools
- `config/` - Konfigurationsdateien
- `tests/` - Test-Suite
- `requirements.txt` - Dependencies
**Ausgeschlossen:**
- `.env*` - Umgebungsvariablen (bleiben auf Server)
- `.venv` - Virtuelle Umgebung (wird neu erstellt)
- `vault/` - Content (bleibt auf Server)
### 2.2 Manuelles Deployment
**Für:** Hotfixes, manuelle Rollouts, Debugging
**Prozess:**
```bash
# 1. Auf Server einloggen
ssh llmadmin@llm-node
# 2. In Produktions-Verzeichnis wechseln
cd ~/mindnet
# 3. Code aktualisieren
git fetch origin
git checkout main
git pull origin main
# 4. Dependencies aktualisieren
source .venv/bin/activate
pip install -r requirements.txt
# 5. Services neu starten
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
# 6. Status prüfen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
```
---
## 3. Systemd Services
### 3.1 Backend Service (API)
**Datei:** `/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
ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
Restart=always
RestartSec=5
Environment="MINDNET_VOCAB_PATH=/home/llmadmin/mindnet/vault/_system/dictionary/edge_vocabulary.md"
[Install]
WantedBy=multi-user.target
```
**Wichtig:**
- `--env-file .env` lädt Umgebungsvariablen
- `MINDNET_VOCAB_PATH` muss absolut sein (für Edge Registry)
### 3.2 Frontend Service (UI)
**Datei:** `/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="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"
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
### 3.3 Service-Management
**Befehle:**
```bash
# Status prüfen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
# Starten
sudo systemctl start mindnet-prod
sudo systemctl start mindnet-ui-prod
# Stoppen
sudo systemctl stop mindnet-prod
sudo systemctl stop mindnet-ui-prod
# Neustart
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
# Logs anzeigen
sudo journalctl -u mindnet-prod -f
sudo journalctl -u mindnet-ui-prod -f
```
---
## 4. Rollout-Strategien
### 4.1 Blue-Green Deployment (Empfohlen)
**Konzept:** Zwei identische Environments, Switch zwischen ihnen.
**Aktuell:** Prod/Dev als Blue-Green Setup
**Vorgehen:**
1. Deploy auf Dev (Port 8002/8502)
2. Tests auf Dev durchführen
3. Wenn erfolgreich: Deploy auf Prod (Port 8001/8501)
4. Switch erfolgt durch Service-Restart
**Vorteile:**
- Schneller Rollback (alte Version läuft noch)
- Keine Downtime
- Test vor Produktion
### 4.2 Canary Deployment (Zukünftig)
**Konzept:** Schrittweise Rollout an einen Teil der Nutzer.
**Umsetzung:**
- Load Balancer mit Traffic-Splitting
- Monitoring der Fehlerrate
- Automatischer Rollback bei Fehlern
**Status:** Noch nicht implementiert (Single-User-Szenario)
---
## 5. Versionierung & Releases
### 5.1 Version-Schema
**Format:** `v2.9.1`
- **Major (2):** Breaking Changes
- **Minor (9):** Neue Features, Backward Compatible
- **Patch (1):** Bugfixes, kleine Verbesserungen
### 5.2 Release-Prozess
**1. Feature-Entwicklung:**
```bash
git checkout -b feature/neue-funktion
# ... Entwicklung ...
git push origin feature/neue-funktion
```
**2. Testing:**
- Unit Tests
- Integration Tests
- Smoke Tests auf Dev
**3. Merge:**
```bash
# Pull Request in Gitea
# Review & Merge nach main
```
**4. Deployment:**
- Automatisch via CI/CD (bei Push auf main)
- Oder manuell (siehe 2.2)
**5. Tagging (Optional):**
```bash
git tag -a v2.9.2 -m "Release v2.9.2: Neue Funktion X"
git push origin v2.9.2
```
---
## 6. Rollback-Strategien
### 6.1 Code-Rollback
**Methode 1: Git Revert**
```bash
cd ~/mindnet
git log --oneline -10 # Finde letzten guten Commit
git checkout <commit-hash>
sudo systemctl restart mindnet-prod
```
**Methode 2: Git Reset (Vorsicht!)**
```bash
cd ~/mindnet
git reset --hard <commit-hash>
sudo systemctl restart mindnet-prod
```
### 6.2 Datenbank-Rollback
**Problem:** Code-Rollback hilft nicht bei Schema-Änderungen.
**Lösung:**
- **Qdrant-Snapshots:** Regelmäßige Backups (siehe [Server Operations Manual](04_server_operation_manual.md))
- **Collection-Versionierung:** Separate Collections pro Version (nicht empfohlen)
**Vorgehen bei Schema-Änderung:**
1. Snapshot vor Deployment erstellen
2. Deployment durchführen
3. Bei Problemen: Snapshot wiederherstellen
---
## 7. Pre-Deployment Checkliste
Vor jedem Deployment sollten folgende Punkte geprüft werden:
- [ ] **Code-Qualität:**
- [ ] Unit Tests bestehen
- [ ] Integration Tests bestehen
- [ ] Linting bestanden
- [ ] **Dependencies:**
- [ ] `requirements.txt` aktualisiert
- [ ] Neue Dependencies dokumentiert
- [ ] Breaking Changes in Dependencies geprüft
- [ ] **Konfiguration:**
- [ ] `.env` Variablen dokumentiert (falls neu)
- [ ] Config-Dateien (`types.yaml`, etc.) kompatibel
- [ ] Edge Registry Pfad korrekt
- [ ] **Datenbank:**
- [ ] Schema-Änderungen dokumentiert
- [ ] Migration-Skripte vorhanden (falls nötig)
- [ ] Backup erstellt
- [ ] **Dokumentation:**
- [ ] Changelog aktualisiert
- [ ] Dokumentation synchronisiert
- [ ] Breaking Changes dokumentiert
---
## 8. Post-Deployment Validierung
Nach jedem Deployment sollten folgende Checks durchgeführt werden:
### 8.1 Service-Status
```bash
# Services laufen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
# Health Check
curl http://localhost:8001/healthz
```
### 8.2 Funktionalität
```bash
# API-Test
curl -X POST http://localhost:8001/query \
-H "Content-Type: application/json" \
-d '{"query": "test", "top_k": 1}'
# UI-Test (Manuell)
# Öffne http://localhost:8501 im Browser
```
### 8.3 Logs prüfen
```bash
# Fehler in Logs
sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i error
# Warnings
sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i warning
```
---
## 9. CI/CD Pipeline Details
### 9.1 Gitea Actions Workflow
**Datei:** `.gitea/workflows/deploy.yml`
**Trigger:**
- Push auf `main` Branch
- Concurrency: Nur ein Deployment gleichzeitig
**Schritte:**
1. **Checkout:** Code aus Repository
2. **Stop API:** Graceful Stop (continue-on-error)
3. **Deploy:** Rsync der Verzeichnisse
4. **Python Setup:** Venv & Requirements
5. **Start API:** Service neu starten
**Wichtig:**
- `.env` wird **nicht** deployed (bleibt auf Server)
- Vault wird **nicht** deployed (bleibt auf Server)
### 9.2 Deployment-Verzeichnisse
**Whitelist:**
```
app scripts schemas docker tests config requirements.txt README.md
```
**Excluded:**
- `.git/`
- `.env*`
- `.venv/`
- `vault/`
- `hf_cache/`
---
## 10. Monitoring & Alerting
### 10.1 Health Checks
**API Health Endpoint:**
```bash
curl http://localhost:8001/healthz
```
**Response:**
```json
{
"status": "ok",
"qdrant": "http://localhost:6333",
"prefix": "mindnet"
}
```
**Monitoring-Script:**
```bash
python3 -m scripts.health_check_mindnet --url http://localhost:8001 --strict
```
### 10.2 Log-Monitoring
**Systemd Journal:**
```bash
# Live-Logs
sudo journalctl -u mindnet-prod -f
# Letzte 100 Zeilen
sudo journalctl -u mindnet-prod -n 100
# Seit gestern
sudo journalctl -u mindnet-prod --since "yesterday"
```
### 10.3 Metriken (Zukünftig)
**Geplante Metriken:**
- Request-Rate
- Response-Zeiten
- Fehler-Rate
- LLM-Call-Dauer
- Qdrant-Performance
**Tools:** Prometheus + Grafana (noch nicht implementiert)
---
## 11. Disaster Recovery
Siehe [Server Operations Manual](04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr) für detaillierte Disaster-Recovery-Prozeduren.
**Kurzfassung:**
1. **Stage 1:** Basis-Image Restore (Bare Metal)
2. **Stage 2:** Daten-Update via Borgmatic
3. **Dienste:** Gitea, Qdrant, Ollama spezifisch wiederherstellen
---
## 12. Best Practices
### 12.1 Deployment-Zeiten
- **Produktion:** Während Wartungsfenstern (nachts, Wochenenden)
- **Development:** Jederzeit (ist Test-Umgebung)
### 12.2 Kommunikation
- **Breaking Changes:** Vorher ankündigen
- **Downtime:** Bei größeren Deployments kommunizieren
- **Rollback-Plan:** Immer bereit haben
### 12.3 Testing
- **Immer zuerst auf Dev testen**
- **Smoke Tests nach Deployment**
- **Monitoring für erste Stunden nach Deployment**
---
## 13. Weitere Informationen
- **Admin Operations:** Siehe [Admin Operations Guide](04_admin_operations.md)
- **Server Operations:** Siehe [Server Operations Manual](04_server_operation_manual.md)
- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](04_admin_operations.md#33-troubleshooting-guide)
---
**Letzte Aktualisierung:** 2025-01-XX
**Version:** 2.9.1