Updates, Backups und Wiederherstellung

Updates und Backups sichern zwei verschiedene Ergebnisse: Updates bringen die Plattform voran, während Backups es ermöglichen, Identität, Sollzustand, Zugangsdaten von Diensten und Anwendungsdaten nach einem Ausfall wiederherzustellen. Der Plattformverantwortliche ist für die Update-Reihenfolge zuständig, der Sicherheitsverantwortliche für die Wiederherstellungsschlüssel, Datenbank- und Anwendungsverantwortliche für engine-native Datenbackups und deren Prüfung.

Legen Sie das Wiederherstellungspunktziel (wie viele Daten verloren gehen dürfen) und das Wiederherstellungszeitziel (wie lange die Wiederherstellung dauern darf) fest, bevor Sie Backup-Häufigkeit oder Update-Fenster wählen. Erfolg ist eine getestete Wiederherstellung, nicht das Vorhandensein von Archivdateien.

Lesen Sie vor einem Opfield-Update die Release Notes, prüfen Sie die Mindestversionen für die Kompatibilität, sichern Sie PostgreSQL und persistente Dateien, bewahren Sie Verschlüsselungs- und Master-Schlüssel und halten Sie die laufenden Image-Referenzen fest. Aktualisieren Sie über den unterstützten Installer oder die generierte Compose-Konfiguration.

Daemon-Updates sind signiert und werden pro Node verwaltet. Halten Sie den Betrieb mit gemischten Versionen innerhalb des dokumentierten Kompatibilitätsfensters und prüfen Sie nach jedem Rollen-Update erneuten Verbindungsaufbau, Inventar, Bindings, Logs und Operationen.

Sichern Sie:

• PostgreSQL;
• persistente Volumes für Artefakte und Konfiguration von Opfield;
• Verschlüsselungs- und PKI-Master-Schlüssel;
• das Identitäts-Volume von Relay;
• engine-native Datenbank-Backups;
• außerhalb von Opfield gehaltene Konfiguration von externem DNS, Identitätsanbieter, E-Mail, Registry und SIEM.

Ein Wiederherstellungstest muss Anmeldung, Entschlüsselung, erneute Verbindung der Nodes, Relay-Autorisierung, Routen, Zertifikate, Bindings verwalteter Datenbanken und lückenloses Audit nachweisen. Ein Backup, das nie wiederhergestellt wurde, ist kein Wiederherstellungsplan.

Datenbankdaten gehören nicht zu diesem Wiederherstellungssatz. Ab Personal erstellen Datenbank-Backups geplante native Backups verwalteter und externer PostgreSQL-, Key-Value- und ClickHouse-Datenbanken in einer Speicherverbindung; verwenden Sie auf Community oder für Engines, die eine Wiederherstellung zu einem Zeitpunkt benötigen, engine-native Werkzeuge. Siehe Verwaltete und externe Datenbanken im Überblick.

Integrierte Abläufe

Speicherverbindungen und verwalteter Objektspeicher und Backup und Wiederherstellung von Datenbanken sind ab Personal verfügbar. Der Konfigurationsexport, um Opfield auf einen anderen Host zu verschieben, ist in jedem Tarif verfügbar.

Konfigurationsexport

Settings > General > Configuration export (Scope admin:system) packt die Installation in eine Datei, die mit einer Passphrase von mindestens 12 Zeichen verschlüsselt ist: die Opfield-Datenbank, PKI_MASTER_KEY, die Signaturschlüssel der CA und der Relay-Richtlinie, die Dateien von Opfield, den kommerziellen Kern einer kostenpflichtigen Installation, die Installations-ID und optional die Einstellungen aus .env. Images der internen Registry und die Logs des von Opfield verwalteten ClickHouse sind optional. Opfield läuft während des Exports weiter und speichert die Passphrase nicht.

Ein Export lässt sich nur in eine frische Installation derselben Opfield-Version wiederherstellen, entweder im Einrichtungsassistenten (Restore from an export) oder mit der Installer-Option --restore <file>; aktualisieren Sie danach wie gewohnt. Die Wiederherstellung fragt nach der öffentlichen URL und der gRPC-Adresse des neuen Hosts, und die neue Installation behält ihre eigenen Datenbank- und Registry-Passwörter. Anmeldesitzungen werden nicht übertragen. Daten von Datenbanken auf Storage Nodes sind nicht Teil des Exports: Schützen Sie sie mit Datenbank-Backups. Um Nodes auf eine neue Adresse umzuziehen, verwenden Sie Settings > General > Move nodes to a new address auf der alten Installation, bevor Sie sie herunterfahren.

Ein Konfigurationsexport ist etwas anderes als der Export von Container-Archiven. Der manuelle Wiederherstellungssatz unten bleibt eine Möglichkeit, eigene Backups der Control Plane vorzuhalten; Datenbank-Backups schützen Anwendungsdaten, nicht den eigenen Zustand von Opfield.

Den Wiederherstellungssatz zusammenstellen

Dokumentieren Sie für jede Backup-Komponente Verantwortlichen, Speicherort, Aufbewahrung, Verschlüsselungsverfahren und Wiederherstellungsreihenfolge. Bewahren Sie Master-Schlüssel und Wiederherstellungszugangsdaten außerhalb des Opfield-Hosts und außerhalb der Fehlerdomäne des Datenbank-Backups auf.

PostgreSQL ist der maßgebliche Speicher für Identitäten, Sollzustand, Beziehungen, Operationen und Audit-Metadaten. Persistente Volumes enthalten Artefakte und Identitätsmaterial von Diensten, das sich nicht allein aus PostgreSQL rekonstruieren lässt. Engine-native Backups verwalteter Datenbanken schützen Anwendungsdaten; ein Backup der Control Plane ist kein Ersatz dafür.

Manueller Compose-Wiederherstellungssatz

Der manuelle Installer verwendet die Dienste app, relay, registry, postgres und redis sowie diese persistenten Volumes:

Volume	Zweck für die Wiederherstellung
postgres_data	Benutzer, Ressourcen, Sollzustand, Tasks und Audit-Metadaten
app_data	hochgeladene Artefakte, generierte Konfiguration, TLS und Anwendungszustand
relay_identity	lokale Relay-Identität, die von app und relay gemeinsam genutzt wird
relay_state	lokaler Laufzeitzustand von Relay
registry_data	Blobs und Manifeste der privaten Registry
registry_auth	Signaturmaterial für Registry-Tokens
redis_data	persistierter Redis-Zustand; nützlich für eine koordinierte vollständige Wiederherstellung, aber kein Ersatz für PostgreSQL

