github-actions[bot]
a0493dbc4b
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
103 lines
5.6 KiB
Plaintext
103 lines
5.6 KiB
Plaintext
---
|
||
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、…）段階的にアップグレードする必要があります。 そこからは、最新バージョンに直接アップグレードできます。
|