Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

basebox-Komponenten

Gilt für

Produkt: Server (Cloud zum Verständnis) · Zielgruppe: Platform Operator

Die Dienste, aus denen eine basebox-Installation besteht – Frontend, AISRV, storesrv, ragsrv und ragsrv-support, Identitätsanbieter, Datenbanken, Inferenz, Konnektoren –, was jeder tut, zu welcher Schicht er gehört und wie sie miteinander kommunizieren. Das Umbrella-Chart basebox.ai stellt sie gemeinsam bereit.

Komponentenkarte

flowchart TB
  U["Nutzer / API-Clients"] -->|HTTPS| ING["Ingress / TLS"]
  ING --> FE["frontend<br/>Vue 3 · :3000"]
  ING --> AISRV["AISRV<br/>GraphQL · REST · OpenAI-API · MCP-Gateway · :8888"]
  ING --> IDP["idp (Keycloak)<br/>OIDC · /auth · :8080"]
  FE -->|GraphQL| AISRV
  FE -->|OIDC| IDP
  AISRV -->|Token-Prüfung| IDP
  AISRV --> STORE["storesrv<br/>GraphQL · :8889"]
  AISRV -->|RAG-API| RAG["ragsrv<br/>Vektor-DB · :3001"]
  RAG --> RAGS["ragsrv-support<br/>Extraktion · OCR · Embeddings · STT · :8000"]
  AISRV -->|OpenAI-kompatibel| INF["inference<br/>vLLM · :8000"]
  AISRV -->|POST /mcp| MCP["MCP-Konnektoren<br/>mcp-&lt;name&gt;"]
  MCP --> EXT["Zielsysteme · Suchanbieter"]
  AISRV --- DB1[("aisrv-db")]
  STORE --- DB2[("storesrv-db")]
  RAG --- DB3[("ragsrv-db<br/>pgvector")]
  IDP --- DB4[("idp-db")]
  CNPG["CloudNativePG-Operator"] -.-> DB1 & DB2 & DB3 & DB4
  style FE fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style AISRV fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style STORE fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style IDP fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style RAG fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c
  style RAGS fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c
  style INF fill:#dbeafe,stroke:#1e40af,color:#1d1e1c

Beige = basebox-Plattform · Grün = Service-Modelle · Blau = Inferenz. Die Schichten erklärt Architektur verstehen.

Die Dienste

Dienst	Schicht	Aufgabe	Port	Abhängigkeiten	Referenz
frontend	Plattform	Vue-3-Single-Page-Application; spricht GraphQL mit AISRV, OIDC mit Keycloak	3000	AISRV, IDP	Frontend
AISRV	Plattform	Anwendungsserver: Chat-Orchestrierung, Apps, Benutzer/Organisationen, GraphQL-API, REST- und OpenAI-kompatible API, MCP-Gateway, Audit-Log, SMTP, Medien	8888	aisrv-db, IDP, inference, ragsrv, storesrv	AISRV
storesrv	Plattform	Speicherdienst (GraphQL) für Persistenz	8889	storesrv-db, IDP	Storesrv
idp (Keycloak)	Plattform	Identitätsanbieter: Realms, Benutzer, OIDC-Tokens, LDAP-Federation, Identity Brokering	8080	idp-db	IDP (Keycloak)
ragsrv	Service-Modelle	RAG-Server: Dokumentaufnahme, Chunking, Embeddings, semantische Suche; PostgreSQL mit pgvector	3001	ragsrv-db, ragsrv-support, GPU (oder CPU-Modus)	Ragsrv
ragsrv-support	Service-Modelle	Modelldienst für Dokumentextraktion, OCR, Embeddings, Sprache-zu-Text	8000	GPU (oder CPU-Modus)	Ragsrv-Support
inference	Inferenz	Gebündelter LLM-Inferenzserver (vLLM), OpenAI-kompatible API	8000	GPU	Inference Server
MCP-Konnektoren	Plattform (optional)	Je Konnektor ein Deployment + Service `mcp-<name>`; erreichen genau ihr Zielsystem	je Konnektor	AISRV	MCP-Konnektoren mit Helm
CloudNativePG-Operator	Plattform	Verwaltet die PostgreSQL-Cluster `aisrv-db`, `storesrv-db`, `ragsrv-db`, `idp-db` (Image `postgresql:16-standard-bookworm`)	–	Storage Class	Helm-Chart-Übersicht
Ingress / TLS	Plattform	Eingangspunkt; Pfade `/`, `/graphql`, `/rest`, `/subscriptions`, `/media`, `/auth`, `/v1`	443	Ingress-Controller, Zertifikat	Helm Charts verwenden