Das sind die Schlüssel in docker-compose.yml. Eine frische Installation benennt die Volumes opfield_app_data usw.; eine Installation, die aus /opt/gateway umgezogen ist (siehe Update auf 2.12.1), behält ihre bisherigen Namen wie gateway_gateway_data, die unter name: in docker-compose.yml stehen. Die folgenden Befehle verwenden die Container-Pfade einer Installation, die mit 2.12.3 oder später eingerichtet wurde (/var/lib/opfield, /var/lib/opfield-relay, /var/lib/opfield-registry-auth); eine früher eingerichtete Installation bindet dieselben Daten unter /var/lib/gateway, /var/lib/gateway-relay und /var/lib/gateway-registry-auth ein, verwenden Sie dort also diese Pfade.

Ist das lokale strukturierte Logging aktiviert, sichern Sie auch das Volume des von Opfield verwalteten ClickHouse.

Bewahren Sie außerdem .env und die exakte docker-compose.yml der Installation; sowohl der Installer als auch die manuelle Installation legen sie neben .env ab, beim Installer standardmäßig in /opt/opfield. Die Datei .env enthält für die Wiederherstellung sensible Secrets; verschlüsseln Sie ihr Backup separat und hängen Sie sie nie an ein Support-Ticket an.

Das folgende Beispiel erzeugt ein kurzes Offline-Fenster für einen konsistenten Stand. Führen Sie es in dem Verzeichnis aus, das die manuelle Compose-Datei enthält:

mkdir -p opfield-recovery/{app_data,relay_identity,relay_state,registry_data,registry_auth,redis_data}
cp .env docker-compose.yml opfield-recovery/
chmod 700 opfield-recovery
chmod 600 opfield-recovery/.env

docker compose -f docker-compose.yml stop app relay registry
docker compose -f docker-compose.yml exec -T postgres \
  pg_dump -U opfield -d opfield -Fc > opfield-recovery/postgres.dump
docker compose -f docker-compose.yml stop redis
docker compose -f docker-compose.yml cp --archive app:/var/lib/opfield/. opfield-recovery/app_data/
docker compose -f docker-compose.yml cp --archive app:/var/lib/opfield-relay/. opfield-recovery/relay_identity/
docker compose -f docker-compose.yml cp --archive relay:/var/lib/opfield-relay/state/. opfield-recovery/relay_state/
docker compose -f docker-compose.yml cp --archive registry:/var/lib/registry/. opfield-recovery/registry_data/
docker compose -f docker-compose.yml cp --archive app:/var/lib/opfield-registry-auth/. opfield-recovery/registry_auth/
docker compose -f docker-compose.yml cp --archive redis:/data/. opfield-recovery/redis_data/
docker compose -f docker-compose.yml start redis registry app relay

Die Datenbank und ihre Rolle heißen opfield; eine Installation, die noch nicht aus /opt/gateway umgezogen ist, verwendet für beides gateway.

Kopieren Sie opfield-recovery in verschlüsselten Speicher außerhalb des Hosts und prüfen Sie dort die Prüfsumme. Dieses Beispiel sichert keine auf Storage Nodes verwalteten Datenbanken; schützen Sie deren Daten mit Datenbank-Backups oder den nativen Werkzeugen der Engine.

Um auf einem sauberen, kompatiblen Host wiederherzustellen, stellen Sie zuerst .env und dieselbe Compose-Datei wieder her, erstellen dann gestoppte Container, kopieren die persistenten Daten, starten PostgreSQL und importieren den Dump, bevor Sie den Rest der Control Plane starten:

docker compose -f docker-compose.yml create

docker compose -f docker-compose.yml cp --archive opfield-recovery/app_data/. app:/var/lib/opfield
docker compose -f docker-compose.yml cp --archive opfield-recovery/relay_identity/. app:/var/lib/opfield-relay
docker compose -f docker-compose.yml cp --archive opfield-recovery/relay_state/. relay:/var/lib/opfield-relay/state
docker compose -f docker-compose.yml cp --archive opfield-recovery/registry_data/. registry:/var/lib/registry
docker compose -f docker-compose.yml cp --archive opfield-recovery/registry_auth/. app:/var/lib/opfield-registry-auth
docker compose -f docker-compose.yml cp --archive opfield-recovery/redis_data/. redis:/data

docker compose -f docker-compose.yml up -d postgres
docker compose -f docker-compose.yml cp opfield-recovery/postgres.dump postgres:/tmp/opfield.dump
docker compose -f docker-compose.yml exec -T postgres \
  pg_restore -U opfield -d opfield --clean --if-exists /tmp/opfield.dump

docker compose -f docker-compose.yml up -d redis registry app relay

Verwenden Sie zuerst dasselbe Release. Prüfen Sie Anmeldung, Entschlüsselung von Secrets, Relay-Identität und frische Verbindungen der Nodes, bevor Sie ein Upgrade versuchen. Dateieigentümer können sich zwischen Hosts unterscheiden; meldet ein Dienst Berechtigungsfehler, vergleichen Sie die Eigentümer in den ursprünglichen und wiederhergestellten Containern, statt pauschal Schreibrechte zu vergeben.

Update-Verfahren für Opfield

1. Lesen Sie die Release Notes und die erforderlichen Zwischenversionen.
2. Bestätigen Sie den aktiven Update-Kanal und die Zielversion und, für eine Installation, die einen kostenpflichtigen Tarif hat oder hatte, dass Opfield den Lizenzdienst erreicht; siehe Update-Voraussetzungen in 2.11. Folgen Sie beim Update von 2.10 zuerst Update von 2.10.
3. Prüfen Sie aktuelle Backups von PostgreSQL und persistenten Volumes.
4. Halten Sie die aktuellen Versionen und Image-Digests von Opfield, Relay und Daemons fest.
5. Bestätigen Sie den Zustand von PostgreSQL, Redis, Relay und Festplatte.
6. Versetzen Sie kundenseitige Dienste nur dann in Wartung, wenn das Update es erfordert.
7. Wenden Sie das unterstützte Update an, ohne persistente Volumes oder Master-Schlüssel zu ersetzen.
8. Warten Sie, bis Opfield bereit ist und die Schemamigration abgeschlossen ist.
9. Prüfen Sie Relay, Anmeldung, das Laden des Dashboards, erneute Verbindungen der Nodes, Routen und Datenbank-Bindings.
10. Heben Sie die Wartung erst nach externer Prüfung auf.

