nexarch/STORAGE-KONZEPT.md

# NEXARCH 2.0 – Storage-Konzept

Stand: 2026-08-26, Abschnitt 9 aktualisiert + Abschnitt 10 neu (Arbeitsverzeichnisse) 2026-08-28. Grundlage: `dms-kanban/tickets/FDN-03.md`, `mail-kanban/tickets/ARC-01.md`, `archive-kanban/tickets/RET-*.md`, `archive-kanban/tickets/BAK-*.md`, `SKALIERUNGSKONZEPT.md` (Kanban-Boards inzwischen aus dem Repo entfernt, Ticket-Historie liegt in der Gitea-PR-Historie).

## 1. Grundprinzip

Strikte Trennung, bereits in FDN-03 (DMS) und ARC-01 (Mail) unabhängig, aber konsistent so entschieden:

- **PostgreSQL**: ausschließlich Metadaten (wer, was, wann, Tenant, Beziehungen, Status, Fristen).
- **Objekt-Storage**: ausschließlich Binärinhalte (Dokumente, E-Mails, Anhänge, Thumbnails, Backups).

Kein Binärinhalt landet je in einer Datenbankspalte (kein `bytea` für Dateien) — das ist Bedingung für alles Weitere in diesem Dokument (Skalierung, Backup-Strategie, S3-Austauschbarkeit).

## 2. Backend-Optionen je Betriebsstufe

Deckt sich mit `SKALIERUNGSKONZEPT.md` Abschnitt 3:

| Betriebsstufe | Backend | Treiber |
|---|---|---|
| Stufe 1 (Einzel-LXC) | lokales Dateisystem oder ZFS | lokaler Treiber (FDN-03/ARC-01 "ein Interface, zwei austauschbare Treiber") |
| Stufe 2 (verteilt) | S3-kompatibel: MinIO (selbst betrieben) oder Ceph (RADOS Gateway) | S3-Treiber, identische API wie Stufe 3 |
| Stufe 3 (Private Cloud / SaaS) | S3-kompatibel: MinIO/Ceph selbst betrieben oder Managed-Object-Storage beim Provider | S3-Treiber, kein Unterschied im Code |

Der Übergang Stufe 1 → 2/3 ist ein reiner Infrastruktur-Schritt (Treiber-Konfiguration ändern, nicht Code), das war der explizite Zweck der Abstraktion. Datenübernahme beim Wechsel: einmaliger Kopiervorgang (z.B. `mc mirror` bei MinIO) mit anschließendem Prüfsummen-Abgleich (Abschnitt 6) — kein Big-Bang-Risiko wie bei der Systemmigration aus `MIGRATIONSKONZEPT.md`, da es dieselbe NEXARCH-Instanz ist, nur das Backend wechselt.

**Bewusst nicht vorgesehen:** NFS als produktives Ziel für Stufe 2/3 — das S3-Protokoll ist die gemeinsame Klammer, NFS wäre ein dritter, inkompatibler Zugriffspfad. NFS bleibt als Option für den lokalen Stufe-1-Treiber denkbar (Mount-Punkt statt echtes lokales Dateisystem), ändert aber nichts am Treiber-Interface.

## 3. Pfad-/Namenskonvention (modulübergreifend vereinheitlicht)

FDN-03 und ARC-01 legen je ihre eigene Pfadkonvention fest (Akzeptanzkriterium in beiden Tickets), bisher ohne geteilten Rahmen. Damit Backup (Archive `BAK-02`), Export (Archive `DMS2-01` im Connect-Board, DMS `DOC-08`) und Betrieb nicht drei verschiedene Konventionen lernen müssen, gilt projektweit ein gemeinsames Schema — und, analog zur Datenbank (Modell C, eigene Datenbank pro Mandant), jetzt auch eine physische Trennung im Objekt-Storage: **jeder Mandant erhält einen eigenen Bucket bzw. Pfad-Root**, statt eines gemeinsamen Buckets mit `tenant_id`-Pfadpräfix.

