---
pkg: '@nocobase/plugin-migration-manager'
title: "移行管理"
description: "運用管理の移行：アプリケーション設定を環境間で移行し、スキーマのみ、上書き、スキップのルールに対応します。バックアップ管理プラグインに依存します。"
keywords: "移行管理,Migration,アプリケーション設定移行,移行ルール,スキーマのみ,上書き,スキップ,NocoBase"
---
# 移行管理

## はじめに

移行管理プラグインは、アプリケーション設定をある環境（例：Staging）から別の環境（例：PROD）へ移行するために使用します。

**主な違い：**

- **移行管理：** 特定のアプリケーション設定、データテーブル構造、または一部のデータの移行に重点を置いています。
- **[バックアップマネージャー](../backup-manager/index.mdx)：** 全量データのバックアップと復元に重点を置いています。

## インストール

[バックアップ管理](../backup-manager/index.mdx) プラグインに依存しています。事前にインストールおよび有効化されていることをご確認ください。

## フローと仕組み

メインデータベースのデータテーブルおよびデータを、移行ルールに基づいてあるアプリケーションから別のアプリケーションへ移行します。外部データベースやサブアプリケーションのデータは移行されませんのでご注意ください。

![20250102202546](https://static-docs.nocobase.com/20250102202546.png)

## 移行ルール

### 組み込みルール

移行管理は次の 3 種類のルールに対応しています。

- **スキーマのみ：** テーブル構造のみを同期し、データの挿入や更新は行いません。
- **上書き：** 既存のテーブルレコードを削除し、新しいデータを挿入します。
- **スキップ：** そのテーブルに対して処理を行いません。

**補足：**
- 上書きでもテーブル構造の変更は同期されます。
- ユーザー定義の業務データテーブルは通常、本番データの上書きを避けるためスキーマのみを選択します。

### 詳細設計

![20250102204909](https://static-docs.nocobase.com/20250102204909.png)

### 設定画面

移行ルールの設定

既定戦略に対応するテーブルについては、[アプリケーションと主要プラグインの組み込みテーブル](./built-in-tables.md) を参照してください。

![20250102205450](https://static-docs.nocobase.com/20250102205450.png)

独立ルールの有効化

![20250107105005](https://static-docs.nocobase.com/20250107105005.png)

独立ルールおよび、その独立ルールで処理するデータテーブルの選択

![20250107104644](https://static-docs.nocobase.com/20250107104644.png)

## 移行ファイル

![20250102205844](https://static-docs.nocobase.com/20250102205844.png)

### 新規移行の作成

![20250102205857](https://static-docs.nocobase.com/20250102205857.png)

### 移行の実行

![20250102205915](https://static-docs.nocobase.com/20250102205915.png)

#### 環境変数の検出

アプリケーション環境変数の検出（[環境変数](../variables-and-secrets/index.md) について）

![20250102212311](https://static-docs.nocobase.com/20250102212311.png)

.env 内の `DB_UNDERSCORED`、`USE_DB_SCHEMA_IN_SUBAPP`、`DB_TABLE_PREFIX`、`DB_SCHEMA`、`COLLECTION_MANAGER_SCHEMA` が一致しない場合、移行を続行できないことを示すポップアップが表示されます。

![918b8d56037681b29db8396ccad63364](https://static-docs.nocobase.com/918b8d56037681b29db8396ccad63364.png)

動的に設定された環境変数またはシークレットが不足している場合、ポップアップが表示され、新たに追加が必要な環境変数やシークレットをここで入力してから続行するよう促されます。

![93a4fcb44f92c43d827d57b7874f6ae6](https://static-docs.nocobase.com/93a4fcb44f92c43d827d57b7874f6ae6.png)

#### プラグインの検出

アプリケーションのプラグイン検出を行い、現在の環境にプラグインが不足している場合はポップアップが表示されます。この場合、移行を続行することも可能です。

![bb5690a1e95660e1a5e0fd7440b6425c](https://static-docs.nocobase.com/bb5690a1e95660e1a5e0fd7440b6425c.png)

## 移行ログとストレージ

移行の実行後、サーバー上に実行ログファイルが保存され、オンラインで確認またはダウンロードできます。

![20251225184721](https://static-docs.nocobase.com/20251225184721.png)

実行ログファイルをオンラインで確認する際に、データ構造の移行時に実行された SQL もダウンロードできます。

![20251227164116](https://static-docs.nocobase.com/20251227164116.png)

「プロセス」ボタンをクリックすると、完了した移行の実行過程を確認できます。

![c065716cfbb7655f5826bf0ceae4b156](https://static-docs.nocobase.com/c065716cfbb7655f5826bf0ceae4b156.png)

![f4abe566de1186a9432174ce70b2f960](https://static-docs.nocobase.com/f4abe566de1186a9432174ce70b2f960.png)

### `storage` ディレクトリについて

移行管理は主にデータベースレコードを処理します。`storage` ディレクトリ内の一部のデータ（ログ、バックアップ履歴、リクエストログなど）は自動的には移行されません。

- 新しい環境でこれらのファイルを保持する必要がある場合は、`storage` ディレクトリ内の関連フォルダを手動でコピーしてください。

## ロールバック

移行を実行する前に、システムが自動的にバックアップを作成します。

### ロールバックの原則

1.  **サービスの停止：** ロールバックを開始する前にアプリケーションを停止し、新しいデータの書き込みを防止します。
2.  **バージョンの一致：** NocoBase のコアバージョン（Docker イメージ）はバックアップファイルが生成された時点のバージョンと**一致している必要があります**。
3.  **新規環境での復元：** 現在のデータベースやストレージが破損している場合、イメージバージョンの復元だけでは不十分な可能性があります。最も安全な方法は、正しいコアイメージを使用して**新しいアプリケーションインスタンス（新しいデータベースとストレージ）**でバックアップを復元することです。

### ロールバックフロー

#### シーン A：移行タスクの実行が失敗した場合
移行タスクの実行でエラーが発生しただけでコアバージョンが変更されていない場合は、[バックアップマネージャー](../backup-manager/index.mdx) を使用して、移行前に自動作成されたバックアップを直接復元してください。

#### シーン B：システムの破損またはコアアップグレードの失敗
アップグレードや移行によりシステムが稼働できなくなった場合、安定した状態にロールバックする必要があります：
1.  **アプリケーションの停止：** 現在のコンテナサービスを停止します。
2.  **新規環境の準備：** 新しい空のデータベースと空のストレージ環境を準備します。
3.  **ターゲットバージョンのデプロイ：** Docker イメージタグを*バックアップが生成された時点の*バージョンに戻します。
4.  **バックアップの復元：** このクリーンな環境で [バックアップマネージャー](../backup-manager/index.mdx) を使用して復元を実行します。
5.  **トラフィックの切り替え：** ゲートウェイ/ロードバランサーを更新し、復元済みの新しいインスタンスにトラフィックを向けます。

![20251227164004](https://static-docs.nocobase.com/20251227164004.png)

## コマンドライン

### `yarn nocobase migration generate`

```bash
Usage: nocobase migration generate [options]

Options:
  --title [title]    migration title
  --ruleId <ruleId>  migration rule id
```

例

```bash
yarn nocobase migration generate --ruleId=1
```

### `yarn nocobase migration run`

```bash
Usage: nocobase migration run [options] <filePath>

Arguments:
  filePath           migration file path

Options:
  --skip-backup      skip backup
  --var [var]        variable (default: [])
  --secret [secret]  secret (default: [])
```

例

```bash
yarn nocobase migration run /your/path/migration_1775658568158.nbdata \
  && --var A=a --var B=b \
  && --secret C=c --secret D=d
```

## ベストプラクティス

### 推奨デプロイフロー（ブルーグリーン切り替え）

ゼロダウンタイムまたは極めて短いダウンタイムを実現し、最高の安全性を確保するために、デュアル環境切り替え方式を推奨します：

1.  **準備段階（Staging）：** Staging 環境で移行ファイルを作成します。
2.  **安全なバックアップ（PROD-A）：** 現在の本番環境（PROD-A）のフルバックアップを作成します。
3.  **並行デプロイ（PROD-B）：** ターゲットコアバージョンを使用して、*新しい空のデータベース*の本番インスタンス（PROD-B）をデプロイします。
4.  **復元と移行：**
    *   PROD-A のバックアップを PROD-B に復元します。
    *   PROD-B で Staging からの移行ファイルを実行します。
5.  **検証：** PROD-A がまだサービスを提供している間に、PROD-B を徹底的にテストします。
6.  **トラフィックの切り替え：** Nginx/ゲートウェイを更新し、PROD-A から PROD-B にトラフィックを切り替えます。
    *   *問題が発生した場合、即座に PROD-A に切り戻すことができます。*

### データの一貫性とメンテナンス停止

現在、NocoBase はゼロダウンタイムでの移行をサポートしていません。バックアップや移行中のデータ不整合を回避するために：
- **ゲートウェイ/エントリの停止：** バックアップや移行を開始する前に、ユーザーアクセスを停止することを強く推奨します。Nginx またはゲートウェイで **503 メンテナンスページ**を設定し、システムがメンテナンス中であることをユーザーに通知するとともに、新しいデータの書き込みを防止できます。
- **手動データ同期：** 移行中にユーザーが旧バージョンでデータを生成し続けた場合、そのデータは後から手動で同期する必要があります。
