103 lines
6.8 KiB
Plaintext
103 lines
6.8 KiB
Plaintext
---
|
||
title: Руководство по обновлению
|
||
icon: arrow-up-right-dots
|
||
---
|
||
|
||
## Общие рекомендации
|
||
|
||
**Всегда создавайте резервную копию базы данных перед началом процесса обновления**, выполнив:
|
||
|
||
```bash
|
||
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
|
||
```
|
||
|
||
Восстановление из резервной копии:
|
||
|
||
```bash
|
||
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
|
||
```
|
||
|
||
Если вы используете Docker Compose, выполните следующие шаги:
|
||
|
||
1. Остановите Twenty: `docker compose down`
|
||
2. Измените значение `TAG` в файле `.env` рядом с вашим `docker-compose.yml`
|
||
3. Запустите Twenty: `docker compose up -d`
|
||
|
||
Сервер автоматически выполняет все необходимые миграции обновления при запуске. Ручных команд не требуется.
|
||
|
||
## Межверсионные обновления (v1.22+)
|
||
|
||
Начиная с **v1.22**, Twenty поддерживает межверсионные обновления. Вы можете перейти напрямую с любой поддерживаемой версии на последний релиз, не проходя каждую промежуточную версию.
|
||
|
||
Например, полностью поддерживается обновление с v1.22 сразу до 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, чтобы процедура дополнения с самого начала записывала строки под этим ключом. Смена ключей после завершения дополнения требует [ротации](/l/ru/developers/self-host/capabilities/key-rotation).
|
||
|
||
## Ротация секретов и ключей подписи
|
||
|
||
Для повседневных операционных задач, таких как ротация `ENCRYPTION_KEY`, ротация ключа подписи JWT или отзыв скомпрометированного ключа подписи, см. специализированное руководство [Key rotation guide](/l/ru/developers/self-host/capabilities/key-rotation).
|
||
|
||
## Проверка статуса обновления
|
||
|
||
Команда `upgrade:status` позволяет просмотреть текущее состояние вашего экземпляра и миграций рабочих пространств. Это полезно для отладки проблем с обновлением или при обращении в поддержку.
|
||
|
||
Запустите её из контейнера сервера:
|
||
|
||
```bash
|
||
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
|
||
```
|
||
|
||
Пример результата:
|
||
|
||
```sh
|
||
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`) повторит обновление с того места, где оно остановилось.
|
||
|
||
Чтобы быстро выявить проблемы, выполните:
|
||
|
||
```bash
|
||
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
|
||
```
|
||
|
||
Будут показаны только рабочие пространства, которые отстают или завершились с ошибкой, вместе с сообщением об ошибке для каждого сбоя.
|
||
|
||
## До v1.22
|
||
|
||
Если ваш экземпляр старее v1.22, необходимо поэтапно обновляться через каждую основную помеченную версию (с v1.6 до v1.7, затем с v1.7 до v1.8 и так далее) до v1.22. После этого можно перейти сразу на последнюю версию.
|