Werten Sie einen laufenden Container nicht als erfolgreiches Update. Die Anwendung muss bestehende Secrets entschlüsseln, den bisherigen Zustand lesen, Hintergrunddienste abgleichen und fehlerfreie Kundenpfade bereitstellen.

Update-Voraussetzungen in 2.11

Jedes Opfield-Update autorisiert das Ziel-Release zuerst beim Lizenzdienst. Opfield führt eine signierte Liste der Adressen des Dienstes und verwendet die, die antwortet, normalerweise license.opfield.dev. LICENSE_SERVICE_URL in .env, zum Beispiel ein Egress-Proxy, wird zuerst versucht. Das gilt für aus der Konsole gestartete Updates und für das erneute Ausführen des Installers. Opfield prüft das signierte Release, bevor es den Host ändert:

• Kostenpflichtige Installationen: Eine Installation, die eine kostenpflichtige Aktivierung hat oder hatte – auch eine abgelaufene, widerrufene, übertragene oder deaktivierte –, erhält den kommerziellen Kern für die Zielversion, sodass ihre bestehenden kostenpflichtigen Ressourcen nach dem Update weiterlaufen. Opfield prüft Signatur, Version, Größen und Hashes des Kerns und akzeptiert die Autorisierung nur als signierten Lizenzzustand für diese Anfrage. Eine solche Installation benötigt den Lizenzdienst während des Updates: Ist der Dienst nicht erreichbar, lehnt er das Release ab oder liefert er einen Zustand, der die Prüfung nicht besteht, stoppt das Update vor jeder Änderung, und das aktuelle Opfield läuft weiter. Opfield ersetzt eine kostenpflichtige Installation nie stillschweigend durch Community; erlauben Sie daher während der Update-Fenster ausgehenden Zugriff auf den Lizenzdienst.

• Community-Installationen: Eine Installation, die nie einen kostenpflichtigen Tarif hatte, wird als Community aktualisiert. Hat sie keinen Lizenzschlüssel, keinen kostenpflichtigen Tarif in ihrem Lizenzzustand und keinen kommerziellen Kern auf dem Host, wird sie auch aktualisiert, wenn der Lizenzdienst nicht erreichbar ist, da sie nichts Privates herunterlädt. Eine Ablehnung oder ein Lizenzzustand, der die Prüfung nicht besteht, stoppt das Update dennoch.

• Laufende Operationen: Nach dem Herunterladen der Images und vor der Änderung des Hosts wartet Opfield, bis laufende und eingereihte Orchestrierungsarbeit abgeschlossen ist – Blue/Green-Deployments und das Leeren ihrer vorherigen Slots, Compose-Operationen, Workload-Availability-Aktionen, Migrationen und Build-Rollouts. Die Wartezeit beträgt standardmäßig bis zu 15 Minuten oder bis zur längsten von laufender Arbeit angekündigten Frist, höchstens 60 Minuten. Der Update-Bildschirm listet die Operationen auf, auf die gewartet wird. Neue Orchestrierungsarbeit, die während der Wartezeit gestartet wird, wird mit OPFIELD_UPDATING abgelehnt. Ein Administrator kann die Wartezeit mit Update now vorzeitig beenden; Opfield setzt die unterbrochenen Operationen dann nach dem Neustart fort oder gleicht sie ab.

• Freier Speicherplatz: Bevor die App ersetzt wird, erstellt das Update eine Momentaufnahme der Opfield-Datenbank und benötigt dafür freien Platz auf dem Dateisystem, das das Opfield-Verzeichnis enthält: Datenbankgröße plus 10 % plus 256 MiB. Bei weniger Platz stoppt das Update vor jeder Änderung, und die Logs des Update-Containers nennen den benötigten Platz.

Das vorherige Image und der vorherige kommerzielle Kern werden aufbewahrt, damit ein fehlgeschlagenes Update zurückgesetzt werden kann. Wie kostenpflichtige Funktionen ausgeliefert werden, steht unter Kommerzieller Kern.

Die Wartezeit für laufende Operationen, die Prüfung des Speicherplatzes und die Datenbank-Momentaufnahme unten gehören zum Updater der laufenden Version. Sie gelten für Updates ab 2.11, nicht für das Update von 2.10; siehe Update von 2.10.

Automatisches Rollback und die Datenbank-Momentaufnahme

Unmittelbar bevor die neue Version startet, schreibt das Update eine pg_dump-Momentaufnahme im Custom-Format der Opfield-Datenbank nach .opfield-foundation-backups/pre-update-<time>/opfield-db.dump im Opfield-Verzeichnis, neben die gesicherten .env und docker-compose.yml. Wird die neue Version nicht innerhalb von etwa fünf Minuten fehlerfrei, setzt der Update-Container zurück: Er stellt .env und docker-compose.yml wieder her, stoppt alle Compose-Dienste außer postgres, löscht die Opfield-Datenbank und erstellt sie aus der Momentaufnahme neu (Updates, die von einem Release vor 2.12.1 gestartet wurden, schreiben .gateway-foundation-backups/pre-update-<time>/gateway-db.dump). Die vorherige Version läuft daher nie auf einem Schema, das die Migrationen der neuen Version geändert haben. Nach der Momentaufnahme geschriebene Daten gehen verloren.

Die Momentaufnahme wird gelöscht, sobald das Update oder die Wiederherstellung erfolgreich ist, und ein späteres Update löscht übrig gebliebene Momentaufnahmen, die älter als 7 Tage sind. Lässt sich die migrierte Datenbank nicht löschen, startet die vorherige Version wie zuvor darauf, und die Momentaufnahme bleibt erhalten. Schlägt die Wiederherstellung nach dem Löschen fehl, bleibt Opfield gestoppt und die Momentaufnahme erhalten: Beheben Sie die in den Logs des Update-Containers angezeigte Ursache und stellen Sie dann aus dem Opfield-Verzeichnis wieder her:

