upstream-twenty/packages/twenty-docs/l/ru/developers/self-host/capabilities/upgrade-guide.mdx

---
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`

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

## Обновление до v2.34+ — требуется PostgreSQL 15

Для Twenty v2.34 требуется PostgreSQL 15 или более поздней версии. В официальной конфигурации Docker Compose используется PostgreSQL 16. Если ваш экземпляр подключается к внешне управляемой базе данных, обновите её перед запуском сервера v2.34.

## Межверсионные обновления (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, чтобы процедура дополнения с самого начала записывала строки под этим ключом. Смена ключей после завершения дополнения требует [ротации](/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.23

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