Руководство по обновлению

Общие рекомендации

Всегда создавайте резервную копию базы данных перед началом процесса обновления, выполнив:

docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql

Восстановление из резервной копии:

cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}

Если вы используете Docker Compose, выполните следующие шаги:

Остановите Twenty: docker compose down
Измените значение TAG в файле .env рядом с вашим docker-compose.yml
Запустите Twenty: docker compose up -d

Сервер автоматически выполняет все необходимые миграции обновления при запуске. Ручных команд не требуется.

Межверсионные обновления (v1.23+)

Начиная с v1.23, Twenty поддерживает межверсионные обновления. Вы можете перейти напрямую с любой поддерживаемой версии на последний релиз, не проходя каждую промежуточную версию. Например, полностью поддерживается обновление с v1.23 сразу до v2.0.

Переход на v2.5+ — конверт шифрования данных в состоянии покоя

Начиная с v2.5, Twenty хранит секреты в состоянии покоя (токены OAuth, переменные приложения, закрытые ключи подписи, конфиденциальные значения конфигурации, TOTP‑секреты) внутри версионируемого конверта enc:v2:, зашифрованного с помощью ENCRYPTION_KEY (или APP_SECRET, если ENCRYPTION_KEY не задан). Первый запуск на v2.5 выполняет медленные команды обновления, которые дополняют существующие строки, помещая их в новый конверт. Они идемпотентны — при прерывании и перезапуске сервера выполнение продолжается с того места, где остановилось, — но на больших базах данных это может занять продолжительное время. Вы можете отслеживать прогресс с помощью upgrade:status. Вам следует задать отдельный ENCRYPTION_KEY перед обновлением до v2.5, чтобы процедура дополнения с самого начала записывала строки под этим ключом. Смена ключей после завершения дополнения требует ротации.

Ротация секретов и ключей подписи

Для повседневных операционных задач, таких как ротация ENCRYPTION_KEY, ротация ключа подписи JWT или отзыв скомпрометированного ключа подписи, см. специализированное руководство Key rotation guide.

Проверка статуса обновления

Команда upgrade:status позволяет просмотреть текущее состояние вашего экземпляра и миграций рабочих пространств. Это полезно для отладки проблем с обновлением или при обращении в поддержку. Запустите её из контейнера сервера:

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status

Пример результата:

APP_VERSION: v1.23.0

Instance
    Inferred version: 1.23.0
    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
    Status:           Up to date
    Executed by:      v1.23.0
    At:               2026-04-16T11:43:58.823Z

Workspace
  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
      Inferred version: 1.23.0
      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
      Status:           Up to date
      Executed by:      v1.23.0
      At:               2026-04-16T11:44:09.361Z

Summary
    Instance: Up to date
    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)

Настройки

Флаг	Описание
`-w, --workspace-id <id>`	Фильтрует по конкретному рабочему пространству. Можно передавать несколько раз.
`-f, --failed-only`	Скрывает актуальные рабочие пространства, показывает только отстающие и с ошибками.

Устранение неполадок

Если обновление завершается ошибкой в некоторых рабочих пространствах, сервер не перейдёт дальше проблемного шага. Перезапуск сервера (docker compose up -d) повторит обновление с того места, где оно остановилось. Чтобы быстро выявить проблемы, выполните:

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only

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

До v1.23

Если ваш экземпляр старее v1.23, необходимо поэтапно обновляться через каждую основную помеченную версию (с v1.6 до v1.7, затем с v1.7 до v1.8 и так далее) до v1.23. После этого можно перейти сразу на последнюю версию.

Обзор

Приложения

API

Самостоятельный хостинг

Внести вклад

Руководство по обновлению

Общие рекомендации

Межверсионные обновления (v1.23+)

Переход на v2.5+ — конверт шифрования данных в состоянии покоя

Ротация секретов и ключей подписи

Проверка статуса обновления

Настройки

Устранение неполадок

До v1.23

​Общие рекомендации

​Межверсионные обновления (v1.23+)

​Переход на v2.5+ — конверт шифрования данных в состоянии покоя

​Ротация секретов и ключей подписи

​Проверка статуса обновления

​Настройки

​Устранение неполадок

​До v1.23

Общие рекомендации

Межверсионные обновления (v1.23+)

Переход на v2.5+ — конверт шифрования данных в состоянии покоя

Ротация секретов и ключей подписи

Проверка статуса обновления

Настройки

Устранение неполадок

До v1.23