docker compose exec -T postgres psql -U opfield -d postgres -c 'DROP DATABASE IF EXISTS opfield WITH (FORCE)'
docker compose exec -T postgres pg_restore --create --exit-on-error -U opfield -d postgres < .opfield-foundation-backups/pre-update-<time>/opfield-db.dump
docker compose up -d

Die Momentaufnahme schützt nur das Update selbst. Bewahren Sie zusätzlich die PostgreSQL-Backups des Wiederherstellungssatzes auf.

Update von 2.10

Das Update von 2.10.x führt der Updater von 2.10.x aus. Er wartet weder auf laufende Operationen noch erstellt er eine Momentaufnahme der Opfield-Datenbank; bereiten Sie es daher selbst vor.

Vor dem Update

1. Sichern Sie im Opfield-Verzeichnis (standardmäßig /opt/gateway) die Datenbank und bewahren Sie eine Kopie von .env auf, die PKI_MASTER_KEY enthält:

   docker compose exec -T postgres pg_dump -Fc -U gateway gateway > gateway-2.10.dump
   cp .env env-2.10.backup

2. Vermeiden Sie Deployments, Backups und Docker-Migrationen, während das Update läuft.

3. Stellen Sie bei einer kostenpflichtigen Installation sicher, dass der Opfield-Host den Lizenzdienst erreicht: Das Update lädt den signierten kommerziellen Kern von 2.11 herunter und stoppt, bevor die App ersetzt wird, wenn das nicht gelingt. Community-Installationen, die nie einen kostenpflichtigen Tarif hatten, werden ohne ihn aktualisiert.

4. Lesen Sie auf Community Upgrade einer Community-Installation von 2.10: Ab 2.11 benötigen Datenbanken (einschließlich in 2.10 gespeicherter externer Verbindungen), Speicher, die GitLab-Integration sowie Plan Mode, Scenarios und Sandboxes im AI Workspace Personal oder höher. Ihre Datensätze bleiben in der Datenbank und werden mit einem Schlüssel für Personal oder höher wieder nutzbar.

Das Update wendet die Datenbankmigrationen von 2.11 an. Bestehende Daten, die 2.11 nicht mehr zulässt, etwa zwei Workloads auf einem Host-Port eines Nodes, zwei aktivierte Routen mit demselben Namen auf einem Node oder doppelte aktive Backup-Läufe, werden im Audit-Log markiert, statt das Update scheitern zu lassen; siehe Durch das Update auf 2.11 aufgelöste Konflikte.

Wird das Update zurückgesetzt, startet 2.10.x wieder auf der bereits migrierten Datenbank und behält seine Berechtigungen und eine gültige Lizenz; ein erneutes Update stellt alles wieder her, was 2.11 hatte. Beheben Sie die in den Logs des Update-Containers angezeigte Ursache und aktualisieren Sie erneut. Um stattdessen zum Zustand vor dem Update zurückzukehren, legen Sie die gesicherte .env zurück, stoppen alle Dienste außer postgres (docker compose stop app relay registry redis), stellen gateway-2.10.dump mit den Befehlen DROP DATABASE und pg_restore aus Automatisches Rollback und die Datenbank-Momentaufnahme wieder her und führen docker compose up -d aus.

Update-Reihenfolge

1. Aktualisieren Sie Opfield.
2. Aktualisieren Sie die Node-Daemons mit Nodes > Update Nodes; die Seite listet jeden Docker, Nginx, Storage und Monitoring Node mit einem neueren Daemon auf und aktualisiert die ausgewählten gemeinsam.
3. Aktualisieren Sie den Relay-Pool mit Settings > General > Update Relay Pool.

Aktualisieren Sie Node-Daemons oder Relays nicht vor Opfield: Das Relay von 2.11 erfordert Opfield 2.11, und viele Funktionen und Korrekturen von 2.11 benötigen die Docker-, Nginx- und Relay-Releases von 2.11. Relays von 2.10 behalten die Relay-Richtlinien-Lease von 15 Minuten, bis sie aktualisiert werden.

Nach den Daemon- und Relay-Updates:

• Die erste Anwendung eines Compose-Projekts, selbst einer unveränderten Revision, erstellt seine Dienste einmal neu, weil sie die neuen Log-Einstellungen und ein Label mit dem Digest ihrer eigenen Konfiguration erhalten; spätere Revisionen erstellen nur die Dienste neu, die sie ändern; siehe Unterstützte Compose-Konfiguration. Deployment-Router begrenzen Request-Bodys ab ihrem nächsten Deploy, Slot-Wechsel oder Neustart nicht mehr.
• Docker-Availability-Richtlinien wechseln von selbst in den Lease-Modus, sobald jeder Docker Node, Ingress Node und jedes Relay des Workloads 2 Minuten lang 2.11 ausgeführt hat. Jeder Docker Node benötigt den Lease-Watchdog: Der Docker-Node-Installer installiert ihn, und ein Docker-Daemon von 2.11, der als root mit systemd oder OpenRC läuft, installiert ihn selbst. Andernfalls führt die Richtlinie den Node unter Excluded nodes auf; führen Sie den Docker-Node-Installer dort erneut mit sudo und demselben --user aus. Im Lease-Modus muss jeder Node der Richtlinie jedes Relay erreichen. Siehe Failover der Datenebene.
• Storage Nodes benötigen ausgehendes HTTPS zu ghcr.io, um den Backup-Runner herunterzuladen. Andere Laufzeit-Images von Drittanbietern kommen zuerst aus dem Opfield-Spiegel auf ghcr.io und fallen auf Docker Hub zurück.
• Externe PostgreSQL- und Key-Value-Verbindungen mit TLS, die vor 2.11 erstellt wurden, bleiben ungeprüft und zeigen eine Warnung. Führen Sie die Prüfung mit einem Klick aus oder fügen Sie die private CA hinzu; siehe Prüfung von TLS-Zertifikaten.
• In Opfield Inference vor 2.11 veröffentlichte Modelle Claude Fable 5.1 und Opus 5.5 haben deaktivierte Werkzeuge; öffnen und speichern Sie sie erneut.

Berechtigungen nach dem Update

