---
title: アップグレードガイド
icon: arrow-up-right-dots
---

## 一般ガイドライン

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

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

バックアップから復元:

```bash
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.22+)

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

たとえば、v1.22 から 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` を設定しておく必要があります。 バックフィル後にキーを切り替えるには、[ローテーション](/l/ja/developers/self-host/capabilities/key-rotation)が必要です。

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

`ENCRYPTION_KEY` のローテーション、JWT 署名鍵のローテーション、漏えいした署名鍵の失効といった日常的な運用タスクについては、専用の[鍵ローテーションガイド](/l/ja/developers/self-host/capabilities/key-rotation)を参照してください。

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

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

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

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

出力例:

```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)
```

### オプション

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

## トラブルシューティング

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

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

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

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

## v1.22 以前

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