---
title: Синхронизация и восстановление
description: Какую команду когда использовать, как читать вывод синхронизации и поэтапный план восстановления на случай расхождения локальных метаданных — до того, как дойдет до полного сброса.
icon: compass
---

Локальная разработка приложения строится вокруг **синхронизации**: CLI пересобирает ваш манифест, а сервер применяет только разницу между ним и метаданными, которые уже есть в вашем рабочем пространстве. На этой странице описано, какую команду выбрать, как читать, что изменила синхронизация, и что делать — по шагам — когда локальное состояние выглядит несогласованным.

## Какую команду и когда использовать

<Note>
Для повседневной локальной разработки вам почти всегда нужна команда `yarn twenty dev`. Развертывание и публикация предназначены для выпуска релизов, **а не** для локального цикла разработки.
</Note>

| Вы хотите…                                                       | Команда                             | Заметки                                                                                                                            |
| ---------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Выполнять локальные итерации с синхронизацией в реальном времени | `yarn twenty dev`                   | Отслеживает ваши файлы и синхронизирует при каждом изменении.                                                                      |
| Выполнить одну синхронизацию и выйти (CI, скрипты, хуки)         | `yarn twenty apply`                 | Одна сборка + синхронизация, затем завершение работы. Добавьте `--force`, чтобы пропустить подтверждение разрушительных изменений. |
| Предпросмотр изменений **без их применения**                     | `yarn twenty plan`                  | Вычисляет и выводит diff; ничего не записывает.                                                                                    |
| Удалить приложение из рабочего пространства                      | `yarn twenty app:uninstall`         | Добавьте `--yes`, чтобы пропустить запрос подтверждения.                                                                           |
| Отправить на сервер tar-архив                                    | `yarn twenty app:publish --private` | Требуется **строго более высокая** версия в `package.json` — см. [Публикация](/l/ru/developers/extend/apps/operations/publishing).      |
| Опубликовать на маркетплейсе (npm)                               | `yarn twenty app:publish`           | —                                                                                                                                  |
| Установить / обновить развернутую версию                         | `yarn twenty app:install`           | Устанавливает версию, которая сейчас развернута.                                                                                   |
| Очистить локальный сервер и начать с нуля                        | `yarn twenty docker:reset`          | Удаляет **все** локальные данные — крайняя мера.                                                                                   |

<Note>
`yarn twenty dev --once` и `yarn twenty dev --once --dry-run` по-прежнему работают как устаревшие псевдонимы для `yarn twenty apply` и `yarn twenty plan`.
</Note>

### Для локальной синхронизации не нужно повышать версию

Правило строго возрастающей `version` (`VERSION_ALREADY_EXISTS` при deploy, `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION` при install) относится к **`app:publish` / `app:install`** — пути релизов. `yarn twenty dev` синхронизирует ваш манифест на месте и никогда не требует изменения версии, поэтому вам не нужно трогать `package.json`, чтобы делать итерации. Если вы ловите себя на том, что поднимаете версию, чтобы протестировать локальное изменение, значит вы используете релизный путь, когда вам нужен цикл разработки (dev loop).

## Чтение вывода синхронизации

Каждая синхронизация выводит изменения метаданных, которые она применила (или применила бы, с `plan`), в стиле Terraform — по одному блоку на сущность с её атрибутами, затем строку с итогами:

```text filename="Terminal"
  # objectMetadata "rocket" will be created
  + icon          = "IconRocket"
  + labelSingular = "Rocket"
  + ...

  # fieldMetadata "launchedAt" will be updated
  ~ isNullable = false -> true

Plan: 2 to add, 1 to change, 1 to destroy.

✓ Synced My App (4 files)
```

Это ваша первая диагностическая точка: она показывает, какие именно объекты, поля и макеты изменились, чтобы вы могли подтвердить, что синхронизация сделала то, что вы ожидали, до проверки в интерфейсе.

Разрушительные изменения (`to destroy`) перечисляются вместе с тем, что они удаляют (например, `objectMetadata "auditNote" — drops the table and all its rows`) и требуют интерактивного подтверждения или `--force` в скриптах.

Когда синхронизация завершается с ошибкой на одной сущности, в сообщении указываются проблемная сущность и её `universalIdentifier`, например:

```text
Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
```