• Gruppen, Benutzer, API-Tokens und OAuth-Berechtigungen, die einen ausgemusterten Scope-Namen hatten, haben dessen Ersatz erhalten, und ausgemusterte Namen werden bei der Eingabe noch zwei Releases lang akzeptiert. Skripte, die Scope-Namen zurücklesen, sollten die neuen Namen erwarten. Siehe Ausgemusterte Scope-Namen.
• Einige Ersatz-Scopes sind breiter als der alte Scope. Prüfen Sie Gruppen, Benutzerberechtigungen, API-Tokens und OAuth-Berechtigungen, die einen der folgenden hatten:
  • integrations:gitlab:ci:edit, :variables:edit, :variables:delete, :webhooks:manage und :registry:manage wurden zu integrations:gitlab:repo:write, das außerdem Repository-Dateien committet und CI-Konfiguration, CI/CD-Variablen, Webhooks und Registry-Einstellungen ändert. Ein CI-Token, das nur die Registry bereinigt hat, kann jetzt Commits pushen.
  • integrations:gitlab:ci:view wurde zu integrations:gitlab:repo:read, das außerdem Repository-Dateien liest.
  • integrations:gitlab:sync, :github:sync und :git:sync wurden zur Berechtigung manage des Connectors: Einstellungen, Tokens, Allowlist, Test und Löschen.
  • nodes:config:edit wurde zu nodes:manage, das außerdem die Secure Runtime installiert, Dienstadressen ändert sowie gehostete VMs ein- und ausschaltet, in der Größe ändert und aus Snapshots wiederherstellt.
  • proxy:advanced:bypass und proxy:raw:bypass wurden beide zu proxy:unrestricted, sodass jeder von ihnen jetzt beide Einschränkungen aufhebt.
  • proxy:templates:create, :edit und :delete wurden zu proxy:templates:manage, also jeder Operation mit nginx-Vorlagen.
  • notifications:alerts:create, :edit und :delete wurden zu notifications:alerts:manage, und notifications:webhooks:create, :edit und :delete wurden zu notifications:webhooks:manage, das außerdem Webhook-URLs, Header und Zustellungs-Payloads anzeigt.
  • docker:containers:folders:manage wurde zu docker:folders:manage, das die Ordner aller Docker-Ressourcentypen abdeckt.
• integrations:gitlab:variables:view wurde zu integrations:gitlab:repo:read und liest keine Werte von CI/CD-Variablen mehr; das Lesen von Werten erfordert integrations:gitlab:repo:write.
• Jede Aktionsberechtigung außer create schließt jetzt die View-Berechtigung ihrer Familie mit demselben Qualifier ein: Eine Gruppe oder ein Token, das nur eine Berechtigung zum Löschen, Bearbeiten, Verwalten oder Ausführen hatte, kann diese Ressourcen jetzt auch auflisten und ansehen. Prüfen Sie Berechtigungen, die nur Löschen erlauben.
• Integrierte Gruppen erhalten die neuen Berechtigungen automatisch. Benutzerdefinierte Gruppen nicht: Vergeben Sie bei Bedarf diagnostics:view und diagnostics:logs für die Opfield-Diagnose, databases:backups:view, :manage, :run und :restore, nodes:backups:execute sowie storage:view, :create, :edit, :delete, :iam, storage:objects:* und storage:credentials:use. storage:credentials:reveal schließt storage:credentials:use ein.
• Tokens sehen nie mehr als das Konto, das sie erstellt hat, und eine Create-Berechtigung zählt bei delegiertem Zugriff nicht mehr als View: Tokens von Benutzern, deren Zugriff eingeschränkt wurde, verlieren diesen Zugriff.
• Nach dem Update gespeicherte Git-Quellen bauen nur so lange automatisch, wie das Konto, das sie gespeichert hat, use für das Repository behält; Webhooks und automatische Deployments prüfen das Konto, das sie konfiguriert hat.
• Das Bereitstellen oder Aktualisieren eines Deployments mit neuem Image, Befehl oder neuer Umgebung und das Aktualisieren des Images eines Containers erfordern die Berechtigungen für Umgebung und Secrets; das Anbinden eines Containers an Netzwerke erfordert Bearbeitungszugriff auf Netzwerke. SQL mit Schreib-Scope auf einem externen PostgreSQL läuft Anweisung für Anweisung, und Schema- oder Rollenänderungen erfordern die Admin-Berechtigung.
• Die Grenzen des Community-Tarifs sind 25 verwaltete Nodes, 3 Benutzer und 1 benutzerdefinierte Berechtigungsgruppe (in 2.10: 100, 10 und 5). Nichts Bestehendes wird entfernt; das Erstellen weiterer wird abgelehnt.

Geändertes Verhalten

