> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 同期と復旧

> どのコマンドをいつ使うか、同期の出力の読み方、そしてローカルのメタデータがずれたときに完全リセットへ到達する前に行うべき復旧手順の段階的な手引きについて説明します。

ローカルでのアプリ開発は**同期**を中心に回ります。CLI がマニフェストを再ビルドし、サーバーはそれと、すでにワークスペースに存在するメタデータとの差分だけを適用します。 このページでは、どのコマンドを使うべきか、同期で何が変更されたのかをどう読み取るか、そしてローカルの状態が一貫していないように見えるときに取るべき手順を（順番に）説明します。

## どのコマンドをいつ使うか

<Note>
  日々のローカルでの反復開発では、ほとんどの場合 `yarn twenty dev` を使うことになります。 デプロイと公開はリリースのためのものであり、ローカルでの開発ループのためのもの**ではありません**。
</Note>

| やりたいこと…                        | コマンド                                | ノート                                                                                                                    |
| ------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| ライブ同期でローカルに反復開発する              | `yarn twenty dev`                   | ファイルを監視し、変更のたびに同期します。                                                                                                  |
| 1 回だけ同期して終了（CI、スクリプト、フック向け）    | `yarn twenty dev --once`            | 1 回ビルドして同期し、その後終了します。                                                                                                  |
| 変更を**適用せずに**プレビュー              | `yarn twenty dev --once --dry-run`  | 差分を計算して表示しますが、何も書き込みません。                                                                                               |
| ワークスペースからアプリを削除する              | `yarn twenty app:uninstall`         | プロンプトをスキップするには、`--yes` を追加します。                                                                                         |
| サーバーに tarball をアップロードする        | `yarn twenty app:publish --private` | `package.json` のバージョンが**厳密により高い**必要があります — [Publishing](/l/ja/developers/extend/apps/operations/publishing) を参照してください。 |
| マーケットプレイス（npm）に公開する            | `yarn twenty app:publish`           | —                                                                                                                      |
| デプロイ済みバージョンをインストール / アップグレードする | `yarn twenty app:install`           | 現在デプロイされているバージョンをインストールします。                                                                                            |
| ローカルサーバーを消去してクリーンに開始する         | `yarn twenty docker:reset`          | ローカルデータを**すべて**削除します — 最終手段です。                                                                                         |

### ローカル同期ではバージョンの更新は不要

厳密に増加する `version` のルール（デプロイ時の `VERSION_ALREADY_EXISTS`、インストール時の `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION`）は、リリースパスである **`app:publish` / `app:install`** に適用されます。 `yarn twenty dev` はマニフェストをその場で同期し、バージョン変更を要求することはないため、反復するのに `package.json` を触る必要はありません。 ローカルの変更をテストするためにバージョンを上げている場合は、開発ループが必要なところでリリース経路を使ってしまっています。

## 同期出力の読み方

各同期では、適用された（`--dry-run` の場合は適用されるはずだった）メタデータ変更が出力されます。

```text filename="Terminal" theme={null}
Metadata changes: 2 created, 1 updated, 1 deleted
  created objectMetadata rocket
  created fieldMetadata timelineActivities
  updated fieldMetadata launchedAt
  deleted pageLayout legacyTab
✓ Synced
```

これは最初の診断手段です。どのオブジェクト、フィールド、レイアウトが変更されたかを正確に示すので、UI を確認する前に、同期が想定どおりに動作したかを確認できます。

同期が単一のエンティティで失敗した場合、エラーには問題のエンティティとその `universalIdentifier` が、次のように示されます。

```text theme={null}
Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
```

その識別子を使って、推測で衝突元を探すのではなく、マニフェスト内（必要であればワークスペース内）のエンティティを特定してください。

## 変更内容のプレビュー（ドライラン）

`yarn twenty dev --once --dry-run` はマニフェストをビルドし、サーバーにマイグレーションプランを問い合わせ、その内容を**何も適用せずに**表示します。 コミットする前に「この同期は何を変更するか？」という問いに安全に答える方法です。

```bash filename="Terminal" theme={null}
yarn twenty dev --once --dry-run
```

```text filename="Terminal" theme={null}
Building manifest...
Computing metadata diff (dry run, nothing will be applied)...
Metadata changes: 1 created, 1 updated
  created fieldMetadata timelineActivities
  updated objectMetadata rocket
✓ Dry run complete for My App — no changes were applied
```

