Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
c8c828c8a8
mindnet/docs/04_Operations/04_server_operation_manual.md
Lars bfb42cfc24
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Details
handbuch
2025-12-15 08:29:08 +01:00

10 KiB
Raw Blame History

doc_type audience scope status version hostname ip_address context created_date last_updated
operations_manual system_admin, devops server_lifecycle, disaster_recovery, maintenance, backup, monitoring active 1.9 llm-node 192.168.2.144 Zentrale Dokumentation für Host-Konfiguration, Mindnet-Applikation, Gitea und Backup-Strategie. Aktualisiert um die Two-Stage Disaster Recovery und Backup-Monitoring. 2025-12-14 2025-12-15

Server Operations Manual: llm-node (192.168.2.144)

Dieses Dokument beschreibt den Betrieb, die Wartung und die Wiederherstellung (Disaster Recovery) des Servers "llm-node".

1. Systemübersicht & Netzwerk

1.1 Host Details

  • Hostname: llm-node
  • IP-Adresse: 192.168.2.144
  • OS: Ubuntu Server
  • Qdrant Host-Volume Pfad: /home/llmadmin/docker/qdrant/qdrant_data (Bind-Mount)

1.2 Storage & NAS Mount

Das System sichert auf ein Synology NAS via NFSv3.

  • Mount Point: /mnt/nas_backup
  • Quelle: 192.168.2.63:/volume1/Backup_LLM
  • Fstab-Eintrag (Referenz für Restore): 
    192.168.2.63:/volume1/Backup_LLM  /mnt/nas_backup  nfs  vers=3,_netdev,x-systemd.automount,nofail  0  0

2. Dienste & Port-Matrix

2.1 Native Dienste (Systemd)

Service Port User Beschreibung
SSH 22 root Remote Zugriff
Gitea 3000 git Git Version Control (User: git)
Ollama 11434 ollama AI Model Server
Mindnet Prod API 8001 llmadmin Backend Applikation
Mindnet Dev API 8002 llmadmin Backend Applikation (Entwicklung)
Mindnet Prod UI 8501 llmadmin Frontend Applikation
Mindnet Dev UI 8502 llmadmin Frontend Applikation (Entwicklung)
Act Runner 38703 root Gitea CI/CD Runner

2.2 Docker Container

Übersicht der Container (docker ps).

Container Name Port Beschreibung Backup Strategie
qdrant 6333 Vektor Datenbank (Container Name: qdrant) Stop -> Tar -> Start (Konsistenter Snapshot)
mindnet-embed 8990 Embeddings Service Volume Backup
code-server 8443 VS Code (Web) Volume Backup
silverbullet 13000 Knowledge Base Volume Backup

3. Applikations-Management

3.1 Gitea (Git Server)

  • User: git
  • Datenpfad: /var/lib/gitea
  • Backup: Konsistenter Dump (gitea-dump.zip) im before_backup Hook integriert.

3.2 Ollama (AI Models)

  • User: ollama
  • Modell-Speicher: /usr/share/ollama/.ollama/models
  • Backup: Nur Metadaten. Blobs werden exkludiert.

3.3 Mindnet (AI App)

  • User: llmadmin
  • Qdrant Storage: /home/llmadmin/docker/qdrant/qdrant_data
  • Cronjob: Regelmäßiger Import (stündlich) unter User llmadmin.

4. Backup Strategie (Borgmatic)

Status: Automatisiert via systemctl start borgmatic.timer. Ziel: /mnt/nas_backup/borg_repo

4.1 Konsistenz-Strategie

Alle schreibenden Dienste werden durch Hooks für das Backup vorbereitet:

4.2 Konfiguration (/etc/borgmatic/config.yaml)

source_directories:
    - /etc
    - /home
    - /var
    - /opt
    - /root

repositories:
    - path: /mnt/nas_backup/borg_repo
      label: nas

