Updates
Restow wird als Docker-Images ausgeliefert, ein Build je Release, mit automatisch angewendeten Datenbankmigrationen. Es gibt zwei Wege zu aktualisieren:
- Von Hand, mit
docker compose. Das ist der Standard und funktioniert immer. Die nächsten Abschnitte beginnen dort. - Über die Weboberfläche, unter Einstellungen → Updates. Restow sagt Ihnen, wenn es eine neuere Version gibt, und installiert sie, wenn Sie den Updater-Dienst aktivieren, für Sie: mit einem Countdown für alle angemeldeten Personen, zuerst einer Datenbanksicherung und einem automatischen Zurücksetzen, wenn die neue Version nicht startet.
Auf dieser Seite passiert nichts, solange Sie es nicht einschalten. Eine frische Installation sucht nicht nach Updates, kontaktiert dafür keinen Server und startet den Updater nicht.
Vor jedem Update
Abschnitt betitelt „Vor jedem Update“-
Lesen Sie die Release-Notes jeder Version zwischen Ihrer und der neuen, besonders Breaking Changes und Update-Aufwand. Jedes Release nennt seinen Update-Aufwand (siehe die drei Arten unten), dazu die erwartete Ausfallzeit und den Weg zurück.
-
Sichern Sie die Datenbank. Sie enthält Metadaten, die Job-Warteschlange und das Audit-Log. Gesicherte Inhalte liegen im Chunk-Store und werden von einem Update nicht angefasst.
Terminal-Fenster docker compose exec -T postgres pg_dump -U restow -Fc restow > restow-$(date +%F).dumpDer Updater erledigt das selbst (siehe unten).
-
Prüfen Sie, dass
RESTOW_MASTER_KEYoffline gesichert ist. Ein Update ändert ihn nie, aber ohne ihn lässt sich keine Sicherung lesen. Siehe Restow selbst sichern.
Die drei Arten von Updates
Abschnitt betitelt „Die drei Arten von Updates“1. Nur Konfiguration
Abschnitt betitelt „1. Nur Konfiguration“Nur Werte in der .env ändern sich (eine neue optionale Variable, eine geänderte Einstellung).
docker compose up -dup -d erstellt die Container neu, deren Konfiguration sich geändert hat. docker compose restart ist kein Update: Es startet die laufenden Container mit ihrem alten Image und ihrer alten Umgebung neu und übernimmt weder ein neues Image noch eine geänderte .env.
2. Neues Image, mit automatischen Migrationen
Abschnitt betitelt „2. Neues Image, mit automatischen Migrationen“Der übliche Fall. Restow wendet Datenbankmigrationen selbst an: Der api-Container führt sie als Datenbankbesitzer (DATABASE_MIGRATION_URL) aus, bevor er eine Anfrage bedient, und startet nicht, wenn eine fehlschlägt. Die Release-Notes sagen, ob es Migrationen gibt und wie lange sie ungefähr dauern.
Release-Stack (die veröffentlichten Images, deploy/release/docker-compose.yml). Tragen Sie die Version in die .env ein und ziehen Sie die Images:
RESTOW_IMAGE=ghcr.io/restow-backup/restow:X.Y.ZRESTOW_WEB_IMAGE=ghcr.io/restow-backup/restow-web:X.Y.Zdocker compose pulldocker compose up -dHat der Updater jemals RESTOW_IMAGE und RESTOW_WEB_IMAGE in die .env geschrieben, bestimmen diese beiden Zeilen, welche Images die Dienste ausführen. Ändern Sie sie, oder entfernen Sie sie, um wieder aus einem Quellcode-Checkout zu bauen.
Quellcode-Checkout (die docker-compose.yml des Repositorys, die aus dem Quellcode baut):
git fetch --tagsgit checkout vX.Y.Zdocker compose up -d --buildVerfolgen Sie dann die Migrationen und den Start:
docker compose logs -f apiDas Log zeigt restow: applying database migrations, danach restow: starting role 'api'.
3. Manuelle Schritte
Abschnitt betitelt „3. Manuelle Schritte“Ein Release, das mehr braucht als die Befehle oben (eine neue Pflichtvariable, eine geänderte Compose-Datei, einen einmaligen Befehl), nennt jeden Schritt in der richtigen Reihenfolge unter Update-Aufwand und Breaking Changes. Führen Sie sie in dieser Reihenfolge aus, vor oder nach docker compose up -d, genau wie beschrieben. Der Updater kennt solche Schritte nicht: Er wendet das Image an und startet die Dienste neu. Lesen Sie zuerst die Notes, und aktualisieren Sie von Hand, wenn dort mehr steht.
Nach dem Update
Abschnitt betitelt „Nach dem Update“curl -fsS http://127.0.0.1:3000/healthzcurl -fsS http://127.0.0.1:3000/readyzdocker compose psPrüfen Sie dann die Version unten in der Seitenleiste der Weboberfläche und starten Sie für einen Mandanten Jetzt prüfen: Eine bestandene Restore-Prüfung belegt, dass die neue Version noch lesen kann, was die alte geschrieben hat.
Einstellungen → Updates
Abschnitt betitelt „Einstellungen → Updates“Der Reiter ist für alle Provider-Administratoren sichtbar. Er zeigt die laufende Version, den Release-Kanal, die neueste Version mit Tag und Veröffentlichungsdatum, einen Link zu den Release-Notes (und die Notes selbst, sicher dargestellt und eingeklappt), den Stand der letzten Prüfung und ob ein Update verfügbar ist.
Wer ändern darf. Einstellungen ändern, Jetzt prüfen, ein Update ankündigen, abbrechen und ausblenden erfordern die Rolle Inhaber im Provider-Team. Der vom Einrichtungsassistenten angelegte Administrator ist Inhaber. Alle anderen sehen nur den Status. Siehe Team und Rollen.
Die Prüfung einschalten
Abschnitt betitelt „Die Prüfung einschalten“Die Prüfung ist standardmäßig aus. Schaltet ein Inhaber sie ein (Einmal täglich auf Updates prüfen), liest Restow einmal täglich die Release-Liste der Update-Quelle und jedes Mal, wenn Sie Jetzt prüfen drücken. Nach einer fehlgeschlagenen Prüfung versucht es frühestens nach einer Stunde erneut.
Was gelesen wird. Nur die Release-Liste der Quelle. Keine Anfrage trägt Daten über Ihre Installation, und das Ergebnis wird zwischengespeichert. Wie bei jeder Web-Anfrage sieht die Quelle die Adresse, von der Ihr Server sich verbindet. Schlägt eine Prüfung fehl, nennt der Reiter den Grund und zeigt weiter das letzte gute Ergebnis:
| Grund | Bedeutung |
|---|---|
| Rate-Limit | Die Quelle hat weitere Anfragen vorerst abgelehnt. Der Reiter zeigt, wann es endet. |
| Token abgelehnt | Der Zugriffstoken ist falsch, abgelaufen oder widerrufen. |
| Nicht gefunden | Das Repository existiert nicht, oder es ist privat und es ist kein Token gespeichert. |
| Zugriff verweigert | Der Token darf die Releases dieses Repositorys nicht lesen. |
| Quellenfehler, keine Antwort | Die Quelle hat mit einem Serverfehler geantwortet, nicht rechtzeitig reagiert oder war nicht erreichbar. |
| Keine Release-Liste | Die Adresse hat geantwortet, aber nicht mit Releases. |
| Kein Release veröffentlicht | Die Quelle hat für diesen Kanal noch kein Release. |
| Weiterleitung abgelehnt | Die Quelle hat auf einen anderen Host weitergeleitet. Restow folgt dem nicht, tragen Sie stattdessen die endgültige Adresse des Repositorys ein. |
Quelle, Kanal und Token
Abschnitt betitelt „Quelle, Kanal und Token“- Quelle. Standard sind die öffentlichen Releases von
https://github.com/restow-backup/restow. Sie können auf ein eigenes Repository verweisen: ein GitHub-Repository oder ein Forgejo- oder Gitea-Repository (deren Releases-API ist kompatibel), zum Beispielhttps://git.example.com/acme/restow. Akzeptiert werden nurhttps-Adressen ohne Zugangsdaten in der URL, weil ein Zugriffstoken mit der Anfrage reist. - Kanal. Stabil bietet nur finale Releases an. Beta bietet zusätzlich Vorabversionen wie
0.3.0-rc.1. Versionen werden als Semantic Versions verglichen, eine Vorabversion steht also vor ihrem Release. Ein Release wie 0.1.0 ist ein gewöhnliches Release, das auch der Kanal Stabil anbietet. - Zugriffstoken. Für ein privates Repository hinterlegen Sie einen Zugriffstoken mit Leserechten. Er wird verschlüsselt in der Datenbank gespeichert, nur als
Authorization-Header an den eigenen Host der Quelle gesendet, nie wieder angezeigt (der Reiter sagt nur, ob einer gespeichert ist, und lässt Sie ihn ersetzen oder entfernen) und nie in ein Log oder das Audit-Log geschrieben. Verweisen Sie die Quelle auf einen anderen Host, wird der gespeicherte Token entfernt, statt Ihnen dorthin zu folgen. Ein privates Repository wird aus dem Quellcode gebaut (siehe unten).
RESTOW_UPDATE_CHECK_URL und ihr Vorrang
Abschnitt betitelt „RESTOW_UPDATE_CHECK_URL und ihr Vorrang“RESTOW_UPDATE_CHECK_URL ist ein Umgebungs-Override, der älter ist als der Reiter und weiter funktioniert. Vom stärksten zum schwächsten:
RESTOW_UPDATE_CHECK_URL, wenn sie auf einehttps-Adresse gesetzt ist. Die Prüfung ist an, die Quelle ist diese Adresse, und der Reiter zeigt sie schreibgeschützt. Ein gespeicherter Token wird dorthin nie gesendet. Akzeptiert werden: eine GitHub-Adressehttps://api.github.com/repos/<owner>/<repo>/releases(oder.../releases/latest), eine Forgejo- oder Gitea-Adresse.../api/v1/repos/<owner>/<repo>/releasesoder jede anderehttps-Adresse, die dasselbe JSON liefert. Der Kanal lässt sich im Reiter weiterhin ändern.- Die Einstellungen des Reiters (Schalter, Quelle, Kanal, Token).
- Die Standardwerte: aus, die öffentlichen Releases des Projekts, stabil.
Der Alarm „Update verfügbar“
Abschnitt betitelt „Der Alarm „Update verfügbar““Einmal je neuer Version löst Restow einen Alarm Update verfügbar aus: einen Eintrag in der Benachrichtigungsglocke der Provider-Administratoren und die Alarmregeln unter Alarme & Berichte, die das Ereignis Update verfügbar führen (E-Mail, Webhook), in jedem Mandanten. Nur Provider-Administratoren können eine Regel für dieses Ereignis anlegen, die eigenen Administratoren eines Mandanten erfahren nichts von Ihren Updates. Dieselbe Version löst ihn nie zweimal aus. Siehe Alarme und Berichte.
In der Integrations-API
Abschnitt betitelt „In der Integrations-API“GET /api/v1/status enthält ein Objekt version, damit ein RMM Installationen markieren kann, die zurückgefallen sind: running, latest, updateAvailable (null, wenn unbekannt), releaseUrl, updateCheck (disabled, pending, ok oder failed), checkedAt, channel, latestTag, publishedAt, checkError (der Grundcode einer fehlgeschlagenen Prüfung) und maintenance (ein angekündigtes oder laufendes Update: phase, targetVersion, startsAt). Felder wurden bisher nur hinzugefügt, nie umbenannt oder entfernt. Siehe Integrations-API.
Der Updater (opt-in)
Abschnitt betitelt „Der Updater (opt-in)“Der Reiter Updates zeigt Update installieren nur, wenn der Updater-Dienst läuft. Ohne ihn zeigt der Reiter stattdessen die manuellen Schritte dieser Seite.
Aktivieren
Abschnitt betitelt „Aktivieren“-
Tragen Sie in der
.envden absoluten Pfad des Verzeichnisses ein, dasdocker-compose.ymlund.enventhält. Der Updater hängt es unter demselben Pfad ein, sodass relative Pfade in der Compose-Datei so aufgelöst werden wie auf dem Host.Terminal-Fenster RESTOW_PROJECT_DIR=/opt/restow -
Starten Sie den Updater neben dem Rest des Stacks:
Terminal-Fenster docker compose --profile updater up -d -
Öffnen Sie Einstellungen → Updates. Die Installationskarte sagt, ob der Updater bereit ist oder was ihn blockiert: Docker nicht erreichbar, das Docker-Kommandozeilen-Image noch nicht gezogen, Compose-Datei nicht gefunden, Projektverzeichnis stimmt nicht mit
RESTOW_PROJECT_DIRüberein,.envnicht beschreibbar oder zu wenig freier Speicher. Beim ersten Start zieht der Updater das Docker-Kommandozeilen-Image (siehe unten), wofür er Zugriff auf Docker Hub braucht. Bis dahin sagt die Karte, dass er sich vorbereitet.
Zum Entfernen: docker compose --profile updater rm -sf updater. Das Volume des Updaters (restow-updater, mit den Datenbanksicherungen) bleibt, bis Sie es mit docker volume rm entfernen.
Der Updater wird durch ein Update nicht aktualisiert. Er läuft weiter in der Version, mit der er gestartet wurde. Erstellen Sie ihn nach einem Update neu, damit er passt: docker compose --profile updater up -d updater. Der Reiter erinnert Sie daran, wenn seine Version von der laufenden abweicht.
Zwei Modi
Abschnitt betitelt „Zwei Modi“Restow wählt den Modus anhand der Update-Quelle und zeigt ihn im Reiter:
- Image (die Standardquelle, die öffentlichen Releases des Projekts). Zieht
ghcr.io/restow-backup/restow:<Version>für die Anwendung undghcr.io/restow-backup/restow-web:<Version>für den Web-Edge. Er prüft die gezogenen Images gegen die Digests, die das Release in seinen Notes veröffentlicht (die Releases des Projekts tun das), schreibt die beiden Image-Referenzen in die.env(RESTOW_IMAGE,RESTOW_WEB_IMAGE) und erstellt die Dienste neu. Hat ein Release kein Web-Image, bleibt der Web-Edge, wie er ist, und der Lauf sagt das. Ein Release ohne Digests lässt sich trotzdem installieren, der Lauf vermerkt dann, dass das Image nicht geprüft wurde. Der Updater prüft diese Digests, er prüft nicht die cosign-Signatur: Siehe Ein Release verifizieren, wenn Sie diesen Schritt möchten. - Quellcode (jedes andere Repository, zum Beispiel Ihr eigenes Forgejo). Lädt das getaggte Archiv des Repositorys herunter, mit dem gespeicherten Token in einem
Authorization-Header (nie in einer URL, einer Kommandozeile oder einem Log), baut die Anwendungs- und Web-Images lokal mitdocker buildund erstellt die Dienste dann auf dieselbe Weise neu. Das dauert länger als ein Download.
Was ein Update tut
Abschnitt betitelt „Was ein Update tut“Der Inhaber wählt die Version und eine Vorlaufzeit (sofort, 1, 5, 15, 30 Minuten oder 1 Stunde) und bestätigt. Ab dann sieht jede angemeldete Person, nicht nur Administratoren, ein Banner mit Live-Countdown und beim Ankündigen einen Hinweis. Der Inhaber kann bis zum Start abbrechen. Beim Start sehen alle einen Vollbild-Hinweis mit den Schritten und dem Fortschritt.
- Vorbereiten. Prüft, dass Docker antwortet, die Compose-Datei da ist, die
.envbeschreibbar ist, freier Speicher vorhanden ist, das Ziel neuer ist als die laufende Version und dass die Compose-Datei das Image von API, Worker, Scheduler und Web-Edge ausRESTOW_IMAGEundRESTOW_WEB_IMAGEbezieht (damit keine Installation mit gemischten Versionen entstehen kann). - Herunterladen oder bauen. Es wird noch nichts angehalten: Ein Fehler hier ändert nichts.
- Datenbanksicherung.
pg_dump -Fcder Datenbank in das Volume des Updaters, auf Lesbarkeit geprüft. Die letzten drei bleiben erhalten, dazu die, auf die sich ein Lauf mit Handlungsbedarf stützt. - Worker und Scheduler anhalten. Jobs in der Warteschlange laufen nach dem Neustart weiter.
- Neue Version starten. Die API wird mit dem neuen Image neu erstellt und wendet beim Start ihre Datenbankmigrationen an.
- Health-Check. Wartet, bis die API bereit meldet und die neue Version nennt (er gibt sofort auf, wenn der API-Container immer wieder neu startet), startet dann Worker und Scheduler und erstellt zuletzt den Web-Edge neu.
- Fertig.
Solange die API neu startet, antwortet der Edge Browsern mit einer statischen Wartungsseite (in der Sprache des Browsers, hell oder dunkel) und API-Aufrufen mit 503. Die Weboberfläche versteht das als „der Server startet neu“ und lädt sich selbst neu, sobald die neue Version antwortet.
Der Zustand liegt im Volume des Updaters und übersteht daher den Neustart der API. Das Ergebnis jedes Laufs erscheint außerdem in der Benachrichtigungsglocke.
Wenn etwas schiefgeht
Abschnitt betitelt „Wenn etwas schiefgeht“Der Updater rät nie. Er beendet einen fehlgeschlagenen Lauf in genau einem von drei Zuständen:
- Unverändert. Er ist fehlgeschlagen, bevor etwas angehalten wurde (Docker nicht erreichbar, das Image ließ sich nicht ziehen oder passte nicht zu seinem Digest, der Build ist fehlgeschlagen, die Sicherung ist fehlgeschlagen). Die alte Version wurde nie angehalten.
- Zurückgesetzt. Die neue Version kam nicht hoch, und die Datenbankmigrationen waren noch nicht gelaufen (der Updater hält zuerst die neue API an und vergleicht dann die Zahl der angewendeten Migrationen mit der vor dem Update). Die vorherigen Images laufen wieder, die
.envist Byte für Byte wiederhergestellt, und der Reiter nennt, welcher Schritt warum fehlschlug. - Erfordert Ihr Eingreifen. Die neue API ist nach ihren Migrationen fehlgeschlagen. Migrationen lassen sich nicht rückgängig machen, deshalb startet der Updater die alte Version nicht auf einer migrierten Datenbank. Er hält API, Worker und Scheduler an, behält die Datenbanksicherung und sagt Ihnen, was zu tun ist. Der Web-Edge zeigt weiter die Wartungsseite.
Wird der Updater selbst mitten in einem Lauf neu gestartet oder beendet, wird der Lauf als unterbrochen festgehalten (unverändert, wenn er noch nichts angehalten hatte, sonst erfordert er Ihr Eingreifen), und von selbst wird nichts gestartet.
Bei erfordert Ihr Eingreifen spielen Sie die vor dem Update gemachte Sicherung zurück. Der Reiter zeigt den genauen Dateinamen und die vorherigen Image-Referenzen:
# copy the dump out of the updater's volumedocker compose --profile updater cp updater:/state/dumps/<file> ./<file># stop the application and restoredocker compose stop api worker schedulerdocker compose exec -T postgres pg_restore -U restow -d restow --clean --if-exists < <file># put the previous images back into .env (RESTOW_IMAGE, RESTOW_WEB_IMAGE), thendocker compose up -dSicherungen, die nach dem Update entstanden sind, liegen im Chunk-Store, aber nicht in der zurückgespielten Datenbank, führen Sie daher nach dem Zurücksetzen ein Backup aus. Melden Sie den Fehler dann mit dem Log-Ausschnitt, den der Reiter zeigt. Ausblenden entfernt einen beendeten Lauf von der Seite. Nutzen Sie es erst, nachdem Sie die Installation wiederhergestellt haben, denn die Wiederherstellungsbefehle verschwinden damit. Der Lauf bleibt im Audit-Log.
Audit-Ereignisse
Abschnitt betitelt „Audit-Ereignisse“Jeder wichtige Schritt steht im Audit-Log: update.check, update.settings.updated, update.scheduled, update.cancelled, update.started, update.succeeded, update.failed und update.acknowledged (Ausblenden eines beendeten Laufs). Der Updater hat keinen eigenen Datenbankzugriff, er führt daher ein Journal, und die API schreibt es danach ins Audit-Log, in der richtigen Reihenfolge und genau einmal, auch wenn die API zwischendurch ersetzt wurde. Siehe Audit-Log.
Einstellungen des Updaters
Abschnitt betitelt „Einstellungen des Updaters“Der Compose-Dienst setzt, was er braucht. Diese Variablen liest nur der Updater (ROLE=updater):
| Variable | Standard | Bedeutung |
|---|---|---|
RESTOW_UPDATER_PROJECT_DIR |
erforderlich, aus RESTOW_PROJECT_DIR gesetzt |
Absoluter Host-Pfad des Compose-Projekts, unter demselben Pfad eingehängt. |
RESTOW_UPDATER_IMAGE_REPOSITORY |
ghcr.io/restow-backup/restow |
Repository des Anwendungs-Images für den Image-Modus. |
RESTOW_UPDATER_WEB_IMAGE_REPOSITORY |
ghcr.io/restow-backup/restow-web |
Repository des Web-Images für den Image-Modus. |
RESTOW_UPDATER_HEALTH_TIMEOUT_SECONDS |
600 |
Wie lange auf die neue API gewartet wird (Migrationen können dauern). |
RESTOW_UPDATER_MIN_FREE_MB |
1024 |
Erforderlicher freier Speicher im Volume des Updaters. |
RESTOW_UPDATER_CLI_IMAGE |
docker:27-cli |
Image, mit dem docker und docker compose ausgeführt werden (siehe unten). |
RESTOW_UPDATER_SOURCE_HOSTS |
leer (jeder https-Host) | Optionale, kommagetrennte Positivliste der Hosts, von denen ein Quellcode-Archiv heruntergeladen werden darf. |
Das veröffentlichte Image enthält keine Docker-Kommandozeile. Der Updater führt daher jeden Befehl docker und docker compose in einem kurzlebigen Hilfs-Container aus RESTOW_UPDATER_CLI_IMAGE aus (standardmäßig von Docker Hub, im Hintergrund beim Start des Updaters gezogen; vorher kann der Updater nichts installieren und sagt das), über den eingehängten Socket, ohne Netzwerkzugriff und mit eingehängtem Projektverzeichnis und State-Volume des Updaters. Steckt im Image des Updaters selbst eine docker-Binärdatei, wird stattdessen diese direkt verwendet. Die Hilfs-Container tragen keine Registry-Zugangsdaten: Die Images der öffentlichen Releases des Projekts brauchen keine, und eine private Registry wird in diesem Modus nicht unterstützt. Die API erreicht den Updater unter RESTOW_UPDATER_URL (Standard http://updater:8090). Dort antwortet nichts, solange das Updater-Profil nicht läuft.
Von Hand zurücksetzen
Abschnitt betitelt „Von Hand zurücksetzen“-
Keine Migrationen im Release: Checken Sie die vorherige Version aus (oder ziehen Sie sie) und führen Sie erneut
docker compose up -daus. Der Updater tut das selbst, wenn eine neue Version nicht startet. -
Mit Migrationen: Migrationen lassen sich nicht zurückdrehen. Halten Sie den Stack an, spielen Sie die vor dem Update gemachte Datenbanksicherung zurück und starten Sie dann die vorherige Version:
Terminal-Fenster docker compose stop api worker schedulerdocker compose exec -T postgres pg_restore -U restow -d restow --clean --if-exists < restow-YYYY-MM-DD.dumpgit checkout vPREVIOUSdocker compose up -d --buildTragen Sie beim Release-Stack statt des
git checkoutdie vorherigenRESTOW_IMAGEundRESTOW_WEB_IMAGEwieder in die.envein und verwenden Siedocker compose up -d. Sicherungen, die nach dem Update entstanden sind, liegen im Chunk-Store, aber nicht in der zurückgespielten Datenbank, führen Sie daher nach dem Zurücksetzen ein Backup aus.
Versionen und Kanäle
Abschnitt betitelt „Versionen und Kanäle“Restow verwendet Semantic Versioning. Vor 1.0.0 bringt eine Minor-Version (0.2.0) neue Funktionen und kann Migrationen enthalten. Eine Patch-Version (0.1.1) behebt Probleme und enthält nur dann Migrationen, wenn eine Korrektur sie braucht. Tags heißen vMAJOR.MINOR.PATCH, Vorabversionen tragen -rc.N. Der Kanal Stabil der Update-Prüfung bietet nur Releases an, der Kanal Beta zusätzlich die Vorabversionen. Die Docker-Tags eines Releases sind eine eigene Sache, siehe Ein Release verifizieren.