Kommunikationspfade

Von → Nach	Protokoll	Wozu
Browser → frontend, AISRV, idp	HTTPS über Ingress	Oberfläche, GraphQL/Subscriptions, Login
API-Client → AISRV	HTTPS `/v1/…`, `/rest/…`	OpenAI-kompatible und REST-API
frontend → idp	OIDC	Anmeldung, Tokens (`VITE_BB_OIDC_DOMAIN`, endet mit `/auth/realms/`)
AISRV → idp	HTTP intern (`AISRV_OIDC_IDP_URL`)	Token-Validierung, Benutzersynchronisation
AISRV → inference	OpenAI-kompatible API (`AISRV_LLM_URL`, API-Schlüssel)	Chat Completions; alternativ externer Endpunkt
AISRV → ragsrv	RAG-API (`AISRV_RAG_URL`, `X-API-KEY`)	Wissensbasen, Retrieval
ragsrv → ragsrv-support	HTTP (`SUPPORT_SERVICE_URL`, gemeinsamer `API_KEY`)	Extraktion, OCR, Embeddings, STT
ragsrv → AISRV	Webhook (`WEBHOOK_STATE_URL`)	Verarbeitungsstatus von Dateien
AISRV → storesrv	GraphQL (`AISRV_STORE_URL`)	Persistenz
AISRV → MCP-Konnektor	`POST /mcp` mit `Authorization` des Nutzers	Werkzeugaufrufe
MCP-Konnektor → Zielsystem	systemspezifisch, nur erlaubte Hosts	Wiki, Tickets, IMAP, Suchanbieter
AISRV → SMTP	STARTTLS/TLS	Einladungen, Benachrichtigungen
Dienste → PostgreSQL	TCP 5432 (`*-db-rw`)	Zustand

Nutzer und Browser sprechen nie direkt mit inference, ragsrv oder den Konnektoren – nur über AISRV.

Was wo gespeichert wird

Daten	Ort
Benutzer, Organisationen, Apps, Einstellungen, Audit-Log, Konnektor-Zugangsdaten (nur schreibend)	`aisrv-db`
Persistenz des Store-Servers	`storesrv-db`
Dokumentabschnitte und Embeddings der Wissensbasen	`ragsrv-db` (pgvector)
Identitäten, Realms, Clients	`idp-db`
Hochgeladene Dateien / Medien	`AISRV_MEDIA_ROOT` (persistentes Volume) und temporär `/tmp/ragsrv`
Modellgewichte und Caches	Volumes von inference (`/data/.cache/huggingface`) und ragsrv-support (`/models`) – neu erzeugbar
Geheimnisse	Kubernetes-Secrets (`aisrv-database`, `keycloak-admin-secret`, `basebox-admin-secret`, …)

Details für Backup und Sicherheit: Backup & Wiederherstellung · Speicher (Sicherheit).

Ressourcenprofil je Komponente

GPU: nur inference, ragsrv und ragsrv-support (letztere auch im CPU-Modus betreibbar).
CPU/RAM-lastig: AISRV, Keycloak, PostgreSQL-Cluster.
Leicht: frontend, storesrv, MCP-Konnektoren.

Richtwerte des Charts: minimal 5+ Kerne, 12 GB+ RAM, 1+ GPU, 200 GB+ Speicher; empfohlen 10+ Kerne, 32 GB+ RAM, 2+ GPUs, 500 GB+ SSD/NVMe – siehe Helm-Chart-Übersicht. Was mit Nutzern, Dokumenten und Modellgröße wächst: Ressourcen & Skalierung.

Nächster Schritt: Helm-Chart-Übersicht