# 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 |