# Konzept: MinIO durch SeaweedFS ersetzen

Stand: 25. September 2026. Status: Entscheidungsvorschlag auf Basis des FEDEO-Codes bei Commit `29155f91` und der unten verlinkten Herstellerquellen. Eine Migration, ein Kompatibilitätstest mit einem Ersatzserver oder eine Änderung an einer laufenden Instanz wurde für dieses Konzept nicht durchgeführt.

## 1. Empfehlung und Umfang

**SeaweedFS Open Source wird der bevorzugte Kandidat für den FEDEO-Dateispeicher.** Ziel ist ein einzelner Container auf dem bisherigen Docker-Host mit S3-Schnittstelle, privaten Buckets und persistentem lokalen Speicher. Die Freigabe erfolgt erst nach den unter Abschnitt 10 beschriebenen Tests mit einem festgelegten Release und Image-Digest.

„Eins zu eins“ bedeutet für FEDEO: gleiche Dateien, gleiche Objektschlüssel, gleiche Datenbankverweise, gleiche Mandantentrennung und gleiche Benutzerabläufe. Das interne Speicherformat wird durch eine kontrollierte Kopie über S3 umgestellt. Das Verzeichnis `minio/` wird weder umbenannt und wiederverwendet noch vom Ersatzserver geöffnet.

Zur Lösung gehören drei zusammenhängende Änderungen:

1. MinIO-Server und MinIO-Client `mc` aus dem künftigen Standardbetrieb entfernen.
2. Installer, Update-Dienst, Datenübernahme und Wiederherstellung auf den neuen Speicher abstimmen.
3. Freigegebene Speicher-Images und Hilfswerkzeuge unter FEDEO-Kontrolle verfügbar halten, damit Kundenupdates nicht direkt von einer fremden Registry abhängen.

Nicht Teil dieses Austauschs sind Hochverfügbarkeit, ein Kubernetes-Cluster, neue fachliche Dateifunktionen oder die Ablösung von S3 durch ein eigenes Dateisystem-Backend. Ein Container auf einem Host bleibt ein einzelner Ausfallpunkt; eine zweite Kopie auf demselben Datenträger ersetzt kein externes Backup.

## 2. Konkreter Anlass und heutiger Zustand

Der gemeldete Auftrag von 3.3.0 nach 3.4.1 scheiterte beim Abruf von `quay.io/minio/mc` mit `401 Unauthorized`. `phase: pulling`, `mutationStarted: false` und `recoveryRequired: false` zeigen einen Abbruch vor der Wartungsphase. Das Protokoll belegt ein Bezugsproblem des Client-Images, keinen Datenfehler im laufenden MinIO. Es belegt auch nicht, ob das benötigte Image bereits lokal vorhanden ist.

Der inzwischen im Repository vorhandene Cache-Fix kann passende lokale Digest-Images weiterverwenden. Er ist eine Überbrückung und garantiert weder Neuinstallationen noch künftige Sicherheitsupdates.

Die Anwendung hat bereits eine weitgehend herstellerneutrale Schnittstelle:

| Bereich | Befund im Repository | Konsequenz |
| --- | --- | --- |
| S3-Client | `backend/src/utils/s3.ts`: AWS SDK, `forcePathStyle: true`, Endpunkt/Region/Schlüssel/Bucket aus `S3_*` | Kein Austausch des SDK erforderlich |
| Dateioperationen | `PutObject`, `GetObject`, `HeadObject`, `DeleteObject` | Überschaubarer verbindlicher API-Vertrag |
| Dateiablage | `backend/src/utils/files.ts`: Schlüssel wie `<Mandant>/filesbyid/<ID>/<Name>`, Content-Type und Länge | Schlüssel und Objektinhalt müssen unverändert bleiben |
| WebDAV | `backend/src/webdav/server.ts`: GET und HEAD | Lesen und Dateigrößen gezielt prüfen |
| Normale Dateilinks | `backend/src/routes/files.ts`: `/api/files/content/...` mit FEDEO-Token | Interne Speicheradresse bleibt vor dem Browser verborgen |
| DATEV/SEPA | `backend/src/routes/exports.ts`: echte S3-Presigned-URLs, 24 Stunden gültig, zusätzlich gespeicherter Objektschlüssel | Signaturen und bereits gespeicherte Links gesondert behandeln |
| Mandantenexport/-import | `backend/src/utils/tenantFullExport.ts` und `backend/src/routes/admin.ts` | Auch Archive, Vorlagen und temporäre Objekte übernehmen |
| Systemstatus | `backend/src/modules/system-status.service.ts`: `/minio/health/live` | Herstellerneutralen Funktionscheck einführen |
| Installation | Compose, `.env.example`, `scripts/selfhost-setup.sh`: MinIO und `mc` fest verdrahtet | Speicherbereitstellung und Initialisierung ersetzen |
| Host-Updater | `scripts/selfhost-update.py`: feste Dienste, Mounts, Hostname `minio`, Zugangsdaten, Start-/Backup-/Restore-Logik | Expliziten Übergangsadapter entwickeln |