Begründung: physische Trennung schließt bei Objekt-Storage dieselbe Fehlerklasse aus wie bei der Datenbank — ein Codefehler ohne Tenant-Kontext kann kein fremdes Bucket erreichen, nicht nur einen falschen Pfad innerhalb eines gemeinsamen Buckets. Ein vergessener Pfadfilter/Präfix-Check in einem gemeinsamen Bucket führt zum Cross-Tenant-Leck; ein fehlendes Tenant-Bucket-Mapping führt dagegen nur dazu, dass gar kein Bucket referenzierbar ist.

Die Provisionierung des Tenant-Buckets ist Teil desselben Provisioning-Schritts wie die Anlage der Tenant-Datenbank in Core `TEN-01` — ein neuer Mandant erhält Datenbank und Bucket in einem automatisierten Schritt.

Innerhalb des Tenant-Buckets entfällt das führende `tenant_id`-Segment, das Schema wird zu:

```
{modul}/{objekttyp}/{objekt_id}/{revision-oder-teil}
```

Beispiele (innerhalb des Buckets von Mandant `t-4471`):
- `dms/documents/doc-9021/rev-3.bin`
- `mail/messages/msg-88213/part-2-attachment.bin`
- `archive/backups/2026-08-26/snapshot.tar.zst`

Innerhalb des Pfads bleibt jedes Modul für sein `{objekttyp}`-Vokabular selbst zuständig (DMS: `documents`, `thumbnails`; Mail: `messages`, `attachments`) — nur die äußeren zwei Ebenen (`modul`/Rest) sind projektweit fix, damit ein Werkzeug (Backup, Export, Kapazitätsauswertung) modulübergreifend funktioniert, ohne pro Modul eine Sonderbehandlung zu brauchen. Die Mandantentrennung selbst (Bucket-Auswahl) ist damit kein Bestandteil des Pfadschemas mehr, sondern eine reine Provisioning-/Zugriffsschicht-Frage (siehe Ticket ARC-06, Mandantentrennung im Objekt-Storage; Kanban-Board inzwischen aus dem Repo entfernt, Historie in Gitea).

## 4. Verarbeitungsreihenfolge (Lebenszyklus einer Datei)

Zusammengeführt aus den bereits getroffenen Einzelentscheidungen (FDN-01/DOC-01/DOC-02/FDN-09 im DMS-Board, ARC-01/ARC-02/ARC-03 im Mail-Board):

```
1. Empfang (Klartext, im Speicher/temporär)
2. SHA-256-Hash auf Klartext
3. Duplikatsprüfung (DOC-02 / ARC-03) — Gate: nur neue oder bewusste Duplikate gehen weiter
4. Verschlüsselung at rest (FDN-09 / ARC-02, AES-256-GCM, Envelope Encryption)
5. Ablage im Objekt-Storage nach Pfadkonvention (Abschnitt 3)
6. Prüfsummenvergleich nach dem Schreiben (Akzeptanzkriterium in FDN-03/ARC-01)
7. Registrierung bei Archive-Retention-Engine (RET-05 Modul-Adapter) — Aufbewahrungsfrist beginnt zu laufen
8. OCR (SRC-05 / SRC-07) und Indexierung (SRC-02 / SRC-01+SRC-02) — läuft NACH Schritt 3, nicht parallel dazu
```

Löschung läuft ausschließlich über die Archive-Engine (Retention/Legal-Hold-geprüft), niemals direkt durch DMS oder Mail — das ist bereits Konsequenz der Archive-Konsolidierung, hier nur noch einmal aus Storage-Sicht festgehalten: kein Modul löscht Objekte eigenständig aus dem Storage.

## 5. Zugriffsmodell

- **Kein direkter Client-Zugriff auf den Objekt-Storage.** Up-/Downloads laufen über zeitlich begrenzte signierte URLs (FDN-03 Akzeptanzkriterium 2, Standard-Pattern für S3-kompatible Backends), die das Backend ausstellt — Storage-Zugangsdaten selbst erreichen nie den Browser.
- Presigned-URL-Gültigkeit kurz und konfigurierbar halten (Minuten, nicht Stunden) — lange gültige URLs sind ein unnötig großes Zeitfenster für Linkweitergabe.
- Storage-Zugangsdaten (S3-Credentials) sind Secrets wie jedes andere — ausschließlich über Umgebungsvariablen, nie im Code (bereits projektweite Regel aus jedem Ticket-Abschluss-Abschnitt).

