github-actions[bot]
44c4c27c76
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
112 lines
15 KiB
Plaintext
112 lines
15 KiB
Plaintext
---
|
||
title: Синхронизация и восстановление
|
||
description: Какую команду когда использовать, как читать вывод синхронизации и поэтапный план восстановления на случай расхождения локальных метаданных — до того, как дойдет до полного сброса.
|
||
icon: компас
|
||
---
|
||
|
||
Локальная разработка приложения строится вокруг **синхронизации**: CLI пересобирает ваш манифест, а сервер применяет только разницу между ним и метаданными, которые уже есть в вашем рабочем пространстве. На этой странице описано, какую команду выбрать, как читать, что изменила синхронизация, и что делать — по шагам — когда локальное состояние выглядит несогласованным.
|
||
|
||
## Какую команду и когда использовать
|
||
|
||
<Note>
|
||
Для повседневной локальной разработки вам почти всегда нужна команда `yarn twenty dev`. Развертывание и публикация предназначены для выпуска релизов, **а не** для локального цикла разработки.
|
||
</Note>
|
||
|
||
| Вы хотите… | Команда | Заметки |
|
||
| ---------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||
| Выполнять локальные итерации с синхронизацией в реальном времени | `yarn twenty dev` | Отслеживает ваши файлы и синхронизирует при каждом изменении. |
|
||
| Выполнить одну синхронизацию и выйти (CI, скрипты, хуки) | `yarn twenty dev --once` | Одна сборка + синхронизация, затем завершение работы. |
|
||
| Предпросмотр изменений **без их применения** | `yarn twenty dev --once --dry-run` | Вычисляет и выводит 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` | Удаляет **все** локальные данные — крайняя мера. |
|
||
|
||
### Для локальной синхронизации не нужно повышать версию
|
||
|
||
Правило строго возрастающей `version` (`VERSION_ALREADY_EXISTS` при deploy, `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION` при install) относится к **`app:publish` / `app:install`** — пути релизов. `yarn twenty dev` синхронизирует ваш манифест на месте и никогда не требует изменения версии, поэтому вам не нужно трогать `package.json`, чтобы делать итерации. Если вы ловите себя на том, что поднимаете версию, чтобы протестировать локальное изменение, значит вы используете релизный путь, когда вам нужен цикл разработки (dev loop).
|
||
|
||
## Чтение вывода синхронизации
|
||
|
||
Каждая синхронизация выводит изменения метаданных, которые она применила (или применила бы, с `--dry-run`):
|
||
|
||
```text filename="Terminal"
|
||
Metadata changes: 2 created, 1 updated, 1 deleted
|
||
created objectMetadata rocket
|
||
created fieldMetadata timelineActivities
|
||
updated fieldMetadata launchedAt
|
||
deleted pageLayout legacyTab
|
||
✓ Synced
|
||
```
|
||
|
||
Это ваша первая диагностическая точка: она показывает, какие именно объекты, поля и макеты изменились, чтобы вы могли подтвердить, что синхронизация сделала то, что вы ожидали, до проверки в интерфейсе.
|
||
|
||
Когда синхронизация завершается с ошибкой на одной сущности, в сообщении указываются проблемная сущность и её `universalIdentifier`, например:
|
||
|
||
```text
|
||
Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
|
||
```
|
||
|
||
Используйте этот идентификатор, чтобы найти сущность в своем манифесте (и, при необходимости, в рабочем пространстве), вместо того чтобы гадать, какая из них конфликтует.
|
||
|
||
## Предпросмотр изменений (dry run)
|
||
|
||
`yarn twenty dev --once --dry-run` собирает ваш манифест, запрашивает у сервера план миграции и выводит его — **без применения чего-либо**. Это безопасный способ ответить на вопрос «что изменит эта синхронизация?» до того, как вы на неё согласитесь.
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty dev --once --dry-run
|
||
```
|
||
|
||
```text filename="Terminal"
|
||
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
|
||
```
|
||
|
||
Пробный запуск (dry run):
|
||
|
||
* **Ничего не записывает** — ни миграции метаданных, ни обновления записи приложения, ни изменений ролей/вкладок по умолчанию, ни генерации API‑клиента.
|
||
* Возвращает **тот же diff**, который применит реальная синхронизация, чтобы вы могли заранее просмотреть создаваемые/обновляемые/удаляемые сущности.
|
||
* Полезен перед рискованным изменением, при проверке изменения, сгенерированного ИИ, или в скрипте, который должен завершаться с ошибкой, если вот-вот будет применено неожиданное изменение.
|
||
|
||
<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>
|
||
|
||
## Избегайте одновременных синхронизаций в одном рабочем пространстве
|
||
|
||
Синхронизация применяет миграции метаданных. Запуск нескольких операций sync, deploy или install по отношению к **одному и тому же рабочему пространству одновременно** — например, из нескольких терминалов или при параллельных итерациях агентов ИИ — может перемешать эти миграции и оставить метаданные в частично примененном состоянии.
|
||
|
||
Сервер последовательно обрабатывает синхронизации для каждого рабочего пространства, чтобы предотвратить это, но вам всё равно следует пропускать чувствительные операции с метаданными через **один** процесс, а не запускать их параллельно. Если вы организуете разработку с несколькими агентами, направляйте их вызовы sync/deploy/install через одну очередь, чтобы в каждый момент времени выполнялась только одна операция.
|
||
|
||
## Как различать типы сбоев
|
||
|
||
Когда что‑то идёт не так, diff метаданных и именованные ошибки помогают определить, на каком этапе произошел сбой:
|
||
|
||
* **Ошибка сборки манифеста** — CLI завершается с ошибкой до синхронизации (`MANIFEST_BUILD_FAILED`, `TYPECHECK_FAILED`); исправьте исходный код приложения.
|
||
* **Ошибка синхронизации / миграции** — сборка проходит успешно, но применение diff завершается сбоем с указанием сущности и `universalIdentifier`; исправьте конфликтующие метаданные.
|
||
* **Ошибка выполнения кода приложения** — синхронизация проходит успешно, но ваши логические функции или компоненты ведут себя неправильно во время выполнения; проверьте [журналы функций](/l/ru/developers/extend/apps/operations/cli).
|
||
* **Локальное состояние экземпляра** — ни один из вышеперечисленных пунктов не подходит, и рабочее пространство всё ещё выглядит неправильно; двигайтесь вниз по лестнице восстановления.
|