snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ru/developers/extend/apps/operations/sync-and-recovery.mdx

@@ -0,0 +1,126 @@
+---
+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).
+* **Локальное состояние экземпляра** — ни один из вышеперечисленных пунктов не подходит, и рабочее пространство всё ещё выглядит неправильно; двигайтесь вниз по лестнице восстановления.