Aktualisieren, Backups und Rollback

Aktualisieren

Updates kommen als neues Distributionsarchiv. Es gibt zwei Wege, eines einzuspielen.

Der Knoten holt es sich

sudo scripts/tc-operator/tc-operator update --config operator.yaml

Der Knoten holt das Release-Manifest, vergleicht es mit der installierten Version, und lädt, falls es eine neuere gibt, diese herunter, verifiziert ihre Prüfsumme, entpackt sie und führt den Installer des neuen Archivs erneut aus. Er braucht kein Terminal, du kannst ihn also zeitgesteuert laufen lassen.

Die Verbindung ist ausschließlich ausgehend — der Knoten holt, die Zentrale verbindet sich nie hinein —, das funktioniert also auch hinter einer Firewall. Die Signatur des Manifests wird geprüft, bevor irgendein Feld darin als vertrauenswürdig gilt, denn der Update-Weg entpackt ein Archiv über die laufende Installationswurzel und führt dessen Installer als root erneut aus. --force installiert erneut, selbst wenn der Knoten bereits aktuell ist.

Du spielst ein Archiv von Hand ein

Du bekommst zwei Dateien: den Tarball und eine Prüfsummen-Sidecar-Datei.

# 1. Das Archiv verifizieren, bevor du irgendetwas anfasst
sha256sum -c trusted-codes-operator-<version>-<sha>.tar.gz.sha256

# 2. Über den bestehenden Baum entpacken, an Ort und Stelle. Lösche das
#    Verzeichnis nicht zuerst — die laufenden Container mounten Pfade
#    darin per Bind-Mount.
sudo tar -xzf trusted-codes-operator-<version>-<sha>.tar.gz -C /opt/trusted-codes

# 3. Die Installation erneut ausführen. --archive behält diesen Build,
#    damit du zu ihm zurückrollen kannst.
cd /opt/trusted-codes
sudo scripts/tc-operator/tc-operator install --config operator.yaml \
  --archive ~/trusted-codes-operator-<version>-<sha>.tar.gz

Was der erneute Lauf tut

Unangetastet erhalten: deine operator.yaml, alles unter /etc/trusted-codes — Geheimnisse, mTLS-Identität, Backups — und alle Daten in der Datenbank. Geheimnisse werden bei einem erneuten Lauf wiederverwendet, nie rotiert.

Angewendet: nur neue Migrationen, da bereits angewendete übersprungen werden; Referenzdaten werden erneut angewendet; die Function-Laufzeit wird neu gestartet, damit sie den neuen Code bedient; Oberflächen werden neu gebaut und neu gestaged; die veröffentlichten Informationen des Knotens werden neu signiert; das README auf der Box wird neu erzeugt.

Aufgezeichnet: der Build, sichtbar in status und am Kopf des On-Box-README. Mit --archive wird der Tarball unter /etc/trusted-codes/archives behalten — die letzten fünf —, sodass ein Rollback kein erneutes Herunterladen braucht.

Verweigert: Ein älteres Archiv über einen neueren Knoten zu installieren bricht ab, weil es den Code zurückrollen würde. --allow-downgrade fährt fort, falls das Absicht ist, und rollback setzt das für dich.

Nicht nötig: finalize-tls. Der Proxy bedient die neu gestagten Dateien sofort von der Platte. Führ es nur erneut aus, wenn du Domains geändert hast.

Prüf tc-operator status nach jedem Update. Es gibt den gerade laufenden Build aus.

Zurückrollen

scripts/tc-operator/tc-operator rollback                    # behaltene Builds auflisten
sudo scripts/tc-operator/tc-operator rollback --to <version|sha>

Er entpackt diesen Build erneut und führt die Installation erneut aus, und bittet dich, das Ziel einzutippen, um zu bestätigen.

Rollback setzt nur Code zurück — Edge Functions, Oberflächen, Installer-Skripte. Er setzt das Datenbankschema nicht zurück. Migrationen sind nur vorwärts gerichtet, der ältere Code läuft also gegen das aktuelle Schema. Das ist unproblematisch für ein Release, das nur etwas hinzugefügt hat. Es ist nicht in Ordnung für eines, das etwas entfernt oder umbenannt hat, das der alte Code liest.

Ein echtes vollständiges Rollback ist eine Wiederherstellung aus einem Datenbank-Dump, kein erneutes Entpacken von Code.

Backups

Der Installer nimmt automatisch in genau einem Fall einen Datenbank-Dump: wenn du deinstallierst. Ein laufender Knoten braucht deinen eigenen Zeitplan.

Du brauchst beide Hälften

1. Die Datenbank — Konten, Verbindungen, Daten.
2. /etc/trusted-codes/secrets.env — die Identität des Knotens und seine Verschlüsselungsschlüssel: der Föderations-Signaturschlüssel, das JWT-Secret, der Verschlüsselungsschlüssel für personenbezogene Daten, das Datenbankpasswort.

Wiederhergestellte Daten sind unlesbar ohne den ursprünglichen Verschlüsselungsschlüssel, und ein ohne diese Datei neu aufgebauter Knoten bekommt eine brandneue Föderationsidentität. Sichere sie zusammen mit jedem Dump und bewahre sie offline auf. Ein Dump allein ist kein Backup.

Eines erstellen

source /etc/trusted-codes/secrets.env
docker exec -e PGPASSWORD="$POSTGRES_PASSWORD" tcnode-db \
  pg_dump -U supabase_admin -d postgres \
  | gzip > tc-backup-$(date -u +%Y%m%dT%H%M%SZ).sql.gz

Der Container ist <projekt>-db; bei einer Standardinstallation ist das tcnode-db, und docker ps zeigt ihn. Das ist derselbe Dump, den uninstall nimmt. Kopiere das Ergebnis und ein aktuelles secrets.env von der Box, und plane das für jede echte Installation ein.

Auf einer frischen Box wiederherstellen

1. Die Box bereitstellen und das Archiv daraufbringen.

2. Zuerst dein gesichertes secrets.env wiederherstellen, nach /etc/trusted-codes/secrets.env, Modus 0600. Das erhält die Identität des Knotens und den Schlüssel, der die Daten entschlüsselt. Ohne das Original sind die wiederhergestellten Zeilen unlesbar.

3. Deine operator.yaml wiederherstellen und tc-operator install ausführen. Der Stack kommt hoch und spielt das Schema ein. Es gibt noch keine Nutzerdaten.

4. Den Dump laden:

   source /etc/trusted-codes/secrets.env
   gunzip -c tc-backup-<ts>.sql.gz \
     | docker exec -i -e PGPASSWORD="$POSTGRES_PASSWORD" tcnode-db \
         psql -U supabase_admin -d postgres

Der Dump ist eine vollständige logische Momentaufnahme. Ihn über das frisch migrierte Schema zu laden gibt harmlose „already exists”-Hinweise für Objekte aus, die die Migrationen ebenfalls angelegt haben; die Datenzeilen sind es, die deine Nutzer wiederherstellen. Verifiziere mit tc-operator status und einer Test-Anmeldung.

Probe das auf einer Wegwerf-Box, bevor du es im Ernstfall tun musst. Der Schritt, den Leute falsch machen, ist der zweite, und sie merken es im ungünstigsten Moment.