## 6. Konsistenzprüfung

Jeder Schreibvorgang wird durch Prüfsummenvergleich verifiziert (bestehende Akzeptanzkriterien in FDN-03 und ARC-01). Für den Bestand insgesamt zusätzlich:

- **Reconciliation** (Archive `BAK-05`): periodischer Abgleich zwischen den in Postgres referenzierten Objekten und dem tatsächlichen Storage-Inhalt — erkennt verwaiste Metadaten-Einträge (Objekt fehlt im Storage) und verwaiste Storage-Objekte (kein Metadaten-Eintrag mehr, z.B. nach einem Fehler bei Schritt 5/6 aus Abschnitt 4).
- Reale Lehre aus archivmail: Reconciliation-Reports existierten dort bereits als Soll/Ist-Abgleich (siehe `datenmodell-altsysteme.md`) — Muster wird über Archive `BAK-05` fortgeführt, nicht neu erfunden.
- **Integritätsprüfung per Hash** (Archive `BAK-08`): periodischer Scrub-Job, der Stichproben liest, SHA-256 neu berechnet und gegen `file_revisions.checksum_sha256` vergleicht — erkennt stille Inhaltsveränderung/Bit-Rot bei Objekten, die noch existieren.

### 6.1 Grenzen der Prüfung bei extern eingebundenem Kunden-Storage

Bindet ein Kunde einen eigenen S3-Bucket ein, überwachen wir weder dessen Hardware noch dessen Betreiber. Was NEXARCH technisch leisten kann, hängt davon ab, was wir dürfen:

- **Kein Lesezugriff, nur Schreiben:** keine Verifikation möglich. Wir können höchstens den Upload-Beleg und den Hash zum Upload-Zeitpunkt festhalten — das ist kein Monitoring, sondern ein Nachweis für später.
- **Lese-/API-Zugriff vorhanden:** Existenz- (`BAK-05`) und Inhaltsprüfung (`BAK-08`) sind möglich, aber periodisch/stichprobenhaft, nicht in Echtzeit, und nur für das, was wir selbst wieder lesen können.

Was diese beiden Prüfungen NICHT leisten:

- Sie erkennen nicht lückenlos, ob ein Objekt unbefugt gelöscht oder durch ein neues ersetzt wurde, wenn uns keine Inventar-/Versionsdaten vom Storage vorliegen (ETag/LastModified/VersionId — sofern verfügbar, nicht überall ein einfacher Hash, besonders bei Multipart-Uploads oder providerseitiger Verschlüsselung, daher nicht als alleinige Wahrheitsquelle nehmen).
- Sie ersetzen keine storage-seitige WORM-/Versionierungsstrategie und keine Zugriffs-/Audit-Logs des Storage-Providers — nur Object Lock, Versioning, Retention Policies und providerseitige Audit-Logs verhindern Veränderungen oder machen sie lückenlos nachweisbar, ein nachträglicher Scrub kann sie nur *bemerken*, nicht verhindern.

### 6.2 Drei Betriebsmodi für Objekt-Storage

1. **NEXARCH-managed Storage** — wir kontrollieren Policies, Versioning, Object Lock, Backup vollständig.
2. **Customer-managed, compliant Storage** — Kunde stellt den S3-Bucket, aber vertraglich/beim Onboarding verbindlich verlangt: Versioning aktiviert, Object Lock/Retention bei revisionssicherer Nutzung, Audit-Logs aktiviert, eingeschränkte Löschrechte, idealerweise eigener Backup-/Replikationspfad.
3. **Customer-managed, non-compliant Storage** — nur für nicht revisionssichere Nutzung zulässig; muss im System klar markiert sein ("keine belastbare Unveränderbarkeitsgarantie"), damit keine falsche GoBD-Erwartung entsteht.

