From 53c5970c609c2cee1d82990948f87c3c1d38f5e5 Mon Sep 17 00:00:00 2001 From: spektr Date: Tue, 22 Sep 2026 15:07:16 +0200 Subject: [PATCH] =?UTF-8?q?Projektrestrukturierung=20und=20Aufr=C3=A4umen.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 3 + README.md | 9 +- docs/GNAI-000-DOC_Index.md | 196 ++++++++---------- docs/GNAI-001-PLAN_Project-Roadmap.md | 193 +++++++++++++++++ ...ture.md => GNAI-004-INFRA_Architecture.md} | 65 ++++-- ...md => GNAI-008-PLAN_Ansible-Deployment.md} | 178 +++++----------- ...> GNAI-009-PLAN_Llama-Model-Evaluation.md} | 8 +- ...ving.md => GNAI-010-TECH_Llama-Serving.md} | 31 +-- docs/ai/README.md | 9 +- ...System.md => GNAI-002-INFRA_BaseSystem.md} | 10 +- ...INFRA_Users.md => GNAI-003-INFRA_Users.md} | 4 +- ...trol.md => GNAI-005-SEC_Access-Control.md} | 31 +-- ...Proxy.md => GNAI-006-SEC_Reverse-Proxy.md} | 6 +- docs/platform/GNAI-006-profiles/.gitignore | 4 - ...NAI-006-SEC_VPN.md => GNAI-007-SEC_VPN.md} | 10 +- ... => GNAI-007-SEC_VPN_Client-Management.md} | 4 +- ...x.md => GNAI-007-SEC_VPN_Clients_Linux.md} | 4 +- ... => GNAI-007-SEC_VPN_Clients_Windows11.md} | 4 +- ...=> GNAI-007-SEC_VPN_Implementation-Log.md} | 13 +- docs/platform/README.md | 18 +- 20 files changed, 479 insertions(+), 321 deletions(-) create mode 100644 docs/GNAI-001-PLAN_Project-Roadmap.md rename docs/ai/{GNAI-003-INFRA_Architecture.md => GNAI-004-INFRA_Architecture.md} (80%) rename docs/ai/{GNAI-007-PLAN_Ansible-Deployment.md => GNAI-008-PLAN_Ansible-Deployment.md} (84%) rename docs/ai/{GNAI-008-PLAN_Llama-Model-Evaluation.md => GNAI-009-PLAN_Llama-Model-Evaluation.md} (97%) rename docs/ai/{GNAI-009-TECH_Llama-Serving.md => GNAI-010-TECH_Llama-Serving.md} (94%) rename docs/platform/{GNAI-001-INFRA_BaseSystem.md => GNAI-002-INFRA_BaseSystem.md} (96%) rename docs/platform/{GNAI-002-INFRA_Users.md => GNAI-003-INFRA_Users.md} (98%) rename docs/platform/{GNAI-004-SEC_Access-Control.md => GNAI-005-SEC_Access-Control.md} (88%) rename docs/platform/{GNAI-005-SEC_Reverse-Proxy.md => GNAI-006-SEC_Reverse-Proxy.md} (98%) delete mode 100644 docs/platform/GNAI-006-profiles/.gitignore rename docs/platform/{GNAI-006-SEC_VPN.md => GNAI-007-SEC_VPN.md} (98%) rename docs/platform/{GNAI-006-SEC_VPN_Client-Management.md => GNAI-007-SEC_VPN_Client-Management.md} (97%) rename docs/platform/{GNAI-006-SEC_VPN_Clients_Linux.md => GNAI-007-SEC_VPN_Clients_Linux.md} (98%) rename docs/platform/{GNAI-006-SEC_VPN_Clients_Windows11.md => GNAI-007-SEC_VPN_Clients_Windows11.md} (97%) rename docs/platform/{GNAI-006-SEC_VPN_Implementation-Log.md => GNAI-007-SEC_VPN_Implementation-Log.md} (95%) diff --git a/.gitignore b/.gitignore index f361c46..3ab75a7 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ .venv/ .ansible/ *.retry + +# Local WireGuard profiles contain private key material; ignore the directory completely. +/docs/platform/GNAI-007-profiles/ diff --git a/README.md b/README.md index 673f852..4078cee 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Die drei vorgesehenen VPN-Netzwerkrollen sind **Familie** (gesamtes Heimnetz), * | Bereich | Belegter Stand | Nächster Nachweis oder Schritt | | --- | --- | --- | -| KI-Server | Debian-Basissystem, Deployment-Zugang, Podman 5.4.2, drei getrennte rootless Workload-Konten sowie zwei als `gfx1030` und als `llama.cpp`-ROCm-Geräte geprüfte RX 6900 XT | `llama.cpp` als Testing-Quadlet mit geprüftem Modellprofil bereitstellen | +| KI-Server | Debian-Basissystem, Deployment-Zugang, Podman 5.4.2, drei getrennte rootless Workload-Konten sowie zwei als `gfx1030` und als `llama.cpp`-ROCm-Geräte geprüfte RX 6900 XT | nach der Prioritätsentscheidung internes `llama.cpp`-Testing ohne öffentliche Route bereitstellen | | VPN | wg-easy v15.4.0 auf CT 105 aktiv; ein externer Laptop-Teiltest liegt vor | Rollenrechte serverseitig umsetzen und mit erlaubten sowie gesperrten Zielen testen | | Reverse Proxy | NPM auf CT 103 dokumentiert; Fail2Ban laut Betreiber fest gepinnt und wieder in Betrieb | Effektive Jails, Sperren und Wiederanlauf prüfen | | Identität | Keycloak/OIDC laut Betreiber produktiv für Vaultwarden | Öffentlich erreichbare Keycloak-Administration sperren und den OIDC-Login erneut prüfen | @@ -38,6 +38,7 @@ Der [Dokumentationsindex](docs/GNAI-000-DOC_Index.md) enthält die datierten Que | Einstieg | Inhalt | | --- | --- | | [Dokumentationsindex und Projektstand](docs/GNAI-000-DOC_Index.md) | Dokumentenübersicht, bestätigte Entscheidungen und offene Befunde | +| [High-Level-Implementierungsplan](docs/GNAI-001-PLAN_Project-Roadmap.md) | priorisierte nächste Schritte, Entscheidungstore und messbare Abschlusskriterien | | [Plattform-Dokumentation](docs/platform/README.md) | Hostbasis, Zugriffsmodell, Reverse Proxy und VPN | | [KI-Dokumentation](docs/ai/README.md) | KI-Zielarchitektur, Ansible-Planung, Modellbewertung und technische `llama.cpp`-Sollkonfiguration | | [Video-Encoding](docs/video-encoding/GNENC-000-DOC_Index.md) | getrennter Planungs- und späterer SOP-Bereich für den CPU-Encoding-Workload | @@ -47,6 +48,10 @@ Der [Dokumentationsindex](docs/GNAI-000-DOC_Index.md) enthält die datierten Que Dieses Repository enthält Dokumentation und ein Ansible-Control-Projekt. Es prüft Inventar, SSH-Zugang, Hostidentität, Betriebssystem und die dokumentierten GPUs. Gemeinsame Rollen verwalten Plattform, Podman und getrennte Workload-Identitäten. KI- und Encoding-Fachdokumentation bleiben in getrennten Bereichen. Im Testing-Store liegt nur das gepinnte ROCm-Probeimage; dauerhafte Anwendungscontainer sind noch nicht bereitgestellt. Vor einer Infrastrukturänderung den Ist-Stand am betroffenen Host prüfen, die passende Fachanleitung lesen und die dort genannten Abnahmeschritte dokumentieren. -WireGuard-Profile enthalten private Schlüssel. Sie gehören nicht in Git, Ausgaben oder freigegebene Dokumente. Das lokale Verzeichnis `docs/platform/GNAI-006-profiles/` schließt Profil-Dateien über eine eigene `.gitignore` aus; es ist kein Verteiler- oder Backup-Ort für Zugangsdaten. +WireGuard-Profile enthalten private Schlüssel. Sie gehören nicht in Git, +Ausgaben oder freigegebene Dokumente. Das lokale Verzeichnis +`docs/platform/GNAI-007-profiles/` wird vollständig durch die +Repository-`.gitignore` ausgeschlossen; es ist kein Verteiler- oder Backup-Ort +für Zugangsdaten. Änderungen am Projektstand sollten zuerst im zuständigen Fachdokument mit Datum und Beleg erfasst werden. Anschließend den [Index](docs/GNAI-000-DOC_Index.md) und diese README aktualisieren, wenn sich eine übergreifende Aussage geändert hat. diff --git a/docs/GNAI-000-DOC_Index.md b/docs/GNAI-000-DOC_Index.md index b7a3af4..e5bd569 100644 --- a/docs/GNAI-000-DOC_Index.md +++ b/docs/GNAI-000-DOC_Index.md @@ -1,135 +1,119 @@ # Ghostnet.AI – Dokumentationsindex und Projektstand **Stand:** 2026-09-21 -**Status:** Revisionen zusammengeführt; Sicherheitsumsetzung und technische Endabnahme offen -## 1. Dokumente und Zielgruppen +**Status:** Plattformgrundlage vorhanden; Sicherheitsabschluss und LLM-Serving offen -### Plattform und Host +Dieses Dokument ist der zentrale Einstieg, nicht das technische Nachweisprotokoll. +Details, historische Laufdaten und Bedienverfahren stehen ausschließlich in den +jeweiligen Fachdokumenten. Die priorisierte weitere Umsetzung beschreibt der +[High-Level-Implementierungsplan](GNAI-001-PLAN_Project-Roadmap.md). -| Dokument | Zweck / Zielgruppe | +## 1. Dokumente + +### Projektsteuerung + +| Dokument | Verbindlicher Inhalt | | --- | --- | -| [Bereichsindex](platform/README.md) | Einstieg in die Plattform- und Hostdokumentation | -| [GNAI-001-INFRA_BaseSystem.md](platform/GNAI-001-INFRA_BaseSystem.md) | Hardware und Debian-Installation; Intermediate IT | -| [GNAI-002-INFRA_Users.md](platform/GNAI-002-INFRA_Users.md) | Benutzer, statisches Hostnetz, Resolver und SSH; Intermediate IT | -| [GNAI-004-SEC_Access-Control.md](platform/GNAI-004-SEC_Access-Control.md) | verbindliches Rollen- und Zugriffsziel; Intermediate IT | -| [GNAI-005-SEC_Reverse-Proxy.md](platform/GNAI-005-SEC_Reverse-Proxy.md) | NPM/Fail2Ban und Keycloak-Korrekturverfahren; Intermediate IT | -| [GNAI-006-SEC_VPN.md](platform/GNAI-006-SEC_VPN.md) | wg-easy-Installation/Konfiguration in Proxmox LXC; Intermediate IT | -| [GNAI-006-SEC_VPN_Client-Management.md](platform/GNAI-006-SEC_VPN_Client-Management.md) | eigenständige GUI-SOP für Ausgabe, Änderungen und Widerruf; Intermediate IT | -| [GNAI-006-SEC_VPN_Clients_Windows11.md](platform/GNAI-006-SEC_VPN_Clients_Windows11.md) | offizieller Windows-Client, Import und Verwendung; Junior IT | -| [GNAI-006-SEC_VPN_Clients_Linux.md](platform/GNAI-006-SEC_VPN_Clients_Linux.md) | Debian, Arch/CachyOS, Fedora/Kinoite; Junior IT | -| [GNAI-006-SEC_VPN_Implementation-Log.md](platform/GNAI-006-SEC_VPN_Implementation-Log.md) | historische v14/v15-Umsetzung und Evidenzkorrekturen; Intermediate IT | +| [GNAI-001](GNAI-001-PLAN_Project-Roadmap.md) | priorisierte nächste Schritte, Entscheidungstore und Abnahmekriterien | -### KI +### Plattform und Sicherheit -| Dokument | Zweck / Zielgruppe | +| Dokument | Verbindlicher Inhalt | | --- | --- | -| [Bereichsindex](ai/README.md) | Einstieg in die KI-spezifische Dokumentation | -| [GNAI-003-INFRA_Architecture.md](ai/GNAI-003-INFRA_Architecture.md) | Gesamtzielarchitektur und Inventar des KI-Stacks; Intermediate IT | -| [GNAI-007-PLAN_Ansible-Deployment.md](ai/GNAI-007-PLAN_Ansible-Deployment.md) | nicht finaler Arbeitsentwurf zum Ansible-/Gitea-Deployment und zur geplanten Folgedokumentation; Infrastrukturadministratoren und Mitwirkende | -| [GNAI-008-PLAN_Llama-Model-Evaluation.md](ai/GNAI-008-PLAN_Llama-Model-Evaluation.md) | nicht finaler A/B- und Abnahmeplan für Swift, Unsloth, Kontext und MTP; KI-Administratoren und Tester | -| [GNAI-009-TECH_Llama-Serving.md](ai/GNAI-009-TECH_Llama-Serving.md) | technische Sollkonfiguration für Modellartefakte, rootless Quadlet, ROCm und `llama-server`; Infrastrukturadministratoren | +| [Bereichsindex](platform/README.md) | Einstieg in Host-, Zugriffs-, Reverse-Proxy- und VPN-Dokumentation | +| [GNAI-002](platform/GNAI-002-INFRA_BaseSystem.md) | Hardware und Debian-Basis des KI-Servers | +| [GNAI-003](platform/GNAI-003-INFRA_Users.md) | Benutzer, Hostnetz, Resolver und SSH | +| [GNAI-005](platform/GNAI-005-SEC_Access-Control.md) | Rollen- und Zugriffsziel | +| [GNAI-006](platform/GNAI-006-SEC_Reverse-Proxy.md) | NPM, Fail2Ban und Keycloak-Adminpfad | +| [GNAI-007](platform/GNAI-007-SEC_VPN.md) | WireGuard-Gateway und Rollen-Firewall | +| [VPN-Client-Verwaltung](platform/GNAI-007-SEC_VPN_Client-Management.md) | Ausgabe, Änderung und Widerruf von Geräteprofilen | +| [Windows 11](platform/GNAI-007-SEC_VPN_Clients_Windows11.md) / [Linux](platform/GNAI-007-SEC_VPN_Clients_Linux.md) | Client-SOPs | +| [VPN-Implementation-Log](platform/GNAI-007-SEC_VPN_Implementation-Log.md) | historische Umsetzung und datierte Evidenz | -### Video-Encoding und Automatisierung +### KI und Deployment -| Dokument | Zweck / Zielgruppe | +| Dokument | Verbindlicher Inhalt | | --- | --- | -| [Video-Encoding-Dokumentation](video-encoding/GNENC-000-DOC_Index.md) | getrennter Index für Architektur und spätere Nutzer-SOPs des CPU-Encoding-Workloads | -| [Ansible-Control-Projekt](../ansible/README.md) | Control-Node, Preflight, Deployment-Account, Host-Baseline, Podman und Workload-Konten; Intermediate IT | +| [Bereichsindex](ai/README.md) | Einstieg in die KI-Dokumentation | +| [GNAI-004](ai/GNAI-004-INFRA_Architecture.md) | Zielarchitektur und Vertrauensgrenzen | +| [GNAI-008](ai/GNAI-008-PLAN_Ansible-Deployment.md) | detaillierter Ansible-/Gitea-Planungsstand und Implementierungshistorie | +| [GNAI-009](ai/GNAI-009-PLAN_Llama-Model-Evaluation.md) | reproduzierbarer Modellvergleich | +| [GNAI-010](ai/GNAI-010-TECH_Llama-Serving.md) | technische Sollkonfiguration des Testing-Servings | +| [Ansible-Control-Projekt](../ansible/README.md) | ausführbare Playbooks, Rollen und belegter technischer Stand | -## 2. Verbindliche, bestätigte Entscheidungen +### Video-Encoding -NPM ist `.10`, WireGuard `.15`, Proxmox `.2`, KI-Server `.90`, Fritzbox `.1`, jeweils im Heimnetz `10.0.0.0/24`. Server/LXCs verwenden statische Adressen bis `.99`, Client-DHCP `.100–.200`. Der aktuelle Bereich ist keine VLAN-Isolation und keine automatische Server-Admin-ACL. - -Familie darf das gesamte Heimnetz erreichen; Server Admins Proxmox, Service-LXCs und KI-Server; LLM Admins ausschließlich KI-Server. Profile werden durch Administratoren pro Gerät erstellt und geschützt verteilt. Serverseitige Firewall Allowed IPs sollen die Rechte erzwingen. Per-Client Firewall ist aber derzeit deaktiviert. wg-easy-GUI-Zugriff ist für Familie und Server Admin vorgesehen; HTTPS ist ein offener Umsetzungsvorschlag. - -wg-easy läuft rootful in CT 105 als Podman-Quadlet mit v15.4.0 und host-Netz im LXC. Ein lesender SSH-Abgleich am 18.09.2026 bestätigte aktives `wg-easy`/`nftables`, IPv4-Forwarding, eine breite VPN→LAN-Regel und MASQUERADE in `iptables-legacy`; Details und Grenzen stehen im [Implementation-Log](platform/GNAI-006-SEC_VPN_Implementation-Log.md). MASQUERADE wird mangels Rückroute gebraucht. Ein nftables-Reload mit `flush ruleset` kann dynamische Regeln entfernen; Wiederanlauf muss abgenommen werden. - -Der KI-Server heißt laut lesendem SSH-Abgleich vom 18.09.2026 `ghostnet-ki`; damals bestanden die persönlichen Konten `ghost`, `debugofen` und das Agentenkonto `ghost-agent`. Inzwischen ergänzen `ansible-deploy` sowie die gesperrten Workload-Konten `gnai-production`, `gnai-testing` und `gn-encoding` diesen Bestand. `admin` existiert auf diesem Host nicht; der WireGuard-LXC verwendet separat `admin`. `ghostnet.ki` mit Punkt ist höchstens ein lokal angelegter SSH-Alias. OIDC ist laut Betreiber produktiv nur für Vaultwarden; weitere Dienste sind geplant. - -Die getrennten Schlüsselzugänge für `ghost` und `ghost-agent` wurden am 19.09.2026 erfolgreich getestet. Der persönliche Login wurde vom Betreiber interaktiv bestätigt; der Agentenlogin wurde technisch gegen Benutzername und Hostname geprüft. - -Der KI-Server wurde als frisches Debian-Basissystem begonnen. Inzwischen sind die dokumentierten Ansible-Zugänge, die minimale Host-Baseline und Podman eingerichtet. Ein gepinntes ROCm-Probeimage liegt im rootless Testing-Store und hat beide GPUs erkannt; dauerhafte LLM-Anwendungen sind weiterhin nicht installiert. GNAI-003 und GNAI-004 beschreiben für sie ein Zielbild. - -Der [Ansible-Deployment-Entwurf](ai/GNAI-007-PLAN_Ansible-Deployment.md) persistiert den seit dem 19.09.2026 fortgeschriebenen Planungs- und Implementierungsstand. Er ist ausdrücklich keine verbindliche Spezifikation und kein Nachweis einer vollständig eingerichteten Deploymentkette. Die dort genannten Runner-, Freigabe- und Secret-Verfahren sind bis zu ihrer Prüfung und formalen Übernahme vorläufig. - -Das erste Ansible-Control-Projekt mit Testing-Inventar und lesendem Preflight wurde am 19.09.2026 angelegt. Der Live-Lauf über `ghost-agent` bestätigte Hostidentität, Debian 13.6, IPv4-Adresse, Python, CPU, RAM und zwei Navi-21-Geräte mit `changed=0`, `unreachable=0` und `failed=0`. Dieser Nachweis umfasst weder privilegierten Zugriff noch eine eingerichtete Production-/Testing-Laufzeitumgebung. - -Der separate Ed25519-Schlüssel mit Fingerprint `SHA256:IKEInbIo8VVI1USg5+a3ypGK8H8FweJiQu+v7KvhQDU` und das Bootstrap-Playbook wurden am 19.09.2026 verwendet, um `ansible-deploy` einzurichten. Der private Schlüssel liegt ausschließlich außerhalb des Repositories. Der Account besitzt ein gesperrtes Passwort, einen auf LAN- und WireGuard-Quellnetze beschränkten Public Key und eine mit `visudo` validierte Regel `NOPASSWD: ALL`. Ein getrenntes Prüfplaybook bestätigte anschließend Anmeldung, Modulausführung und effektive UID 0 über sudo mit `ok=5 changed=0 unreachable=0 failed=0`. - -Die erste schreibende Rolle `host_baseline` wurde am 19.09.2026 nach erfolgreichem Syntax- und Check-Modus-Lauf angewendet. Sie prüft Hostname, Debian-Hauptversion, Standard-IPv4 sowie mindestens 100 GiB freien Speicher. Die zunächst dort angelegten Umgebungsverzeichnisse werden seit Einführung der Servicekonten durch `workload_accounts` verwaltet; `host_baseline` besitzt nur noch die gemeinsamen Eltern und `/var/lib/ghostnet-ai/shared`. Der erste reale Lauf meldete `ok=6 changed=1 unreachable=0 failed=0`; der unmittelbar folgende identische Lauf belegte Idempotenz mit `ok=6 changed=0 unreachable=0 failed=0`. - -Die Rolle `podman_runtime` wurde am 20.09.2026 angewendet. Sie installierte Podman 5.4.2 aus Debian 13 einschließlich expliziter DNS- und rootless Netzwerkvoraussetzungen, prüfte systemd, cgroup v2, Overlay-Storage und den Quadlet-Generator und legte `/etc/containers/systemd` an. `podman.socket` und `podman-auto-update.timer` werden deaktiviert und gestoppt gehalten. Der abschließende Gesamtlauf meldete `ok=20 changed=0 unreachable=0 failed=0`; eine getrennte Prüfung bestätigte leere Image- und Containerlisten sowie beide Units als `disabled` und `inactive`. - -Die Rolle `workload_accounts` richtete am 20.09.2026 die gesperrten Konten `gnai-production` (UID/GID 980), `gnai-testing` (981) und `gn-encoding` (982) mit festen, getrennten SubID-Bereichen ein. Konfiguration bleibt rootverwaltet; Daten, rootless Podman-Stores und persistente systemd-User-Manager sind pro Workload getrennt. Der korrigierte Gesamtlauf meldete `ok=36 changed=0 unreachable=0 failed=0` und bestätigte drei unterschiedliche rootless Graph Roots. Images und Container wurden nicht angelegt. - -Die Rolle `amd_gpu_access` bestätigte am 20.09.2026 zwei Sapphire-Navi-21-Geräte `1002:73bf` mit dem Kernel-Treiber `amdgpu`, `/dev/kfd` sowie die zugehörigen Render-Nodes `/dev/dri/renderD128` und `/dev/dri/renderD129`. Alle drei Geräte verwenden die Gruppe `render`. `gnai-production` und `gnai-testing` besitzen nachweislich Lese-/Schreibzugriff; `gn-encoding` erhielt keine GPU-Gruppe. Nach Beseitigung einer konkurrierenden Gruppenverwaltung endete der Gesamtlauf mit `ok=55 changed=0 unreachable=0 failed=0`. Dieser Rollenlauf allein wies ROCm im Container oder tatsächliche Inferenz noch nicht nach. - -Das getrennte Playbook `verify-rocm-container.yml` lud am 20.09.2026 für `gnai-testing` den offiziellen `llama.cpp`-ROCm-Build `b11058` als unveränderliches amd64-Manifest `sha256:b429b8be10d3d0353a09c98f4ab840fe516f779858a28f9fd4e5bdf10bc63cb4`. Mit `/dev/kfd`, beiden Render-Nodes und `keep-groups` meldete `rocminfo` genau zwei `gfx1030`-Agents; `llama-server --list-devices` meldete `ROCm0` und `ROCm1` als Radeon RX 6900 XT. Der abschließende Lauf endete mit `ok=33 changed=0 unreachable=0 failed=0`. Die Probecontainer wurden entfernt; dauerhafter Container-, Modell- und Inferenzbetrieb sind damit noch nicht abgenommen. - -Am 21.09.2026 wurden die Modellrecherche und die daraus abgeleitete Sollkonfiguration in GNAI-008 und GNAI-009 persistiert. Installiert werden sollen Swift-Qwen3.8-27B Q6_K und Unsloth Qwen3.8-27B UD-Q6_K, jeweils mit Q8-K/V, einem Zielkontext von 131.072 Token, einem Slot und zunächst ohne Vision-Projektor oder MTP. Revisionen und SHA-256 beider Artefakte sind festgehalten. Jedes Modell erhält ein eigenes Quadlet; systemd schließt deren gleichzeitigen Betrieb aus und führt den Wechsel als Stop vor Start aus. Der kontrollierte A/B-Test verwendet zunächst `xhigh` für beide Modelle; danach folgt Swift `xhigh` gegen Unsloth `medium`. Dies ist eine Planungsentscheidung und noch kein Nachweis für Modelldownload, 128k-Betrieb oder Inferenz. - -## 3. Sicherheitsbefunde mit Priorität - -| Befund | dokumentiertes Verfahren / Status | +| Dokument | Verbindlicher Inhalt | | --- | --- | -| Keycloak-Administration öffentlich erreichbar, externe Anmeldung möglich | [GNAI-005](platform/GNAI-005-SEC_Reverse-Proxy.md): Adminpfad-Schutz, interner Adminzugang, externe Sperrtests und Vaultwarden-OIDC-Prüfung; noch nicht angewendet | -| VPN-Zielrechte nur im lokalen Profil | [GNAI-006](platform/GNAI-006-SEC_VPN.md) und [GUI-SOP](platform/GNAI-006-SEC_VPN_Client-Management.md): Per-Client Firewall, Gateway-INPUT-Regeln und negative Tests; noch nicht angewendet | -| Fail2Ban-Image auf `1.1.0-r2-ls43` fest gepinnt; Container läuft wieder | [GNAI-005](platform/GNAI-005-SEC_Reverse-Proxy.md): Pin umgesetzt; effektives Image, Jails, kontrollierte Bans sowie Dienst-/LXC-Wiederanlauf noch abzunehmen | -| HTTP-Client-User-Agents werden bewusst gebannt | [GNAI-005](platform/GNAI-005-SEC_Reverse-Proxy.md): mögliche legitime Treffer und rollen-/routingabhängiger VPN-Ausweichweg dokumentiert | +| [GNENC-000](video-encoding/GNENC-000-DOC_Index.md) | Bereichsstatus und offene Festlegungen | +| [GNENC-001](video-encoding/GNENC-001-PLAN_Architecture.md) | vorläufige Architektur des CPU-Encoding-Workloads | -## 4. Noch erforderliche Angaben +Die Dokumente wurden am 21.09.2026 neu geordnet: Die Roadmap belegt +`GNAI-001`; die zuvor bestehenden Dokumente `GNAI-001` bis `GNAI-009` wurden +unter Beibehaltung ihrer Reihenfolge zu `GNAI-002` bis `GNAI-010`. -| Frage / fehlender Nachweis | Grund | -| --- | --- | -| Aktualisiert selfHOST den VPN-Eintrag nach einem WAN-IP-Wechsel zuverlässig? | Am 18.09.2026 stimmte `vpn.ghostnet.selfhost.eu` mit der ausgehenden IPv4 des Gateways überein; `vpn.ghostnet.dyndns.eu` zeigte auf eine andere IPv4. Profile verwenden `selfhost.eu`. Ein einzelner Abgleich belegt keinen dauerhaften DynDNS-Betrieb. | -| Gehört Altpeer Laptop-FullAdmin künftig Familie oder Server Admin? | neue Zielrechte und Gateway-INPUT-Freigaben hängen davon ab. | -| Welche Verwaltungsgeräte dürfen lokal auf die GUI und welcher interne Adminhostname soll verwendet werden? | VPN-Rollen ordnen lokale LAN-Quellen nicht automatisch zu. | -| Welchen OIDC-Issuer/Realm nutzt Vaultwarden und wo terminiert auth-HTTPS tatsächlich? | NPM-SSL-Optionen aus, externer HTTPS-Login möglich; Realm-Sperren dürfen den produktiven Login nicht unbeabsichtigt stören. | -| Welcher Dienst erzeugt `/etc/resolv.conf` auf dem KI-Server tatsächlich? | `networking` verwaltet die statische Schnittstelle; die Datei trägt einen dhcpcd-Kommentar, obwohl dhcpcd beim Abgleich nicht aktiv war. Vor einer DNS-Änderung den Erzeugungsweg prüfen. | +## 2. Belegter Stand -Es werden keine Werte für diese offenen Angaben angenommen. Die betreffenden Verfahren sind entsprechend eingeschränkt oder als Vorschlag markiert. +| Bereich | Nachgewiesen | Noch nicht nachgewiesen | +| --- | --- | --- | +| KI-Host | Debian 13.6, Deployment-Zugang, Podman 5.4.2, getrennte rootless Konten, Gerätezugriff für beide KI-Konten | Host-/Treiber-Upgradepfad, Backup und Restore | +| GPU/ROCm | beide RX 6900 XT als `gfx1030`, `ROCm0` und `ROCm1` im gepinnten Testing-Image erkannt | Modellladen, Layer-Verteilung, reale Inferenz, 64k/128k-Stabilität | +| LLM-Serving | zwei unveränderlich definierte Modellkandidaten und technische Sollkonfiguration | Modelle, Quadlets, dauerhaftes Podman-Netz und Health Checks | +| Deployment | lokales Ansible-Control-Projekt und idempotente Hostrollen | statische CI, Runner, geschützte Freigaben, Production-Inventar und automatisierter Rollback | +| VPN | wg-easy v15.4.0 aktiv, WAN-Handshake als Teiltest | serverseitige Rollenrechte, negative Tests, IPv6-/Restart-/Restore-Abnahme | +| Reverse Proxy | NPM aktiv; Fail2Ban-Pin laut Betreiber umgesetzt | wirksame Jails/Bans und Wiederanlauf; Keycloak-Adminpfad weiterhin offen | +| Encoding | Konto, Pfade und eigener rootless Store | Workload, Zeitsteuerung, Ressourcenlimits und Lasttest | -## 5. Validierung und Abschluss +Ein Zielbild, eine Betreiberangabe oder ein erfolgreicher Teiltest gilt nicht als +vollständige Abnahme. Datierte Details stehen im zuständigen Fachdokument. -Bei der Dokumentationskonsolidierung wurden keine Serverkonfigurationen geändert, keine VPN-Praxisprüfungen nachgeholt und keine Keycloak-Sperre live bestätigt. Aussagen zum Ist-Stand beruhen auf den protokollierten Betreiberangaben und Tests; sie sind keine neue Live-Inventur. +## 3. Bestätigte Leitentscheidungen -Am 18.09.2026 wurden WireGuard-LXC und KI-Server ergänzend lesend per SSH geprüft. Der KI-Server-Teilabgleich bestätigt Hostname, Konten, Netzkonfiguration, Debian-Version, CPU, RAM, zwei Navi-21-GPUs und SSD-Partitionierung; BIOS, ROCm und die Anwendungsdienste wurden dabei nicht abgenommen. Details stehen in [GNAI-001](platform/GNAI-001-INFRA_BaseSystem.md) und [GNAI-002](platform/GNAI-002-INFRA_Users.md). +- Ein Infrastructure-Repository verwaltet den Sollzustand des gemeinsamen Hosts. +- AI Production und AI Testing verwenden bereits getrennte Konten, + Datenpfade und Podman-Stores; ihre späteren Units und Netze bleiben ebenfalls + getrennt. Host, Kernel und GPUs teilen sie dennoch. Sie sind daher keine + getrennten Fehlerdomänen und laufen GPU-seitig nicht gleichzeitig. +- Video-Encoding bleibt CPU-basiert, besitzt keinen GPU-Zugriff und wird erst + nach einem gemeinsamen Lasttest parallel freigegeben. +- Container- und Modellartefakte werden unveränderlich über Version, Revision, + Digest beziehungsweise SHA-256 festgelegt; `latest` ist kein Deploymentziel. +- `llama.cpp` bleibt ein internes Backend ohne Host-Port. Eine öffentliche + Schnittstelle benötigt eine eigene Authentifizierungs-, Quota- und + Veröffentlichungsentscheidung. +- Managementzugriff erfolgt über WireGuard plus Dienstauthentifizierung. + Client-Routing allein ist keine serverseitige Autorisierung. +- Der Schlüssel von `ansible-deploy` ist wegen `NOPASSWD: ALL` root-äquivalent + und darf nicht ungeprüft an Pull-Request-Workflows weitergegeben werden. -Am 19.09.2026 bestätigte ein erster reproduzierbarer Ansible-Preflight über das unprivilegierte Konto `ghost-agent` erneut `ghostnet-ki`, Debian 13.6, `10.0.0.90`, 14 vCPUs, 64.123 MiB RAM, Remote-Python 3.13.5 und zwei PCI-Geräte `1002:73bf`. Der Play Recap lautete `ok=5 changed=0 unreachable=0 failed=0`. Das Playbook verwendete kein `sudo` und nahm keine Serverkonfiguration vor. +## 4. Offene Sicherheits- und Entscheidungsgrenzen -Beim anschließenden Bootstrap wurden Benutzer, Home-/SSH-Verzeichnisse, `authorized_keys` und sudoers-Datei erfolgreich angelegt. Nur die letzte Assertion des ersten Laufs schlug wegen einer als Mapping interpretierten YAML-Bedingung fehl; die Bedingung wurde anschließend als String korrigiert. Da alle schreibenden Tasks vorher erfolgreich waren, bestätigte das unabhängige Prüfplaybook den wirksamen Endzustand ohne weitere Änderung. Ein vollständiger zweiter Bootstrap-Lauf zur Idempotenzprüfung steht noch aus. +Vor einer neuen öffentlichen KI-Schnittstelle müssen mindestens diese Befunde +geschlossen sein: -Für die gemeinsame Host-Baseline bestätigte ein vorgelagerter Check-Modus genau sieben neu anzulegende Verzeichnisse und rund 1.677,7 GiB freien Platz auf `/`. Der anschließende reale Lauf legte die Verzeichniswurzeln an. Eine sofortige Wiederholung ergab `changed=0`; die Rolle konvergiert damit für ihren derzeitigen Umfang. Dieser Nachweis umfasst keine Paket-, Runtime-, GPU- oder Anwendungsinstallation. +1. öffentliche Keycloak-Administration sperren und Vaultwarden-OIDC erneut + prüfen; +2. VPN-Rollen serverseitig erzwingen und positive sowie negative Zugriffe + einschließlich Gateway-INPUT testen; +3. Fail2Ban-Jails, kontrollierten Ban und Wiederanlauf nachweisen; +4. öffentliche IPv4-/IPv6-Exposure erneut erfassen. -Am 20.09.2026 sagte der Podman-Check-Modus 38 neue Debian-Pakete und das Quadlet-Verzeichnis voraus. Der reale Lauf installierte diese Pakete; seine erste Nachprüfung bewertete den Debian-Symlink des Quadlet-Generators irrtümlich nicht als reguläre Datei. Nach Korrektur der Ansible-`stat`-Prüfung auf das aufgelöste Ziel bestanden Podman 5.4.2, cgroup v2, Overlay-Storage und der Generator-Dry-Run. Der finale Gesamtlauf war mit `changed=0` idempotent. Es wurden weder Images geladen noch Container oder Anwendungsdienste angelegt. +Noch zu entscheiden sind insbesondere: -Der anschließende Workload-Account-Lauf richtete drei Konten, feste -SubUID-/SubGID-Bereiche, rootverwaltete Quadlet-Pfade und persistente -systemd-User-Manager ein. Zwei reine Abschlussprüfungen deckten zunächst den -nicht erlaubten direkten sudo-Benutzerwechsel sowie konkurrierende -Verzeichniseigentümer zwischen Rollen auf. Nach Umstellung der Prüfung auf -rootseitiges `runuser` und eindeutiger Eigentümerzuständigkeit endete der -Gesamtlauf mit `ok=36 changed=0 unreachable=0 failed=0`. Die drei rootless -Podman-Stores sind voneinander getrennt und noch leer. +- Sicherheitsabschluss vor oder parallel zum internen LLM-Vertical-Slice; +- API-only oder zusätzlich Weboberfläche als erstes Nutzerprodukt; +- ob LiteLLM in der ersten Veröffentlichung für individuelle Keys, Quoten oder + Routing tatsächlich benötigt wird; +- Freigabe- und Secret-Modell für einen späteren privilegierten Runner; +- Backupziel, Aufbewahrung und praktisch getesteter Restore; +- akzeptierte Mindestkonfiguration: 64k als belastbare Basis und 128k als Ziel + oder 128k als zwingende Production-Voraussetzung. -Der folgende GPU-Zugriffslauf ordnete beide erkannten AMD-Render-Nodes anhand -von PCI-Vendor und Geräte-ID den Navi-21-Karten zu und leitete aus ihnen sowie -`/dev/kfd` ausschließlich die Gruppe `render` ab. Der erste Wiederholungslauf -deckte auf, dass `workload_accounts` ergänzende Gruppen wieder entfernte. Nach -Übernahme von `render` in den expliziten Kontosollzustand blieb -`amd_gpu_access` für Hardwareerkennung und effektive Rechteprüfung zuständig. -Der Abschlusslauf war mit `changed=0` idempotent; Images und Container blieben -weiterhin leer. +## 5. Pflegeprinzip -Der anschließende rootless ROCm-Probelauf verwendete das Image ausschließlich -über seinen amd64-Manifest-Digest. Die OCI-Labels bestätigten Build `b11058` -und Revision `f072b103714dfa1eee531f80b24512faf38e3dd2`. Zwei kurzlebige -Container prüften mit denselben minimalen Geräteoptionen zunächst die -Architektur über `rocminfo` und anschließend die Geräteerkennung von -`llama-server`. Beide RX 6900 XT wurden als `gfx1030` und als getrennte -`ROCm0`-/`ROCm1`-Geräte erkannt. Der finale Wiederholungslauf meldete -`changed=0`; das Image bleibt im Testing-Store, laufende Container, Modelle -und Inferenz wurden nicht eingerichtet. - -Die WireGuard-Evidenz bleibt der Teiltest vom 12.09.2026: CachyOS-Laptop von WAN, Handshake, Ping auf Gateway/Proxmox und direkter IPv4-Internetpfad bestanden; KI-Server war ausgeschaltet. Neue Rollen, weitere Clientvarianten, Gateway-GUI-Zugriff, WAN-/IPv6-Isolation, Neustart und Restore sind noch nicht abgenommen. GNAI-006 ist erst nach Klärung der offenen Werte, Umsetzung und dokumentierter Abnahme technisch abgeschlossen. +Neue technische Evidenz wird zuerst im ausführbaren Projekt beziehungsweise im +zuständigen Fachdokument aktualisiert. Dieser Index wird nur geändert, wenn +sich ein bereichsübergreifender Status, eine Leitentscheidung oder die +Priorisierung ändert. Dadurch werden lange Laufprotokolle und Sollparameter +nicht mehr an mehreren Stellen dupliziert. diff --git a/docs/GNAI-001-PLAN_Project-Roadmap.md b/docs/GNAI-001-PLAN_Project-Roadmap.md new file mode 100644 index 0000000..9fa141c --- /dev/null +++ b/docs/GNAI-001-PLAN_Project-Roadmap.md @@ -0,0 +1,193 @@ +# High-Level-Implementierungsplan + +**Dokumenten-ID:** GNAI-001-PLAN + +**Titel:** Priorisierte Roadmap für Ghostnet.AI + +**Stand:** 2026-09-21 + +**Status:** Arbeitsgrundlage; Entscheidungstore vor externer Veröffentlichung offen + +**Referenzen:** [Projektstand](GNAI-000-DOC_Index.md), [Zielarchitektur](ai/GNAI-004-INFRA_Architecture.md), [Ansible-Plan](ai/GNAI-008-PLAN_Ansible-Deployment.md), [Modellbewertung](ai/GNAI-009-PLAN_Llama-Model-Evaluation.md), [`llama.cpp`-Sollkonfiguration](ai/GNAI-010-TECH_Llama-Serving.md) + +## 1. Ziel und Planungsprinzip + +Die nächste Ausbaustufe soll zuerst die bekannten externen Risiken schließen +und danach einen kleinen, reproduzierbaren LLM-Pfad von Ansible bis zur realen +Inferenz liefern. Weitere Plattformkomponenten werden erst ergänzt, wenn der +vorherige Meilenstein messbar abgenommen ist. + +Jeder Meilenstein endet mit einem überprüfbaren Ergebnis. Detailaufgaben und +Befehle gehören in Rollen und SOPs; diese Roadmap enthält weder lange +Laufprotokolle noch duplizierte Sollparameter. + +## 2. Kritisch überprüfte Entscheidungen + +| Entscheidung | Bewertung | Konsequenz für die Roadmap | +| --- | --- | --- | +| Bekannte Sicherheitsbefunde versus sofortiger LLM-Ausbau | Eine neue Anwendung zu bauen, während öffentliche Admin- und Netzwerkgrenzen offen sind, vergrößert die Angriffsfläche und erschwert spätere Abnahmen. | Empfehlung: Sicherheitsabschluss ist Meilenstein 1. Ein rein interner LLM-Test darf nur bewusst parallelisiert werden und erzeugt noch keine öffentliche Route. | +| Privilegierter Gitea-Runner vor erster Anwendung | Der vorhandene Deployment-Schlüssel ist root-äquivalent. Veränderbarer PR-Code und Production-Secrets dürfen diese Grenze nicht teilen. Der Runner würde vor dem ersten Vertical-Slice mehr Sicherheits- als Produktnutzen erzeugen. | Zuerst lokal kontrolliert deployen. Statische CI ohne Serverzugang kann früh kommen; privilegierte Deployment-Automation erst nach stabilem Rollen- und Recovery-Verfahren. | +| LiteLLM als bereits feststehende Pflichtkomponente | `llama.cpp` stellt die interne Inferenz bereit; der Mehrwert von LiteLLM entsteht erst durch konkrete Anforderungen an individuelle API-Keys, Quoten, Policy oder Routing. Ohne diese Anforderungen ist es eine zusätzliche Betriebs- und Fehlerdomäne. | LiteLLM bleibt Zielbild-Kandidat, aber Entscheidungstor vor Meilenstein 6. Der Testing-Vertical-Slice hängt nicht davon ab. | +| 128k als erste harte Betriebsgrenze | Die VRAM-Rechnung ist plausibel, aber noch ungemessen. Ein zwingendes 128k-Ergebnis würde Modell-, ROCm- und Integrationsfehler unnötig mit Speicherdruck vermischen. | 64k ist die technische Basisabnahme; 128k bleibt das Zielprofil und wird separat freigegeben. | +| Production und Testing auf demselben Host | Konten und Stores trennen Konfiguration und Daten, nicht Kernel, Treiber oder Ausfallrisiko. Echte Hochverfügbarkeit oder sichere Host-Upgrade-Tests entstehen dadurch nicht. | Bewusst als Single-Host-Betrieb mit Wartungsfenstern führen; keine HA-Aussage treffen. Umschalt- und Recovery-Mechanismus vor Production abnehmen. | +| Zwei feste Modell-Quadlets | Die Lösung ist leicht prüfbar und vermeidet eine dynamische Verwaltungs-API, kann aber bei kopierter Konfiguration driften. | Beide Units aus einem gemeinsamen Profiltemplate rendern und den gegenseitigen Ausschluss automatisiert testen. Router-Modus erst später bewerten. | +| Encoding parallel zur Inferenz | Die Trennung der Konten verhindert keine CPU-, RAM- oder I/O-Konkurrenz. „Nur nachts“ ist allein keine Ressourcenkontrolle. | Encoding bleibt nachgelagert, bis Limits und ein gemeinsamer Lasttest vorhanden sind. | + +## 3. Roadmap + +### Meilenstein 0 – Prioritäten und Produktgrenze bestätigen + +**Ergebnis:** Der erste Nutzerpfad und die Sicherheitsreihenfolge sind eindeutig. + +- festlegen, ob Sicherheits-Meilenstein 1 den internen LLM-Test blockiert oder + kontrolliert parallel läuft; +- erstes Produkt als API-only oder API plus Weboberfläche festlegen; +- 64k-Basis und 128k-Ziel als Abnahmemodell bestätigen; +- Verantwortliche für Review, Deployment und Sicherheitsabnahme benennen. + +**Fertig, wenn:** Die vier Entscheidungen im Projektstand vermerkt sind und +kein nachfolgender Meilenstein eine stillschweigende Annahme dazu benötigt. + +### Meilenstein 1 – Bestehende externe Risiken schließen + +**Ergebnis:** Die aktuelle Plattform besitzt belegte Management- und +Netzwerkgrenzen, bevor weitere öffentliche Dienste hinzukommen. + +- Keycloak-Adminpfad extern sperren und Vaultwarden-OIDC regressionsprüfen; +- VPN-Peers Rollen zuordnen, Per-Client-Regeln sowie Gateway-INPUT umsetzen und + erlaubte wie verbotene Ziele aktiv testen; +- Fail2Ban-Image, Jails, kontrollierten Ban/Unban und Dienst-/LXC-Wiederanlauf + prüfen; +- WAN- und IPv6-Exposure für Managementports erfassen; +- Ergebnisse mit Datum und Negativtests in GNAI-006/GNAI-007 dokumentieren. + +**Fertig, wenn:** Die vier priorisierten Sicherheitsbefunde im zentralen Index +als bestanden oder mit ausdrücklich akzeptiertem Restrisiko dokumentiert sind. + +### Meilenstein 2 – Internes LLM-Serving als Vertical-Slice + +**Ergebnis:** Ein reproduzierbarer, nicht öffentlich erreichbarer +`llama.cpp`-Dienst führt reale Inferenz auf beiden GPUs aus. + +- Ansible-Rolle `llama_cpp` mit validiertem Profilmanifest, atomarem Download, + Prüfsummen, gepinntem Image, rootless Netzwerk und zwei aus einem Template + erzeugten Quadlets implementieren; +- Image- und Modellbereitstellung vom Start beziehungsweise Profilwechsel + trennen; +- Swift zunächst bei 64k, danach bei 128k abnehmen; +- Unsloth mit demselben technischen Verfahren abnehmen; +- Health, Modellalias, Tool-Call, Reasoning-Trennung, GPU-Verteilung, + CPU-Offload, VRAM und Neustartverhalten protokollieren; +- zweiten identischen Ansible-Lauf mit `changed=0` nachweisen. + +**Fertig, wenn:** Beide Profile die technische Abnahme aus GNAI-010 bestehen +oder ein dokumentierter Messwert eine Profilanpassung auslöst. Es existiert +weiterhin kein Host-Port und keine NPM-Route. + +### Meilenstein 3 – Modellprofil auswählen + +**Ergebnis:** Ein durch lokale Aufgaben belegtes Standardprofil und ein +Rollbackprofil sind festgelegt. + +- kleine versionierte Testsuite mit automatischen Erwartungen und manueller + Bewertungsrubrik erstellen; +- Swift und Unsloth zunächst mit identischen `xhigh`-Parametern vergleichen; +- anschließend Swift `xhigh` gegen Unsloth `medium` als Praxisprofile messen; +- Qualität, Tool-Zuverlässigkeit, Tokenverbrauch, Laufzeit und Ressourcen + gemeinsam bewerten; +- MTP und Vision nur als getrennte optionale Experimente nach der Baseline + ausführen; +- Lizenz und Nutzungsrahmen vor einer externen Freigabe bestätigen. + +**Fertig, wenn:** Ein datierter Evaluierungsbericht das bevorzugte Profil, +zulässigen Kontext, Ausgabegrenze und Rollbackprofil benennt. + +### Meilenstein 4 – Production- und Recovery-Fähigkeit + +**Ergebnis:** Der ausgewählte interne Dienst kann kontrolliert als Production +betrieben und nach Fehlern wiederhergestellt werden. + +- Production-Inventar und dieselbe Rollenlogik mit getrennten Variablen, + Konten, Stores, Netzen und Units einführen; +- exklusiven Environment-Lock, Stop-vor-Start, Timeout und hostseitigen + Rückfall auf den letzten Production-Stand implementieren; +- Backupumfang, Ziel, Aufbewahrung und Restore-SOP festlegen; +- Konfiguration und mindestens einen zustandsbehafteten Testbestand sichern + und praktisch wiederherstellen; +- Hostreboot, fehlgeschlagenen Testing-Start, Rollback und Idempotenz testen; +- minimales Health-/Ressourcenmonitoring mit klarer Alarmgrenze einführen. + +**Fertig, wenn:** Ein abgebrochener Testlauf Production ohne Zugriff auf +Production-Secrets wiederherstellen kann und Backup/Restore praktisch belegt +sind. + +### Meilenstein 5 – Delivery-Kette absichern + +**Ergebnis:** Änderungen werden reproduzierbar geprüft und bewusst +freigegeben, ohne PR-Code root-äquivalente Secrets zu geben. + +- Gitea-Version, Actions, Branch-/Tag-Schutz und Runner-Semantik live erfassen; +- zunächst repository-spezifische statische CI ohne Serverzugang einführen; +- Werkzeug- und Collection-Versionen pinnen; +- Secret-Store, Schlüsselrotation und getrennte Testing-/Production-Rechte + festlegen; +- privilegierten Deploymentpfad erst mit unveränderlichem, geprüftem Commit, + Parallelität eins und bewusstem Freigabeschritt abnehmen; +- keinen Production-Schlüssel in Pull-Request-Workflows bereitstellen; +- Deploymentnachweis mit Commit, Artefaktdigests und Prüfergebnis erzeugen. + +**Fertig, wenn:** Ein ungefährliches Testdeployment und anschließend ein +freigegebenes Production-Deployment einschließlich fehlgeschlagenem Lauf und +Recovery reproduzierbar nachgewiesen sind. + +### Meilenstein 6 – Ersten Nutzerpfad veröffentlichen + +**Ergebnis:** Genau ein klar definierter, authentifizierter Nutzerpfad ist +öffentlich nutzbar; Backend- und Managementports bleiben intern. + +- anhand der Produktentscheidung LiteLLM einführen oder den alternativen + API-Gateway-Pfad ausdrücklich spezifizieren; +- individuelle Credentials, Widerruf, Quoten/Rate Limits, Logging und + Missbrauchsgrenzen umsetzen; +- NPM-Route, TLS und Health getrennt vom Backend abnehmen; +- bei Weboberfläche OIDC-Endpunkte und Rollen minimal freigeben; +- externe Positiv- und Negativtests für API, Adminpfade, Backendports sowie + IPv4/IPv6 durchführen; +- Betriebs-, Schlüsselwiderrufs- und Störungs-SOP fertigstellen. + +**Fertig, wenn:** Der Nutzerpfad funktioniert, direkte `llama.cpp`- und +Managementzugriffe extern scheitern und Widerruf sowie Rate Limit getestet +sind. + +### Meilenstein 7 – Nachgelagerte Workloads + +**Ergebnis:** Zusätzliche Anwendungen beeinträchtigen den freigegebenen +LLM-Betrieb nicht. + +- OpenWebUI, GPT Researcher oder weitere Anwendungen einzeln nach Nutzen, + Datenhaltung und Vertrauensgrenze priorisieren; +- Encoding-Produktanforderungen festlegen, CPU-/RAM-/I/O-Limits implementieren + und unter gleichzeitiger Inferenzlast testen; +- erst danach Zeitplan, Queue, Benachrichtigung und Nutzer-SOP freigeben. + +## 4. Bewusst nicht Teil der nächsten Ausbaustufe + +- dynamischer `llama.cpp`-Router; +- gleichzeitiger GPU-Betrieb von Production und Testing; +- Vision und MTP vor stabiler Text-/Tool-Baseline; +- automatische Production-Updates über bewegliche Tags; +- Hochverfügbarkeitsversprechen auf dem einzelnen Host; +- neue VLAN-/Netzarchitektur ohne eigenen Netzwerk-Sprint; +- umfassende Anwendungssuite vor dem ersten abgenommenen Nutzerpfad. + +## 5. Pflege und Steuerung + +Der jeweils aktive Meilenstein erhält ein kleines umsetzbares Arbeitspaket mit +Owner, Risiken und Abnahmeevidenz. Neue Detaildokumente werden nur erstellt, +wenn Zielgruppe oder Betriebsverfahren wirklich eigenständig sind; ansonsten +wird das zuständige Rollen-README oder die bestehende SOP erweitert. + +Eine Phase gilt nicht wegen implementierter Tasks als abgeschlossen, sondern +erst nach ihren Abnahmekriterien. Abweichungen ändern zuerst das zuständige +Fachdokument und anschließend nur bei bereichsübergreifender Wirkung diese +Roadmap und den zentralen Index. diff --git a/docs/ai/GNAI-003-INFRA_Architecture.md b/docs/ai/GNAI-004-INFRA_Architecture.md similarity index 80% rename from docs/ai/GNAI-003-INFRA_Architecture.md rename to docs/ai/GNAI-004-INFRA_Architecture.md index ea0d717..c695d07 100644 --- a/docs/ai/GNAI-003-INFRA_Architecture.md +++ b/docs/ai/GNAI-004-INFRA_Architecture.md @@ -1,9 +1,9 @@ # Technical Architecture Specification -**Dokumenten-ID:** GNAI-003-INFRA +**Dokumenten-ID:** GNAI-004-INFRA **Titel:** Homelab / LLM-Infrastruktur – Zielarchitektur **Status:** Zielarchitektur; bestätigter Teilstand und offene Umsetzung separat ausgewiesen -**Vorgänger / Referenzen:** [Basisinstallation](../platform/GNAI-001-INFRA_BaseSystem.md), [Benutzer/SSH](../platform/GNAI-002-INFRA_Users.md), [Zugriffskonzept](../platform/GNAI-004-SEC_Access-Control.md), [Reverse Proxy](../platform/GNAI-005-SEC_Reverse-Proxy.md), [WireGuard](../platform/GNAI-006-SEC_VPN.md) +**Vorgänger / Referenzen:** [Basisinstallation](../platform/GNAI-002-INFRA_BaseSystem.md), [Benutzer/SSH](../platform/GNAI-003-INFRA_Users.md), [Zugriffskonzept](../platform/GNAI-005-SEC_Access-Control.md), [Reverse Proxy](../platform/GNAI-006-SEC_Reverse-Proxy.md), [WireGuard](../platform/GNAI-007-SEC_VPN.md) --- @@ -15,6 +15,7 @@ | 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. | +| 2026-09-21 | 1.4 | spektr / Codex | belegten Plattformstand aktualisiert und LiteLLM als zu bestätigenden Kandidaten einer allgemeinen API-Policy-Schicht eingeordnet | --- @@ -24,9 +25,15 @@ Dieses Dokument beschreibt die festgelegte Zielarchitektur für die sichere Bere 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. +Die Architektur baut auf dem in **GNAI-002-INFRA** beschriebenen Debian-basierten LLM-Server und der in **GNAI-003-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. +Der KI-Server begann am 18.09.2026 als frisches Basissystem. Inzwischen sind +Deployment-Zugang, Host-Baseline, Podman, getrennte Workload-Konten und der +rootless ROCm-Gerätenachweis mit Ansible umgesetzt. Dauerhaftes +`llama.cpp`-Serving und weitere Anwendungen sind noch nicht installiert. +LiteLLM, OpenWebUI und GPT Researcher sind **Zielbild-Kandidaten**, aber ohne +Bestätigung in der priorisierten Roadmap keine Zusage für die nächste +Ausbaustufe. --- @@ -38,7 +45,10 @@ Die Infrastruktur folgt diesen Grundsätzen: 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. +5. **LLM-API als dedizierte Applikationsschnittstelle:** Direkter Zugriff auf + `llama.cpp` aus dem Internet ist nicht vorgesehen. Eine öffentliche + Schnittstelle benötigt eine getrennte Policy-Schicht; LiteLLM ist dafür der + bisherige Kandidat, aber noch nicht als erste Ausbaustufe bestätigt. 6. **Defense in Depth:** Reverse Proxy, Fail2Ban, Firewall-Regeln, MFA, Patchmanagement, Monitoring und Backups ergänzen sich. 7. **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. 8. **Isolation:** Öffentlich exponierte Infrastruktur und einzelne Backend-Dienste bleiben logisch bzw. durch eigene LXCs getrennt. @@ -69,11 +79,11 @@ Heimnetz `10.0.0.0/24`, Fritzbox/Gateway/DNS `.1`. Statische Server-/LXC-Adresse | 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 | +| Jellyfin | `10.0.0.11:8096` | GNAI-006-Inventar, vor Freigabe abgleichen | +| Nextcloud | `10.0.0.12:8080` | GNAI-006-Inventar, vor Freigabe abgleichen | +| Gitea | `10.0.0.17:3000` | GNAI-006-Inventar, vor Freigabe abgleichen | +| Japanese Web App | `10.0.0.23:80` | GNAI-006-Inventar, vor Freigabe abgleichen | +| Vaultwarden | `10.0.0.47:8080` | GNAI-006-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. @@ -142,19 +152,22 @@ Beispiele: - Vaultwarden - Keycloak -### Services auf dem LLM-Server +### Mögliche Services auf dem LLM-Server - OpenWebUI - GPT Researcher - LiteLLM API +Diese Liste beschreibt Architektur-Kandidaten, keine gemeinsam freigegebene +Implementierungsreihenfolge. Die aktive Reihenfolge steht in GNAI-001. + 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. +Der LLM-Server basiert auf der in **GNAI-002-INFRA** dokumentierten Debian-Basis mit AMD-Multi-GPU-Konfiguration und der in **GNAI-003-INFRA** vorgesehenen SSH-Key-basierten Absicherung. ### 6.1 LLM-Inferenz @@ -166,9 +179,12 @@ Grundsatz: Der Zugriff erfolgt intern über die dafür vorgesehene API-Schicht. -### 6.2 LiteLLM +### 6.2 API- und Policy-Schicht -LiteLLM soll die standardisierte OpenAI-kompatible API- und Policy-Schicht vor `llama.cpp` bilden. +Für eine externe API ist eine standardisierte API- und Policy-Schicht vor +`llama.cpp` vorgesehen. LiteLLM ist der bisherige Kandidat. Seine Einführung +wird vor der Veröffentlichung gegen die tatsächlich benötigten individuellen +Keys, Quoten, Routing- und Beobachtbarkeitsfunktionen geprüft. Verantwortlichkeiten: @@ -181,7 +197,10 @@ Verantwortlichkeiten: 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. +Im Zielbild verbindet sich ein externer Client per HTTPS mit NPM. NPM leitet +an die beschlossene Policy-Schicht weiter; diese nutzt `llama.cpp` über das +interne Container-/Hostnetz. Die Inferenz läuft auf den GPUs. Dieser Pfad ist +noch nicht umgesetzt. --- @@ -206,7 +225,7 @@ WireGuard ist die dedizierte Zugangsschicht für privilegierte Netzwerkzugriffe. 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. +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-007. --- @@ -230,7 +249,7 @@ Die Keycloak-Administrationsoberfläche und administrative Managementschnittstel SSH auf dem LLM-Server wird ausschließlich schlüsselbasiert betrieben. -Aus **GNAI-002-INFRA** übernimmt die Zielkonfiguration insbesondere: +Aus **GNAI-003-INFRA** übernimmt die Zielkonfiguration insbesondere: - `PermitRootLogin no` - `PasswordAuthentication no` @@ -311,7 +330,7 @@ Folgende konkrete Werte und Verfahren werden in den Fachdokumenten geführt. Ein - genaue `wg-easy`-Version und Containerparameter - genaue NPM-Container-/Storage-Konfiguration - konkrete Fail2Ban-Jails und Filter -- konkrete LiteLLM-Modell- und Key-Policies +- konkrete Modell-, Credential- und Quota-Policies der späteren API-Schicht - konkrete Keycloak-Realm-/Client-Struktur - konkrete DNS-/Domainnamen - konkrete Backup- und Monitoring-Implementierung @@ -329,8 +348,12 @@ Die Architektur gilt als korrekt umgesetzt, wenn mindestens folgende Eigenschaft - Ö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. +- Webanwendungen verwenden Keycloak/OIDC, sofern dies für den jeweiligen + Nutzerpfad beschlossen und von der Anwendung belastbar unterstützt wird; + Maschinen-APIs behalten eigene Credentials und Policies. +- Die LLM-API wird über eine ausdrücklich beschlossene Policy-Schicht + bereitgestellt und über individuelle Credentials geschützt; bei Auswahl von + LiteLLM werden dessen Key-, Quota- und Routingfunktionen gesondert abgenommen. - Administrative Weboberflächen von Keycloak sind nicht öffentlich. - Service-LXCs bleiben voneinander isoliert und erlauben nur erforderliche Kommunikationsbeziehungen. @@ -338,4 +361,4 @@ Die Architektur gilt als korrekt umgesetzt, wenn mindestens folgende Eigenschaft ## 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](../GNAI-000-DOC_Index.md); technische Nachweise und offene Prüfungen werden in GNAI-005 und GNAI-006 geführt. Backendisolation und lokale Netzwerksegmentierung sind ebenfalls noch nachzuweisen. +Die Architektur-Abnahmekriterien in Abschnitt 13 sind Sollkriterien und keine bestätigte Abnahme. Der aktuelle Projektstand und die priorisierten Befunde stehen im [Dokumentationsindex](../GNAI-000-DOC_Index.md); technische Nachweise und offene Prüfungen werden in GNAI-006 und GNAI-007 geführt. Backendisolation und lokale Netzwerksegmentierung sind ebenfalls noch nachzuweisen. diff --git a/docs/ai/GNAI-007-PLAN_Ansible-Deployment.md b/docs/ai/GNAI-008-PLAN_Ansible-Deployment.md similarity index 84% rename from docs/ai/GNAI-007-PLAN_Ansible-Deployment.md rename to docs/ai/GNAI-008-PLAN_Ansible-Deployment.md index 8b55528..766bf03 100644 --- a/docs/ai/GNAI-007-PLAN_Ansible-Deployment.md +++ b/docs/ai/GNAI-008-PLAN_Ansible-Deployment.md @@ -1,10 +1,10 @@ # Arbeitsentwurf -**Dokumenten-ID:** GNAI-007-PLAN +**Dokumenten-ID:** GNAI-008-PLAN **Titel:** Ansible-Deployment für den KI-Server – Planungsstand **Stand:** 2026-09-21 **Status:** Nicht finaler Arbeitsentwurf zur Persistierung des aktuellen Planungsstands -**Referenzen:** [Projektstand](../GNAI-000-DOC_Index.md), [Zielarchitektur](GNAI-003-INFRA_Architecture.md), [Modellbewertung](GNAI-008-PLAN_Llama-Model-Evaluation.md), [llama.cpp-Sollkonfiguration](GNAI-009-TECH_Llama-Serving.md), [Zugriffskonzept](../platform/GNAI-004-SEC_Access-Control.md) +**Referenzen:** [Projektstand](../GNAI-000-DOC_Index.md), [Zielarchitektur](GNAI-004-INFRA_Architecture.md), [Modellbewertung](GNAI-009-PLAN_Llama-Model-Evaluation.md), [llama.cpp-Sollkonfiguration](GNAI-010-TECH_Llama-Serving.md), [Zugriffskonzept](../platform/GNAI-005-SEC_Access-Control.md) > **Abgrenzung:** Dieses Dokument hält die Ergebnisse der am 19.09.2026 > begonnenen und bis zum 21.09.2026 fortgeschriebenen Planungssession fest. Es ist @@ -34,6 +34,7 @@ | 2026-09-21 | 0.13 | spektr / Codex | Swift-Qwen3.8 Q6_K mit 128k und `xhigh` als Testing-Kandidat übernommen; Modellbewertung und technische Sollkonfiguration ausgelagert | | 2026-09-21 | 0.14 | spektr / Codex | Unsloth UD-Q6_K als zweites installiertes 128k-Profil und A/B-Kandidat festgelegt | | 2026-09-21 | 0.15 | spektr / Codex | je Modell ein festes, gegenseitig ausgeschlossenes Quadlet vorgesehen und dynamischen llama.cpp-Router zurückgestellt | +| 2026-09-21 | 0.16 | spektr / Codex | überholten Phasen- und Dokumentenbacklog konsolidiert, Umsetzungsreihenfolge an GNAI-001 delegiert und privilegierten Runner nach Recovery verschoben | --- @@ -61,9 +62,10 @@ Dokumentation für Administratoren, Entwickler und Deployment-Berechtigte. ## 2. Ausgangslage -Nach dem dokumentierten Stand ist der KI-Server ein Debian-Basissystem unter -`10.0.0.90`. Der geplante Anwendungsstack aus `llama.cpp`, LiteLLM, OpenWebUI -und weiteren Anwendungen ist noch nicht installiert. Gitea ist im bestehenden +Nach dem dokumentierten Stand besitzt der KI-Server die gemeinsame +Ansible-/Podman-/ROCm-Grundlage unter `10.0.0.90`. Dauerhaftes `llama.cpp`- +Serving und die Zielbild-Kandidaten LiteLLM, OpenWebUI und weitere Anwendungen +sind noch nicht installiert. Gitea ist im bestehenden Serviceinventar unter `10.0.0.17:3000` geführt; Version, Actions-Konfiguration und Registry-Funktionen müssen vor der Implementierung live geprüft werden. @@ -405,8 +407,8 @@ Abweichungen als rootless Quadlet erzeugt: Geräte-Gruppen im rootless Container; - das gemeinsame Modellverzeichnis wird nur lesbar unter `/models` eingebunden; -- `llama-server` erhält keinen Host-Port und ist ausschließlich für LiteLLM im - umgebungseigenen Podman-Netz erreichbar; +- `llama-server` erhält keinen Host-Port und ist ausschließlich für die später + beschlossene API-Policy-Schicht im umgebungseigenen Podman-Netz erreichbar; - systemd übernimmt Start, Neustart, Abhängigkeiten und Health-Überwachung; - Modell- und Laufzeitwerte werden als Ansible-Variablen in die Quadlet-Kommandozeile gerendert. Zusätzliche Container-Environment-Variablen @@ -421,9 +423,9 @@ Abweichungen als rootless Quadlet erzeugt: wird es nicht vorsorglich gesetzt. Die ausführliche Kandidatenbewertung steht in -[GNAI-008-PLAN](GNAI-008-PLAN_Llama-Model-Evaluation.md), die technische +[GNAI-009-PLAN](GNAI-009-PLAN_Llama-Model-Evaluation.md), die technische Sollkonfiguration einschließlich revisionsgebundener Downloadquelle und -SHA-256 in [GNAI-009-TECH](GNAI-009-TECH_Llama-Serving.md). Der bevorzugte +SHA-256 in [GNAI-010-TECH](GNAI-010-TECH_Llama-Serving.md). Der bevorzugte erste Testing-Kandidat ist: | Parameter | Ausgangswert | @@ -592,126 +594,61 @@ Production- und Testing-Berechtigungen bleibt davon unabhängig zu spezifizieren ## 10. Zu erstellende technische Dokumentation und SOPs -Die folgenden Dokumente sind vorgesehen. Titel, Dokumenten-IDs und Zuschnitt -werden bei der Ausarbeitung final festgelegt. +Die frühere Liste aus neun Einzeldokumenten war für den aktuellen Umfang zu +feingranular und hätte Rollen-READMEs, Betriebsabläufe und Sicherheitsregeln +mehrfach beschrieben. Dokumentation wird deshalb entlang realer Zielgruppen +gebündelt und erst gemeinsam mit der zugehörigen Implementierung erstellt: -| Arbeitsname | Inhalt | Zielgruppe | -| --- | --- | --- | -| Technische Spezifikation der Ansible-Plattform | Komponenten, Vertrauensgrenzen, Repository-Struktur, Inventar, Rollenmodell, Runner, Netzpfade, Production-/Testing-Isolation, Secret-Konzept, Versionierung und Abnahmekriterien | Infrastrukturadministratoren und Reviewer | -| SOP: Gitea Runner einrichten | LXC-Voraussetzungen, Installation, Registrierung, Labels, Job-Isolation, Netzwerkregeln, Logging, Updates, Backup und Funktionsabnahme | Server Admin | -| SOP: KI-Server für Ansible vorbereiten | Deployment-Account, SSH-Key, Host-Key, `sudo`, Python-Voraussetzungen, Bootstrap und negative Zugriffstests | Server Admin | -| SOP: Lokales Ansible-Environment einrichten | unterstütztes Betriebssystem, Repository-Checkout, Python-/Ansible-Versionen, Collections, Linting, Vault-Zugriff und lokale Prüfkommandos | Mitwirkende und Reviewer | -| SOP: Änderung und Pull Request | Branching, Rollen- und Variablenänderungen, Dokumentationspflicht, lokale Tests, Review und Merge | Mitwirkende | -| SOP: Deployment ausführen und prüfen | Freigabe-Tag, Actions-Lauf, erwartete Prüfungen, Auswertung, Betriebsnachweis und Fehlerbehandlung | Deployment-Berechtigte | -| SOP: Testing-Umgebung verwenden | Teststand und Wartungsfenster auswählen, kontrollierten Lauf freigeben, Production geordnet umschalten, interne Endpunkte verwenden, Testdaten zurücksetzen, Production wiederherstellen und Ergebnisse im Pull Request dokumentieren | Mitwirkende und Reviewer | -| SOP: Rollback und Wiederherstellung | Revert, erneutes Deployment, Image-Rückkehr, Backup/Restore, Datenmigrationen und Abnahmetests | Server Admin | -| SOP: Geheimnisse verwalten | Vault-Dateien, Passwortaufbewahrung, Runner-Secrets, Rotation, Widerruf und Verhalten bei möglicher Offenlegung | Server Admin und Security-Verantwortliche | +| Artefakt | Inhalt | +| --- | --- | +| Deployment-Architektur | Runner- und Secret-Grenzen, Inventar, Freigaben, Production-/Testing-Isolation und Abnahmekriterien | +| Contributor- und Deployment-SOP | lokales Environment, Änderung, Review, statische CI, bewusste Freigabe und Deploymentnachweis | +| Betriebs- und Recovery-SOP | Testing-Fenster, Environment-Wechsel, Rollback, Backup/Restore und Störungsbehandlung | +| Rollen-READMEs | konkrete Variablen, Voraussetzungen, Aufrufe, erwartete Ergebnisse und technische Fehlerfälle | -Die Nutzer-SOPs sollen konkrete Voraussetzungen, Befehle, erwartete Ergebnisse, -Fehlerfälle und Abnahmekriterien enthalten. Eine Zielbeschreibung allein gilt -nicht als Nachweis einer erfolgreichen Einrichtung. +Ein eigenes Dokument entsteht nur bei eigenständiger Zielgruppe oder +Vertrauensgrenze. Eine Zielbeschreibung allein gilt nicht als Nachweis einer +erfolgreichen Einrichtung. --- -## 11. Vorgesehene Umsetzungsphasen +## 11. Umsetzungsreihenfolge -### Phase A – Ist-Aufnahme und Festlegung +Der frühere Phasenplan vermischte bereits erledigte Grundlagen mit offener +Arbeit und stellte die Gitea-Integration pauschal vor den ersten +Anwendungsnachweis. Er wird durch den statusbasierten +[High-Level-Implementierungsplan](../GNAI-001-PLAN_Project-Roadmap.md) ersetzt. -- Gitea-Version, Actions, Runner-Kompatibilität und Registry prüfen; -- vorbereitete Repositories und Zuständigkeiten aufnehmen; -- Runner-LXC, Netzwerkpfad und Ressourcen festlegen; -- Isolation, exklusiven Umschaltmechanismus, Wartungsfenster und interne - Erreichbarkeit von Production und Testing festlegen; -- eingerichteten Deployment-Account in das endgültige Secret-, Rotations- und - Runner-Verfahren überführen; -- Backup- und Restore-Voraussetzungen klären. +Für diesen Ansible-Teilplan gelten daraus drei Leitplanken: -### Phase B – Ansible-Grundgerüst - -- Repository-Struktur, Inventar und `ansible.cfg` anlegen; -- Werkzeug- und Collection-Versionen festlegen; -- Basisrolle und Verifikationsplaybook entwickeln; -- getrennte Inventare und Variablenvalidierung für Production und Testing - erstellen; -- lokale Entwickler-SOP erstellen und gegen einen frischen Checkout testen. - -### Phase C – Gitea-Integration - -- Runner-LXC reproduzierbar einrichten und abnehmen; -- Validierungsworkflow ohne Produktionszugang einführen; -- Branch- und Tag-Schutz konfigurieren; -- Deployment-Workflow mit einem ungefährlichen Testplaybook abnehmen; -- Testing-Deployment vor dem Merge und Production-Freigabe nach dem Merge - getrennt abnehmen. - -### Phase D – KI-Laufzeit - -- Podman- und Quadlet-Grundruntime sowie getrennte rootless Workload-Konten - eingerichtet und geprüft; -- rootless Host-Gerätezugriff auf beide RX 6900 XT eingerichtet und geprüft; -- ROCm-Funktion und `llama.cpp`-Geräteerkennung im rootless Testing-Container - mit gepinntem Image geprüft; -- `llama.cpp` mit Modell und lokalem Inferenztest; -- Wiederanlauf nach geplantem Reboot prüfen. - -### Phase E – Anwendungen und Veröffentlichung - -- LiteLLM, OpenWebUI und weitere beschlossene Anwendungen; -- persistente Daten, Backups und Restore-Test; -- interne Dienste und NPM-Veröffentlichung getrennt abnehmen; -- Authentifizierung, API-Keys, Health Monitoring und Betriebs-SOPs ergänzen. +1. Der erste interne `llama.cpp`-Vertical-Slice wird lokal kontrolliert und + ohne öffentliche Route ausgerollt. +2. Statische CI erhält keine SSH- oder Deployment-Secrets. +3. Ein privilegierter Runner folgt erst nach stabilem Rollen-, Rollback- und + Recovery-Verfahren. --- -## 12. Offene Entscheidungen und Nachweise +## 12. Verbleibende Deployment-Entscheidungen -Vor der technischen Spezifikation sind mindestens folgende Punkte zu klären: +Produkt- und Prioritätsentscheidungen stehen zentral in GNAI-001. Für die +spätere Delivery-Kette bleiben hier nur folgende technische Fragen: -1. Welche Gitea-Version läuft, und sind Actions sowie geschützte Tags in der - eingesetzten Version aktiviert und geeignet? -2. Welche Komponenten werden zunächst ausschließlich als versionierte - Upstream-Artefakte eingebunden, und für welche ist mittelfristig eigener - Quellcode zu erwarten? -3. Wo wird der Runner-LXC betrieben, welche Adresse erhält er, und darf dort - Docker für isolierte Jobs eingesetzt werden? -4. Soll die erste Produktionsfreigabe über einen geschützten Tag oder zunächst - über einen manuell gestarteten Workflow erfolgen? -5. Welche Personen oder Gitea-Teams dürfen reviewen, mergen und Deployments - freigeben? -6. Wie wird der bestehende root-äquivalente Schlüssel von der lokalen - Control-Umgebung auf den späteren Runner überführt beziehungsweise rotiert, - und wie werden Production- und Testing-Berechtigungen dabei getrennt? -7. Wird Ansible Vault verwendet, oder soll ein anderer vorhandener - Secret-Store angebunden werden? -8. Werden eigene Images in der Gitea Registry gebaut, und wie werden - Registry-Credentials und Image-Signaturen behandelt? -9. Welche Backupziele, Aufbewahrungsfristen und nachgewiesenen Restore-Verfahren - gelten für Konfiguration, Modelle und Anwendungsdaten? -10. Welche Versionen und Installationswege werden für AMD-GPU-Laufzeit, - `llama.cpp`, LiteLLM, OpenWebUI und weitere Anwendungen unterstützt? -11. Welche ausgehenden Internetzugriffe erhalten Runner und KI-Server für - Pakete, Collections, Images und Modelle? -12. Welche Health Checks und fachlichen Inferenztests bilden die verbindliche - Abnahme eines Deployments? -13. Welche maximale Dauer, Häufigkeit und Ankündigungsfrist gelten für - Testing-Wartungsfenster, in denen Production nicht verfügbar ist? -14. Welcher hostseitige Lock-, Timeout- und Recovery-Mechanismus stellt den - Wiederanlauf von Production sicher, wenn Runner oder Testing ausfallen? -15. Welche internen Hostnamen und Ports erhält Testing, und welche LAN-/VPN- - Rollen dürfen darauf zugreifen? -16. Muss der für Testing nachgewiesene AMD-GPU-Zugriff vor der ersten - Production-Freigabe mit demselben gepinnten Image separat unter - `gnai-production` abgenommen werden? -17. Wie wird ein Testing-Deployment eines Pull-Request-Commits in der - eingesetzten Gitea-Version autorisiert, ohne Production-Secrets oder - Production-Runner für veränderbaren PR-Code verfügbar zu machen? -18. Welche Testdaten dürfen verwendet werden, und wie wird ausgeschlossen, - dass personenbezogene oder geheime Production-Daten nach Testing kopiert - werden? +1. Welche Gitea-/Actions-/Runner-Version und welche Schutzfunktionen sind live + verfügbar? +2. Wo läuft der repository-spezifische Runner, und welche Job-Isolation wird + nachweisbar unterstützt? +3. Welche Personen dürfen reviewen, mergen und Testing beziehungsweise + Production freigeben? +4. Welcher Secret-Store, welche Schlüsselrotation und welche getrennten + Testing-/Production-Rechte werden verwendet? +5. Welcher unveränderliche Commit und welcher manuelle Freigabeschritt lösen + Production aus? +6. Welcher hostseitige Lock-, Timeout- und Recovery-Mechanismus stellt + Production nach einem Abbruch wieder her? -Diese Fragen werden nicht durch Annahmen in Playbooks ersetzt. Entscheidungen -werden zunächst in der technischen Spezifikation dokumentiert und anschließend -in Implementierung und SOPs übernommen. +Diese Fragen werden vor Einführung eines privilegierten Runners entschieden, +nicht als Voraussetzung für den internen Testing-Vertical-Slice. --- @@ -908,9 +845,8 @@ Insbesondere wurden noch nicht: - Backups oder Rollbacks praktisch getestet oder - die geplante Deploymentkette technisch abgenommen. -Der nächste technische Schritt ist die `llama.cpp`-Rolle für Testing. Sie soll -das gepinnte Image als rootless Quadlet betreiben, beide festgelegten Modelle -mit geprüften Checksummen bereitstellen und jeweils einzeln mit dem -vorgesehenen Layer-Split und realer Inferenz abnehmen. Dafür werden zwei feste, -gegenseitig ausgeschlossene Quadlets aus derselben Rollenlogik erzeugt. Danach -folgt die reproduzierbare A/B-Serie; darauf baut anschließend LiteLLM auf. +Der nächste KI-spezifische Schritt ist die `llama.cpp`-Rolle für Testing. Die +bereichsübergreifende Priorität und die Abhängigkeit von den offenen +Sicherheitsbefunden legt GNAI-001 fest. LiteLLM ist nicht länger automatisch +der Folgeschritt, sondern wird vor einer Veröffentlichung anhand der benötigten +API-Policies entschieden. diff --git a/docs/ai/GNAI-008-PLAN_Llama-Model-Evaluation.md b/docs/ai/GNAI-009-PLAN_Llama-Model-Evaluation.md similarity index 97% rename from docs/ai/GNAI-008-PLAN_Llama-Model-Evaluation.md rename to docs/ai/GNAI-009-PLAN_Llama-Model-Evaluation.md index b1c8afc..cc85f4e 100644 --- a/docs/ai/GNAI-008-PLAN_Llama-Model-Evaluation.md +++ b/docs/ai/GNAI-009-PLAN_Llama-Model-Evaluation.md @@ -1,10 +1,10 @@ # Arbeitsentwurf -**Dokumenten-ID:** GNAI-008-PLAN +**Dokumenten-ID:** GNAI-009-PLAN **Titel:** Modell- und Laufzeitbewertung für `llama.cpp` **Stand:** 2026-09-21 **Status:** Nicht finaler Evaluierungsplan; keine Production-Freigabe -**Referenzen:** [Ansible-Deployment](GNAI-007-PLAN_Ansible-Deployment.md), [technische Sollkonfiguration](GNAI-009-TECH_Llama-Serving.md), [Zielarchitektur](GNAI-003-INFRA_Architecture.md) +**Referenzen:** [Ansible-Deployment](GNAI-008-PLAN_Ansible-Deployment.md), [technische Sollkonfiguration](GNAI-010-TECH_Llama-Serving.md), [Zielarchitektur](GNAI-004-INFRA_Architecture.md) > Dieses Dokument persistiert die Modellrecherche und legt fest, wie daraus > eine belastbare Entscheidung für den KI-Server entsteht. Veröffentlichte @@ -18,6 +18,7 @@ | Datum | Version | Autor | Beschreibung | | --- | --- | --- | --- | +| 2026-09-21 | 0.4 | spektr / Codex | Metrikübergabe an die später gewählte API-Policy-Schicht statt vorab an LiteLLM gebunden | | 2026-09-21 | 0.3 | spektr / Codex | feste, gegenseitig ausgeschlossene Quadlet-Unit je Modell als Umschaltverfahren festgelegt | | 2026-09-21 | 0.2 | spektr / Codex | Unsloth Qwen3.8 UD-Q6_K als verbindlichen zweiten 128k-Kandidaten festgelegt und kontrollierten A/B-Test ergänzt | | 2026-09-21 | 0.1 | spektr / Codex | Swift-Qwen3.8, Q6_K, Reasoning, Kontext, MTP und lokales Vergleichsverfahren als ersten Evaluierungsstand aufgenommen | @@ -324,7 +325,8 @@ aktiviert werden. - maximal zulässige Antwortdauer und Ausgabegröße für externe Nutzer festlegen; - entscheiden, ob Vision Bestandteil des ersten Production-Profils wird; -- Metrikerfassung für Reasoning- und Antworttoken mit LiteLLM abstimmen; +- Metrikerfassung für Reasoning- und Antworttoken mit der später gewählten + API-Policy-Schicht abstimmen; - Aufgabenbestand und erwartete Ergebnisse der lokalen Suite versionieren; und - nach Veröffentlichung bewerten, ob Swift 1.5 oder eine geprüfte Swift-Dynamic-Quantisierung als neuer Kandidat aufgenommen wird. diff --git a/docs/ai/GNAI-009-TECH_Llama-Serving.md b/docs/ai/GNAI-010-TECH_Llama-Serving.md similarity index 94% rename from docs/ai/GNAI-009-TECH_Llama-Serving.md rename to docs/ai/GNAI-010-TECH_Llama-Serving.md index 4fe60d1..ca41aaa 100644 --- a/docs/ai/GNAI-009-TECH_Llama-Serving.md +++ b/docs/ai/GNAI-010-TECH_Llama-Serving.md @@ -1,10 +1,10 @@ # Technischer Arbeitsentwurf -**Dokumenten-ID:** GNAI-009-TECH +**Dokumenten-ID:** GNAI-010-TECH **Titel:** `llama.cpp`-Serving mit ROCm und rootless Podman **Stand:** 2026-09-21 **Status:** Technische Sollkonfiguration für Testing; noch nicht implementiert -**Referenzen:** [Modellbewertung](GNAI-008-PLAN_Llama-Model-Evaluation.md), [Ansible-Deployment](GNAI-007-PLAN_Ansible-Deployment.md), [Zielarchitektur](GNAI-003-INFRA_Architecture.md), [Ansible-Anleitung](../../ansible/README.md) +**Referenzen:** [Modellbewertung](GNAI-009-PLAN_Llama-Model-Evaluation.md), [Ansible-Deployment](GNAI-008-PLAN_Ansible-Deployment.md), [Zielarchitektur](GNAI-004-INFRA_Architecture.md), [Ansible-Anleitung](../../ansible/README.md) > Dieses Dokument beschreibt den vorgesehenen technischen Sollzustand. Es ist > keine Betriebs-SOP und kein Nachweis, dass Modell, Quadlet oder Inferenz @@ -17,6 +17,7 @@ | Datum | Version | Autor | Beschreibung | | --- | --- | --- | --- | +| 2026-09-21 | 0.4 | spektr / Codex | Serving von der noch zu entscheidenden externen API-Policy-Schicht entkoppelt | | 2026-09-21 | 0.3 | spektr / Codex | je Modell ein festes Quadlet vorgesehen; Swift und Unsloth durch kontrollierten Stop/Start gegenseitig ausgeschlossen; Router-Modus zurückgestellt | | 2026-09-21 | 0.2 | spektr / Codex | Unsloth UD-Q6_K als zweites installiertes Modellprofil und kontrollierten Profilwechsel für A/B-Tests ergänzt | | 2026-09-21 | 0.1 | spektr / Codex | erstes technisches Profil für Swift Q6_K, 128k, Q8-KV, rootless Quadlet und gestufte MTP-Abnahme erstellt | @@ -36,9 +37,10 @@ Testing-Umgebung, von denen immer genau eines aktiv ist. Sie legt fest: - welche technischen Prüfungen vor der Übernahme nach Production bestehen müssen. -LiteLLM, öffentliche Veröffentlichung, Nutzer-SOPs und die zeitliche +API-Policy-Schicht, öffentliche Veröffentlichung, Nutzer-SOPs und die zeitliche Umschaltung zwischen Production und Testing erhalten eigene Rollen und -Dokumente. `llama-server` wird nicht direkt für LAN, VPN oder Internet +Dokumente. Ob dafür LiteLLM eingesetzt wird, entscheidet GNAI-001 erst vor der +Veröffentlichung. `llama-server` wird nicht direkt für LAN, VPN oder Internet veröffentlicht. ## 2. Bereits belegte Voraussetzungen @@ -205,7 +207,7 @@ Der `[Container]`-Abschnitt muss mindestens folgende Eigenschaften abbilden: | `AddDevice=` | `/dev/kfd`, `/dev/dri/renderD128`, `/dev/dri/renderD129` | | `GroupAdd=` | `keep-groups` | | `Volume=` | Modellverzeichnis nach `/models:ro` | -| `Network=` | dediziertes Testing-Netz für `llama.cpp` und LiteLLM | +| `Network=` | dediziertes Testing-Netz für `llama.cpp` und eine spätere API-Policy-Schicht | | `NetworkAlias=` | `llama-cpp`; wegen gegenseitigem Ausschluss immer nur einmal aktiv | | `PublishPort=` | nicht gesetzt | | `ReadOnly=` | nach erfolgreichem Starttest `true` | @@ -279,7 +281,8 @@ Für die erste Abnahme bleibt jedes Quadlet im einfacheren Single-Model-Modus. Damit sind Startparameter, Logs, Health, VRAM-Verbrauch und Fehlerzustand einem Modell eindeutig zugeordnet. Außerdem benötigt der interne Dienst keine dynamische Modellverwaltungs-API. Nach stabiler Abnahme kann der Router-Modus -separat bewertet werden; er ist keine Voraussetzung für LiteLLM. +separat bewertet werden; er ist keine Voraussetzung für eine externe +API-Policy-Schicht. ## 6. `llama-server`-Ausgangsprofil @@ -343,12 +346,13 @@ betriebenen Testing-Dienst vor unbegrenzten Läufen. Die Evaluierung enthält zusätzlich einen kontrollierten 65.536-Token-Lauf. Vor Production wird entschieden, ob die allgemeine Obergrenze erhöht oder -später durch LiteLLM pro Nutzer und Modell gesteuert wird. Ein Default von +später durch die API-Policy-Schicht pro Nutzer und Modell gesteuert wird. Ein Default von 2.048 oder 4.096 Token ist für dieses Profil nicht vorgesehen. Die API muss Reasoning getrennt von der finalen Antwort liefern. Zunächst wird das automatische `--reasoning-format` des gepinnten Builds geprüft. Ein fester -Wert wird erst gesetzt, wenn die Kombination aus llama.cpp, LiteLLM und den +Wert wird erst gesetzt, wenn die Kombination aus `llama.cpp`, der gewählten +API-Policy-Schicht und den verwendeten Clients mit einem reproduzierbaren Request abgenommen wurde. Für Unsloth werden zwei Reasoning-Varianten gerendert. `xhigh` dient dem @@ -443,13 +447,14 @@ Ressourcen-Fallback vorgesehen. ## 8. Netzwerk und API-Grenze `llama-server` hört im Container auf TCP 8080. Es gibt kein `PublishPort=` und -keine Host-Portweiterleitung. LiteLLM wird später in dasselbe -umgebungsspezifische rootless Podman-Netz aufgenommen und erreicht den Dienst -über `http://llama-cpp:8080`. +keine Host-Portweiterleitung. Eine später beschlossene API-Policy-Schicht wird +in dasselbe umgebungsspezifische rootless Podman-Netz aufgenommen und erreicht +den Dienst über `http://llama-cpp:8080`. Direkte Funktionsprüfungen erfolgen aus dem Container-Netz oder über einen kurzlebigen administrativen Prüfcontainer. Externe Nutzer sprechen später nur -LiteLLM beziehungsweise die dafür vorgesehene veröffentlichte Anwendung an. +die freigegebene API-Policy-Schicht beziehungsweise die dafür vorgesehene +veröffentlichte Anwendung an. Der integrierte Webserver wird mit `--no-webui` betrieben. Metriken und Health bleiben ausschließlich im internen Container-Netz. Vor der Health-Quadlet- @@ -521,7 +526,7 @@ Rolle darf nie beide GPU-Umgebungen gleichzeitig starten. Diese Abnahme wird zuerst für Swift und danach für Unsloth wiederholt. Erst wenn beide Profile die technische Abnahme bestanden haben, beginnt die -fachliche A/B-Serie aus GNAI-008. +fachliche A/B-Serie aus GNAI-009. ### 10.4 Wiederanlauf und Idempotenz diff --git a/docs/ai/README.md b/docs/ai/README.md index 24a98d4..180465f 100644 --- a/docs/ai/README.md +++ b/docs/ai/README.md @@ -8,10 +8,11 @@ Video-Encoding-Workload besitzt einen | Dokument | Inhalt | | --- | --- | -| [GNAI-003](GNAI-003-INFRA_Architecture.md) | Zielarchitektur, Komponenten und Datenwege des KI-Stacks | -| [GNAI-007](GNAI-007-PLAN_Ansible-Deployment.md) | nicht finaler Arbeitsentwurf für Ansible- und Gitea-Deployment | -| [GNAI-008](GNAI-008-PLAN_Llama-Model-Evaluation.md) | nicht finaler A/B-Plan für Swift, Unsloth, Reasoning-, Kontext- und MTP-Abnahme | -| [GNAI-009](GNAI-009-TECH_Llama-Serving.md) | technische Sollkonfiguration für zwei geprüfte Modellprofile auf rootless `llama.cpp` mit ROCm | +| [GNAI-001](../GNAI-001-PLAN_Project-Roadmap.md) | priorisierter High-Level-Implementierungsplan mit Entscheidungstoren und Abnahmekriterien | +| [GNAI-004](GNAI-004-INFRA_Architecture.md) | Zielarchitektur, Komponenten und Datenwege des KI-Stacks | +| [GNAI-008](GNAI-008-PLAN_Ansible-Deployment.md) | nicht finaler Arbeitsentwurf für Ansible- und Gitea-Deployment | +| [GNAI-009](GNAI-009-PLAN_Llama-Model-Evaluation.md) | nicht finaler A/B-Plan für Swift, Unsloth, Reasoning-, Kontext- und MTP-Abnahme | +| [GNAI-010](GNAI-010-TECH_Llama-Serving.md) | technische Sollkonfiguration für zwei geprüfte Modellprofile auf rootless `llama.cpp` mit ROCm | Der übergreifende Projektstand steht im [zentralen Dokumentationsindex](../GNAI-000-DOC_Index.md). diff --git a/docs/platform/GNAI-001-INFRA_BaseSystem.md b/docs/platform/GNAI-002-INFRA_BaseSystem.md similarity index 96% rename from docs/platform/GNAI-001-INFRA_BaseSystem.md rename to docs/platform/GNAI-002-INFRA_BaseSystem.md index b7c4460..3b632e6 100644 --- a/docs/platform/GNAI-001-INFRA_BaseSystem.md +++ b/docs/platform/GNAI-002-INFRA_BaseSystem.md @@ -1,6 +1,6 @@ # Standard Operating Procedure -**Dokumenten-ID:** GNAI-001-INFRA +**Dokumenten-ID:** GNAI-002-INFRA **Titel:** Initialisierung und OS-Installation: LLM-Server (Phase 1) **Status:** Installationsanleitung mit lesendem Teilabgleich; vollständige Abnahme offen **Referenzen:** - @@ -13,7 +13,7 @@ | --- | --- | --- | --- | | 2026-08-24 | 1.0 | spektr | Erstellung des Initial-Dokuments (Hardware & OS) | | 2026-08-24 | 1.1 | spektr | Detaillierung der BIOS-ReBAR-Settings, Netinst-CLI-Schritte, Post-Installation & Abnahmekriterien hinzugefügt. | -| 2026-09-16 | 1.2 | spektr | Benutzer- und Netzwerkaufgaben nach GNAI-002 verlagert; ungesicherte Downloadpfade und Domainvorgabe entfernt. | +| 2026-09-16 | 1.2 | spektr | Benutzer- und Netzwerkaufgaben nach GNAI-003 verlagert; ungesicherte Downloadpfade und Domainvorgabe entfernt. | | 2026-09-18 | 1.3 | spektr | GPU-Abnahme auf nachweisbare Geräteerkennung begrenzt; Firmwarepaket präzisiert. | | 2026-09-19 | 1.4 | spektr | Getrennte SSH-Zugänge für `ghost` und `ghost-agent` als erfolgreich getestet übernommen. | @@ -21,7 +21,7 @@ ## 1. Zweck und Geltungsbereich -Dieses Dokument beschreibt Hardware, BIOS und Debian-Installation des KI-Servers. Benutzer, statische Netzkonfiguration und SSH-Härtung werden in [GNAI-002](GNAI-002-INFRA_Users.md) eingerichtet. Die Schritte sind eine Anleitung, kein Nachweis ihrer Ausführung auf dem bestehenden Host. +Dieses Dokument beschreibt Hardware, BIOS und Debian-Installation des KI-Servers. Benutzer, statische Netzkonfiguration und SSH-Härtung werden in [GNAI-003](GNAI-003-INFRA_Users.md) eingerichtet. Die Schritte sind eine Anleitung, kein Nachweis ihrer Ausführung auf dem bestehenden Host. --- @@ -137,7 +137,7 @@ apt update apt install -y curl wget git htop tmux pciutils firmware-amd-graphics ``` -Für Sudo, Netzwerk und SSH mit [GNAI-002](GNAI-002-INFRA_Users.md) fortfahren. Vor Änderungen auf einem laufenden Host die dort dokumentierte Netzverwaltung prüfen. +Für Sudo, Netzwerk und SSH mit [GNAI-003](GNAI-003-INFRA_Users.md) fortfahren. Vor Änderungen auf einem laufenden Host die dort dokumentierte Netzverwaltung prüfen. --- @@ -147,7 +147,7 @@ Vor der Übergabe an das KI-Team (Phase 2) muss das System folgende Punkte beste * **RAM-Check:** `free -h` zeigt mindestens ~62 GB RAM an. * **GPU-Erkennung:** `lspci -nn | grep -Ei 'vga|display|3d'` listet **zwei** AMD-Grafikgeräte auf. Das genaue Kartenmodell anhand des Hardwareinventars oder der Geräte selbst prüfen; die PCI-Familienkennung allein genügt dafür nicht. -* **Netzwerk:** Der Server ist nach GNAI-002 unter `10.0.0.90` erreichbar. Die getrennten SSH-Zugänge für `ghost` und `ghost-agent` wurden am 19.09.2026 erfolgreich getestet. +* **Netzwerk:** Der Server ist nach GNAI-003 unter `10.0.0.90` erreichbar. Die getrennten SSH-Zugänge für `ghost` und `ghost-agent` wurden am 19.09.2026 erfolgreich getestet. * **Storage:** `lsblk -f` zeigt die vorgesehene Partitionierung der 2-TB-SSD; `df -h /` zeigt die nutzbare Dateisystemgröße (in binären Einheiten kleiner als 2 TB). * **Re-Size BAR:** BIOS-Einstellung und zugewiesene PCIe-BAR-Größen getrennt prüfen; ein bloßer `dmesg | grep -i BAR`-Treffer gilt nicht als Funktions- oder Leistungsnachweis. diff --git a/docs/platform/GNAI-002-INFRA_Users.md b/docs/platform/GNAI-003-INFRA_Users.md similarity index 98% rename from docs/platform/GNAI-002-INFRA_Users.md rename to docs/platform/GNAI-003-INFRA_Users.md index df7ad76..9fcf4ec 100644 --- a/docs/platform/GNAI-002-INFRA_Users.md +++ b/docs/platform/GNAI-003-INFRA_Users.md @@ -1,6 +1,6 @@ # Standard Operating Procedure -**Dokumenten-ID:** GNAI-002-INFRA +**Dokumenten-ID:** GNAI-003-INFRA **Titel:** Benutzerverwaltung, SSH-Härtung & Netzwerkkonfiguration (Phase 2) **Status:** Betriebsanleitung; tatsächliche Netzverwaltung und Konten vor Anwendung prüfen @@ -28,7 +28,7 @@ Dieses Dokument beschreibt Benutzer, statische IP und SSH des KI-Servers. Der ur ## 2. Voraussetzungen & Berechtigungen -* Bereits installiertes Debian-Grundsystem gemäß [GNAI-001](GNAI-001-INFRA_BaseSystem.md). +* Bereits installiertes Debian-Grundsystem gemäß [GNAI-002](GNAI-002-INFRA_BaseSystem.md). * Root-Zugriff oder Benutzer mit `sudo`-Rechten. * Admin-Workstation mit lokal installierter SSH-Suite (`ssh`, `ssh-keygen`); für den bestehenden Host ist die lokale Konsole oder ein bereits berechtigter Zugang zur Schlüsselaufnahme nötig. diff --git a/docs/platform/GNAI-004-SEC_Access-Control.md b/docs/platform/GNAI-005-SEC_Access-Control.md similarity index 88% rename from docs/platform/GNAI-004-SEC_Access-Control.md rename to docs/platform/GNAI-005-SEC_Access-Control.md index d34014c..0d4274c 100644 --- a/docs/platform/GNAI-004-SEC_Access-Control.md +++ b/docs/platform/GNAI-005-SEC_Access-Control.md @@ -1,9 +1,9 @@ # Security & Access Control Specification -**Dokumenten-ID:** GNAI-004-SEC +**Dokumenten-ID:** GNAI-005-SEC **Titel:** Homelab / LLM-Infrastruktur – Sicherheits-, Authentifizierungs- und Zugriffskonzept **Status:** Verbindliches Zielmodell; technische Durchsetzung teilweise offen -**Vorgänger / Referenzen:** [Architektur](../ai/GNAI-003-INFRA_Architecture.md), [Gateway](GNAI-006-SEC_VPN.md), [GUI-SOP](GNAI-006-SEC_VPN_Client-Management.md), [Reverse Proxy](GNAI-005-SEC_Reverse-Proxy.md) +**Vorgänger / Referenzen:** [Architektur](../ai/GNAI-004-INFRA_Architecture.md), [Gateway](GNAI-007-SEC_VPN.md), [GUI-SOP](GNAI-007-SEC_VPN_Client-Management.md), [Reverse Proxy](GNAI-006-SEC_Reverse-Proxy.md) --- @@ -13,8 +13,9 @@ | --- | --- | --- | --- | | 2026-08-28 | 1.0 | spektr | Erstellung des Sicherheits- und Zugriffskonzepts. | | 2026-09-15 | 1.1 | spektr | Familie, Server Admin und LLM Admin getrennt; serverseitige Zielrechte, NAT und Umsetzungsdefizite dokumentiert; OIDC-Ist präzisiert. | -| 2026-09-16 | 1.2 | spektr | Fail2Ban-Pin `1.1.0-r2-ls43` und wieder laufenden Container als Ist-Stand übernommen; technische Abnahme bleibt in GNAI-005 geführt. | +| 2026-09-16 | 1.2 | spektr | Fail2Ban-Pin `1.1.0-r2-ls43` und wieder laufenden Container als Ist-Stand übernommen; technische Abnahme bleibt in GNAI-006 geführt. | | 2026-09-18 | 1.3 | spektr | KI-Anwendungsdienste als Zielbild und bestehende Fail2Ban-Jails als dokumentierten Ist-Stand eingeordnet. | +| 2026-09-21 | 1.4 | spektr / Codex | Zugriffsziel von einer vorentschiedenen LiteLLM-Implementierung auf eine noch festzulegende API-Policy-Schicht verallgemeinert | --- @@ -55,7 +56,7 @@ Kein privilegierter Netzwerkzugang. **Zugang:** -HTTPS über NPM zur LiteLLM-API. +HTTPS über NPM zur freigegebenen LLM-API-Policy-Schicht. **Authentifizierung:** @@ -63,7 +64,7 @@ HTTPS über NPM zur LiteLLM-API. **Erlaubt:** -- Nutzung der von LiteLLM freigegebenen Modelle / Endpunkte +- Nutzung der von der API-Policy freigegebenen Modelle / Endpunkte - Nutzung nach den für den Benutzer gesetzten Quoten und Policies **Nicht erlaubt:** @@ -88,7 +89,7 @@ Ein normaler LLM User erhält **keinen WireGuard-Peer**, sofern für einen konkr | KI-Server SSH/Management | erlaubt + Dienstauthentifizierung | erlaubt + Dienstauthentifizierung | erlaubt + Dienstauthentifizierung | gesperrt | | Keycloak Administration | intern, nach Dienstberechtigung | intern, nach Dienstberechtigung | gesperrt | Soll: gesperrt; Ist: öffentlich erreichbar | | benötigte OIDC-Endpunkte | anwendungsbezogen | anwendungsbezogen | anwendungsbezogen | öffentlich für Login | -| LiteLLM API | nach API-Policy | nach API-Policy | nach API-Policy | Soll: HTTPS + individueller API-Key | +| LLM API | nach API-Policy | nach API-Policy | nach API-Policy | Soll: HTTPS + individuelles Credential | | OpenWebUI / weitere Webanwendungen | nach Anwendungsrechten | nach Anwendungsrechten | nach Anwendungsrechten | Soll: HTTPS und geeignete Anmeldung | | llama.cpp / Datenbanken | nur nach Backend-/Dienstpolicy | nur nach Backend-/Dienstpolicy | nur KI-Server-bezogen nach Bedarf | nicht direkt öffentlich | @@ -121,17 +122,19 @@ Ziel: Benutzer melden sich an der zentralen Keycloak-Identitätsquelle an. Die vorgesehenen Anwendungen binden diese per OIDC ein. -Administrative Keycloak-Funktionen müssen auf interne berechtigte Zugriffe beschränkt werden. Ist: externe Admin-Anmeldung möglich, Korrektur in GNAI-005 dokumentiert. Laut Betreiber wird OIDC produktiv nur für Vaultwarden genutzt; Nextcloud, Gitea, OpenWebUI und weitere Dienste sind geplant. +Administrative Keycloak-Funktionen müssen auf interne berechtigte Zugriffe beschränkt werden. Ist: externe Admin-Anmeldung möglich, Korrektur in GNAI-006 dokumentiert. Laut Betreiber wird OIDC produktiv nur für Vaultwarden genutzt; Nextcloud, Gitea, OpenWebUI und weitere Dienste sind geplant. --- -### 4.3 LiteLLM API +### 4.3 LLM-API Die LLM-API ist ein anwendungsbezogener Dienst und wird deshalb nicht durch einen allgemeinen LAN-/VPN-Zugang für normale Benutzer bereitgestellt. Ziel: -Der Client erreicht LiteLLM per HTTPS über NPM; LiteLLM nutzt intern llama.cpp. +Der Client erreicht die beschlossene API-Policy-Schicht per HTTPS über NPM; +diese nutzt intern `llama.cpp`. LiteLLM ist dafür ein Kandidat, aber bis zur +Produkt- und Policy-Entscheidung keine zwingende Komponente. Die Autorisierung erfolgt über API-Keys. @@ -168,14 +171,16 @@ MASQUERADE wird mangels Rückroute verwendet; es verbirgt gegenüber LAN-Dienste ## 6. Vorgesehene öffentliche und private Erreichbarkeit -Die folgende Einordnung ist das Zielmodell. LiteLLM und die Webanwendungen auf dem KI-Server werden erst im späteren Ansible-Sprint eingerichtet. +Die folgende Einordnung ist das Zielmodell. Die LLM-API-Policy-Schicht und die +Webanwendungen auf dem KI-Server werden erst nach der jeweiligen +Produktentscheidung eingerichtet. ### Öffentlich - HTTP/HTTPS auf NPM - für den VPN-Betrieb: WireGuard UDP-Port - OIDC-Endpunkte, soweit für Web-Login erforderlich -- LiteLLM API über HTTPS +- freigegebene LLM-API über HTTPS - öffentliche Webanwendungen ### Privat @@ -208,7 +213,7 @@ Nicht vorgesehen ist ein pauschales Blocking aller HTTP-Fehlercodes. Insbesondere soll ein allgemeiner `404` nicht automatisch als Angriff gewertet werden. -Die vorhandenen NPM-Jails sind in [GNAI-005](GNAI-005-SEC_Reverse-Proxy.md) dokumentiert. Ihre Funktion nach dem Image-Pin sowie Neustart und Wiederanlauf müssen noch abgenommen werden. +Die vorhandenen NPM-Jails sind in [GNAI-006](GNAI-006-SEC_Reverse-Proxy.md) dokumentiert. Ihre Funktion nach dem Image-Pin sowie Neustart und Wiederanlauf müssen noch abgenommen werden. --- @@ -297,4 +302,4 @@ Das Sicherheitsmodell basiert damit nicht auf einem einzelnen „Security-Progra ## 11. Umsetzungsnachweise -Dieses Dokument definiert die Zugriffsziele. Der [Dokumentationsindex](../GNAI-000-DOC_Index.md) bündelt den aktuellen Projektstand. Konkrete Gateway-Regeln und Rollentests stehen in [GNAI-006](GNAI-006-SEC_VPN.md), der Keycloak-Adminpfad und Fail2Ban in [GNAI-005](GNAI-005-SEC_Reverse-Proxy.md). Offene Zielrechte gelten bis zu ihrer technischen Abnahme nicht als durchgesetzt. +Dieses Dokument definiert die Zugriffsziele. Der [Dokumentationsindex](../GNAI-000-DOC_Index.md) bündelt den aktuellen Projektstand. Konkrete Gateway-Regeln und Rollentests stehen in [GNAI-007](GNAI-007-SEC_VPN.md), der Keycloak-Adminpfad und Fail2Ban in [GNAI-006](GNAI-006-SEC_Reverse-Proxy.md). Offene Zielrechte gelten bis zu ihrer technischen Abnahme nicht als durchgesetzt. diff --git a/docs/platform/GNAI-005-SEC_Reverse-Proxy.md b/docs/platform/GNAI-006-SEC_Reverse-Proxy.md similarity index 98% rename from docs/platform/GNAI-005-SEC_Reverse-Proxy.md rename to docs/platform/GNAI-006-SEC_Reverse-Proxy.md index 5d4fd30..5559175 100644 --- a/docs/platform/GNAI-005-SEC_Reverse-Proxy.md +++ b/docs/platform/GNAI-006-SEC_Reverse-Proxy.md @@ -1,9 +1,9 @@ # Betriebs- und Sicherheitsdokumentation – Reverse Proxy -**Dokumenten-ID:** GNAI-005-SEC +**Dokumenten-ID:** GNAI-006-SEC **Titel:** Reverse Proxy und Fail2Ban – Konfiguration, Betrieb und Sicherheitsabnahme **Status:** NPM aktiv; Fail2Ban laut Betreiber fest gepinnt und wieder in Betrieb; Keycloak-Admin-Exposure bestätigt, Korrektur offen -**Vorgänger / Referenzen:** [Architektur](../ai/GNAI-003-INFRA_Architecture.md), [Zugriffskonzept](GNAI-004-SEC_Access-Control.md), [WireGuard](GNAI-006-SEC_VPN.md) +**Vorgänger / Referenzen:** [Architektur](../ai/GNAI-004-INFRA_Architecture.md), [Zugriffskonzept](GNAI-005-SEC_Access-Control.md), [WireGuard](GNAI-007-SEC_VPN.md) --- @@ -329,7 +329,7 @@ Vor strukturellen Änderungen an nftables, Proxy-Konfiguration oder Quadlets ein ### 11.1 Bestätigter Ist-Stand -Der Betreiber konnte **von extern** `https://auth.ghostnet.selfhost.eu/admin` öffnen und sich anmelden. Das widerspricht GNAI-004. Die Korrektur wurde bei dieser Dokumentationsrevision noch nicht auf dem System durchgeführt. +Der Betreiber konnte **von extern** `https://auth.ghostnet.selfhost.eu/admin` öffnen und sich anmelden. Das widerspricht GNAI-005. Die Korrektur wurde bei dieser Dokumentationsrevision noch nicht auf dem System durchgeführt. | NPM-Einstellung | Betreiberangabe | | --- | --- | diff --git a/docs/platform/GNAI-006-profiles/.gitignore b/docs/platform/GNAI-006-profiles/.gitignore deleted file mode 100644 index 16dcb7b..0000000 --- a/docs/platform/GNAI-006-profiles/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -# Secrets: WireGuard PrivateKeys/PresharedKeys – niemals committen -* -!.gitignore -!README.md diff --git a/docs/platform/GNAI-006-SEC_VPN.md b/docs/platform/GNAI-007-SEC_VPN.md similarity index 98% rename from docs/platform/GNAI-006-SEC_VPN.md rename to docs/platform/GNAI-007-SEC_VPN.md index cad5aa1..7bc3b1d 100644 --- a/docs/platform/GNAI-006-SEC_VPN.md +++ b/docs/platform/GNAI-007-SEC_VPN.md @@ -1,8 +1,8 @@ # Technische Architekturbeschreibung – WireGuard-Gateway -**Dokumenten-ID:** GNAI-006-SEC +**Dokumenten-ID:** GNAI-007-SEC **Status:** Dokumentation bereinigt; technische Umsetzung und Abnahme teilweise offen -**Referenzen:** [Zielarchitektur](../ai/GNAI-003-INFRA_Architecture.md), [Zugriffskonzept](GNAI-004-SEC_Access-Control.md), [GUI-SOP](GNAI-006-SEC_VPN_Client-Management.md), [Implementation-Log](GNAI-006-SEC_VPN_Implementation-Log.md) +**Referenzen:** [Zielarchitektur](../ai/GNAI-004-INFRA_Architecture.md), [Zugriffskonzept](GNAI-005-SEC_Access-Control.md), [GUI-SOP](GNAI-007-SEC_VPN_Client-Management.md), [Implementation-Log](GNAI-007-SEC_VPN_Implementation-Log.md) ## Änderungsverlauf @@ -30,7 +30,7 @@ Das WireGuard-Gateway läuft bereits. Die nachfolgende Installation beschreibt s | NPM, CT 103 | `10.0.0.10`; TCP 80/443 öffentlich, TCP 81 administrativ | | WireGuard, CT 105 | `10.0.0.15/24`, Hostname `wireguard` | | KI-Server | `10.0.0.90`, Hostname `ghostnet-ki` | -| Statischer Server-/LXC-Adressbereich | bis `.99`; konkrete Belegung siehe GNAI-003 | +| Statischer Server-/LXC-Adressbereich | bis `.99`; konkrete Belegung siehe GNAI-004 | | DHCP-Clients | `10.0.0.100–10.0.0.200` | | VPN-Netz / Gateway | `10.8.0.0/24` / `10.8.0.1` | | WireGuard-Port | UDP 51820 | @@ -113,7 +113,7 @@ sudo install -m 600 /dev/null /opt/wg-easy/environment Der letzte Befehl ist ausschließlich für eine **Neuinstallation**: ein vorhandenes Environment-File nicht überschreiben. Dokumentiert ist Podman 5.4.2. Die durch Debian bereitgestellte Version mit `podman --version` festhalten und Quadlet-Unterstützung prüfen. -Den Benutzer `admin` nur anlegen, wenn er noch nicht existiert. SSH-Key hinterlegen und Rechte testen. Für die SSH-Härtung die allgemeinen Prüfschritte aus [GNAI-002](GNAI-002-INFRA_Users.md) auf diesen LXC übertragen; dessen KI-Server-Konten und Netzwerte nicht übernehmen. Im bestehenden WireGuard-LXC ist `admin ALL=(ALL) NOPASSWD: ALL` eingerichtet; das ist der bestätigte Ist-Stand und keine allgemeine Vorgabe für alle LLM-Benutzer. Änderungen an SSH immer mit einer offenen zweiten Sitzung oder Proxmox-Konsole absichern. +Den Benutzer `admin` nur anlegen, wenn er noch nicht existiert. SSH-Key hinterlegen und Rechte testen. Für die SSH-Härtung die allgemeinen Prüfschritte aus [GNAI-003](GNAI-003-INFRA_Users.md) auf diesen LXC übertragen; dessen KI-Server-Konten und Netzwerte nicht übernehmen. Im bestehenden WireGuard-LXC ist `admin ALL=(ALL) NOPASSWD: ALL` eingerichtet; das ist der bestätigte Ist-Stand und keine allgemeine Vorgabe für alle LLM-Benutzer. Änderungen an SSH immer mit einer offenen zweiten Sitzung oder Proxmox-Konsole absichern. ### 3.3 IP-Forwarding @@ -142,7 +142,7 @@ Die VPN-Route entsteht erst mit dem Interface. Bei Neuinstallation vor dem erste ### 3.4 nftables-Baseline: Ist und erforderliche Erweiterung -Die Quellen dokumentieren folgende Baseline in `/etc/nftables.conf`. Ein lesender Live-Abgleich der entscheidenden INPUT- und FORWARD-Regeln am 18.09.2026 bestätigt weiterhin die breite VPN→LAN-Freigabe; das vollständige Regelwerk ist im [Implementation-Log](GNAI-006-SEC_VPN_Implementation-Log.md) nicht als neue Gesamtabnahme ausgewiesen: +Die Quellen dokumentieren folgende Baseline in `/etc/nftables.conf`. Ein lesender Live-Abgleich der entscheidenden INPUT- und FORWARD-Regeln am 18.09.2026 bestätigt weiterhin die breite VPN→LAN-Freigabe; das vollständige Regelwerk ist im [Implementation-Log](GNAI-007-SEC_VPN_Implementation-Log.md) nicht als neue Gesamtabnahme ausgewiesen: ```nft #!/usr/sbin/nft -f diff --git a/docs/platform/GNAI-006-SEC_VPN_Client-Management.md b/docs/platform/GNAI-007-SEC_VPN_Client-Management.md similarity index 97% rename from docs/platform/GNAI-006-SEC_VPN_Client-Management.md rename to docs/platform/GNAI-007-SEC_VPN_Client-Management.md index 8e86dd9..1c3363a 100644 --- a/docs/platform/GNAI-006-SEC_VPN_Client-Management.md +++ b/docs/platform/GNAI-007-SEC_VPN_Client-Management.md @@ -1,9 +1,9 @@ # Standard Operating Procedure -**Dokumenten-ID:** GNAI-006-SEC-SOP-01 +**Dokumenten-ID:** GNAI-007-SEC-SOP-01 **Titel:** Clients in der wg-easy-GUI einrichten und verwalten **Status:** Betriebsverfahren dokumentiert; Rollen-Firewall noch nicht umgesetzt oder abgenommen -**Referenzen:** [Gateway-Architektur](GNAI-006-SEC_VPN.md), [Rollenmodell](GNAI-004-SEC_Access-Control.md), [Windows](GNAI-006-SEC_VPN_Clients_Windows11.md), [Linux](GNAI-006-SEC_VPN_Clients_Linux.md) +**Referenzen:** [Gateway-Architektur](GNAI-007-SEC_VPN.md), [Rollenmodell](GNAI-005-SEC_Access-Control.md), [Windows](GNAI-007-SEC_VPN_Clients_Windows11.md), [Linux](GNAI-007-SEC_VPN_Clients_Linux.md) ## Änderungsverlauf diff --git a/docs/platform/GNAI-006-SEC_VPN_Clients_Linux.md b/docs/platform/GNAI-007-SEC_VPN_Clients_Linux.md similarity index 98% rename from docs/platform/GNAI-006-SEC_VPN_Clients_Linux.md rename to docs/platform/GNAI-007-SEC_VPN_Clients_Linux.md index a59f4b5..332c8a8 100644 --- a/docs/platform/GNAI-006-SEC_VPN_Clients_Linux.md +++ b/docs/platform/GNAI-007-SEC_VPN_Clients_Linux.md @@ -1,9 +1,9 @@ # SOP – WireGuard unter Linux einrichten und verwenden -**Dokumenten-ID:** GNAI-006-SEC-SOP-03 +**Dokumenten-ID:** GNAI-007-SEC-SOP-03 **Plattformen:** Debian, Arch/CachyOS und Fedora; Fedora Kinoite gesondert berücksichtigt **Status:** Anleitung bereinigt; bisheriger CachyOS-CLI-Test teilweise bestanden, übrige Varianten nicht abgenommen -**Referenzen:** [Gateway](GNAI-006-SEC_VPN.md), [Profilverwaltung](GNAI-006-SEC_VPN_Client-Management.md) +**Referenzen:** [Gateway](GNAI-007-SEC_VPN.md), [Profilverwaltung](GNAI-007-SEC_VPN_Client-Management.md) ## Änderungsverlauf diff --git a/docs/platform/GNAI-006-SEC_VPN_Clients_Windows11.md b/docs/platform/GNAI-007-SEC_VPN_Clients_Windows11.md similarity index 97% rename from docs/platform/GNAI-006-SEC_VPN_Clients_Windows11.md rename to docs/platform/GNAI-007-SEC_VPN_Clients_Windows11.md index 24e617a..c8bc679 100644 --- a/docs/platform/GNAI-006-SEC_VPN_Clients_Windows11.md +++ b/docs/platform/GNAI-007-SEC_VPN_Clients_Windows11.md @@ -1,8 +1,8 @@ # SOP – WireGuard unter Windows 11 einrichten und verwenden -**Dokumenten-ID:** GNAI-006-SEC-SOP-02 +**Dokumenten-ID:** GNAI-007-SEC-SOP-02 **Status:** Anleitung bereinigt; Windows-Praxistest noch offen -**Referenzen:** [Gateway](GNAI-006-SEC_VPN.md), [Profilverwaltung für Administratoren](GNAI-006-SEC_VPN_Client-Management.md) +**Referenzen:** [Gateway](GNAI-007-SEC_VPN.md), [Profilverwaltung für Administratoren](GNAI-007-SEC_VPN_Client-Management.md) ## Änderungsverlauf diff --git a/docs/platform/GNAI-006-SEC_VPN_Implementation-Log.md b/docs/platform/GNAI-007-SEC_VPN_Implementation-Log.md similarity index 95% rename from docs/platform/GNAI-006-SEC_VPN_Implementation-Log.md rename to docs/platform/GNAI-007-SEC_VPN_Implementation-Log.md index a4e3d1b..ebffa5c 100644 --- a/docs/platform/GNAI-006-SEC_VPN_Implementation-Log.md +++ b/docs/platform/GNAI-007-SEC_VPN_Implementation-Log.md @@ -1,7 +1,7 @@ -# GNAI-006-SEC – Implementation-Log +# GNAI-007-SEC – Implementation-Log -**Dokumenten-ID:** GNAI-006-SEC-SOP-04 -**Bezug:** [Gateway-Architektur](GNAI-006-SEC_VPN.md) +**Dokumenten-ID:** GNAI-007-SEC-SOP-04 +**Bezug:** [Gateway-Architektur](GNAI-007-SEC_VPN.md) **Zweck:** Historische Umsetzung, Korrekturen an früheren Befunden und noch offene Abnahmen nachvollziehbar halten. ## Änderungsverlauf @@ -50,7 +50,12 @@ Der aktuelle Quadlet-Pin `15.4.0` ist durch den Betreiber bestätigt. v15 verwen | Laptop-FullAdmin | `10.8.0.2` | 1 | neue Rolle Familie oder Server Admin noch ausdrücklich zuordnen | | Android-LLMAdmin | `10.8.0.3` | 2 | Altbestand; Android außerhalb des neuen SOP-Umfangs, keine Praxisabnahme | -Profile wurden laut Log manuell aus der SQLite-Datenbank generiert und gegen die Serverkonfiguration geprüft. Das ist ein historischer Vorgang, kein künftiges SOP-Verfahren. Neue Profile werden über die GUI exportiert. Der Pfad `docs/platform/GNAI-006-profiles/` wurde als gitignored genannt; Profile bleiben unabhängig von Git-Ausschlüssen Geheimnisse. +Profile wurden laut Log manuell aus der SQLite-Datenbank generiert und gegen +die Serverkonfiguration geprüft. Das ist ein historischer Vorgang, kein +künftiges SOP-Verfahren. Neue Profile werden über die GUI exportiert. Der Pfad +`docs/platform/GNAI-007-profiles/` wird inzwischen vollständig durch die +Repository-`.gitignore` ausgeschlossen; Profile bleiben unabhängig von +Git-Ausschlüssen Geheimnisse. Der Laptop wurde von außerhalb des Heimnetzes über EasyCable mit damaliger Außen-IPv4 `80.187.120.60` getestet. Diese und die damalige Heimnetz-WAN-IP sind zeitgebundene Messwerte, keine DNS-Sollwerte. diff --git a/docs/platform/README.md b/docs/platform/README.md index b9d05cb..0a45e46 100644 --- a/docs/platform/README.md +++ b/docs/platform/README.md @@ -7,15 +7,15 @@ Architektur und Nutzerverfahren liegen in den jeweiligen Nachbarverzeichnissen. | Dokument | Inhalt | | --- | --- | -| [GNAI-001](GNAI-001-INFRA_BaseSystem.md) | Hardware und Debian-Basisinstallation des KI-Servers | -| [GNAI-002](GNAI-002-INFRA_Users.md) | Hostbenutzer, Netzwerk, Resolver und SSH | -| [GNAI-004](GNAI-004-SEC_Access-Control.md) | Rollen- und Zugriffsziel für die Infrastruktur | -| [GNAI-005](GNAI-005-SEC_Reverse-Proxy.md) | Reverse Proxy, Keycloak-Adminpfad und Fail2Ban | -| [GNAI-006](GNAI-006-SEC_VPN.md) | WireGuard-Gateway und Rollen-Firewall | -| [VPN-Client-Verwaltung](GNAI-006-SEC_VPN_Client-Management.md) | Profile ausgeben, ändern und widerrufen | -| [Windows 11](GNAI-006-SEC_VPN_Clients_Windows11.md) | WireGuard-Client unter Windows 11 | -| [Linux](GNAI-006-SEC_VPN_Clients_Linux.md) | WireGuard-Client unter unterstützten Linux-Varianten | -| [VPN-Implementation-Log](GNAI-006-SEC_VPN_Implementation-Log.md) | historische Umsetzung, Tests und Evidenzkorrekturen | +| [GNAI-002](GNAI-002-INFRA_BaseSystem.md) | Hardware und Debian-Basisinstallation des KI-Servers | +| [GNAI-003](GNAI-003-INFRA_Users.md) | Hostbenutzer, Netzwerk, Resolver und SSH | +| [GNAI-005](GNAI-005-SEC_Access-Control.md) | Rollen- und Zugriffsziel für die Infrastruktur | +| [GNAI-006](GNAI-006-SEC_Reverse-Proxy.md) | Reverse Proxy, Keycloak-Adminpfad und Fail2Ban | +| [GNAI-007](GNAI-007-SEC_VPN.md) | WireGuard-Gateway und Rollen-Firewall | +| [VPN-Client-Verwaltung](GNAI-007-SEC_VPN_Client-Management.md) | Profile ausgeben, ändern und widerrufen | +| [Windows 11](GNAI-007-SEC_VPN_Clients_Windows11.md) | WireGuard-Client unter Windows 11 | +| [Linux](GNAI-007-SEC_VPN_Clients_Linux.md) | WireGuard-Client unter unterstützten Linux-Varianten | +| [VPN-Implementation-Log](GNAI-007-SEC_VPN_Implementation-Log.md) | historische Umsetzung, Tests und Evidenzkorrekturen | Der übergreifende Projektstand steht im [zentralen Dokumentationsindex](../GNAI-000-DOC_Index.md).