103 lines
4.9 KiB
Plaintext
103 lines
4.9 KiB
Plaintext
---
|
||
title: Upgrade-Anleitung
|
||
icon: arrow-up-right-dots
|
||
---
|
||
|
||
## Allgemeine Richtlinien
|
||
|
||
**Sichern Sie Ihre Datenbank immer, bevor Sie den Upgrade-Vorgang starten**, indem Sie Folgendes ausführen:
|
||
|
||
```bash
|
||
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
|
||
```
|
||
|
||
Aus Sicherung wiederherstellen:
|
||
|
||
```bash
|
||
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
|
||
```
|
||
|
||
Wenn Sie Docker Compose verwenden, befolgen Sie diese Schritte:
|
||
|
||
1. Twenty stoppen: `docker compose down`
|
||
2. Ändern Sie den Wert von `TAG` in der Datei `.env` neben Ihrer `docker-compose.yml`
|
||
3. Twenty starten: `docker compose up -d`
|
||
|
||
Der Server führt beim Start alle erforderlichen Upgrade-Migrationen automatisch aus. Kein manueller Befehl erforderlich.
|
||
|
||
## Versionsübergreifende Upgrades (v1.22+)
|
||
|
||
Ab **v1.22** unterstützt Twenty versionsübergreifende Upgrades. Sie können direkt von jeder unterstützten Version auf die neueste Version wechseln, ohne jede Zwischenversion durchlaufen zu müssen.
|
||
|
||
Zum Beispiel wird ein Upgrade direkt von v1.22 auf v2.0 vollständig unterstützt.
|
||
|
||
## Upgrade auf v2.5+ – Verschlüsselungsumschlag für ruhende Daten
|
||
|
||
Ab **v2.5** speichert Twenty Secrets im Ruhezustand (OAuth-Tokens, Anwendungsvariablen, private Signaturschlüssel, sensible Konfigurationswerte, TOTP-Secrets) in einem versionierten Umschlag `enc:v2:`, der mit `ENCRYPTION_KEY` (oder `APP_SECRET`, falls `ENCRYPTION_KEY` nicht gesetzt ist) verschlüsselt wird.
|
||
|
||
Beim ersten Start mit v2.5 werden langsame Upgrade-Befehle ausgeführt, die den neuen Umschlag mit bestehenden Zeilen befüllen. Sie sind idempotent – ein Unterbrechen und Neustarten des Servers setzt an der Stelle fort, an der er aufgehört hat –, aber sie können bei großen Datenbanken eine Weile dauern. Sie können den Fortschritt mit `upgrade:status` überwachen.
|
||
|
||
Sie sollten **vor** dem Upgrade auf v2.5 einen dedizierten `ENCRYPTION_KEY` setzen, damit beim Nachbefüllen die Zeilen von Anfang an unter diesem Schlüssel geschrieben werden. Ein Schlüsselwechsel nach der Nachbefüllung erfordert eine [Rotation](/l/de/developers/self-host/capabilities/key-rotation).
|
||
|
||
## Rotation von Secrets und Signaturschlüsseln
|
||
|
||
Für alltägliche operative Aufgaben wie das Rotieren von `ENCRYPTION_KEY`, das Rotieren des JWT-Signaturschlüssels oder das Widerrufen eines kompromittierten Signaturschlüssels siehe den dedizierten [Leitfaden zur Schlüsselrotation](/l/de/developers/self-host/capabilities/key-rotation).
|
||
|
||
## Upgrade-Status prüfen
|
||
|
||
Mit dem Befehl `upgrade:status` können Sie den aktuellen Status Ihrer Instanz und der Workspace-Migrationen prüfen. Er ist nützlich zum Debuggen von Upgrade-Problemen oder beim Erstellen einer Support-Anfrage.
|
||
|
||
Führen Sie ihn im Server-Container aus:
|
||
|
||
```bash
|
||
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
|
||
```
|
||
|
||
Beispielausgabe:
|
||
|
||
```sh
|
||
APP_VERSION: v1.23.0
|
||
|
||
Instance
|
||
Inferred version: 1.23.0
|
||
Latest command: 1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
|
||
Status: Up to date
|
||
Executed by: v1.23.0
|
||
At: 2026-04-16T11:43:58.823Z
|
||
|
||
Workspace
|
||
Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
|
||
Inferred version: 1.23.0
|
||
Latest command: 1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
|
||
Status: Up to date
|
||
Executed by: v1.23.0
|
||
At: 2026-04-16T11:44:09.361Z
|
||
|
||
Summary
|
||
Instance: Up to date
|
||
Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
|
||
```
|
||
|
||
### Optionen
|
||
|
||
| Flag | Beschreibung |
|
||
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||
| `-w, --workspace-id <id>` | Auf einen bestimmten Workspace filtern. Kann mehrfach übergeben werden. |
|
||
| `-f, --failed-only` | Workspaces auf dem neuesten Stand ausblenden, nur zurückliegende und fehlgeschlagene Workspaces anzeigen. |
|
||
|
||
## Fehlerbehebung
|
||
|
||
Wenn das Upgrade in einigen Workspaces fehlschlägt, wird der Server nicht über den fehlschlagenden Schritt hinaus fortfahren. Ein Neustart des Servers (`docker compose up -d`) führt das Upgrade ab der zuletzt erreichten Stelle erneut aus.
|
||
|
||
Um Probleme schnell zu identifizieren, führen Sie Folgendes aus:
|
||
|
||
```bash
|
||
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
|
||
```
|
||
|
||
Dies zeigt nur Workspaces, die zurückliegen oder fehlgeschlagen sind, zusammen mit der Fehlermeldung für jeden Fehlschlag.
|
||
|
||
## Vor v1.22
|
||
|
||
Wenn Ihre Instanz älter als v1.22 ist, müssen Sie schrittweise über jede größere getaggte Version ein Upgrade durchführen (von v1.6 auf v1.7, dann von v1.7 auf v1.8 usw.), bis Sie v1.22 erreichen. Danach können Sie direkt auf die neueste Version wechseln.
|