ドライランでは次のことが行われます。

* **何も書き込みません** — メタデータマイグレーション、アプリケーションレコードの更新、デフォルトのロール / タブの変更、API クライアントの生成は一切行いません。
* 実際の同期が適用するのと**同じ差分**を返すため、作成 / 更新 / 削除されるエンティティを事前に確認できます。
* リスクの高い変更の前や、AI 生成の変更をレビューするとき、または予期せぬ変更が行われそうな場合にスクリプトを失敗させたいときなどに有用です。

<Note>
  ドライランでは**メタデータ**の変更のみをプレビューします。また、アプリが少なくとも一度は同期されている（ワークスペース側がその存在を知っている）必要があります。 一度も同期されていないアプリに対して実行すると、サーバーはそのアプリがインストールされていないと報告します — まず一度 `yarn twenty dev` を実行してください。
</Note>

## リカバリーラダー

ローカルのメタデータが正しくないように見える場合は、次の順番でエスカレートし、問題が解消したところで止めてください。 各ステップは前のものよりも影響が大きくなります。

1. **再同期。** `yarn twenty dev --once` を再度実行します。 同期はべき等であり、クリーンなマニフェストを再実行しても安全で、多くの場合は一時的な不具合が解消されます。
2. **プランをプレビュー。** `yarn twenty dev --once --dry-run` を実行して、次の同期が何を変更しようとしているのかを、適用せずに正確に確認します。
3. **名前付きエラーを読む。** 同期が失敗した場合は、メッセージ内のメタデータタイプと `universalIdentifier`（上記参照）を確認し、そのエンティティをマニフェスト内で特定します。 コンフリクトは、重複または再利用された識別子を指していることがほとんどです。
4. **アンインストールして再インストール。** `yarn twenty app:uninstall` を実行し、その後再度同期します（`yarn twenty dev`）。 これにより、ワークスペースの残りを維持したまま、アプリのメタデータをクリーンな状態から再構築します。
5. **フルリセット（最後の手段）。** `yarn twenty docker:reset` を実行し、その後再シードと再同期を行います。

<Warning>
  `yarn twenty docker:reset` はローカルインスタンス内のデータを**すべて**削除します — すべてのワークスペース、レコード、アプリが消去されます。 それまでの手順がすべて失敗した場合にのみ使用してください。
</Warning>

<Note>
  メタデータエラーが発生しましたか？ [issue を作成](https://github.com/twentyhq/twenty/issues/new/choose)し、失敗したマイグレーションメッセージ（メタデータタイプと `universalIdentifier` を含む）、同期時の `Metadata changes` の出力、および実行したコマンドを記載してください。
</Note>

## 1 つのワークスペースでの同時同期を避ける

同期ではメタデータマイグレーションが適用されます。 **同じワークスペースに対して同時に**複数の同期、デプロイ、インストール操作を実行すると（たとえば、複数のターミナルや AI エージェントが並行して反復している場合）、それらのマイグレーションが入り混じり、メタデータが一部だけ適用された状態のままになってしまう可能性があります。

サーバーはワークスペースごとに同期を直列化してこれを防いでいますが、それでも、センシティブなメタデータ操作は同時に実行するのではなく、**単一の**プロセスに集約するべきです。 複数のエージェントで開発をオーケストレーションしている場合は、それらの sync / deploy / install 呼び出しを 1 つのキューに流し込み、同時ではなく一度に 1 つだけ実行されるようにしてください。

## 失敗の切り分け

問題が発生したときは、メタデータの差分と名前付きエラーによって、どこで失敗したかを特定できます。

* **マニフェストビルドエラー** — CLI が同期前に失敗します（`MANIFEST_BUILD_FAILED`、`TYPECHECK_FAILED`）。アプリのソースを修正してください。
* **同期 / マイグレーションエラー** — ビルドは成功しますが、差分の適用が失敗し、エンティティと `universalIdentifier` が示されます。そのコンフリクトしているメタデータを修正してください。
* **アプリコードの実行時エラー** — 同期自体は成功しているものの、ロジック関数やコンポーネントが実行時に正しく動作しません。[function logs](/l/ja/developers/extend/apps/operations/cli) を確認してください。
* **ローカルインスタンスの状態** — 上記のいずれにも当てはまらないのにワークスペースの見た目が依然としておかしい場合は、リカバリーラダーに従って下の段階へ進んでください。