neue Dokumentationstruktur - (QS geprüft)
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Deploy mindnet to llm-node / deploy (push) Successful in 4s
This commit is contained in:
1 parent
0bb5f57cc6
commit
620858a575
39 files changed
+1840
No files matched your search
@@ -0,0 +1,220 @@
|
||||
# Mindnet v2.4 – Entwickler-Workflow
|
||||
**Datei:** `docs/DEV_WORKFLOW.md`
|
||||
**Stand:** 2025-12-12 (Aktualisiert: v2.6 mit Traffic Control)
|
||||
|
||||
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
|
||||
|
||||
---
|
||||
|
||||
## 1. Die Architektur
|
||||
|
||||
* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten!
|
||||
* **Raspberry Pi (Gitea):** Der Tresor. Speichert den Code und verwaltet Versionen.
|
||||
* **Beelink (Runtime):** Hier läuft die Software. Wir nutzen **Systemd-Services**:
|
||||
* **PROD:**
|
||||
* API: `mindnet-prod` (Port 8001). Ordner: `~/mindnet`.
|
||||
* UI: `mindnet-ui-prod` (Port 8501).
|
||||
* **DEV:**
|
||||
* API: `mindnet-dev` (Port 8002). Ordner: `~/mindnet_dev`.
|
||||
* UI: `mindnet-ui-dev` (Port 8502).
|
||||
|
||||
---
|
||||
|
||||
## 2. Der Zyklus: Von der Idee zum Release
|
||||
|
||||
### Phase 1: Entwicklung (Windows / VS Code)
|
||||
|
||||
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
|
||||
|
||||
1. **Basis aktualisieren (WICHTIG!):**
|
||||
Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
|
||||
* Klicke unten links auf den aktuellen Branch und wähle **`main`**.
|
||||
* Klicke links im Menü "Source Control" auf die **drei Punkte (...)** -> **Pull** (oder das Synchronisieren-Symbol).
|
||||
* *Erst jetzt hast du alle Dateien!*
|
||||
|
||||
2. **Branch erstellen:**
|
||||
* Klicke wieder unten links auf `main`.
|
||||
* Wähle `+ Create new branch...`.
|
||||
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp15-traffic-control`).
|
||||
* Drücke **Enter**.
|
||||
|
||||
3. **Sicherheits-Check:**
|
||||
* Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
|
||||
|
||||
4. **Coden:**
|
||||
* Nimm deine Änderungen vor (z.B. neue Schemas in `types.yaml` oder Async-Logik in `ingestion.py`).
|
||||
|
||||
5. **Sichern & Hochladen:**
|
||||
* **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
|
||||
* **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Testen (Beelink / `mindnet_dev`)
|
||||
|
||||
Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
|
||||
|
||||
1. **Einloggen:**
|
||||
`ssh user@<BEELINK-IP>`
|
||||
|
||||
2. **In die Werkstatt gehen:**
|
||||
`cd /home/llmadmin/mindnet_dev`
|
||||
|
||||
3. **Code holen:**
|
||||
```bash
|
||||
git fetch
|
||||
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
|
||||
git checkout feature/wp15-traffic-control
|
||||
git pull
|
||||
```
|
||||
|
||||
4. **Umgebung vorbereiten (WICHTIG für v2.6):**
|
||||
Prüfe deine `.env` Datei. Sie benötigt jetzt Einträge für die Traffic Control.
|
||||
```bash
|
||||
nano .env
|
||||
```
|
||||
**Ergänze/Prüfe:**
|
||||
```ini
|
||||
# Traffic Control (Neu in v2.6)
|
||||
MINDNET_LLM_BACKGROUND_LIMIT=2 # Max. parallele Import-Tasks
|
||||
MINDNET_API_TIMEOUT=300.0 # Frontend wartet länger
|
||||
MINDNET_EMBEDDING_MODEL="nomic-embed-text"
|
||||
```
|
||||
|
||||
**Dependencies aktualisieren:**
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
ollama pull nomic-embed-text
|
||||
```
|
||||
|
||||
5. **Test-Server aktualisieren (WICHTIG):**
|
||||
Der Code ist da, aber die Prozesse im RAM sind noch alt. Wir müssen die Services neustarten.
|
||||
|
||||
**Option A: Standard (Als Service laufen lassen)**
|
||||
Ideal, wenn du nur testen willst, ob es läuft.
|
||||
```bash
|
||||
# 1. API neustarten (Backend)
|
||||
sudo systemctl restart mindnet-dev
|
||||
# 2. UI neustarten (Frontend)
|
||||
sudo systemctl restart mindnet-ui-dev
|
||||
|
||||
# Logs prüfen (um Fehler zu sehen):
|
||||
journalctl -u mindnet-dev -f
|
||||
```
|
||||
|
||||
**Option B: Manuell Debuggen (Direct Output)**
|
||||
Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht.
|
||||
```bash
|
||||
# 1. Services stoppen (wichtig, sonst sind Ports 8002/8502 belegt!)
|
||||
sudo systemctl stop mindnet-dev
|
||||
sudo systemctl stop mindnet-ui-dev
|
||||
|
||||
# 2. Manuell starten (z.B. API)
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
|
||||
```
|
||||
|
||||
6. **Validieren (Smoke Tests v2.6):**
|
||||
|
||||
* **Test A: Last-Test (Traffic Control):**
|
||||
1. Starte einen Import im Terminal: `python3 -m scripts.import_markdown ...`
|
||||
2. Öffne **gleichzeitig** `http://<IP>:8502` im Browser.
|
||||
3. Stelle eine Chat-Frage ("Was ist Mindnet?").
|
||||
4. **Erwartung:** Der Chat antwortet sofort (Realtime Lane), während der Import im Hintergrund weiterläuft (Background Lane).
|
||||
|
||||
* **Test B: API Check**
|
||||
```bash
|
||||
curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Release (Gitea / Raspberry Pi)
|
||||
|
||||
Wenn der Test auf Port 8002 / 8502 erfolgreich war:
|
||||
|
||||
1. Öffne Gitea im Browser.
|
||||
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
||||
3. **Merge** den Pull Request.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Deployment (Beelink / `mindnet`)
|
||||
|
||||
Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501).
|
||||
|
||||
1. **Deploy-Agent (Automatisch):**
|
||||
Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!
|
||||
|
||||
2. **Manuell (Falls nötig):**
|
||||
```bash
|
||||
cd /home/llmadmin/mindnet
|
||||
git pull origin main
|
||||
|
||||
# Dependencies updaten & Modelle checken
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
ollama pull nomic-embed-text
|
||||
|
||||
# .env prüfen (Traffic Control)
|
||||
# Ggf. MINDNET_LLM_BACKGROUND_LIMIT=2 hinzufügen
|
||||
|
||||
# Falls sich die Vektor-Dimension geändert hat (v2.4 Upgrade):
|
||||
# python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||||
# python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||||
|
||||
# Produktions-Services neustarten
|
||||
sudo systemctl restart mindnet-prod
|
||||
sudo systemctl restart mindnet-ui-prod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Aufräumen (Optional aber empfohlen)
|
||||
|
||||
Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
|
||||
|
||||
1. **Gitea:** Im Pull Request auf "Delete Branch" klicken.
|
||||
2. **Beelink (Dev):**
|
||||
```bash
|
||||
cd ~/mindnet_dev
|
||||
git checkout main
|
||||
git pull
|
||||
git branch -d feature/wp15-traffic-control
|
||||
```
|
||||
3. **VS Code:**
|
||||
* Auf `main` wechseln.
|
||||
* Sync drücken.
|
||||
* `F1` -> `Git: Delete Branch` -> Branch auswählen.
|
||||
|
||||
---
|
||||
|
||||
## 3. Cheat Sheet: Die wichtigsten Befehle
|
||||
|
||||
| Wo? | Befehl | Was tut es? |
|
||||
| :--- | :--- | :--- |
|
||||
| **Beelink** | `sudo systemctl restart mindnet-dev` | **Neustart Dev-Backend (Port 8002).** |
|
||||
| **Beelink** | `sudo systemctl restart mindnet-ui-dev` | **Neustart Dev-Frontend (Port 8002).** |
|
||||
| **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs Backend.** |
|
||||
| **Beelink** | `python debug_analysis.py` | **Prüft Aliases & Scores.** |
|
||||
| **Beelink** | `python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes` | **Löscht & Repariert DB.** |
|
||||
| **Beelink** | `python3 -m scripts.import_markdown --vault ./vault_master --prefix "mindnet_dev" --apply --force` | **Löscht & Repariert DB.** |
|
||||
| **Beelink** | `source .venv/bin/activate` | **Aktivieren des virtual environments** |
|
||||
|
||||
---
|
||||
|
||||
## 4. Troubleshooting
|
||||
|
||||
**"Read timed out" im Frontend**
|
||||
* **Ursache:** Backend braucht für Smart Edges länger als 60s.
|
||||
* **Lösung:** `MINDNET_API_TIMEOUT=300.0` in `.env` setzen und Services neustarten.
|
||||
|
||||
**Import ist extrem langsam**
|
||||
* **Ursache:** Smart Edges analysieren jeden Chunk mit LLM.
|
||||
* **Lösung:**
|
||||
* Akzeptieren (Qualität vor Speed).
|
||||
* Oder temporär in `config/types.yaml`: `enable_smart_edge_allocation: false`.
|
||||
|
||||
**"UnicodeDecodeError in .env"**
|
||||
* **Ursache:** Umlaute oder Sonderzeichen in der `.env` Datei.
|
||||
* **Lösung:** `.env` bereinigen (nur ASCII nutzen) und sicherstellen, dass sie UTF-8 ohne BOM ist.
|
||||
Reference in new issue
Block a user