## 7. Backup vs. Storage-Redundanz — zwei verschiedene Schichten

Häufige Verwechslung, deshalb hier explizit getrennt:

- **Storage-Redundanz** (diese Datei, Abschnitt 2): wie das Backend selbst Datenverlust durch Hardware-Ausfall verhindert (S3-Provider-Redundanz, MinIO-Distributed-Mode, Ceph-Replikation). Schützt vor Festplatten-/Knotenausfall, NICHT vor Anwendungsfehlern oder böswilligem/versehentlichem Löschen.
- **Backup** (Archive `BAK-01`/`BAK-02`/`BAK-03`): eigenständige, deduplizierende Sicherung nach restic/Borg-Konzept, zeitversetzt, wiederherstellbar auch wenn die Primärkopie durch einen Anwendungsfehler beschädigt wurde. Das ist die Antwort auf "ein Bug löscht fälschlich Dateien" — Storage-Redundanz allein hilft dabei nicht, weil sie den fehlerhaften Löschvorgang originalgetreu mit-repliziert.

Beide Schichten sind nötig, keine ersetzt die andere.

## 8. Export & Portabilität

Aus der DMS-Produkt-DNA fortgeführt (ecoDMS-Lehre: "was die Oberfläche kann, kann auch die offene Schnittstelle", keine Herstellerbindung):

- Vollständiger Export von Dateiinhalt + Metadaten ohne NEXARCH-eigenes Werkzeug muss jederzeit möglich sein (DMS `DOC-08` Massenexport, Mail `ARC-07` Export/Portabilität, Connect `DMS2-01` offenes Austauschformat für Fremd-DMS-Interoperabilität).
- Objekt-Storage-Ablage selbst nutzt offene Formate (Original-Dateiformat + PDF/A für OCR-Ergebnisse, kein proprietäres Container-Format) — keine Vendor-Lock-Kodierung, die einen Export nachträglich erschweren würde.

## 9. Speicherverbrauch-Messung für Quota/Lizenzierung

~~Offene Lücke~~ — **geklärt (2026-08-28)**: Core `LIC-05` "Speicherverbrauch-Metrik je Tenant" setzt genau den hier vorgeschlagenen Mechanismus um — Objekt-Storage-Treiber der Module (FDN-03/ARC-01) melden bei jedem Schreib-/Löschvorgang die Objektgröße, ein leichtgewichtiger Postgres-Zähler pro Tenant wird geführt, `LIC-03` fragt ihn zur Quota-Durchsetzung ab. `LIC-05` hängt im Core-Abschluss-Gate `QA-05`.

## 10. Arbeitsverzeichnisse (Consume, Quarantäne, Export-Staging, Modell-Cache)

Ergänzung 2026-08-28, angestoßen durch den Vergleich mit paperless-ngx (`consume/`, `data/`, `media/`, `export/`, `trash/`) — mehrere Tickets definieren Funktionalität, die einen lokalen Arbeitsordner braucht, legen aber bisher nicht fest, WO dieser liegt. Papierkorb (DMS `DOC-11`/`DOC-12`, Mail `ARC-05`) braucht dagegen **keinen** eigenen Pfad — das ist ein reines DB-Status-Flag, das Objekt bleibt physisch am gewohnten Platz im Objekt-Storage, bis Archive es nach Fristablauf endgültig entfernt.

### 10.1 Consume-/Hot-Folder (DMS `INT-06`/`INT-08`, Mail `IMP-05`)

Anders als der reguläre Objekt-Storage-Zugriff (Abschnitt 2, ausschließlich über signierte URLs, Abschnitt 5) braucht ein Datei-Watch zwingend ein echtes lokales Dateisystemverzeichnis — S3-kompatible Backends unterstützen kein Datei-Watch. Konsequenz: Consume-Ordner sind **kein Teil des Tenant-Objekt-Storage-Buckets**, sondern ein separater, lokaler Zwischenspeicher je Tenant auf dem Modul-Host:

```
{consume-root}/{tenant_id}/dms/inbox/
{consume-root}/{tenant_id}/mail/inbox/
```

