🛠️ Handbuch für Administratoren (Server & Technik)

Version: 1.1 (Native + CrumbSeal)
Zielgruppe: Admins, DevOps, Techniker

Dieses Dokument beschreibt den technischen Betrieb des Crumbforest Systems.
Für die pädagogische Seite und Crew-Beschreibungen siehe HANDBUCH_KRUEMEL.md.

🏗️ System-Architektur (Native)

Das System läuft nativ auf dem Host-OS (Debian/Ubuntu), ohne Docker-Container für die Applikation selbst.

Komponenten

  • App: FastAPI (Python) als systemd-Service (crumbforest.service)
  • Proxy: Nginx (Port 80/443 -> Port 8000)
  • DB: MariaDB (SQL) für User/Logs
  • Vektor: Qdrant (Single Node)
  • Security: CrumbSeal (Python-Modul)

Pfade

  • Root: /opt/crumbforest
  • Code: /opt/crumbforest/app
  • Kernel: /opt/crumbforest/native_crumbcore_v1 (CrumbSeal, Monitor, Scripts)
  • Logs: /var/log/crumbforest/

🛡️ Security: CrumbSeal

CrumbSeal ist der integrierte Schutzmechanismus ("Passkante"), der kritische Anfragen blockiert, bevor sie das LLM erreichen.

Funktionsweise

  1. Intercept: Jeder Chat-Request wird vor dem LLM-Call geprüft.
  2. Pattern Check: Prüft auf Muster wie Suizidalität oder akute Notfälle.
  3. Hard Block: Bei Treffer ("Passkante Hard") wird der Request abgelehnt.
    • Antwort: Standardisierter Sicherheitshinweis (keine generative Antwort).
    • Log: Eintrag in DB/JSONL als crumbseal_protection.

Monitoring (Wachhund)

Ein Cronjob überwacht die Logs auf Blockierungen:

  • Script: /opt/crumbforest/native_crumbcore_v1/crumbseal_monitor.sh
  • Frequenz: Alle 10 Min (empfohlen).
  • Alarm: Sendet Email an Admin bei neuen Hard-Blocks.

Admin Dashboard

In der Weboberfläche (/admin/logs) werden geblockte Anfragen rot markiert (🛡️ Icon).

🔄 Updates & Deployment

Das System nutzt ein Git-basiertes Rolling Update.

Update-Prozess (Server)

[!IMPORTANT]
Nur git pull reicht nicht!
Der Server läuft isoliert in /opt/crumbforest. Änderungen im Git-Repo (z.B. in /tmp/...) haben keinen Effekt auf die laufende App, bis das Deploy-Skript ausgeführt wurde.

  1. Code holen:
    bash cd /tmp/Repo... # oder wo das Git-Repo liegt git pull

  2. Deployen (Kopieren & Neustart):
    Nutze immer das Skript, um den Code sicher zu kopieren und Services neu zu starten:

    bash sudo native_crumbcore_v1/native-update.sh
    * Stoppt Service
    * Erstellt Backup
    * Kopiert Code nach /opt/crumbforest
    * Startet Service
    * Health-Check

🔧 Wartung & Befehle

Status prüfen

sudo systemctl status crumbforest
curl http://localhost:8000/health

Logs lesen

# Live Logs
sudo journalctl -u crumbforest -f

# CrumbSeal Monitor Check
sudo native_crumbcore_v1/crumbseal_monitor.sh

Datenbank (Quick Check)

mariadb -u crumb_prod -p -e "USE crumbforest; SELECT count(*) FROM users;"

📁 Ordner-Struktur (Produktion)

/opt/crumbforest/
├── app/                  # Aktiver Code (FastAPI)
│   ├── routers/
│   ├── utils/            # inkl. crumbseal.py
│   └── main.py
├── native_crumbcore_v1/  # Kernel & Wartungsscripte
│   ├── crumbseal_monitor.sh
│   ├── native-update.sh
│   └── ...
├── venv/                 # Python Environment
└── .env                  # Config & Secrets

"Keep it ecosystem, not just system." 🌲