Используйте этот идентификатор, чтобы найти сущность в своем манифесте (и, при необходимости, в рабочем пространстве), вместо того чтобы гадать, какая из них конфликтует.

## Предпросмотр изменений (plan)

`yarn twenty plan` собирает ваш манифест, запрашивает у сервера план миграции и выводит его — **без применения чего-либо**. Это безопасный способ ответить на вопрос «что изменит эта синхронизация?» до того, как вы на неё согласитесь.

```bash filename="Terminal"
yarn twenty plan
```

```text filename="Terminal"
Building manifest...
Computing metadata plan (read-only, nothing will be applied)...

  # fieldMetadata "crewCapacity" will be created
  + ...

Plan: 1 to add, 1 to change, 0 to destroy.

✓ Plan complete for My App — no changes were applied
```

План:

* **Ничего не записывает** — ни миграции метаданных, ни обновления записи приложения, ни изменений ролей/вкладок по умолчанию, ни генерации API‑клиента.
* Возвращает **тот же diff**, который применит реальная синхронизация, чтобы вы могли заранее просмотреть создаваемые/обновляемые/удаляемые сущности.
* Полезен перед рискованным изменением, при проверке изменения, сгенерированного ИИ, или в скрипте, который должен завершаться с ошибкой, если вот-вот будет применено неожиданное изменение.

<Note>
План только предварительно показывает изменения **метаданных** и требует, чтобы приложение хотя бы один раз уже было синхронизировано (чтобы рабочее пространство знало о нём). Если вы запускаете его для приложения, которое никогда не синхронизировалось, сервер сообщит, что приложение не установлено — сначала один раз выполните `yarn twenty dev`.
</Note>

## Лестница восстановления

Когда локальные метаданные выглядят неверно, действуйте поэтапно в следующем порядке и останавливайтесь, как только проблема решена. Каждый следующий шаг более разрушителен, чем предыдущий.

1. **Повторно синхронизируйте.** Снова выполните `yarn twenty apply`. Синхронизации идемпотентны — повторный запуск корректного манифеста безопасен и часто устраняет временный сбой.
2. **Просмотрите план.** Выполните `yarn twenty plan`, чтобы увидеть, что именно намеревается изменить следующая синхронизация, не применяя эти изменения.
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>

## Избегайте одновременных синхронизаций в одном рабочем пространстве

Синхронизация применяет миграции метаданных. Запуск нескольких операций sync, deploy или install по отношению к **одному и тому же рабочему пространству одновременно** — например, из нескольких терминалов или при параллельных итерациях агентов ИИ — может перемешать эти миграции и оставить метаданные в частично примененном состоянии.

Сервер последовательно обрабатывает синхронизации для каждого рабочего пространства, чтобы предотвратить это, но вам всё равно следует пропускать чувствительные операции с метаданными через **один** процесс, а не запускать их параллельно. Если вы организуете разработку с несколькими агентами, направляйте их вызовы sync/deploy/install через одну очередь, чтобы в каждый момент времени выполнялась только одна операция.

## Как различать типы сбоев

Когда что‑то идёт не так, diff метаданных и именованные ошибки помогают определить, на каком этапе произошел сбой:

* **Ошибка сборки манифеста** — CLI завершается с ошибкой до синхронизации (`MANIFEST_BUILD_FAILED`, `TYPECHECK_FAILED`); исправьте исходный код приложения.
* **Ошибка синхронизации / миграции** — сборка проходит успешно, но применение diff завершается сбоем с указанием сущности и `universalIdentifier`; исправьте конфликтующие метаданные.
* **Ошибка размера зависимостей** — синхронизация или установка завершается сбоем, потому что продакшен‑зависимости приложения (`dependencies`) слишком велики, чтобы их установить в качестве слоя среды выполнения (`LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED`); перенесите пакеты, которые ваши логические функции не импортируют во время выполнения (UI-библиотеки, инструменты разработки), в `devDependencies`.
* **Ошибка выполнения кода приложения** — синхронизация проходит успешно, но ваши логические функции или компоненты ведут себя неправильно во время выполнения; проверьте [журналы функций](/l/ru/developers/extend/apps/operations/cli).
* **Локальное состояние экземпляра** — ни один из вышеперечисленных пунктов не подходит, и рабочее пространство всё ещё выглядит неправильно; двигайтесь вниз по лестнице восстановления.