mindnet/docs/04_Operations/04_server_operation_manual.md

---
doc_type: operations_manual
audience: system_admin, devops
scope: server_lifecycle, disaster_recovery, maintenance, backup, monitoring
status: active
version: 1.9
hostname: llm-node
ip_address: 192.168.2.144
context: "Zentrale Dokumentation für Host-Konfiguration, Mindnet-Applikation, Gitea und Backup-Strategie. Aktualisiert um die Two-Stage Disaster Recovery und Backup-Monitoring."
created_date: 2025-12-14
last_updated: 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):**
    ```text
    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`)

```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.
    ```bash
    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.
    ```bash
    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.
    ```bash
    # 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.
    ```bash
    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!**
    ```bash
    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.
    ```bash
    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.

```bash
# 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:
    ```bash
    cd /home/llmadmin/docker/qdrant
    ```
2.  Entpacke das gesicherte Tar (stellt den Ordner `qdrant_data` wieder her):
    ```bash
    sudo tar -xzf /home/llmadmin/qdrant_backup_latest.tar.gz
    ```
3.  Container starten (Volume-Mount ist korrekt):
    ```bash
    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:
    ```bash
    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:**
    ```bash
    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.
    ```bash
    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.
    ```bash
    # 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.
    ```bash
    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`