アップグレードガイド

​

一般ガイドライン

アップグレードを開始する前に、必ずデータベースをバックアップしてください。次を実行してください:

docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql

バックアップから復元:

cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}

Docker Composeを使用している場合、次の手順に従います：

1. Twentyを停止：docker compose down
2. docker-compose.yml と同じディレクトリにある .env ファイルの TAG 値を変更します
3. Twentyを起動：docker compose up -d

サーバーは起動時に、必要なアップグレード用のマイグレーションを自動的に実行します。 手動のコマンドは不要です。

​

クロスバージョンのアップグレード (v1.23+)

v1.23 以降、Twenty はクロスバージョンのアップグレードをサポートします。 サポートされている任意のバージョンから、中間バージョンを段階的に経ることなく、最新リリースへ直接移行できます。

たとえば、v1.23 から v2.0 へ直接アップグレードすることが完全にサポートされています。

​

v2.5 以降へのアップグレード — 保存データ暗号化エンベロープ

v2.5 以降、Twenty は保存時のシークレット（OAuth トークン、アプリケーション変数、署名用の秘密鍵、機密な設定値、TOTP シークレット）を、バージョン付きの enc:v2: エンベロープ内に格納し、ENCRYPTION_KEY（ENCRYPTION_KEY が未設定の場合は APP_SECRET）で暗号化します。

v2.5 での最初の起動時には、既存の行を新しいエンベロープにバックフィルする低速なアップグレードコマンドが実行されます。 これらは冪等であり、中断してサーバーを再起動しても処理が中断地点から再開されますが、大規模なデータベースでは時間がかかる場合があります。 upgrade:status で進行状況を監視できます。

バックフィルが最初からそのキーの下に行を書き込めるよう、v2.5 へのアップグレード前に専用の ENCRYPTION_KEY を設定しておく必要があります。 バックフィル後にキーを切り替えるには、ローテーションが必要です。

​

シークレットおよび署名鍵のローテーション

ENCRYPTION_KEY のローテーション、JWT 署名鍵のローテーション、漏えいした署名鍵の失効といった日常的な運用タスクについては、専用の鍵ローテーションガイドを参照してください。

​

アップグレードステータスの確認

upgrade:status コマンドを使用すると、インスタンスとワークスペースのマイグレーションの現在の状態を確認できます。 アップグレードの問題をデバッグしたり、サポートリクエストを提出する際に役立ちます。

サーバーコンテナから実行します：

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status

出力例:

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)

​

オプション

フラグ	説明
-w, --workspace-id <id>	特定のワークスペースに絞り込みます。 複数回指定できます。
-f, --failed-only	最新の状態のワークスペースを非表示にし、遅れているものと失敗したエントリのみを表示します。

​

トラブルシューティング

一部のワークスペースでアップグレードが失敗した場合、サーバーは失敗したステップを超えて先に進みません。 サーバーを再起動すると（docker compose up -d）、中断した地点からアップグレードを再試行します。

問題を迅速に特定するには、次を実行します：

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only

これにより、遅れている、または失敗しているワークスペースのみが表示され、各失敗のエラーメッセージも併せて表示されます。

​

v1.23 以前

インスタンスが v1.23 より前の場合は、v1.23 に到達するまで、各メジャーのタグ付きバージョンを順に（v1.6 から v1.7、次に v1.7 から v1.8、…）段階的にアップグレードする必要があります。 そこからは、最新バージョンに直接アップグレードできます。