Im durchsuchten Anwendungscode gibt es keine Aufrufe für Bucket-Versionierung, Object Lock, Objekt-Tags oder S3-Multipart-Uploads. Das beweist nicht, dass diese Funktionen auf einer bestehenden Instanz nie extern aktiviert wurden. Die Migration muss den tatsächlichen Bucket prüfen. HTTP-Multipart beim Datei-Upload ist außerdem nicht S3-Multipart.

## 3. Auswahl des Ersatzes

| Kandidat | Eignung und Grenzen | Entscheidung für FEDEO |
| --- | --- | --- |
| **SeaweedFS Open Source** | S3, Betrieb aus einem Binary/Container, konfigurierbare Schlüssel; Apache-2.0 laut Projekt. Intern mehrere Speicherkomponenten. S3-Schlüssel werden auf eine Verzeichnisstruktur abgebildet. | Bevorzugter Kandidat; Schlüsselkompatibilität, Authentifizierung und vollständiges Backup sind Freigabebedingungen. [Projekt](https://github.com/seaweedfs/seaweedfs), [S3-Vertrag](https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API) |
| **Garage** | Unterstützt den FEDEO-Kern aus S3, SigV4 und Presigned-URLs. Eigene Bucket-/Schlüsselrechte; keine vollständige AWS-Policy-, Versionierungs- oder Object-Lock-Schnittstelle. Das Einzelknoten-Tutorial rät wegen fehlender Redundanz vom Produktionseinsatz ab. | Alternative für bewusst kleinen Funktionsumfang; für den gewünschten Austausch weniger Spielraum bei bestehenden Sonderkonfigurationen. [Kompatibilität](https://garagehq.deuxfleurs.fr/documentation/reference-manual/s3-compatibility/), [Betriebsgrenzen](https://garagehq.deuxfleurs.fr/documentation/quick-start/) |
| **RustFS** | S3-orientiert, ähnliche Containerkonfiguration. Version 1.0.0 wurde am 16. September veröffentlicht; die direkte MinIO-Datenformat-Kompatibilität ist im aktuellen Projekt als Preview gekennzeichnet und nicht im Standardbuild aktiv. | Weiter beobachten. Die sehr junge stabile Version begründet hier eine längere Erprobung, nicht die Behauptung einer grundsätzlichen Untauglichkeit. Kein direkter Zugriff auf bestehende MinIO-Daten. [Release](https://github.com/rustfs/rustfs/releases/tag/1.0.0), [Datenformat](https://github.com/rustfs/rustfs/blob/main/docs/architecture/minio-file-format-compat.md) |

Die Entscheidung beruht auf dem FEDEO-Betriebsmodell und dem benötigten API-Umfang, nicht auf Hersteller-Benchmarks. Es gibt noch keine gemessene Aussage zu Geschwindigkeit oder Speicherverbrauch auf dieser Instanz. SeaweedFS-Enterprise-Funktionen sind keine Voraussetzung des Konzepts.

Zwei SeaweedFS-Eigenschaften verlangen konkrete Gegenmaßnahmen:

- Laut S3-Dokumentation können ein Objekt `a` und ein Objekt `a/b` nicht wie in einem flachen S3-Namensraum nebeneinander existieren; auch Löschoperationen auf Verzeichnissen haben besondere Semantik. Vorab sämtliche Schlüssel auf Präfixkonflikte, leere Verzeichnismarker, wiederholte Schrägstriche und problematische Pfadsegmente prüfen. Bei Verlust oder Normalisierung eines Schlüssels wird der Austausch blockiert, nicht stillschweigend umbenannt. [S3-Unterschiede](https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API)
- Ohne konfigurierte Identität startet das S3-Gateway standardmäßig mit anonym erlaubten Operationen. Unser Startprogramm muss bei fehlenden oder leeren Zugangsdaten abbrechen, bevor der Server startet. Zusätzlich sind anonyme und falsch signierte Zugriffe Negativtests jeder Freigabe. [Authentifizierung](https://github.com/seaweedfs/seaweedfs/wiki/S3-Credentials)

## 4. Zielarchitektur

```mermaid
flowchart LR
    U[Browser / Mobile / Geräte] --> B[FEDEO-Backend und WebDAV]
    B --> D[(PostgreSQL: unveränderte Dateiverweise)]
    B --> S[S3-Endpunkt: Dateispeicher]
    S --> W[SeaweedFS: ein Container]
    W --> V[(Objekte und Metadaten)]
    M[Host-Updater / Migrationswerkzeug] --> S
    M --> O[Altes MinIO während der Übernahme]
    M --> A[(Geprüfte Backups und Übernahmeprotokoll)]
```

Vorgeschlagene Betriebsnamen und Verzeichnisse:

| Bestandteil | Vorgabe |
| --- | --- |
| Compose-Dienst | `objectstore`, Container `fedeo-objectstore` |
| S3 | Intern Port 9000; keine Veröffentlichung eines neuen Host-Ports |
| Neuinstallation | `S3_ENDPOINT=http://objectstore:9000` |
| Bestehende Installation | Endpunkt zunächst unverändert; nach dem Umschalten exklusiver Netzwerkalias `minio` auf dem neuen Dienst |
| Zugangsdaten | Bestehende `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REGION` und `S3_BUCKET` übernehmen; exakte Werte im Kompatibilitätstest prüfen |
| Neue Ablage | `./storage/seaweedfs/` für sämtliche persistenten Daten und Metadaten |
| Konfiguration | `./storage/config/`, root-geschützte Konfiguration und getrennte Administratorzugänge |
| Legacy-Ablage | `./minio/` bleibt bis nach erfolgreicher Abnahme erhalten |
| Initialisierung | `storage-init` als Einmalprozess aus einem FEDEO-eigenen, gepinnten Hilfsimage; keine Abhängigkeit von `mc` |

SeaweedFS stellt einen Einzelprozess-/Container-Einstieg bereit. Die konkrete Startkonfiguration muss für den ausgewählten Release ausdrücklich Daten-, Metadaten- und Verwaltungszustand in die gesicherten Pfade legen. Keine Speicherung wichtiger Zustände in der beschreibbaren Container-Schicht. Unbenötigte APIs werden deaktiviert; Verwaltungs-, Filer- und Volume-Endpunkte sind für Anwendungscontainer nicht erreichbar. Dafür wird ein getrenntes Speichernetz beziehungsweise eine gezielte Bindung an Loopback innerhalb des Containers verwendet. [Betriebsoptionen](https://github.com/seaweedfs/seaweedfs/blob/master/README.md)

`storage-init` prüft Zugang, Bucket und private Zugriffe idempotent. Es erzeugt einen fehlenden Bucket, überschreibt aber keine fremden Policies oder bestehenden Inhalte. Die FEDEO-Anwendungsidentität erhält nur benötigte Rechte auf den konfigurierten Bucket. Verwaltung und Migration verwenden getrennte, geschützte Zugänge.

Bei Bestandsinstanzen dürfen `MINIO_ROOT_*` und `S3_*` nicht ohne Vergleich gleichgesetzt werden. Maßgeblich sind die tatsächlich vom Backend verwendeten Werte, einschließlich möglicher externer Secret-Verwaltung. Andere Anwendungen, weitere Buckets oder zusätzliche S3-Schlüssel führen zu einer erweiterten Bestandsaufnahme; deren Zugriff darf nicht durch die Stilllegung verloren gehen.

Der DNS-Alias wird nie gleichzeitig von Quelle und Ziel bedient. Während des Kopierens bleibt das Ziel unter einem anderen Namen erreichbar. Vor dem Umschalten wird das alte MinIO aus dem Anwendungsnetz genommen; danach werden Backend und sonstige S3-Clients neu gestartet, um bestehende Verbindungen zu schließen.

## 5. Verbindlicher Kompatibilitätsvertrag

Die Referenz ist der FEDEO-SDK-Stand aus dem Lockfile zusammen mit dem aktuellen MinIO-Verhalten. Der Test verwendet dieselben Dateipfade wie die Anwendung und zusätzlich Grenzfälle:

- PUT/GET/HEAD/DELETE; sofortiges Lesen nach Schreiben und Verhalten nach Löschen.
- Unveränderte Bytes und Schlüssel, MIME-Typ, Länge sowie vorhandene benutzerdefinierte Metadaten und relevante HTTP-Metadaten wie `Content-Disposition`, `Cache-Control` und `Content-Encoding`.
- SigV4, Path-Style, Region `eu-central-1` beziehungsweise der tatsächliche Bestandswert; SDK-Prüfsummen, Streaming und Sonderzeichen im Schlüssel.
- Leere Objekte, Umlaute, Leerzeichen, große Dateien und die größten vorhandenen Exportarchive. Für Objekte außerhalb des getesteten Größenbereichs gibt es einen ausdrücklichen Abbruch vor der Migration.
- Fehlercodes bei nicht vorhandenen Objekten, falschen Schlüsseln, anonymen Anfragen und fremden Buckets; ein HTTP-200 auf der Startseite ist kein ausreichender Healthcheck.
- Bestehende Datenbank-IDs und Pfade bleiben gleich. Mandantenrechte werden weiterhin durch FEDEO geprüft.

Objekt-ETag, S3-Version-ID und serverseitiges `LastModified` sind keine portablen Identitäten und müssen nach der Kopie nicht gleich sein. Fachliche Zeitstempel in PostgreSQL bleiben erhalten. Inhalte werden über einen unabhängig berechneten SHA-256-Hash verglichen; ETags werden nicht pauschal als MD5 interpretiert. [AWS-Prüfsummen](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity-upload.html)

Für den ersten Migrationspfad gilt: keine aktivierte Versionierung, keine aufzubewahrenden früheren Versionen/Delete-Marker, kein Object Lock und keine nicht unterstützte Verschlüsselungs-, Tagging- oder Policy-Konfiguration. Falls die Bestandsprüfung solche Merkmale findet, wird ein eigener getesteter Adapter erforderlich. SeaweedFS-Unterstützung auf dem Papier ist keine Garantie, dass unser Kopierwerkzeug diese Merkmale verlustfrei überträgt.

DATEV-/SEPA-Exporte brauchen einen zusätzlichen Test: Bereits ausgegebene Signaturen bleiben nur bei passender Adresse, Region, Identität und unterstützten Signaturparametern gültig. Die ohnehin vorhandene Backend-Downloadstrecke soll im vorbereitenden Release auch für Exporte verwendet werden; alte gespeicherte URLs werden bei der Ausgabe aus `filePath` neu erzeugt. Für bereits an Nutzer ausgegebene Links werden Kompatibilität oder ein dokumentierter Übergang für ihre maximal 24-stündige Laufzeit nachgewiesen. Ein interner Alias allein macht interne URLs nicht browsererreichbar.

## 6. Images zuverlässig bereitstellen

Eine andere öffentliche Registry würde die jetzige Fehlerklasse nur verlagern. Für freigegebene Speicherstände gilt deshalb:

1. Einen konkreten nicht vorveröffentlichten Upstream-Release auswählen, Herkunft und Digest erfassen und sämtliche Abnahmetests ausführen. Die recherchierte aktuelle SeaweedFS-Version ist 4.47; das ist noch keine FEDEO-Freigabe. [Release](https://github.com/seaweedfs/seaweedfs/releases/tag/4.47)
2. Das geprüfte OCI-Image unter einem unveränderlichen Tag in der FEDEO-Registry bereitstellen. Upstream- und Zieldigest getrennt dokumentieren; ein Registry-Transfer muss nicht dieselbe Manifestdarstellung erhalten.
3. Speicher-, Initialisierungs- und Migrationsimage samt Digests in das Release-Manifest aufnehmen. Diese Infrastruktur-Einträge von den bestehenden Anwendungsimages unterscheiden.
4. Release erst veröffentlichen, wenn jedes Zielimage aus Sicht einer Selfhost-Installation abrufbar ist. Korrekte Leserechte bei privaten Images prüfen.
5. Vor jeder Wartung alle benötigten Images laden und verifizieren. Danach ausschließlich lokal starten. Keine neuen Registry-Abhängigkeiten während Backup, Kopie oder Wiederherstellung.
6. Zusätzlich einen geprüften Offline-Export der notwendigen Images bereitstellen und Wiederherstellung ohne Upstream-Zugriff testen. Eine einzelne eigene Registry bleibt ansonsten ebenfalls ein Ausfallpunkt.

Spiegelung friert den Stand nur für einen Release ein. Sie braucht weiterhin einen gepflegten Sicherheitsupdate-Prozess und die zugehörigen Lizenz-/Herkunftsinformationen. `latest` ist keine Produktionsreferenz.

## 7. Datenübernahme bestehender Instanzen

Der erste unterstützte Weg ist eine Migration mit Wartungsfenster. Live-Vorkopieren wäre eine spätere Optimierung mit zusätzlichem Umgang mit Überschreibungen und Löschungen; für den ersten Wechsel wird keine unterbrechungsfreie Migration versprochen.

| Phase | Aktion | Bedingung zum Weitergehen |
| --- | --- | --- |
| Bestandsprüfung | Effektive Compose-Konfiguration, Images, Datenpfade, S3-Zugänge, alle Buckets, Objektanzahl/-größen und Sonderfunktionen erfassen | Standardfall bestätigt; unbekannte Schreiber oder Speichereigenschaften blockieren |
| Vorbereitung | Zielimages und Offline-Rückfall bereitstellen; Ziel in separatem Netz und leerem Datenpfad starten | Quelle/Ziel eindeutig identifiziert; Authentifizierung und Testbucket funktionieren |
| Schreibpause | Proxy, Backend, WebDAV und alle Hintergrundschreiber anhalten; externe Schreiber ausschließen | Keine fachlichen Schreibzugriffe mehr; PostgreSQL kann für den Dump laufen |
| Sicherung | PostgreSQL-Dump und kalte MinIO-Sicherung samt Konfiguration erstellen und prüfen | Ein zusammengehöriger Wiederherstellungspunkt ist vorhanden |
| Kopie | Altes MinIO ohne Anwendungszugriff wieder starten; gesamten betroffenen Bucket über S3 kopieren | Jedes Objekt im persistenten Migrationsjournal erfasst |
| Prüfung | Quell- und Zielobjekte vollständig lesen, SHA-256 und Metadaten vergleichen; Schlüsselmenge, Anzahl und Bytes abgleichen | Keine Abweichung und keine unerklärten Zielobjekte |
| Umschaltung | Altes MinIO stoppen und Neustart verhindern; Netzwerkalias/Compose wechseln | Ziel ist der einzige aktive Speicher für die Anwendung |
| Abnahme | Funktionstests im Wartungsmodus mit deaktivierten Hintergrundschreibern | Download, PDF, WebDAV, Upload und Export sowie Berechtigungen stimmen |
| Freigabe | Migration dauerhaft als abgeschlossen markieren; dann fachliche Schreiber und öffentlichen Zugriff freigeben | Journal und Backups referenzieren den aktiven Provider eindeutig |

Der neue, noch zu entwickelnde Migrationsprozess läuft als Host-Auftrag unter derselben exklusiven Sperre wie Updates. Er nutzt S3 über das bereits verwendete SDK in einem gepinnten FEDEO-Hilfsimage. Er kopiert mit begrenzter Parallelität und begrenztem RAM; große Objekte werden gestreamt oder in begrenztem lokalen Spool verarbeitet. S3-Multipart für große Objekte ist eine ausdrückliche Werkzeugfunktion und wird separat getestet.

Das root-lesbare Journal enthält Provider, Quell-/Zielidentität, Bucket, Image-Digests, Konfigurationsfingerprint, Phase, je Objekt Schlüssel/Größe/Hash/Metadatenvergleich sowie abgeschlossene Prüfungen. Es enthält keine Zugangsdaten. Abbruch und Wiederaufnahme sind idempotent; die Wiederaufnahme kontrolliert zuerst die Identitäten und den Schreibstopp. Sie vertraut einem alten „kopiert“-Eintrag erst nach erneuter Zielprüfung. Fehler, geänderte Quelle oder falsches Ziel führen zu einem Abbruch ohne Umschaltung.

Es wird der ganze zu migrierende Bucket inventarisiert, nicht nur `files.path` aus der Datenbank. Dadurch bleiben auch Exporte, Vorlagen und bislang nicht zugeordnete Objekte erhalten. Unbekannte weitere Buckets werden weder ignoriert noch gelöscht. Das Ziel ist zu Beginn leer und ausschließlich für diesen Auftrag vorgesehen.

## 8. Platzbedarf, Dauer und Rückkehr

Die Platzprüfung unterscheidet logische Objektbytes und physisch belegte Verzeichnisse. Kompression, Metadaten, Dateisystemreserve und Backup-Ziel werden berücksichtigt; eine Angabe wie „zweimal die Bucket-Größe reicht immer“ wäre falsch.

Für dieselbe Platte wird mindestens gerechnet mit:

`zusätzlich frei = neuer Speicher + altes kaltes Backup + Datenbankdump + Image-/Spoolbedarf + Reserve`

Die bereits vorhandenen MinIO-Daten bleiben zusätzlich belegt. Bei externem Backup entfällt dessen lokaler Platz nur, wenn wirklich direkt dorthin geschrieben und die Rücklesbarkeit geprüft wird. Verbindliche Zahlen gibt es nach Objektinventar, freiem Speicher und einem repräsentativen Probelauf.

Die Unterbrechung umfasst Backup, Kopie, vollständige Gegenprüfung und Neustart. Kopie und Hashprüfung erzeugen mehrere Lese-/Schreibdurchläufe; eine Laufzeit nur aus Dateigröße geteilt durch Netzwerkbandbreite wäre zu optimistisch.

**Bis zur Freigabe fachlicher Schreibzugriffe:** Quelle, ursprüngliche Compose-Datei, Zugangsdaten und Anwendung bleiben verfügbar. Ein Fehler erlaubt, das Ziel zu stoppen, den alten Netzwerkzustand wiederherzustellen und MinIO mit der unveränderten Anwendung zu starten. Testschreibvorgänge müssen in isolierten Testdaten stattfinden. Der Speichertausch wird nicht gleichzeitig mit fachlichen Datenbankschemamigrationen durchgeführt.

**Nach Freigabe fachlicher Schreibzugriffe:** Das alte MinIO ist veraltet. Ein bloßer Endpunktwechsel würde neue Dateien und Änderungen verlieren. Rückkehr erfordert erneut Wartung und eine vollständige, geprüfte Rückübernahme einschließlich Löschungen oder die bewusste Wiederherstellung eines zusammengehörigen DB-/Speicherbackups mit benanntem Datenverlustzeitraum. Kein automatischer Rückfall nach Aufnahme des normalen Betriebs.

Alte Daten und Container bleiben bis zur geprüften ersten vollständigen Sicherung und erfolgreichen Wiederherstellung des neuen Speichers erhalten. Aufräumen ist ein eigener administrativer Vorgang. Aufbewahrungsdauer wird anhand des verfügbaren Platzes festgelegt, nicht durch den Updater stillschweigend erzwungen.

SeaweedFS speichert Inhalt und Filer-Metadaten getrennt; beide müssen zusammenpassen. Für FEDEO wird zunächst ein kaltes Backup aller persistenten Bestandteile bei gestopptem Speicher implementiert. Der Restore-Test umfasst neue leere Verzeichnisse, vollständige Konfiguration, Schlüssel und genau das zugehörige Image. [Herstellerhinweise zu Backups](https://github.com/seaweedfs/seaweedfs/wiki/Data-Backup)

## 9. Änderungen im Projekt und Einführungsreihenfolge

| Arbeitspaket | Betroffene Stellen | Fertig, wenn … |
| --- | --- | --- |
| S3-Vertrag und Erprobung | neue Integrationstests, bestehender S3-Client | MinIO und ausgewählter Ersatz denselben FEDEO-Vertrag bestehen |
| Speicherinitialisierung | neues FEDEO-Hilfsprogramm/-image, Compose | Bucket ohne `mc` privat und wiederholbar bereitsteht |
| Installer | `scripts/selfhost-setup.sh`, `.env.example`, Compose | Neuinstallation und erneuter Start Daten/Zugänge erhalten |
| Providerprüfung | `scripts/selfhost-update.py` | Explizite Adapter für Legacy-MinIO und SeaweedFS statt allgemeiner Lockerung der Mount-/Dienstprüfungen |
| Datenübernahme | neuer Host-Ablauf plus Kopier-/Prüfwerkzeug | Journal, Sperre, Wiederaufnahme, Integritätsprüfung und Rückkehr funktionieren |
| Backup/Restore | Host-Updater und Betriebsdokumentation | Kalte Sicherung und vollständiger Restore für beide Provider geprüft sind |
| Oberfläche und API | `selfhost-update-service.py`, Backend-Updater-Modul/-Routen, `useSelfhostUpdates`, `SelfhostUpdateCard.vue` | Plan, Fortschritt, Sperren und bereinigte Fehlerdetails der Migration sichtbar sind |
| Systemstatus | `system-status.service.ts`, Frontend-Systemstatus | „Dateispeicher“ über einen signierten S3-Funktionscheck bewertet wird |
| Exportlinks | `backend/src/routes/exports.ts` und zugehörige Auslieferung | Neue und bestehende Exportlinks den Speicherwechsel überstehen |
| Veröffentlichung | `scripts/release/publish.mjs`, Manifest, CI und Betriebsassets | Speicher-/Hilfsimages und Hostdateien vollständig geprüft ausgeliefert werden |

Vorgeschlagene Reihenfolge:

1. **Erprobung:** Datensatz und Restore in einer isolierten Umgebung testen. Keine produktive Quelle als Schreibziel verwenden.
2. **Vorbereitender Release:** Herstellerneutrale Checks, Exportlinks, Initialisierung ohne `mc`, beide Provider-Adapter und Migrationsprotokolle liefern. Bestehende Instanzen behalten zunächst MinIO. Für deren Übernahme wird das tatsächlich vorhandene geprüfte MinIO-Image erhalten; der Übergang darf keinen erneuten Bezug des gesperrten `mc` verlangen.
3. **Host-Dienst nachrüsten:** Die zusammengehörigen Host-Dateien aus diesem geprüften Stand installieren. Der aktuelle Host-Dienst ersetzt sich bei einem Anwendungsupdate nicht selbst. Ein Update der Weboberfläche allein reicht daher nicht.
4. **Separater Migrationsauftrag:** Auf unverändertem Anwendung-/Datenbankschema den Speicherwechsel mit Vorschau, Platzbedarf und Wartungsfreigabe durchführen. Nach erfolgreicher Migration normale Anwendungsupdates wieder erlauben.
5. **Neuer Standard:** Neue Installationen erhalten SeaweedFS direkt. Der Legacy-Adapter bleibt während der Übergangszeit zum Migrieren und Wiederherstellen verfügbar.

Die bisherigen Prüfschranken werden nicht pauschal entfernt: Nur ausdrücklich unterstützte Providerübergänge dürfen Dienste, Datenmounts und Bootstrap-Konfiguration ändern. PostgreSQL-, Mandanten- und sonstige Mount-Regeln bleiben streng. Ein ausgefallener Migrationsauftrag blockiert parallele Releases, bis sein Zustand geklärt ist.

API-Felder und Phasen wie `storage_copying` und `storage_verifying` müssen in Host-Dienst, Backend-Allowlist und Frontend gemeinsam eingeführt werden. Ein eigener Migrationsauftrag benötigt dieselben aktuellen globalen Adminrechte, bestätigten Bearer-Zugang und idempotenten Auftrags-IDs wie Updates. Er ist nicht über frei angegebene Shell-Befehle oder URLs konfigurierbar.

Providerwechsel, Journal und Schreibfreigabe benötigen einen dauerhaften Zustand vor dem tatsächlichen Start der Schreiber, damit auch ein Hostabsturz den Rückkehrpunkt nicht verschleiert. Bestehende `mutationStarted`-/`recoveryRequired`-Flags allein beschreiben diese Grenze nicht ausreichend.

Alte Updater können eine neue Compose-Struktur weiterhin ablehnen. Die Mindestversion des Host-Dienstes wird deshalb Bestandteil der Release-Vorschau. Die konkrete FEDEO-Versionsnummer folgt den Commit-Regeln; es wird keine Versionsnummer vorab versprochen und kein bestehender Release überschrieben. Inkompatible Änderungen an Betriebsverträgen müssen gegebenenfalls als Breaking Change mit Migrationshinweis gekennzeichnet werden.

## 10. Abnahmekriterien

Der Austausch ist erst freigegeben, wenn alle folgenden Punkte nachgewiesen sind:

1. Der vollständige S3-Vertrag aus Abschnitt 5 funktioniert mit dem exakten Backend-Lockfile und dem gepinnten Zielimage.
2. Alle inventarisierten Objekte sind vorhanden; Schlüsselmenge, Größen, SHA-256 und zu erhaltende Metadaten stimmen. Kein stiller Ausschluss unbekannter Objekte.
3. Upload, Download, PDF-Vorschau, ZIP, WebDAV, DATEV/SEPA, Mandantenexport und -import sowie Hintergrundverarbeitung funktionieren. Zwei Mandanten können weiterhin nicht gegenseitig auf ihre Dateien zugreifen.
4. Anonymer Zugriff, falsche Schlüssel und Zugriff auf nicht freigegebene Buckets werden abgewiesen. Fehlende Start-Zugangsdaten führen zum Startabbruch.
5. Datei-/Präfixkonflikte, unterstützte maximale Objektgröße und ungewöhnliche Schlüssel sind vorab erkannt beziehungsweise erfolgreich getestet.
6. Abbrüche bei Kopie, Vollprüfung, DNS-Umschaltung und Neustart lassen sich ohne falschen Erfolg oder Verlust vorhandener Daten behandeln. Auch ein harter Host-Neustart wird geprüft.
7. Rückkehr vor Schreibfreigabe und Wiederherstellung nach Schreibfreigabe sind praktisch getestet. Ein Restore nur anhand von Tar-Inhaltsverzeichnissen reicht nicht.
8. Ein reguläres Anwendungsupdate auf dem neuen Speicher erstellt ein vollständiges Backup und kann bei Ausfall der fremden Registry mit bereitgestellten Images weiterarbeiten.
9. Ein Neuaufbau aus externem Backup und Offline-Images funktioniert ohne Quay und ohne öffentlichen Upstream-Download.
10. Gemessene Übernahmedauer und Platzreserve passen zur konkreten Instanz; der Probelauf nennt CPU/RAM, Objektanzahl, Größenverteilung und Datenträger. Unzureichende Werte blockieren die Freigabe.

Offen vor der Implementierung sind insbesondere Objektanzahl/-volumen dieser Instanz, größtes Objekt, freie Plattenkapazität, zusätzliche S3-Nutzer, aktivierte Bucket-Sonderfunktionen, Standort des externen Backups und das akzeptable Wartungsfenster. Diese Werte beeinflussen die Durchführung, nicht die Notwendigkeit der Integritätsprüfung.

## 11. Ergebnis für die betroffene Instanz

Die Instanz steht laut vorgelegtem Protokoll noch vor einer mutierenden Updatephase. Sie kann daher zunächst auf dem vorhandenen Speicher bleiben, während der Ersatz erprobt wird. Das Austauschkonzept benötigt keinen erfolgreichen Download des fehlgeschlagenen `mc`-Images. Voraussetzung der späteren Übernahme ist ein erreichbares, lesbares Quell-MinIO oder dessen geprüfte Wiederherstellung.

Der nächste Umsetzungsschritt ist ein reproduzierbarer S3-Kompatibilitäts- und Restore-Test mit SeaweedFS. Erst dessen Ergebnis rechtfertigt die Implementierung und Freigabe des produktiven Migrationspfads.