• TLS für unbekannte Namen. Ingress Nodes lehnen TLS-Handshakes für Hostnamen ab, die keine Route bedient. Clients oder Load Balancer, die sich per IP über HTTPS ohne SNI verbinden oder sich auf eine Standard-Site verlassen, werden abgewiesen. Nodes, deren nginx bereits einen eigenen Standardserver auf Port 443 hat, überspringen das mit einer Warnung. Siehe Routen.
• Compose-Einschränkungen. Compose-Projekte können weder das Host-Netzwerk noch die internen Netzwerke von Opfield (gateway-secure-links, gateway-db-*, gateway-storage-*) verwenden, die reservierten Labels von Opfield setzen oder Docker-Client-Variablen wie DOCKER_HOST, DOCKER_CONFIG, BUILDKIT_* und COMPOSE_* setzen. Bestehende Projekte, die gegen diese Regeln verstoßen, laufen weiter und können gestoppt und entfernt werden, aber eine neue Revision, Anwendung, ein Start oder Neustart wird abgelehnt, bis sie bearbeitet sind, einschließlich der ersten Anwendung nach dem Update des Docker-Daemons. Siehe Unterstützte Compose-Konfiguration.
• Prüfung von nginx-Direktiven. Der Inhalt von nginx-Vorlagen und die erweiterte Konfiguration zusätzlicher Routen werden wie die Routenkonfiguration geprüft: Ohne proxy:unrestricted werden verbotene Direktiven abgelehnt, und nginx-Logs können nur unter /var/log/nginx geschrieben werden. Vor dem Update gespeicherte Vorlagen werden weiter so gerendert, wie sie gespeichert wurden.
• Relay-Richtlinien-Lease. Relays arbeiten standardmäßig 72 Stunden ohne Opfield weiter (Settings > Relay, 1 Stunde bis 7 Tage); siehe Relays ohne Opfield.
• Bereinigung. Der Operationsverlauf – abgeschlossene Builds mit ihren Logs, Compose-, Availability- und Hosting-Operationen sowie Webhook-Zustellungen – wird 90 Tage aufbewahrt, und abgelaufene OAuth-Berechtigungen sowie OAuth-Clients, die die Autorisierung nie abgeschlossen haben, werden gelöscht. Ändern Sie Settings > Features > Housekeeping vor dem ersten Lauf, wenn Sie einen längeren Verlauf benötigen; siehe Bereinigung und Aufbewahrung.
• Verlängerung der internen PKI. Mit Routen verknüpfte Zertifikate der internen PKI werden vor dem Ablauf automatisch neu ausgestellt, wenn Opfield den privaten Schlüssel hält; die automatische Verlängerung wird für bestehende Verknüpfungen eingeschaltet.
• Rotation von GitLab-Tokens. GitLab-Tokens mit dem Scope api oder self_rotate, die innerhalb von 14 Tagen ablaufen, werden von Opfield rotiert, wobei das alte Token widerrufen wird. Geben Sie Opfield ein eigenes Token, wenn dasselbe Token anderswo verwendet wird; siehe Ablauf und Rotation von Tokens.
• Einstellungen. Das Speichern der Einstellungen startet Opfield nur neu, wenn internes HTTPS umgeschaltet wird oder sich die Public URL bei eingeschaltetem internem HTTPS ändert. Anmeldemethoden, MFA, der OIDC-Anbieter und die Identitätsbereitstellung sind nach Settings > Authentication umgezogen, das strukturierte Logging befindet sich unter Settings > Features, und Authentication email (SMTP) heißt jetzt SMTP configuration.
• API. Node-Abfragen enthalten kein Material von Registrierungstokens mehr, ein leeres Node-Update liefert 400, und eine fehlerhafte ID liefert 404. Änderungen an Umgebung, Neuerstellung und Compose-Revision liefern 409, solange ein Build-Rollout das Ziel besitzt. Ein unbekannter /api-Pfad liefert einen JSON-404.
• Docker Availability ist nicht mehr als Tech Preview gekennzeichnet, und Builds können nicht mehr an das Dashboard oder die Seitenleiste angeheftet werden.

Durch das Update auf 2.11 aufgelöste Konflikte

Opfield 2.11 erzwingt mehrere Eindeutigkeitsregeln in seiner Datenbank statt nur im Anwendungscode, sodass sie auch gelten, wenn mehrere Opfield-Prozesse gleichzeitig Anfragen bearbeiten. Das Update scheitert nie an bestehenden Daten, die gegen eine davon verstoßen: Migration 0207 behält den frühesten Datensatz, markiert oder benennt die anderen um und schreibt jeden Fall in das Audit-Log. Durchsuchen Sie nach dem Update das Audit-Log nach diesen Aktionen und lösen Sie auf, was sie melden.

Regel nach dem Update	Was das Update mit bestehenden Konflikten getan hat	Audit-Aktion
Zwei aktivierte Routen auf einem Ingress Node können nicht denselben Namen bedienen (409 PROXY_HOST_DOMAIN_CONFLICT)	Die früheste Route behält den Namen. Spätere behalten ihre Konfiguration und bleiben markiert, bis sich ihre Namen oder ihr Node ändern. Eine solche Route kann nach dem Deaktivieren nicht wieder aktiviert werden, solange eine andere aktivierte Route den Namen bedient. nginx bedient nur eine von ihnen; entfernen Sie also den Namen aus einer Route oder deaktivieren Sie sie	proxy_host.domain_conflict
Eine Backup-Richtlinie hat ein eingereihtes oder laufendes Backup (409 BACKUP_ALREADY_RUNNING), und es läuft jeweils nur eine Wiederherstellung in einen bestimmten neuen Datenbanknamen (409 BACKUP_RESTORE_ALREADY_RUNNING)	Ein aktiver Lauf wird fortgesetzt: ein laufender vor einem eingereihten, sonst der neueste. Die anderen werden mit der Phase superseded als fehlgeschlagen markiert, geben ihren Executor frei, und ihre Runner werden abgebrochen	database.backup.superseded
Namen von verwaltetem Speicher sind pro Storage Node eindeutig (409 MANAGED_STORAGE_NAME_IN_USE)	Der früheste Cluster behält den Namen. Spätere und ihre Speicherverbindungen werden mit dem ersten freien Suffix -2, -3, … umbenannt	storage.managed.renamed_duplicate
Ein Host-Port auf einem Node gehört zu einem Deployment, einem verwalteten Speicher oder einer verwalteten Datenbank (409 DEPLOYMENT_HOST_PORT_IN_USE, MANAGED_STORAGE_PORT_CONFLICT oder MANAGED_DATABASE_PORT_CONFLICT)	Der früheste Workload behält den Port. Spätere laufen weiter und werden markiert; verschieben Sie einen von ihnen auf einen anderen Port	node.host_port_conflict
Ein von einer Route verwendetes Zertifikat kann nicht gelöscht werden (409 CERT_IN_USE)	Nichts aufzulösen: Die Datenbank erzwingt jetzt die bestehende Prüfung	—

Host-Ports, die der Docker-Daemon für eine verwaltete Datenbank wählt, meiden die Ports, die andere Workloads auf diesem Node reservieren. Eine verwaltete Datenbank, deren veröffentlichter Port noch mit der Reservierung eines anderen Workloads kollidiert, führt dies in managed.hostPortConflicts ihrer Datenbankverbindung auf, mit dem Port und dem Workload, der ihn hält.

Das Update löscht keine Routen, Workloads, Speicher oder Backups und stoppt keine laufenden Workloads. Clients, die verwalteten Speicher umbenennen oder ihn nach Namen nachschlagen, sollten auf die umbenannten Cluster geprüft werden.

Update auf 2.11.1

2.11.1 verlegt Datenbank-Bindings und Speicherverbindungen auf einen gemeinsamen Secure-Link-Connector pro Docker Node und fügt Container-Links hinzu. Aktualisieren Sie zuerst Opfield, dann die Docker-Daemons. Was auf jedem Node nach dem Update seines Docker-Daemons geschieht:

• Jeder Workload mit einem Datenbank-Binding wird einmal neu erstellt, auf jedem Node einer nach dem anderen, der nächste, sobald der vorherige fehlerfrei läuft. Deployments werden per Blue/Green ohne Ausfallzeit ausgerollt; eigenständige Container und Compose-Dienste starten einmal neu, planen Sie das Update von Nodes mit solchen Workloads also entsprechend.
• Jeder Workload mit einer vor 2.11.1 erstellten Speicherverbindung wird einmal neu erstellt, direkt nachdem seine Verbindung umgestellt wurde. Auf 2.11.1 erstellte Verbindungen benötigen keine Neuerstellung.
• Variablennamen und Zugangsdaten ändern sich nicht, und es ist nichts von Hand zu tun. Löschen Sie alte Verbindungsnetzwerke oder Container nicht selbst.
• Das Zurücksetzen eines Docker-Daemons auf 2.11.0 stellt seine Verbindungen automatisch zurück, mit einer Neuerstellung pro Workload. Pro Node werden höchstens vier Workloads gleichzeitig neu erstellt, das Limit des Daemons für gleichzeitige Befehle; auf einem Node mit vielen verbundenen Deployments verbinden sich die späteren daher etwas später.
• Spätere Connector-Updates halten offene Verbindungen: Ab 2.11.4 übergibt der vorherige Connector sie ohne erneuten Verbindungsaufbau an den neuen. Ein Connector von vor 2.11.4 hält sie bis zu einer Stunde und schließt sie dann einmal; ein drittes Update innerhalb dieser Stunde schließt die Verbindungen des ältesten Connectors sofort.

Neue Verbindungsnetzwerke verwenden einen eigenen Adressbereich, standardmäßig 10.213.x.x (ein /16). Überschneidet er sich mit einem Netzwerk, das Ihre Nodes über ihre Standardroute erreichen, setzen Sie docker.secure_links.subnet_pool, bevor Sie den Docker-Daemon aktualisieren, damit die verlegten Verbindungen bereits Ihren Bereich verwenden (frühere Daemons ignorieren den Schlüssel); siehe Gemeinsamer Connector und Verbindungsnetzwerke.

Update auf 2.12

2.12 bringt Apps, Datenbanken und Speicher auf mehreren Servern, Valkey-Key-Value-Stores, geschützte Relays und die Opfield Cloud. Einer Installation mit 2.11 wird zuerst 2.11.5 und dann 2.12 angeboten. Aktualisieren Sie zuerst Opfield, dann die Node-Daemons, dann den Relay-Pool. Was Sie erwartet:

• Dienstadressen. Opfield 2.12 liest Releases und Node-Installer von get.opfield.dev und verwendet die Adressen des Lizenzdienstes, die unter Update-Voraussetzungen aufgeführt sind. Erlauben Sie get.opfield.dev und license.opfield.dev vor dem Update in einer Egress-Allowlist.
• Image-Repository. Images werden nach ghcr.io/opfield/opfield veröffentlicht. Setzen Sie für ein manuelles Update GATEWAY_IMAGE_REF in .env auf ein Image dort (OPFIELD_IMAGE_REF ab 2.12.1).
• Kürzere Seitenleiste. Domains, Ingress Groups, Access Lists und nginx-Templates sind Tabs von Routes; SSL-Zertifikate, Authorities, PKI Certificates und Zertifikats-Templates sind Tabs von Certificates; Profile befindet sich im Kontomenü. Alte Seitenadressen öffnen den passenden Tab.
• Key-Value-Stores behalten Redis. Bestehende verwaltete Key-Value-Stores laufen weiter mit Redis und funktionieren weiter. Neue Stores laufen mit Valkey. Verschieben Sie einen bestehenden Store mit Move to Valkey, wenn es Ihnen passt, und erstellen Sie dann ein neues Backup: Ein Backup lässt sich nur in die Engine wiederherstellen, aus der es stammt.
• Docker-Daemons. Move to Valkey, der Betrieb einer Datenbank oder eines Speichers auf mehreren Servern und die Container-Isolierung durch den Notschalter der App erfordern den Docker-Daemon von 2.12 auf den beteiligten Storage und Docker Nodes; Opfield fordert Sie auf, einen zu alten Daemon zu aktualisieren.
• Relays. Der geschützte Modus und das Hosten von Datenbank-Witnesses erfordern das Relay von 2.12. Führen Sie das Update des Relay-Pools nach den Daemons aus.
• Nichts verschiebt sich von selbst. Bestehende Ressourcen treten keiner App bei, und keine Datenbank und kein Speicher beginnt auf mehreren Servern zu laufen, bis Sie es einschalten.

Update auf 2.12.1

2.12.1 schließt den Umzug auf die Opfield-Namen ab. Nachdem sich das Update auf 2.12.1 gesetzt hat (etwa zehn Minuten, nachdem die neue Version fehlerfrei wurde, damit das automatische Rollback der früheren Version vorbei ist), zieht eine vor 2.12.1 erstellte Installation einmal selbst um:

• das Verzeichnis /opt/gateway wird zu /opt/opfield; /opt/gateway bleibt als Verknüpfung darauf erhalten;
• das Compose-Projekt, die Container (opfield-app-1, …) und das Netzwerk (opfield_default) erhalten den neuen Namen;
• die Datenbank und ihre Rolle werden in opfield umbenannt, und die Einstellungen in .env heißen OPFIELD_*;
• das verwaltete lokale ClickHouse wird zu opfield-clickhouse mit der Datenbank opfield_logs;
• Docker-Volumes behalten ihre Namen (gateway_gateway_data, gateway_postgres_data, …): docker-compose.yml bindet sie über den Namen ein, sodass nichts kopiert wird und kein zusätzlicher Speicherplatz nötig ist.

Während des Umzugs ist Opfield etwa eine Minute lang nicht verfügbar, und Secure Links über das Relay auf dem Opfield-Host brechen einmal für einige zehn Sekunden ab, während der Stack neu erstellt wird. Laufende Orchestrierungsoperationen werden zuerst abgeschlossen, wie vor einem Update. Wenn Sie mit dem Installer aktualisieren, zieht er die Installation direkt nach dem Update um und gibt das neue Verzeichnis aus.