Nach erfolgreicher Verarbeitung (Hash, Duplikatsprüfung, Verschlüsselung, Ablage im Objekt-Storage — Abschnitt 4) wird die Datei aus dem Consume-Ordner entfernt, nicht dauerhaft dort belassen. Consume-Root ist damit strukturell näher an einem Cache als an Aufbewahrung und braucht keine Backup-Einbindung (Abschnitt 7) — im Fehlerfall wird die Quelle erneut abgelegt/gescannt.

### 10.2 Quarantäne (Mail `IMP-06` Virenscan-Fund)

Bei Virenscan-Fund wird die Anhang-Datei nicht gelöscht, sondern in einen isolierten Quarantäne-Bereich verschoben (Nachvollziehbarkeit, siehe Compliance-Anforderung) — ebenfalls lokal, ebenfalls je Tenant:

```
{consume-root}/{tenant_id}/mail/quarantine/
```

Quarantäne-Objekte werden nicht automatisch gelöscht; Aufbewahrungsdauer und Zugriff (nur Admin/Security-Rolle) sind Akzeptanzkriterium von `IMP-06`, nicht Gegenstand dieses Dokuments.

### 10.3 Export-Staging (DMS `DOC-08`, Mail `ARC-07`)

Massenexport (ZIP) erzeugt eine temporäre Datei zwischen "Export angestoßen" und "Download abgeschlossen". Diese Staging-Fläche ist rein ephemer (Lebensdauer im Bereich von Minuten bis wenigen Stunden), braucht keine Tenant-Bucket-Struktur und keine Backup-Einbindung:

```
{export-staging-root}/{tenant_id}/{export_job_id}.zip
```

Aufräumung nach Ablauf einer kurzen Frist (Vorschlag: 24 Stunden) oder nach bestätigtem Download ist Akzeptanzkriterium der jeweiligen Export-Kachel.

### 10.4 Ollama-Modell-Cache (AI `ENG-02`)

Bisher nicht adressierte Lücke: `ENG-02` (Ollama-Adapter) lädt und hält LLM-Modellgewichte lokal vor — je nach Modellklasse mehrere GB bis über 40 GB (siehe `PROXMOX-DEPLOYMENT.md` Abschnitt 6a, dort nur RAM-Sizing, keine Disk-Planung). Anders als Consume/Quarantäne/Export ist das **kein Zwischenspeicher, sondern persistenter, potenziell großer Datenbestand**, der eine eigene Kapazitätsplanung braucht, getrennt vom restlichen Objekt-Storage:

```
{ollama-root}/models/
```

Nicht tenant-partitioniert (Modelle werden über Tenants hinweg geteilt, sofern keine Tenant-spezifische Modellwahl vorliegt — siehe AI `ENG-04`). Bei Stufe-1-Einzel-LXC (siehe `PROXMOX-DEPLOYMENT.md` Abschnitt 2) sollte dieser Pfad auf ein eigenes Volume/Dataset gelegt werden, damit ein wachsender Modellbestand nicht den restlichen Systemspeicher verdrängt — gleiches Isolationsprinzip wie bei Tenant-Buckets (Abschnitt 3), nur nicht tenant-, sondern funktionsbezogen.

### 10.5 Warum eigene Datasets/Mountpoints sinnvoll sind

Alle vier Arbeitsverzeichnisse (10.1–10.4) profitieren aus demselben Grund von eigenen ZFS-Datasets/Mountpoints statt Unterordnern im Root-Dateisystem: unabhängige Quotas (ein vollaufender Consume-Ordner darf nicht das Systemvolume fluten), unabhängige Snapshots/Löschbarkeit (siehe Erfahrung mit `archivmail`-Alt-Deinstallation, `nexarch-state.json` Entscheidungsverlauf 2026-08-28), und die Möglichkeit, unterschiedliche Backup-/Retention-Policies zuzuweisen (Consume/Export brauchen keine, Modell-Cache profitiert von keiner inkrementellen Sicherung großer Binärdateien, sondern von einfacher Neubeschaffung bei Bedarf).