exclude_patterns:
    - /mnt/*
    - /var/lib/gitea/data/tmp/*
    # Ollama Blobs (Speicher sparen)
    - /usr/share/ollama/.ollama/models/blobs/*
    - /home/*/.ollama/models/blobs/*
    # Qdrant Live-Daten exkludieren
    - /home/llmadmin/docker/qdrant/qdrant_data/*

keep_daily: 7
keep_weekly: 4
keep_monthly: 6

before_backup:
    - echo "--- Start Pre-Backup Hooks ---"
    
    # 1. Ollama Liste sichern
    - ollama list > /root/ollama_models_backup.txt
    
    # 2. Gitea Dump
    - echo "Erstelle Gitea Dump..."
    - rm -f /var/lib/gitea/gitea-dump.zip
    - runuser -u git -- gitea dump -c /etc/gitea/app.ini -f /var/lib/gitea/gitea-dump.zip
    
    # 3. Qdrant Snapshot
    - echo "Erstelle Qdrant Snapshot..."
    - docker stop qdrant
    - rm -f /home/llmadmin/qdrant_backup_latest.tar.gz
    # Tar Archiv im Home-Verzeichnis erstellen (wird von Borg gesichert)
    - tar -czf /home/llmadmin/qdrant_backup_latest.tar.gz -C /home/llmadmin/docker/qdrant qdrant_data
    - docker start qdrant

after_backup:
    - echo "Backup erfolgreich beendet."
    # Nach erfolgreichem Backup wird das temporäre Tar-Archiv gelöscht
    - rm -f /home/llmadmin/qdrant_backup_latest.tar.gz

on_error:
    - echo "FEHLER aufgetreten! Versuche Container zu retten..."
    - docker start qdrant

5. Disaster Recovery (Wiederherstellung) - Two-Stage DR

Das Wiederherstellungsverfahren basiert auf einer "Two-Stage DR"-Strategie, die die Geschwindigkeit eines Basis-Images mit der Datenkonsistenz des Borgmatic-Archives kombiniert.

5.0 Vorbereitung: Erstellung des Basis-Images (Monatlich/Quartalsweise)

Dieses Image sichert das bootfähige System (OS, Pakete, Konfiguration) und dient als schneller Startpunkt bei einem Festplattenausfall.

  1. System Bereinigen: Führen Sie eine Systembereinigung durch, um die Image-Größe zu minimieren. 
    sudo apt clean
sudo journalctl --vacuum-time=7d
  2. Booten vom Live-Medium: Starten Sie den Server von einem Ubuntu Live USB-Stick (Größe min. 8 GB).
  3. Mount NAS: Stellen Sie die Verbindung zum NAS her, um das Image direkt dorthin zu schreiben. 
    sudo mkdir /mnt/nas_backup
sudo mount -t nfs 192.168.2.63:/volume1/Backup_LLM /mnt/nas_backup
  4. Image erstellen und streamen: Ermitteln Sie die Root-Partition des Servers (z.B. /dev/sda1) und erstellen Sie das komprimierte Image direkt auf dem NAS. 
    # Das Image wird direkt zum NAS gestreamt (USB-Stick benötigt nur 8GB für Live OS)
sudo dd if=/dev/sda1 bs=1M status=progress | gzip > /mnt/nas_backup/base_image_$(date +%Y%m%d).img.gz

5.1 Stage 1: Basis-Image Restore (Bare Metal Recovery)

Dieses Verfahren setzt das System auf den Stand des letzten Basis-Images zurück.

Prozedur (Von Live-Medium booten):

  1. Voraussetzungen: Booten Sie den neuen/reparierten PC von einem Live-Medium (z.B. Ubuntu Live USB).
  2. Mount NAS (auf Live-System): Stellen Sie die Verbindung zum Backup-Speicher her, um auf das Image zuzugreifen. 
    sudo mkdir /mnt/nas_backup
sudo mount -t nfs 192.168.2.63:/volume1/Backup_LLM /mnt/nas_backup
  3. Zielpartition identifizieren: Ermitteln Sie den Gerätenamen der Root-Partition der neuen Festplatte (z.B. /dev/sda1). ACHTUNG: Falsches Gerät löscht alle Daten! 
    sudo fdisk -l
  4. Image Restore: Schreiben Sie das komprimierte Basis-Image auf die neue Partition zurück. Ersetzen Sie YYYYMMDD durch das tatsächliche Datum und /dev/sda1 durch Ihre Zielpartition. 
    sudo gunzip -c /mnt/nas_backup/base_image_YYYYMMDD.img.gz | sudo dd of=/dev/sda1 status=progress bs=1M
  5. Neustart: Entfernen Sie den Live-USB und starten Sie das System neu. Es sollte nun in das wiederhergestellte Basis-OS booten.

5.2 Stage 2: Daten-Update (Borgmatic)

Nach dem Booten des Basis-Systems (Stage 1) werden die aktuellen Daten und die kritischen Applikations-Snapshots wiederhergestellt.

Schritt 1: Aktueller Daten Restore (Borg)

Das Borg-Repository ist dank des Basis-Images bereits in /etc/borgmatic/config.yaml und /etc/fstab bekannt.

# Alle Daten aus dem letzten Archiv (latest) auf das laufende System wiederherstellen
sudo borgmatic extract --archive latest --path / --destination /

Schritt 2: Dienste spezifisch wiederherstellen (Gitea/Qdrant/Ollama)

A. Gitea (Aus Dump):

  1. Dump entpacken: unzip /var/lib/gitea/gitea-dump.zip -d /tmp/gitea_restore
  2. Service starten: systemctl enable --now gitea

B. Qdrant (Aus Snapshot): Das Tar-Archiv liegt im Home-Verzeichnis (/home/llmadmin/) und muss in das Volume-Verzeichnis entpackt werden.

  1. Wechsle in das Host-Verzeichnis des Volumes: 
    cd /home/llmadmin/docker/qdrant
  2. Entpacke das gesicherte Tar (stellt den Ordner qdrant_data wieder her): 
    sudo tar -xzf /home/llmadmin/qdrant_backup_latest.tar.gz
  3. Container starten (Volume-Mount ist korrekt): 
    docker start qdrant

C. Ollama (Smart Restore):

  1. Ollama installieren (falls im Basis-Image nicht enthalten).
  2. Modelle mit dem Script aus /root/ollama_models_backup.txt neu ziehen: 
    sudo tail -n +2 /root/ollama_models_backup.txt | awk '{print $1}' | while read model; do ollama pull "$model"; done

6. Log- und Fehleranalyse & Wartung

6.1 Backup-Überwachung (Monitoring)

Die Überprüfung der Backup-Korrektheit erfolgt über das Systemd Journal und die Borgmatic-Befehle.

Aktion Befehl Zweck
Prüfung letzter Lauf sudo journalctl -u borgmatic --since "yesterday" Zeigt das Journal der letzten 24 Stunden, inklusive der Hooks und Fehler.
Liste Archive sudo borgmatic list Zeigt alle existierenden Archive, sortiert nach Datum/Uhrzeit. Dient zur Bestätigung, dass das Backup erstellt wurde.
Repo-Integrität sudo borgmatic check Führt eine Konsistenzprüfung des gesamten Repositorys durch (kann lange dauern).

6.2 Granulare Wiederherstellung (Einzelne Dateien)

Um auf einzelne Dateien oder Verzeichnisse in einem Archiv zuzugreifen, wird das Archiv als virtuelles Dateisystem gemountet.

  1. Mount-Punkt erstellen: 
    mkdir /tmp/borg_mount
  2. Archiv einhängen: Hängen Sie das gewünschte Archiv (hier: latest) in den Mount-Punkt ein. Geben Sie bei Bedarf den vollständigen ARCHIVNAMEN an. 
    sudo borgmatic mount --destination /tmp/borg_mount --archive latest
  3. Dateizugriff: Das gesamte Backup-Dateisystem ist nun unter /tmp/borg_mount verfügbar. Dateien können mit cp kopiert werden. 
    # Beispiel: Eine Datei aus dem Home-Verzeichnis wiederherstellen
sudo cp /tmp/borg_mount/home/llmadmin/wichtige_datei.txt /home/llmadmin/
  4. Archiv aushängen: Nach dem Kopieren muss das virtuelle Dateisystem immer ausgehängt werden. 
    sudo umount /tmp/borg_mount
# Oder:
# sudo borgmatic umount /tmp/borg_mount

7. Anhang

  • Qdrant Container Logs: docker logs qdrant
  • Applikations-Logs: journalctl -u mindnet-prod