Der Umzug läuft im Container opfield-host-move und protokolliert jeden Schritt in .opfield-host-move/state.json im Installationsverzeichnis. Nach einem Absturz oder Neustart startet Docker ihn erneut, und er macht dort weiter, wo er aufgehört hat. Schlägt ein Schritt wiederholt fehl, macht der Umzug rückgängig, was er getan hat, und Opfield läuft wie zuvor aus /opt/gateway; er versucht es nach sechs Stunden erneut, höchstens dreimal. docker logs opfield-host-move zeigt jeden Schritt. Um es sofort erneut zu versuchen:

docker rm opfield-host-move
cd /opt/gateway && curl -fsSL https://get.opfield.dev | bash

Eine Rückkehr zu 2.12.0 nach dem Umzug wird nicht unterstützt. Die System-CAs zeigen ihre neuen Namen (Opfield Node CA, Opfield Database CA, Opfield Storage CA); ihre Zertifikate bleiben bestehen, sodass Nodes, Relays und Ihre Anwendungen, die ihnen vertrauen, weiter funktionieren. Installer-Skripte, die GATEWAY_*-Variablen setzen, funktionieren weiter; die OPFIELD_*-Namen haben Vorrang, wenn beide gesetzt sind.

Daemon- und Relay-Updates

Aktualisieren Sie jeweils eine Fehlerdomäne. Leeren, aktualisieren, prüfen und reaktivieren Sie bei Mitgliedern des Relay-Pools jedes Mitglied, bevor Sie zum nächsten übergehen. Prüfen Sie bei gewöhnlichen Nodes nach dem erneuten Verbindungsaufbau die rollenspezifischen Ressourcen. Aktualisieren Sie nicht alle Ingress-, Storage- oder Relay-Mitglieder gleichzeitig, es sei denn, die Umgebung hat einen unabhängig getesteten Wiederherstellungsweg.

Nodes > Update Nodes aktualisiert die Daemons mehrerer Nodes gemeinsam, und Opfield lehnt Daemon-Updates für getrennte Nodes, Relay Nodes und Nodes ab, die das Release bereits ausführen; siehe Daemon-Updates. Aktualisieren Sie nach einem Opfield-Update die Node-Daemons vor dem Relay-Pool, insbesondere beim Umstieg von 2.10: Das Update des Relay-Pools aktualisiert auch das lokale Relay und erstellt es sofort neu, solange es ein Release älter als 2.11.1 ausführt, und aktuelle Daemons verbinden sich innerhalb eines Sekundenbruchteils erneut damit; siehe Relay und Relay-Pool. Daemon- und Relay-Updates von Nodes, die am Failover der Datenebene teilnehmen, werden von Opfield nacheinander ausgeführt, jeweils ein Mitglied jeder Availability-Richtlinie, sodass ein Update auf seine Lease-Partner warten kann.

Wiederherstellungsverfahren

1. Stellen Sie eine saubere, kompatible Opfield-Umgebung bereit.
2. Stellen Sie PostgreSQL und persistente Volumes vom selben Wiederherstellungspunkt wieder her.
3. Stellen Sie Verschlüsselungs-, PKI- und Relay-Identitätsmaterial mit den ursprünglichen Berechtigungen wieder her.
4. Starten Sie interne Abhängigkeiten, Opfield und Relay in der dokumentierten Reihenfolge.
5. Prüfen Sie Anmeldung und Entschlüsselung, bevor Sie Änderungen zulassen.
6. Lassen Sie verwaltete Nodes sich mit ihren bestehenden Identitäten erneut verbinden.
7. Gleichen Sie Routen, Zertifikate, Workloads, Datenbank-Bindings, Benachrichtigungen und Integrationen ab.
8. Stellen Sie Anwendungsdatenbanken bei Bedarf über engine-native Verfahren wieder her.
9. Bestätigen Sie die Lückenlosigkeit des Audits und halten Sie das Wiederherstellungsereignis fest.

Ist nur ein Teil des Wiederherstellungssatzes verfügbar, halten Sie an und bewerten Sie die Folgen. Das Erzeugen neuer Master-Schlüssel oder Identitäten kann verschlüsselten Zustand oder verwaltete Nodes dauerhaft verwaisen lassen.

Rollback-Entscheidung

Legen Sie den Auslöser für ein Rollback fest, bevor Sie ein Update beginnen: fehlgeschlagene Migration, Unfähigkeit, bestehende Secrets zu entschlüsseln, fehlgeschlagene Relay-Autorisierung, inkompatibler Daemon-Zustand, defekte Kundenrouten oder eine andere messbare Bedingung. Bewahren Sie die vorherigen freigegebenen Image-Referenzen und das passende Backup auf, bis das neue Release sein Beobachtungsfenster abgeschlossen hat.

Anwendungs-Rollback und Daten-Rollback sind getrennt. Abgesehen vom automatischen Rollback eines Updates, das nie fehlerfrei wurde, macht das Zurücksetzen eines Opfield-Images eine abgeschlossene PostgreSQL-Schemamigration nicht rückgängig, und das Zurücksetzen eines Workloads auf ein älteres Artefakt setzt veränderliche Volume- oder Datenbankdaten nicht zurück. Folgen Sie den release-spezifischen Kompatibilitätshinweisen und stellen Sie Daten nur von einem koordinierten Wiederherstellungspunkt wieder her, wenn die Integrität es erfordert.

Prüfung durch den Operator nach dem Update

Ebene	Erforderlicher Nachweis
Identität	Bestehende Benutzer melden sich an; MFA, OAuth und Entschlüsselung funktionieren
Control Plane	Migrationen sind abgeschlossen; Hintergrundplaner und Audit laufen weiter
Relay und Nodes	Versionen sind kompatibel; Nodes verbinden sich mit frischem Inventar erneut
Kundenverkehr	Externes DNS, TLS, Health-Zustand der Route und Anwendungsantwort sind erfolgreich
Daten	Verwaltete Datenbanken sind fehlerfrei, und Anwendungs-Bindings können abfragen
Automatisierung	Builds, Webhooks, Benachrichtigungen und von der Installation genutzte Quell-Connectors funktionieren

Bewahren Sie das Update-Protokoll mit Start- und Endzeit, Versionen, Image-Digests, Backup-Kennungen, Operator, Ausnahmen und abschließender Prüfung auf. So wird das nächste Update ein kontrolliertes Verfahren statt einer Rekonstruktion aus dem Shell-Verlauf.