Общие рекомендации
Всегда создавайте резервную копию базы данных перед началом процесса обновления, выполнив:- Остановите Twenty:
docker compose down - Измените значение
TAGв файле.envрядом с вашимdocker-compose.yml - Запустите Twenty:
docker compose up -d
Префикс кэша Redis
REDIS_CACHE_PREFIX является необязательным и по умолчанию имеет значение пустой строки. Если оставить его пустым, существующие имена ключей кэша сохранятся без изменений, без добавления двоеточия и без миграции ключей.
Для развертываний Redis Enterprise или Azure Managed Redis, в которых во время операций с кэшем возникают ошибки CROSSSLOT, задайте REDIS_CACHE_PREFIX={twenty-cache} на каждом сервере, воркере и в каждой команде обновления. Фигурные скобки обеспечивают, что все ключи хранилища кэша используют один слот хеширования Redis. Это не распределяет данные кэша между шардами. REDIS_QUEUE_PREFIX применяется только к очередям и остается отдельным.
Например, engine:workspace:flatObjectMetadataMaps:123:hash становится {twenty-cache}:engine:workspace:flatObjectMetadataMaps:123:hash только при настройке этого префикса. cache:flush автоматически использует настроенный префикс.
Изменение префикса переключает на отдельное пространство имен кэша. Перед его изменением остановите все серверы и воркеры Twenty, затем перезапустите их с тем же значением. Существующие записи с предыдущим префиксом остаются без изменений. Если вы повторно используете ранее использованный префикс, перед перезапуском выполните yarn command:prod cache:flush с этим значением, чтобы удалить устаревшие записи. Поэтапные развертывания с разными значениями префикса не поддерживаются.
Обновление до 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, чтобы процедура дополнения с самого начала записывала строки под этим ключом. Смена ключей после завершения дополнения требует ротации.
Ротация секретов и ключей подписи
Для повседневных операционных задач, таких как ротацияENCRYPTION_KEY, ротация ключа подписи JWT или отзыв скомпрометированного ключа подписи, см. специализированное руководство Key rotation guide.
Проверка статуса обновления
Командаupgrade:status позволяет просмотреть текущее состояние вашего экземпляра и миграций рабочих пространств. Это полезно для отладки проблем с обновлением или при обращении в поддержку.
Запустите её из контейнера сервера:
Настройки
Устранение неполадок
Если обновление завершается ошибкой в некоторых рабочих пространствах, сервер не перейдёт дальше проблемного шага. Перезапуск сервера (docker compose up -d) повторит обновление с того места, где оно остановилось.
Чтобы быстро выявить проблемы, выполните: