Files

T

2026-08-28 18:54:45 +02:00

10 KiB

Raw Permalink Blame History

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:

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.cpp aus 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: Zugriffe werden pro Rolle, Peer, Host und Dienst eingeschränkt.
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:

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:

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:

HTTPS → NPM

Authentifizierung erfolgt je nach Anwendung über:

OIDC / Keycloak
API-Key bei der LLM-API

Management Access