nexarch/SKALIERUNGSKONZEPT.md

NEXARCH 2.0 – Skalierungskonzept

Stand: 2026-08-26. Grundlage: nexarch-state.json (Techstack/Tenancy-Entscheidungen), core-kanban/, archive-kanban/, dms-kanban/, mail-kanban/ (Boards inzwischen aus dem Repo entfernt, Ticket-Historie liegt in der Gitea-PR-Historie).

1. Was schon skalierungsfähig entschieden ist

Baustein	Entscheidung	Warum das skaliert
Backend-Sprache	Go	Goroutinen billig, geringer RAM/Instanz, mehrere Prozesse pro Server möglich
Auth	JWT, zustandslos	Beliebig viele Backend-Instanzen ohne Sticky-Sessions möglich
Storage	S3-kompatible Abstraktion (FDN-03)	Objektspeicher skaliert unabhängig vom Backend, austauschbar (lokal → MinIO/S3)
Job-Queue	Postgres, FOR UPDATE SKIP LOCKED (FDN-04)	Bewusst für mehrere Worker-Prozesse ausgelegt, nicht nur In-Prozess
Rate-Limiting	Shared State statt in-process (Core API-03)	Korrigiert einen bei archivdms gefundenen Mehrinstanz-Bug (known-issues #9)

Das deckt: mehr Backend-Instanzen hinter einem Load Balancer und mehr Worker-Prozesse. Es deckt NICHT: Datenbank-Skalierung, Caching, Kapazitätsgrenzen, Suchindex-Skalierung. Diese vier Lücken sind Gegenstand dieses Dokuments.

2. Skalierungsachsen

NEXARCH muss in vier unabhängigen Dimensionen wachsen können, die sich nicht gleich verhalten:

1. Anzahl Tenants (Mandanten) — wächst mit Kundenzahl, meist viele kleine.
2. Datenvolumen pro Tenant (Dokumente, E-Mails, Anhänge) — wächst mit Nutzungsdauer, stark ungleich verteilt (ein Großkunde kann mehr Daten haben als 100 kleine zusammen).
3. Gleichzeitige Nutzer/Requests — Lastspitzen (z.B. Monatsabschluss, Rechnungslauf-Import).
4. Hintergrundlast (OCR, Indexierung, E-Mail-Abruf) — läuft unabhängig von Nutzeraktivität, oft nachts/batchartig.

Diese vier brauchen unterschiedliche Antworten — "mehr Server" allein löst nicht alle vier.

3. Betriebsstufen (an Master-Prompt orientiert)

Stufe 1 – Einzel-LXC (kleine/mittlere Installation)

Proxmox LXC
├── NEXARCH-Prozesse (Core/DMS/Mail/Archive/Workflow als ein oder mehrere Go-Binaries)
├── Worker (In-Prozess-Goroutinen)
├── PostgreSQL (lokal, eine Datenbank je Mandant plus schlanke Registry-DB — Modell C, siehe Abschnitt 4)
├── Manticore (lokal)
└── Objektspeicher (lokales Dateisystem oder ZFS)

Richtwert (grobe Schätzung, kein Lasttest): bis niedriger dreistelliger Tenant-Zahl bei üblicher KMU-Nutzung, solange kein Einzeltenant die Instanz dominiert. Grenze ist praktisch immer die Postgres-Instanz und die OCR/Indexierungslast, nicht der Go-Prozess selbst.

Stufe 2 – Verteilt (mittlere/große Installation)

├── NEXARCH-Application-Instanzen (mehrere, hinter Reverse Proxy/Load Balancer, zustandslos)
├── NEXARCH-Worker-Instanzen (mehrere, ziehen aus derselben Postgres-Jobqueue)
├── PostgreSQL (dediziert, Tenant-Datenbanken über mehrere Server verteilbar — siehe Abschnitt 4)
├── Manticore (dediziert, ggf. Cluster-Modus — siehe Abschnitt 5)
└── Objektspeicher (S3/MinIO/Ceph, nicht mehr lokales Dateisystem)

Übergang Stufe 1 → 2 ist ein reiner Infrastruktur-Schritt, kein Code-Umbau — das ist der Grund, warum JWT-Auth, Postgres-Jobqueue und S3-Abstraktion von Anfang an so gewählt wurden (Abschnitt 1).

Betriebs-Checkliste für diesen Wechsel: code/docs/BETRIEBS-CHECKLISTE-STUFENWECHSEL.md (Core OPS-07). Enthält u. a. die mTLS-Aktivierung zwischen Modul-Instanzen (Core API-09) als Pflichtschritt — für Stufe 1 ist mTLS bewusst optional, beim Wechsel auf verteilten Betrieb aber zwingend, sonst laufen Modul-zu-Modul-Aufrufe ohne Transport-Authentifizierung. Ein Readiness-Gate (internal/mtls.GateCheck + internal/health Warnungen) macht ein vergessenes mTLS bei mehr als einer Instanz/mehr als einem Host als Warnung im Monitoring sichtbar, statt es unbemerkt zu lassen.

Stufe 3 – Dedizierte Instanz pro Großkunde (Private Cloud, Betriebsmodell aus Master-Prompt)

Ein Tenant mit außergewöhnlichem Datenvolumen oder Compliance-Anforderung bekommt eine eigene Stufe-1- oder Stufe-2-Installation statt eines Platzes auf der gemeinsamen Infrastruktur. Das ist die Antwort auf "was, wenn ein Mandant zu groß für die gemeinsame Instanz wird" (im Modell C liegt er bereits in einer eigenen Datenbank, hier zusätzlich auf eigener Hardware) — ein Ausweich-Betriebsmodell, das ohnehin schon geplant ist.

4. Datenbank-Skalierung — jetzt strukturell durch Modell C gelöst

Geändert (siehe nexarch-state.json Entscheidungsverlauf): Multi-Tenancy ist nicht mehr Modell A (eine Postgres-Instanz, tenant_id-Spalte), sondern Modell C — eine Datenbank pro Mandant (Core TEN-01 Tenant-Registry & Datenbank-Provisioning). Grund: applikationsseitige Filterung verlässt sich darauf, dass jede Query korrekt gefiltert ist — ein einziger vergessener Filter (wie known-issues-archivmail.md #2/#7 real belegt) führt zum Cross-Tenant-Leck. Physische Trennung macht diese Fehlerklasse strukturell unmöglich, nicht nur unwahrscheinlicher. Nebeneffekt: eine Tenant-Datenbank lässt sich als Ganzes zwischen On-Premise und SaaS verschieben (Dump/Restore auf andere Infrastruktur), ohne Umbau an der Anwendung.

Das ändert die Skalierungsfrage von "eine Instanz größer machen" zu "viele kleine Instanzen gut verwalten":

Verbindungs-Pooling ist ab Tag 1 Pflicht, nicht erst ab Stufe 2. Mit vielen Tenant-Datenbanken stößt jede Anwendungsinstanz schnell an die maximale Postgres-Verbindungszahl, unabhängig von der eigentlichen Last. Core TEN-06 (Connection-Routing & Pooling pro Mandant) übernimmt das — PgBouncer-artiges Pooling oder ein LRU-verwalteter Verbindungspool, der Tenant-Verbindungen wiederverwendet statt dauerhaft offen zu halten.

Migrationen laufen gegen N Datenbanken, nicht gegen eine. Core TEN-07 (Migrations-Orchestrierung über alle Tenant-Datenbanken) rollt jede Schemaänderung automatisiert über alle Tenant-Datenbanken aus, mit Fehlerisolation je Mandant — ein inkompatibler Datenbestand bei einem Kunden darf das Ausrollen für alle anderen nicht blockieren.

Vertikale Skalierung bleibt der Standardfall pro Postgres-Server, der mehrere Tenant-Datenbanken hostet (Stufe 1: alle Tenant-DBs auf einer Instanz; Stufe 2/3: Tenant-Datenbanken auf mehrere Postgres-Server verteilt, siehe Abschnitt 3) — das ist kein Sharding-Zusatzaufwand mehr, sondern die natürliche Konsequenz von "jeder Mandant ist ohnehin schon eine eigene Datenbank".

Was dadurch entfällt: Die früher diskutierte Frage "Lesereplikate vs. RLS vs. Schema-pro-Tenant" stellt sich in dieser Form nicht mehr — RLS wäre bei physischer Trennung redundant (siehe Core TEN-01), und "Schema-pro-Tenant" (Modell B) ist mit Modell C bereits übertroffen (noch stärkere Isolation als ein gemeinsames Schema). Lesereplikate bleiben als Option pro einzelner Tenant-Datenbank sinnvoll, falls ein einzelner Großkunde das braucht — dann als individuelle Betriebsentscheidung für diese eine Datenbank, nicht als globale Architekturmaßnahme.

5. Suchindex-Skalierung

Manticore läuft in Stufe 1 lokal neben der Anwendung. In Stufe 2:

• Manticore auf eigene Instanz(en) ziehen, mehrere NEXARCH-Instanzen sprechen dasselbe Manticore an.
• Bei sehr großem Volumen: Manticore unterstützt Cluster-/Replikations-Modus — als Option dokumentieren, nicht in v1 vorwegnehmen (YAGNI, bis ein Tenant das tatsächlich braucht).
• Reindexierung (siehe MIGRATIONSKONZEPT.md Abschnitt 4) ist selbst ein Lastfall — sollte außerhalb von Nutzungsspitzen laufen, Job-Priorität in der Postgres-Jobqueue berücksichtigen.

6. Caching

Aktuell kein Caching-Layer vorgesehen — bewusste Lücke, nicht übersehen: Redis wurde für Queue/Rate-Limit explizit ausgeschlossen (Einfachheit, ein Betriebsteil weniger). Für Caching gilt dieselbe Grundhaltung, aber nicht dieselbe Antwort:

• Kein Cache für v1. Postgres mit vernünftigen Indizes trägt die erwartete Last in Stufe 1/2.
• Wenn nötig: In-Prozess-Cache (z.B. für Feature-Flags aus Core LIC-02, die sich selten ändern) statt eines externen Cache-Dienstes — passt zur "so wenig bewegliche Teile wie möglich"-Linie des Projekts.
• Erst bei nachgewiesenem Bedarf einen externen Cache (Redis oder Postgres-UNLOGGED-Tabelle als Kompromiss) einführen, nicht vorab.

7. Hintergrundlast (OCR, Indexierung, E-Mail-Abruf)

Das ist die Last, die am wenigsten mit Nutzeraktivität korreliert und am leichtesten "einen Tenant die anderen ausbremsen lässt". Bereits im Datenmodell bedacht: die Postgres-Jobqueue aus archivdms (Vorbild für FDN-04) hat Round-Robin-Fairness pro Mandant eingebaut, genau um das zu verhindern — das ist eine reale Lehre aus dem Altsystem und sollte 1:1 in FDN-04 übernommen werden (ist es laut Ticket-Text bereits).

Für Stufe 2/3 zusätzlich:

• Worker-Anzahl je Job-Typ getrennt konfigurierbar (OCR-Worker ≠ Indexierungs-Worker ≠ Mail-Abruf-Worker), damit ein Engpass in einem Typ nicht die anderen blockiert.
• Quotas (Core LIC-03 Nutzungszähler) auch als Drosselungsmechanismus nutzen: ein Tenant mit ungewöhnlich hohem Job-Aufkommen bekommt eine Obergrenze, keinen unbegrenzten Vorrang.

8. Kapazitätsgrenzen — was bisher fehlt

Es gibt aktuell keine dokumentierten Richtwerte, ab wann Stufe 1 verlassen werden muss. Vorschlag, sobald erste Testinstallation läuft, folgende Kennzahlen zu erheben und hier nachzutragen:

• Dokumente/E-Mails gesamt, ab denen Postgres-Query-Latenz spürbar steigt (typischer Auslöser: fehlende/veraltete Indizes eher als reines Volumen).
• Gleichzeitige aktive Tenants, ab denen die In-Prozess-Job-Fairness (Abschnitt 7) nicht mehr ausreicht.
• OCR-Durchsatz (Seiten/Minute) je Worker, um Personal-/Kapazitätsplanung für Kunden mit hohem Scan-Aufkommen zu ermöglichen.

Diese Zahlen sind aus der Architektur allein nicht seriös vorhersagbar — sie brauchen einen Lasttest (siehe DMS-Board QA-10 Last- & Leistungstest, Mail-Board QA-07) und sollten aus dessen Ergebnis hierher zurückgeschrieben werden.

9. Monitoring-Kopplung

Skalierungsentscheidungen brauchen Messwerte, keine Vermutungen. Vorhandene Anknüpfungspunkte:

• Core OPS-01 Health-Checks je Modul, OPS-03 Metrics-Aggregation über Module hinweg — sollte Postgres-Connection-Auslastung, Job-Queue-Länge je Tenant und Manticore-Latenz mit aufnehmen, nicht nur Modul-Health.
• grafana-expert/prometheus-expert-Subagenten (siehe .claude/agents/) stehen für die konkrete Umsetzung bereit.

10. Core selbst hochverfügbar machen (Primary/Replica-Failover)

Abschnitt 11 beschreibt, wie die ANDEREN Module einen Core-Ausfall überstehen. Dieser Abschnitt beschreibt, wie Core selbst seltener ausfällt.

Core-Anwendungsprozesse sind bereits zustandslos (Abschnitt 1) — das löst die Anwendungsschicht: mehrere Core-Instanzen hinter einem Load Balancer, jede darf jederzeit neu starten oder wegfallen, ohne dass Sessions verloren gehen. Der eigentliche Single Point of Failure ist die Postgres-Instanz, auf der Core (wie alle Module) aufsetzt.

Stufe 1 – Einzel-LXC: kein automatisches Failover

Für kleine Installationen ist automatisches DB-Failover unverhältnismäßiger Aufwand. Antwort auf Ausfall ist Restore aus Backup (Archive-Board BAK-03 Restore-Verfahren), keine Live-Umschaltung. Akzeptierter Trade-off, konsistent mit der "keine unnötige Komplexität"-Linie des Projekts.

Stufe 2/3 – Primary/Replica mit automatischem Failover

Sobald Verfügbarkeit über reinem Backup/Restore hinaus gefordert ist:

1. Postgres-Streaming-Replikation: ein Primary (Schreibziel), ein oder mehrere Replicas (physische Streaming-Replikation, nicht nur die logischen Read-Replicas aus Abschnitt 4 — hier geht es um Ausfallsicherheit, dort um Leselast-Verteilung; dieselbe Replica-Infrastruktur kann beides gleichzeitig bedienen).
2. Automatisches Failover braucht einen Konsens-Mechanismus, nicht nur Replikation allein — sonst entscheidet im Zweifel niemand zuverlässig, wer nach einem Ausfall der neue Primary ist (Split-Brain-Risiko: zwei Knoten halten sich beide für Primary). Etablierter Ansatz: Patroni (nutzt etcd/Consul als verteilten Konsens-Store) oder das leichtgewichtigere pg_auto_failover (kommt ohne separaten Konsens-Store aus, dafür geringere Ausfalltoleranz bei komplexeren Szenarien). Für den Proxmox-LXC-Kontext des Projekts ist pg_auto_failover der pragmatischere Einstieg — Patroni erst, wenn Stufe 3 mit mehreren Standorten ansteht.
3. Verbindungsindirektion: Core-Anwendungsinstanzen dürfen nicht die IP des Primary fest codieren — sonst bringt Failover nichts, weil alle Clients weiter den toten Knoten ansprechen. Lösung: PgBouncer/HAProxy mit Healthcheck auf den aktuellen Primary, oder eine virtuelle IP, die dem Failover-Mechanismus folgt. Das ist derselbe PgBouncer-Baustein wie in Abschnitt 4 Stufe C (Connection-Pooling) — ein Werkzeug, zwei Zwecke.
4. Fencing: der alte Primary muss nach einem Failover zuverlässig daran gehindert werden, weiter Schreibzugriffe anzunehmen (sonst Split-Brain trotz Konsens-Mechanismus, z.B. bei Netzwerkpartitionierung). Patroni/pg_auto_failover übernehmen das, ist aber ein Punkt, der beim Aufsetzen bewusst getestet werden muss (simulierte Netzwerktrennung im Rahmen von DMS QA-10/Mail QA-07-artigen Lasttests), nicht nur beim Konfigurieren angenommen werden darf.

Was NICHT dupliziert werden muss

Der JWKS-Mechanismus aus Abschnitt 11/API-05 (öffentlicher Schlüssel wird von anderen Modulen gecacht) bleibt unabhängig von einem laufenden DB-Failover funktionsfähig — Signaturprüfung anderer Module braucht während eines kurzen Failover-Fensters keine Core-DB-Verbindung. Das war kein bewusst für HA gedachtes Feature, ergibt sich aber als Nebeneffekt der API-05-Entscheidung: Core-DB-Failover und Core-Anwendungs-Resilienz für andere Module sind zwei getrennte Probleme, die sich gegenseitig entlasten, statt sich zu addieren.

Storage- und Manticore-Redundanz

Objektspeicher (S3-kompatibel) und Manticore-Suchindex haben ihre eigenen, produktüblichen Redundanzmechanismen (S3: providerseitig oder MinIO-Distributed-Mode; Manticore: Replikations-/Cluster-Modus, siehe Abschnitt 5) — kein Bezug zur Postgres-Failover-Frage, aber Teil desselben Gesamtbilds "was darf nicht Single Point of Failure sein", falls eine vollständige HA-Betrachtung für Stufe 3 gemacht wird.

11. Resilienz bei Core-Ausfall

Core ist Fundament (Auth, Rechte, Feature-Flags, Audit, Benachrichtigungen) — das darf nicht bedeuten, dass ein Core-Ausfall die ganze Plattform lahmlegt. Entscheidung: lokale JWT-Verifikation + kurzlebiger Rechte-/Feature-Flag-Cache statt synchroner Rückfrage bei Core pro Request (Core-Board-Ticket API-05).

• DMS/Mail/Archive/Workflow prüfen JWT-Signatur lokal (Core-Public-Key verteilt über JWKS-ähnlichen Mechanismus), kein Request an Core pro Aufruf.
• Rechte/Feature-Flags werden mit kurzer TTL gecacht. Fällt Core aus: laufender Betrieb funktioniert mit letztbekanntem Stand weiter, nur neue Logins und frische Rechteänderungen sind betroffen — kein Komplettausfall der anderen Module.
• Fail-open vs. fail-closed muss pro Aktionsklasse entschieden werden (Teil von API-05): Lesevorgänge mit abgelaufenem Cache eher fail-open (letzter bekannter Stand gilt weiter), sicherheitskritische Aktionen (Rechteänderung, Löschung, Freigabe) eher fail-closed (lieber verweigern als mit veralteten Rechten ausführen).
• Schlüsselrotation für den Core-Public-Key muss ohne Ausfallzeit der anderen Module möglich sein — sonst wird die Resilienzmaßnahme selbst zum Wartungsrisiko.

Diese Entscheidung ist eine direkte Folge der bereits getroffenen JWT-Wahl (Abschnitt 1) — zustandslose Tokens waren dafür gedacht, wurden aber bis zu diesem Punkt nicht konsequent zu Ende gedacht (jedes Modul hätte genauso gut synchron gegen Core validieren können, was den Vorteil zunichtegemacht hätte).

12. Zusammenfassung: was zu tun bleibt

Lücke	Vorschlag	Wo einzuordnen
Read-Replica-Trennung im Code	Query-Routing lesend/schreibend als eigenes Ticket	Core API- oder OPS-Epic (neu)
Connection-Pooling (PgBouncer)	Betriebsempfehlung ab Stufe 2	Core FDN/Deployment-Doku
Kapazitätsrichtwerte	Aus Lasttest ableiten, hier nachtragen	nach DMS QA-10 / Mail QA-07
Manticore-Cluster-Modus	Nur bei nachgewiesenem Bedarf, nicht v1	zukünftiges Ticket, kein Blocker
Cache-Layer	Nur bei nachgewiesenem Bedarf, In-Prozess vor extern	zukünftiges Ticket, kein Blocker

Kein neuer Techstack-Entscheid nötig — das Konzept baut ausschließlich auf bereits getroffenen Entscheidungen (Go, Postgres, S3, Manticore, Modell C) auf und beschreibt deren Wachstumspfad, statt sie zu ändern.