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

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

@@ -0,0 +1,106 @@
+---
+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. После этого можно перейти сразу на последнюю версию.