14 KiB
Technical Architecture Specification
Dokumenten-ID: GNAI-003-INFRA
Titel: Homelab / LLM-Infrastruktur – Zielarchitektur
Status: Zielarchitektur; bestätigter Teilstand und offene Umsetzung separat ausgewiesen
Vorgänger / Referenzen: Basisinstallation, Benutzer/SSH, Zugriffskonzept, Reverse Proxy, WireGuard
Änderungsverlauf
| Datum | Version | Autor | Beschreibung |
|---|---|---|---|
| 2026-08-28 | 1.0 | spektr | Erstellung der Zielarchitektur |
| 2026-09-15 | 1.1 | spektr | Adressplan, Rollenmodell, OIDC-Ist und offene Sicherheitsbefunde ergänzt. |
| 2026-09-16 | 1.2 | spektr | Bestätigten Fail2Ban-Pin und noch offene Funktionsabnahme ergänzt. |
| 2026-09-18 | 1.3 | spektr | Tatsächlichen KI-Server-Hostnamen übernommen; frischen Basisstand und späteren Ansible-Sprint vom Zielbild getrennt. |
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.
Der KI-Server ist laut Betreiber am 18.09.2026 frisch eingerichtet. Sein LLM-Anwendungsstack soll in einem späteren Sprint mit Ansible installiert werden. llama.cpp, LiteLLM, OpenWebUI und GPT Researcher in diesem Dokument sind geplante Komponenten, keine bereits installierten Dienste.
2. Architekturprinzipien
Die Infrastruktur folgt diesen Grundsätzen:
- Minimale Internet-Exposure: Aus dem Internet werden ausschließlich die tatsächlich benötigten öffentlichen Dienste freigegeben.
- Dedizierter Reverse Proxy: Sämtliche öffentlichen HTTP(S)-Dienste werden über einen zentralen Nginx Proxy Manager (NPM) veröffentlicht.
- Managementnetz getrennt von Applikationszugriff: Privilegierter Netzwerkzugriff erfolgt über WireGuard.
- Anwendungsidentität über Keycloak: Webanwendungen verwenden OIDC zur zentralen Authentifizierung.
- LLM-API als dedizierte Applikationsschnittstelle: Direkter Zugriff auf
llama.cppaus dem Internet ist nicht vorgesehen; die öffentliche LLM-Schnittstelle wird durch LiteLLM bereitgestellt. - Defense in Depth: Reverse Proxy, Fail2Ban, Firewall-Regeln, MFA, Patchmanagement, Monitoring und Backups ergänzen sich.
- Least Privilege: Server Admins und LLM Admins erhalten passende Serverrechte; Familie ist ausdrücklich für das gesamte Heimnetz freigegeben. Netzwerkrechte werden pro Peer serverseitig durchgesetzt.
- 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 | 10.0.0.90, Hostname ghostnet-ki |
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.
Adressplanung und aktuelles Serviceinventar
Heimnetz 10.0.0.0/24, Fritzbox/Gateway/DNS .1. Statische Server-/LXC-Adressen sind bis .99 vorgesehen; DHCP vergibt .100–.200 an Clients. Die .90 ist dem physischen KI-Server vorbehalten. Das ist eine Belegungsordnung innerhalb desselben Netzes, keine VLAN-/Firewall-Isolation.
| Host / Service | Quellenstand | Status der Angabe |
|---|---|---|
| Proxmox | 10.0.0.2 |
Betreiber bestätigt |
| Keycloak | 10.0.0.4:8080 |
Betreiber bestätigt NPM-Backend |
| NPM / wg-easy | 10.0.0.10 / 10.0.0.15 |
Betreiber bestätigt |
| Jellyfin | 10.0.0.11:8096 |
GNAI-005-Inventar, vor Freigabe abgleichen |
| Nextcloud | 10.0.0.12:8080 |
GNAI-005-Inventar, vor Freigabe abgleichen |
| Gitea | 10.0.0.17:3000 |
GNAI-005-Inventar, vor Freigabe abgleichen |
| Japanese Web App | 10.0.0.23:80 |
GNAI-005-Inventar, vor Freigabe abgleichen |
| Vaultwarden | 10.0.0.47:8080 |
GNAI-005-Inventar; OIDC-Nutzung vom Betreiber bestätigt |
| KI-Server | 10.0.0.90 |
Betreiber bestätigt |
Neue LXCs im Inventar ergänzen. Der ursprüngliche Bereich .4–.40 war geschätzt und ist keine gültige Grenze. Lokales Gästenetz, mögliche separate Servernetze, Routing und VLAN-Unterstützung gehören in einen späteren Netzwerk-Sprint; es gibt hierfür noch keine beschlossenen Netzadressen. Automatische Broadcast-/Multicast-Geräteerkennung über WireGuard wird nicht vorausgesetzt.
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
10.0.0.10 - TCP 443 → Reverse Proxy LXC
10.0.0.10 - UDP 51820 → WireGuard LXC
10.0.0.15
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 soll die eigentliche lokale Modell-Inferenz bereitstellen.
Grundsatz:
llama.cppwird nicht direkt aus dem Internet exponiert.
Der Zugriff erfolgt intern über die dafür vorgesehene API-Schicht.
6.2 LiteLLM
LiteLLM soll die standardisierte OpenAI-kompatible API- und Policy-Schicht vor llama.cpp bilden.
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:
Im Zielbild verbindet sich ein externer Client per HTTPS mit NPM. NPM leitet an LiteLLM weiter; LiteLLM nutzt llama.cpp über das interne Container-/Hostnetz. Die Inferenz soll auf den GPUs laufen. Dieser Pfad ist auf dem frisch eingerichteten KI-Server noch nicht umgesetzt.
7. WireGuard-Managementnetz
WireGuard ist die dedizierte Zugangsschicht für privilegierte Netzwerkzugriffe.
7.1 Implementierung
- eigener WireGuard-LXC auf Proxmox
wg-easyals Podman-Container- WireGuard-Peer-Authentifizierung ausschließlich über kryptografische Schlüssel
- kein OIDC für die eigentliche WireGuard-Peer-Authentifizierung
7.2 Rollen und VPN-Betrieb
| Rolle | Zielrechte |
|---|---|
| Familie (Brüder) | gesamtes Heimnetz einschließlich PCs/Clients; Serververwaltung nach Dienstanmeldung |
| Server Admin | Proxmox, Service-LXCs und KI-Server; NPM und wg-easy eingeschlossen |
| LLM Admin | ausschließlich KI-Server 10.0.0.90 |
Profile werden pro Gerät vom Administrator erstellt und verteilt. Benutzer benötigen für den Profilbezug keine GUI-Anmeldung. Serverseitige Firewall Allowed IPs in wg-easy sollen die Zielrechte durchsetzen; clientseitige Allowed IPs steuern Split-Tunneling. Per-Client Firewall ist aktuell deaktiviert, Rollenisolierung nicht abgenommen. Gateway-GUI/SSH benötigen zusätzlich passende INPUT-Regeln. Die alte Full-Admin-Bezeichnung wird nicht automatisch einer der neuen Rollen gleichgesetzt.
Das Gateway nutzt MASQUERADE für VPN→LAN; die Fritzbox besitzt keine Rückroute zum VPN-Netz. LAN-Dienste sehen dadurch die Quelladresse des Gateways. Die serverseitige Peer-Zielkontrolle muss vor NAT greifen. Installation, Hooks und Abnahme stehen in GNAI-006.
8. Keycloak / OIDC
Keycloak ist die zentrale Identitäts- und Authentifizierungsplattform für die Webanwendungen.
Vorgesehenes Modell:
Der Browser erreicht den Webdienst über HTTPS und NPM. Der Webdienst bindet Keycloak für den OIDC-Anmeldeprozess ein; Anwendung und Identitätsquelle behalten getrennte Aufgaben.
Webservices sollen OIDC nutzen, soweit die jeweilige Anwendung daran angebunden wird. Laut Betreiber ist derzeit nur Vaultwarden produktiv an Keycloak/OIDC angebunden.
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-002-INFRA übernimmt die Zielkonfiguration insbesondere:
PermitRootLogin noPasswordAuthentication noKbdInteractiveAuthentication noPubkeyAuthentication 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:
HTTPS über NPM.
Authentifizierung erfolgt je nach Anwendung über:
- OIDC / Keycloak
- API-Key bei der LLM-API
Management Access
Zugang über:
WireGuard zum freigegebenen 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:
- Fritzbox als Perimeter
- keine unnötigen Portweiterleitungen
- Proxmox-/LXC-Netzwerk- und Firewallregeln
- dedizierter Reverse Proxy
- Fail2Ban für erkannte Missbrauchsmuster
- TLS/HTTPS
- zentrale Authentifizierung mit Keycloak/OIDC
- MFA/WebAuthn für privilegierte Benutzer, wo unterstützt
- API-Keys bzw. OAuth-/Anwendungscredentials für Maschinenzugriffe
- SSH ausschließlich über Schlüssel
- regelmäßige Updates / Patchmanagement
- Backup- und Restore-Strategie
- externes Monitoring und regelmäßige Prüfung der öffentlichen Exposure
12. Nicht Teil dieser Spezifikation
Folgende konkrete Werte und Verfahren werden in den Fachdokumenten geführt. Einige sind bereits festgelegt, andere dort ausdrücklich als offen markiert:
- 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.cppist nicht direkt aus dem Internet erreichbar.- Öffentliche Webservices terminieren an NPM.
- Fail2Ban befindet sich zusammen mit NPM im Reverse-Proxy-LXC.
- Familie-, Server-Admin- und LLM-Admin-Peers besitzen die beschlossenen, serverseitig durchgesetzten 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. Umsetzungsstand
Die Architektur-Abnahmekriterien in Abschnitt 13 sind Sollkriterien und keine bestätigte Abnahme. Der aktuelle Projektstand und die priorisierten Befunde stehen im Dokumentationsindex; technische Nachweise und offene Prüfungen werden in GNAI-005 und GNAI-006 geführt. Backendisolation und lokale Netzwerksegmentierung sind ebenfalls noch nachzuweisen.