Die Architektur der KI-Integration in openEduSuite
KI ist in openEduSuite kein Zusatzprodukt, sondern eine weitere Klasse von Diensten, die denselben Regeln folgt wie jedes andere Mitglied der Suite: gleiche Identitätsquelle, gleiche Deployment-Mechanik, gleiche Betriebsdisziplin. Dieser Beitrag zeigt, wie die KI-Integration tatsächlich gebaut ist — Schichtenmodell, SSO für n8n, Dify und Open WebUI, der geplante agentic AI Spine, Datenhaltung und Betrieb — und wo die Grenze zwischen produktiver Realität und Entwurf verläuft.
Die Leitidee: KI als Schicht, nicht als Monolith
Die Architektur folgt einem dreistufigen Modell, das auch für die KI-Dienste nicht durchbrochen wird.
Plattform. Keycloak ist die einzige Identitätsquelle (id.example.edu, Realm opendesk). Auch jeder KI-Dienst hängt am selben IdP — keine zweite Benutzerverwaltung, keine Admin-Konten auf Zuruf.
KI-Dienste als eigenständige, isolierte Dienste. Statt eines KI-Monolithen betreibt die Suite getrennte Systeme mit klaren Zuständigkeiten:
- n8n (
k8s/openedusuite/deploy-n8n.yaml) ist die Automatisierungs- und Orchestrierungsebene: ein Pod mit eigenem Persistent Volume (n8n-data, 5 Gi auf Ceph-RBD) und einem nix-gebauten Image aus der Projekt-Registry (openedusuite-nix/n8n, n8n 2.39.6, gestartet über eine Supervisord-Konfiguration im Git-Manifest). - Dify ist ein separater App-Builder für KI-Anwendungen: API, Web, Worker und ein vorgelagerter nginx-Router (
deploy-dify-api.yaml,deploy-dify-web.yaml,deploy-dify-worker.yaml,deploy-dify-nginx.yaml, Version 1.17.0). Dify bringt seine Datenhaltung selbst mit: eine eigene PostgreSQL (deploy-dify-postgres.yaml), einen eigenen Vektorspeicher Weaviate (deploy-dify-weaviate.yaml) und einen eigenen Plugin-Daemon (deploy-dify-plugin-daemon.yaml); ein gemeinsamer Cluster-Redis dient nur als Cache und Broker. - Open WebUI ist das Chat-Frontend (
nix/k8s/open-webui.nix, Helmfile-Deployment unterai.example.edu); die Modelle laufen lokal (Ollama), Prompts verlassen das Rechenzentrum nicht. Für Hochschulen, die an Datenschutz und institutionelle Vertraulichkeit gebunden sind, ist lokale Inferenz nicht Bequemlichkeit, sondern Voraussetzung dafür, KI überhaupt anbieten zu können.
Service-Layer. Zwischen KI-Diensten und den Anwendungen der Suite sitzt der intercom-service (k8s/openedusuite/deploy-intercom-service.yaml): ein OIDC-basierter Broker für Dienst-zu-Dienst-Kommunikation mit stillem Einloggen zwischen Anwendungen und Kontext-Übergabe. Im Manifest sind die angeschlossenen Systeme als Konnektoren sichtbar (OpenCloud, SOGo, Nextcloud, Matrix, ILIAS); der Pod ist hart gehärtet: non-root, seccomp, read-only root filesystem.
SSO als Fundament: ein Tor, zwei Muster
Das Prinzip: Jeder KI-Dienst steht hinter derselben Keycloak-Pforte; die Gate-Mechanik richtet sich nach dem, was der jeweilige Dienst selbst kann. Die Suite kennt zwei Muster.
Gate-only mit oauth2-proxy für Dienste, die Identität über HTTP-Header konsumieren können. Dify steht hinter einer eigenen oauth2-proxy-Instanz (deploy-oauth2-proxy-dify.yaml, Client dify, Callback dify.example.edu/oauth2/callback, Upstream dify-nginx). Der Proxy leitet unauthentifizierte Requests direkt an Keycloak weiter (mit --skip-provider-button ohne Zwischenklickseite); ausgenommen sind nur Health-Endpunkte (--skip-auth-regex=/health|/v1/.well-known). Dasselbe Muster schützt das LMS: deploy-oauth2-proxy-lms.yaml (Client lms) aktiviert --set-xauthrequest; ILIAS liest die injizierte Identität aus den X-Auth-Request-*-Headern. Einheitlich über alle Instanzen: ein Realm, ein Cookie pro Dienst, --backend-logout-url an den IdP für sauberes Abmelden.
SSO-Bridge statt Proxy-Login für n8n — hier weicht die KI-Integration am weitesten vom Standardmuster ab. n8n Community (der OSS-Build unter der Sustainable Use License) hat kein natives SSO: OIDC, LDAP und SAML existieren nur im .ee.-Enterprise-Code, den das Projekt weder ausliefern noch kompilieren will; ein n8n-Fork kommt nicht in Frage. Stattdessen betreibt openEduSuite eine eigene n8n-SSO-Bridge: ein Express-Service, der als Sidecar im selben Pod läuft (configmap-n8n-bridge.yaml, bridge.js, Port 8080; der n8n-Container bleibt unverändert auf 5678). Die Parameter - Issuer, Client-ID, Client-Secret, n8n-Owner-Credentials und ein HMAC-Geheimnis - kommen aus dem Secret n8n-sso (secret-n8n-sso.yaml, provisioniert durch scripts/setup-n8n-secrets.sh).
Der Ablauf ist der Kern des Designs: Der Nutzer läuft bei n8n.example.edu/ auf die Bridge, wird zu Keycloak weitergeleitet und kehrt über /sso/callback zurück. Die Bridge tauscht den Code gegen Token, loggt sich als n8n-Owner über die n8n-REST-API ein, sucht den zum OIDC-email passenden n8n-Nutzer und legt ihn bei Bedarf per Einladung an. Dann loggt sie sich als genau dieser Nutzer ein und übergibt dessen Session-Cookie an den Browser. Passwörter werden nicht gespeichert: aus sub und email wird per HMAC ein deterministisches Passwort abgeleitet. Jeder Keycloak-Nutzer bekommt damit seinen eigenen n8n-Account mit eigenem Workspace (Rolle global:member) — kein geteiltes Admin-Konto, und über die Bridge kann niemand zum n8n-Owner eskalieren.
Warum reicht der Proxy nicht? Ein oauth2-proxy würde die Session zwar vor n8n herstellen, aber n8n selbst bliebe ohne echte Nutzerzuordnung — die Bridge übersetzt die Keycloak-Identität in ein echtes „als genau dieser Nutzer in n8n" mit persönlichen Workflows und eigenen Credentials. Dass SSO an unveränderten Fremdkomponenten tückisch ist, dokumentiert die OpenCloud-OIDC-War-Story dieses Blogs; die Bridge ist deshalb mit Unit-Tests abgesichert (bridge.test.js).
Der agentic AI Spine: Orchestrierung mit verifizierbaren Verträgen
Der nächste Schritt — eigenständige Agenten, die im Auftrag von Menschen über Dienst-APIs arbeiten — ist als Design und Implementierungsplan vollständig dokumentiert, aber noch nicht produktiv: docs/superpowers/specs/2026-10-13-agentic-ai-spine-design.md (Status: Entwurf) und docs/superpowers/plans/2026-10-13-agentic-ai-spine.md beschreiben die Referenz-Saga S13 „Agentische KI".
Die zentrale These der Spine: eine Invariante, zwei Exekutoren. Jeder Agenten-Vertrag trägt zwei Proben: eine env-Probe, die ein Bau- oder Verifikationsagent gegen die Infrastruktur ausführt, und — wo agentisch — eine act-Probe, die der In-Suite-Agent unter eigener Service-Identität zur Laufzeit beweist. Beide prüfen dieselbe Assertion; ein Vertrag gilt erst, wenn beide Welten ihn belegen. Quelle der Wahrheit ist ein Register (docs/requirements/contracts/s13.json), ausgeführt durch einen Runner (scripts/contract-check.mjs), gerendert in die Spez-Pyramide und durch ein Trace-Gate in der CI abgesichert.
Orchestrierungs-Ebene ist ausdrücklich n8n — es existiert bereits und ist SSO-grün. Für den ersten Nutzen-Loop, den Flagship-Formular-Agenten (Grist-Formular → Validierung → RT-Ticket → Matrix-Benachrichtigung → Mail-Bestätigung), kann ein kleines, dependency-freies Script im Trockenmodus starten. Governance steht im Mittelpunkt der Spez: Agenten laufen unter Keycloak-Service-Accounts (agent-*, client_credentials, nicht interaktiv, rotierbare Secrets), bekommen pro Dienst nur Eigen-API-Zugänge (Grist, RT, Mail, Matrix), keine Admin-Rechte und keine Menschen-Impersonierung; Idempotenz wird über die Formular-UUID erzwungen, jede Handlung auditierbar, mit Kill-Switch und ohne hartverdrahtete Credentials.
Daten und Memory: RAG, Vektorspeicher, differenzierte Haltung
RAG ist kein Entwurf, sondern in Dify konfiguriert: Das Manifest configmap-dify.yaml setzt VECTOR_STORE=weaviate und WEAVIATE_ENDPOINT auf den eigenen Weaviate-Dienst (dify-weaviate, semitechnologies/weaviate 1.26.6 mit eigener PVC). Dokumentenbasiertes Fragen bleibt damit vollständig in der Suite: Retrieval über den eigenen Vektorspeicher, Generierung über lokale Modelle.
Dify nutzt zudem eine Zwei-Prozess-Architektur: getrennte Worker für asynchrone Aufgaben (deploy-dify-worker.yaml), ein Plugin-Daemon (deploy-dify-plugin-daemon.yaml, Version 0.6.10) mit eigener Plugin-Datenbank (dify_plugin), eigenem API-Key und eigenem persistenten Plugin-Speicher. Plugins laufen damit isoliert vom Kern-API.
Datenhaltung differenziert. Jeder Dienst besitzt seine eigene Datenbank beziehungsweise sein eigenes Volume — die Dify-PostgreSQL ist von der Kern-Datenbank getrennt, n8n und Weaviate haben eigene Volumes, der gemeinsame Redis dient nur als Cache mit getrennten Indizes. Das ist Betriebsdisziplin: Ein Dienst skaliert, patcht oder fällt aus, ohne einen anderen mitzureißen, und Backup- und Lösch-Kaskaden bleiben pro Dienst beherrschbar.
Betrieb: Nix, GitOps, Secrets-Skripte und Netzdisziplin
Der Betrieb der KI-Dienste unterscheidet sich nicht von dem der übrigen Suite.
Nix-gebaut und aus der eigenen Registry. Die Images entstehen in der Nix-Werkzeugkette (nix/images/, nix/k8s/n8n.nix, nix/k8s/open-webui.nix) und werden in die privat betriebene Container-Registry des Projekts gepusht; n8n und der intercom-service laufen als nix-gebaute Images. Reproduzierbare Builds, SBOMs und Signierung gehören zum Prozess (siehe Beitrag zum „Nix-Shift").
GitOps. Die Manifeste sind kanonisch in Git, ArgoCD wendet sie an (App openedusuite, selfHeal). Selbst der Bridge-Code lebt als ConfigMap im Git (configmap-n8n-bridge.yaml) — kein Ad-hoc-Skript auf einem Knoten.
Secrets nie in Git. Klienten-Secrets werden idempotent provisioniert: scripts/create-keycloak-clients-sso.sh legt die oauth2-proxy-Clients in Keycloak an und liest die Secrets zurück in Kubernetes-Secrets; scripts/setup-n8n-secrets.sh und scripts/setup-dify-secrets.sh erzeugen die nötigen Secrets (Passwörter per openssl rand generiert, nie gehardcodet); scripts/provision-dify.mjs seedet den ersten Dify-Admin, ohne ein Passwort im Code zu führen. Rotation heißt: Skript erneut ausführen, Pods neu starten.
Netz und Beobachtbarkeit. Jeder KI-Pod trägt Liveness- und Readiness-Probes (die Bridge unter /sso/health, Weaviate unter /v1/.well-known/live, Dify unter /health). NetworkPolicies setzen pro Namespace standardmäßig Deny-Ingress und erlauben nur den gleichen Namespace sowie den Ingress-Controller (k8s/network-policies/). Das Monitoring (k8s/monitoring/) umfasst Prometheus, Alert-Regeln und Grafana-Dashboards.
Ausblick: produktiv, Entwurf, offen
Was heute produktiv läuft: SSO-Basis mit Keycloak und einheitlichem Gate-Muster, n8n mit SSO-Bridge und Multi-User-Provisioning, Dify als eigenständiger App-Builder mit eigener Datenhaltung und RAG, Open WebUI mit lokalen Modellen sowie GitOps-, Secrets- und Betriebsinfrastruktur.
Was Entwurf und geplante Arbeit ist: Der agentic AI Spine ist dokumentiert und die Werkzeugkette (Register, Runner, Generator) als Plan konkretisiert, aber die DoD des Designs ist offen — Service-Accounts, Formular-Agent und die env/act-Proben sind noch nicht durchgängig grün. Der Formular-Agent ist der erste Nutzen-Loop, noch nicht produktiv; die Formular-Basis entsteht über die geplante Grist-Souverän-Formulare-Erweiterung.
Was offen bleibt: eine durchgängig konsistente „Agenten-Identität“ über alle Dienste hinweg. Jeder Dienst kennt heute seine eigene Session- und Identitätsmechanik - dieselbe Person handelt als Keycloak-Subject, als oauth2-proxy-Session, als n8n-Nutzer und künftig als Service-Account. Die Einheitlichkeit von Scopes, Audit und Rechten über diese Welten (SSO-Kohärenz) und die KI-Konnektivität weiterer Kollaborationsdienste wie der Dateischicht sind Arbeit, nicht Behauptung.
Fazit
Die KI-Integration in openEduSuite zeigt, dass Souveränität keine Frage einzelner Werkzeuge ist, sondern der Architektur: eine Identitätsquelle, isolierte Dienste mit eigener Datenhaltung, ein Service-Layer zwischen KI und Anwendungen, eine SSO-Bridge nur dort, wo der Dienst sie erfordert, und ein Betrieb, der Secrets, Netz und Konfiguration durch Git und Skripte beherrscht. Der agentic AI Spine zeigt den nächsten Schritt — ein Vertragssystem, das jede Agenten-Handlung beweisbar macht, bevor sie in Produktion geht.
Weiterführende Lektüre: Das Spine-Design und der Implementierungsplan unter docs/superpowers/, die Roadmap des Projekts, die War-Story zur OpenCloud-OIDC-Integration und der Nix-Shift-Beitrag.
KI-Dienste in openEduSuite folgen denselben Regeln wie jede andere Komponente der Suite. Quelle und Manifeste sind im öffentlichen Repository einsehbar.
