339 lines
10 KiB
Markdown
339 lines
10 KiB
Markdown
# Technical Architecture Specification
|
||
|
||
**Dokumenten-ID:** GNAI-003-INFRA
|
||
**Titel:** Homelab / LLM-Infrastruktur – Zielarchitektur
|
||
**Version:** 1.0
|
||
**Status:** Architekturentscheidung
|
||
**Vorgänger / Referenzen:** GNAI-001-INFRA, GNAI-002-INFRA
|
||
|
||
---
|
||
|
||
## 1. Zweck und Geltungsbereich
|
||
|
||
Dieses Dokument beschreibt die festgelegte Zielarchitektur für die sichere Bereitstellung des LLM-Servers und der öffentlich erreichbaren Webservices innerhalb der Ghostnet-Infrastruktur.
|
||
|
||
Es handelt sich ausdrücklich um eine **technische Spezifikation und kein Installationshandbuch**. Konkrete Implementierungsanweisungen, Konfigurationsdateien und Abnahmetests werden in nachgelagerten SOPs dokumentiert.
|
||
|
||
Die Architektur baut auf dem in **GNAI-001-INFRA** beschriebenen Debian-basierten LLM-Server und der in **GNAI-002-INFRA** beschriebenen SSH-/Benutzer-Härtung auf.
|
||
|
||
---
|
||
|
||
## 2. Architekturprinzipien
|
||
|
||
Die Infrastruktur folgt diesen Grundsätzen:
|
||
|
||
1. **Minimale Internet-Exposure:** Aus dem Internet werden ausschließlich die tatsächlich benötigten öffentlichen Dienste freigegeben.
|
||
2. **Dedizierter Reverse Proxy:** Sämtliche öffentlichen HTTP(S)-Dienste werden über einen zentralen Nginx Proxy Manager (NPM) veröffentlicht.
|
||
3. **Managementnetz getrennt von Applikationszugriff:** Privilegierter Netzwerkzugriff erfolgt über WireGuard.
|
||
4. **Anwendungsidentität über Keycloak:** Webanwendungen verwenden OIDC zur zentralen Authentifizierung.
|
||
5. **LLM-API als dedizierte Applikationsschnittstelle:** Direkter Zugriff auf `llama.cpp` aus dem Internet ist nicht vorgesehen; die öffentliche LLM-Schnittstelle wird durch LiteLLM bereitgestellt.
|
||
6. **Defense in Depth:** Reverse Proxy, Fail2Ban, Firewall-Regeln, MFA, Patchmanagement, Monitoring und Backups ergänzen sich.
|
||
7. **Least Privilege:** Zugriffe werden pro Rolle, Peer, Host und Dienst eingeschränkt.
|
||
8. **Isolation:** Öffentlich exponierte Infrastruktur und einzelne Backend-Dienste bleiben logisch bzw. durch eigene LXCs getrennt.
|
||
|
||
---
|
||
|
||
## 3. Netzwerk- und Hoststruktur
|
||
|
||
### 3.1 Bestehende Proxmox-Struktur
|
||
|
||
Der Proxmox-Server bildet die Virtualisierungs- und Isolationsschicht.
|
||
|
||
| Komponente | Adresse | Rolle |
|
||
| --- | --- | --- |
|
||
| Proxmox VE | `10.0.0.2` | Virtualisierungs-/Managementhost |
|
||
| Reverse Proxy LXC | `10.0.0.10` | einziger öffentlicher HTTP(S)-Entry-Point |
|
||
| WireGuard LXC | `10.0.0.15` | VPN-/Managementzugang |
|
||
| LLM Server | gemäß IP-Plan, aktuell `10.0.0.90` | KI-Inferenz und LLM-Dienste |
|
||
|
||
Die Service-LXCs (z. B. Nextcloud, Gitea, Vaultwarden, Keycloak etc.) verbleiben jeweils in eigenen LXCs und werden nicht in den Reverse-Proxy-LXC zusammengelegt.
|
||
|
||
### 3.2 Perimeter
|
||
|
||
Die Fritzbox 7530 bildet den Internet-Perimeter.
|
||
|
||
Aus dem Internet sollen grundsätzlich nur die für den öffentlichen Betrieb erforderlichen Weiterleitungen existieren:
|
||
|
||
- TCP 80 → Reverse Proxy LXC
|
||
- TCP 443 → Reverse Proxy LXC
|
||
- UDP auf dem festgelegten WireGuard-Port → WireGuard LXC
|
||
|
||
Managementdienste wie Proxmox Web UI oder SSH werden **nicht direkt aus dem Internet veröffentlicht**.
|
||
|
||
IPv4- und IPv6-Exposure sind gleichwertig zu betrachten und müssen bei der Implementierung separat verifiziert werden.
|
||
|
||
---
|
||
|
||
## 4. Reverse-Proxy-LXC
|
||
|
||
Der Reverse-Proxy-LXC (`10.0.0.10`) ist eine dedizierte Infrastrukturzone für öffentlich exponierte HTTP(S)-Komponenten.
|
||
|
||
### 4.1 Containerisierung
|
||
|
||
Innerhalb des LXCs wird Podman verwendet.
|
||
|
||
Vorgesehene Container:
|
||
|
||
- **Nginx Proxy Manager**
|
||
- **Fail2Ban**
|
||
|
||
NPM und Fail2Ban befinden sich absichtlich im selben LXC. Dadurch kann Fail2Ban die Logdaten von NPM auswerten und – unter minimal erforderlichen Capabilities – die Netzwerk-/Firewallebene des eigenen LXCs absichern, ohne Zugriff auf die Firewall eines anderen LXCs zu benötigen.
|
||
|
||
### 4.2 Verantwortlichkeiten
|
||
|
||
**NPM**
|
||
|
||
- TLS-Terminierung
|
||
- Reverse Proxy
|
||
- Routing zu internen Services
|
||
- HTTP(S)-Security-Header und weitere Proxy-Policies
|
||
- optionales Rate Limiting, soweit sinnvoll
|
||
|
||
**Fail2Ban**
|
||
|
||
- Erkennung wiederholter bzw. eindeutiger Missbrauchsmuster
|
||
- temporäre Sperrung auffälliger Quelladressen
|
||
- Auswertung gezielter NPM-/Applikationslogs
|
||
|
||
Fail2Ban ist eine **zusätzliche Abuse-Protection-Schicht**, kein Ersatz für Patchmanagement, sichere Authentifizierung oder Netzwerksegmentierung.
|
||
|
||
---
|
||
|
||
## 5. Öffentliche Webservices
|
||
|
||
Alle öffentlich vorgesehenen Webservices werden hinter NPM veröffentlicht.
|
||
|
||
Beispiele:
|
||
|
||
### Services auf separaten Proxmox-LXCs
|
||
|
||
- Nextcloud
|
||
- Gitea
|
||
- Vaultwarden
|
||
- Keycloak
|
||
|
||
### Services auf dem LLM-Server
|
||
|
||
- OpenWebUI
|
||
- GPT Researcher
|
||
- LiteLLM API
|
||
|
||
Direkter Internetzugriff auf die internen Backend-Ports der Services ist nicht vorgesehen.
|
||
|
||
---
|
||
|
||
## 6. LLM-Server-Architektur
|
||
|
||
Der LLM-Server basiert auf der in **GNAI-001-INFRA** dokumentierten Debian-Basis mit AMD-Multi-GPU-Konfiguration und der in **GNAI-002-INFRA** vorgesehenen SSH-Key-basierten Absicherung.
|
||
|
||
### 6.1 LLM-Inferenz
|
||
|
||
`llama.cpp` stellt die eigentliche lokale Modell-Inferenz bereit.
|
||
|
||
Grundsatz:
|
||
|
||
> `llama.cpp` wird nicht direkt aus dem Internet exponiert.
|
||
|
||
Der Zugriff erfolgt intern über die dafür vorgesehene API-Schicht.
|
||
|
||
### 6.2 LiteLLM
|
||
|
||
LiteLLM bildet die standardisierte OpenAI-kompatible API- und Policy-Schicht vor `llama.cpp`.
|
||
|
||
Verantwortlichkeiten:
|
||
|
||
- öffentliche API-Schnittstelle
|
||
- API-Key-Authentifizierung
|
||
- Routing zu laufenden Modellen
|
||
- ggf. Modell-/Benutzer-Policies
|
||
- Rate-/Quota-Steuerung
|
||
- Trennung der öffentlichen API von der eigentlichen Inferenz-Engine
|
||
|
||
Zielpfad:
|
||
|
||
```text
|
||
Internet Client
|
||
↓ HTTPS
|
||
NPM
|
||
↓
|
||
LiteLLM
|
||
↓ internes Container-/Host-Netz
|
||
llama.cpp
|
||
↓
|
||
GPU(s)
|
||
```
|
||
|
||
---
|
||
|
||
## 7. WireGuard-Managementnetz
|
||
|
||
WireGuard ist die dedizierte Zugangsschicht für privilegierte Netzwerkzugriffe.
|
||
|
||
### 7.1 Implementierung
|
||
|
||
- eigener WireGuard-LXC auf Proxmox
|
||
- `wg-easy` als Podman-Container
|
||
- WireGuard-Peer-Authentifizierung ausschließlich über kryptografische Schlüssel
|
||
- kein OIDC für die eigentliche WireGuard-Peer-Authentifizierung
|
||
|
||
### 7.2 Rollen
|
||
|
||
**Full Admin**
|
||
|
||
- Proxmox Management
|
||
- LLM-Server Management
|
||
- weitere ausdrücklich freigegebene Managementziele
|
||
|
||
**LLM Admin**
|
||
|
||
- ausschließlich LLM-Server Management
|
||
- insbesondere SSH und ggf. ausgewählte Managementschnittstellen
|
||
|
||
Die WireGuard-Konfiguration ist peer-basiert. `AllowedIPs` und zusätzliche Firewall-Regeln werden gemeinsam verwendet; ein VPN-Peer erhält nicht automatisch vollständigen Zugriff auf das LAN.
|
||
|
||
---
|
||
|
||
## 8. Keycloak / OIDC
|
||
|
||
Keycloak ist die zentrale Identitäts- und Authentifizierungsplattform für die Webanwendungen.
|
||
|
||
Vorgesehenes Modell:
|
||
|
||
```text
|
||
Browser
|
||
↓ HTTPS
|
||
NPM
|
||
↓
|
||
Web Service
|
||
↓ OIDC
|
||
Keycloak
|
||
```
|
||
|
||
Die Webservices nutzen OIDC zur Benutzeridentifikation und Authentifizierung.
|
||
|
||
Die Keycloak-Administrationsoberfläche und administrative Managementschnittstellen sollen nicht öffentlich zugänglich sein und werden über das Managementnetz bereitgestellt.
|
||
|
||
Öffentlich erforderlich bleiben ausschließlich die für OIDC tatsächlich benötigten Endpunkte des jeweiligen Realms.
|
||
|
||
---
|
||
|
||
## 9. SSH
|
||
|
||
SSH auf dem LLM-Server wird ausschließlich schlüsselbasiert betrieben.
|
||
|
||
Aus **GNAI-INFRA-002** übernimmt die Zielkonfiguration insbesondere:
|
||
|
||
- `PermitRootLogin no`
|
||
- `PasswordAuthentication no`
|
||
- `KbdInteractiveAuthentication no`
|
||
- `PubkeyAuthentication yes`
|
||
|
||
Der LLM-Server-SSH-Port wird nicht aus dem Internet veröffentlicht.
|
||
|
||
Zulässige Herkunft:
|
||
|
||
- lokales vertrauenswürdiges Netzwerk
|
||
- WireGuard-Managementnetz
|
||
|
||
---
|
||
|
||
## 10. Sicherheitszonen und Vertrauensmodell
|
||
|
||
Die Infrastruktur unterscheidet mindestens drei Vertrauensklassen:
|
||
|
||
### Public Application Access
|
||
|
||
Zugang über:
|
||
|
||
```text
|
||
HTTPS → NPM
|
||
```
|
||
|
||
Authentifizierung erfolgt je nach Anwendung über:
|
||
|
||
- OIDC / Keycloak
|
||
- API-Key bei der LLM-API
|
||
|
||
### Management Access
|
||
|
||
Zugang über:
|
||
|
||
```text
|
||
WireGuard → Zielsystem
|
||
```
|
||
|
||
Zusätzliche Dienstauthentifizierung bleibt erhalten, z. B. SSH Public Keys oder Proxmox-Authentifizierung.
|
||
|
||
### Backend Access
|
||
|
||
Nicht öffentlich.
|
||
|
||
Beispiele:
|
||
|
||
- `llama.cpp`
|
||
- interne Datenbankports
|
||
- interne Container-/Serviceports
|
||
- sonstige administrative Backend-Schnittstellen
|
||
|
||
---
|
||
|
||
## 11. Geplante Defense-in-Depth-Schichten
|
||
|
||
Die Zielarchitektur sieht folgende komplementäre Schutzschichten vor:
|
||
|
||
1. Fritzbox als Perimeter
|
||
2. keine unnötigen Portweiterleitungen
|
||
3. Proxmox-/LXC-Netzwerk- und Firewallregeln
|
||
4. dedizierter Reverse Proxy
|
||
5. Fail2Ban für erkannte Missbrauchsmuster
|
||
6. TLS/HTTPS
|
||
7. zentrale Authentifizierung mit Keycloak/OIDC
|
||
8. MFA/WebAuthn für privilegierte Benutzer, wo unterstützt
|
||
9. API-Keys bzw. OAuth-/Anwendungscredentials für Maschinenzugriffe
|
||
10. SSH ausschließlich über Schlüssel
|
||
11. regelmäßige Updates / Patchmanagement
|
||
12. Backup- und Restore-Strategie
|
||
13. externes Monitoring und regelmäßige Prüfung der öffentlichen Exposure
|
||
|
||
---
|
||
|
||
## 12. Nicht Teil dieser Spezifikation
|
||
|
||
Folgende Punkte sind Architekturentscheidungen vorbehalten und werden in Implementierungsdokumenten konkretisiert:
|
||
|
||
- konkrete WireGuard-Subnetze und Peer-Adressen
|
||
- konkrete Firewall-Regelsätze
|
||
- genaue `wg-easy`-Version und Containerparameter
|
||
- genaue NPM-Container-/Storage-Konfiguration
|
||
- konkrete Fail2Ban-Jails und Filter
|
||
- konkrete LiteLLM-Modell- und Key-Policies
|
||
- konkrete Keycloak-Realm-/Client-Struktur
|
||
- konkrete DNS-/Domainnamen
|
||
- konkrete Backup- und Monitoring-Implementierung
|
||
|
||
---
|
||
|
||
## 13. Architektur-Abnahmekriterien
|
||
|
||
Die Architektur gilt als korrekt umgesetzt, wenn mindestens folgende Eigenschaften nachweisbar sind:
|
||
|
||
- Nur vorgesehene öffentliche Ports sind aus dem Internet erreichbar.
|
||
- Proxmox ist nicht direkt aus dem Internet erreichbar.
|
||
- SSH des LLM-Servers ist nicht direkt aus dem Internet erreichbar.
|
||
- `llama.cpp` ist nicht direkt aus dem Internet erreichbar.
|
||
- Öffentliche Webservices terminieren an NPM.
|
||
- Fail2Ban befindet sich zusammen mit NPM im Reverse-Proxy-LXC.
|
||
- Full-Admin- und LLM-Admin-WireGuard-Peers besitzen unterschiedliche, restriktive Zugriffsprofile.
|
||
- Webanwendungen authentifizieren Benutzer über Keycloak/OIDC.
|
||
- Die LLM-API wird über LiteLLM bereitgestellt und über API-Key geschützt.
|
||
- Administrative Weboberflächen von Keycloak sind nicht öffentlich.
|
||
- Service-LXCs bleiben voneinander isoliert und erlauben nur erforderliche Kommunikationsbeziehungen.
|
||
|
||
---
|
||
|
||
## 14. Änderungsverlauf
|
||
|
||
| Datum | Version | Geändert von | Beschreibung |
|
||
| --- | --- | --- | --- |
|
||
| 2026-08-28 | 1.0 | spektr | Erstellung der Zielarchitektur |
|