Эксплуатация и обновления

Эта страница — руководство оператора по запуску Turbo EA в продакшене: как работают обновления и миграции базы данных, как делать резервные копии и откатываться, какие окружения стоит развернуть и какие подводные камни подстерегают команды в масштабе.

Продакшен-образы и фиксация версии

Опубликованные образы ghcr.io/vincentmakes/turbo-ea/* — рекомендуемый способ запуска в продакшене: стандартный docker-compose.yml загружает их по умолчанию, а сборка из исходников — это рабочий процесс разработки. Помимо удобства, опубликованные образы дают гарантии цепочки поставок, которых нет у локальной сборки: каждая публикация мультиархитектурная (amd64 + arm64), подписана cosign (бесключевой OIDC, проверяется по идентичности workflow GitHub Actions) и снабжена аттестацией происхождения SLSA и SBOM. Публикация блокируется при критических CVE, опубликованные образы ежесканируются ежедневно и еженедельно пересобираются на свежих репозиториях Alpine, поэтому патчи базовых образов подтягиваются автоматически. Если ваша организация требует проверки подписей образов при допуске, подписи cosign встраиваются напрямую — команды проверки см. в разделе Цепочка поставок.

Самая важная привычка: фиксируйте версию. Тег :latest переназначается при релизах и еженедельной пересборке — не при каждом коммите — поэтому он может меняться по расписанию, которое вы не контролируете. Задайте явный тег в вашем .env:

TURBO_EA_TAG=2.23.1

Основы см. в разделе Фиксация версии, а полное дерево тегов и политику предрелизных каналов — в разделе Релизы.

Управляемый PostgreSQL

В корпоративных средах с доступом к управляемому сервису PostgreSQL — Azure Database for PostgreSQL, Amazon RDS / Aurora, Google Cloud SQL или аналогичному — запуск Turbo EA на нём является рекомендуемой конфигурацией. Встроенный контейнер db — это удобное значение по умолчанию без зависимостей, а не требование: направьте бэкенд на свой инстанс через переменные POSTGRES_* и не запускайте встроенный сервис (см. Использование существующего PostgreSQL).

Что управляемый сервис снимает с ваших плеч:

• Резервные копии и восстановление на момент времени (PITR) — автоматизированные, с управляемым хранением и восстановлением на любой момент; именно то, что нужно стратегии отката ниже.
• Высокая доступность и переключение при сбое — зональная или региональная избыточность без собственной репликации.
• Патчи движка, шифрование при хранении, сетевая изоляция — по базовым требованиям соответствия вашей организации (приватные конечные точки, интеграция с IAM).

Три вещи, которые не меняются: бэкенд по-прежнему сам выполняет миграции Alembic при запуске (модель обновления на этой странице идентична), тому backend_data по-прежнему нужна собственная резервная копия (файловые вложения и расширения не хранятся в PostgreSQL), и ответственность за SECRET_KEY остаётся на вас. Встроенный образ поставляется с PostgreSQL 18 — подойдёт любая свежая мажорная версия вашего провайдера.

Как работают обновления: миграции Alembic

Совместимость схемы базы данных обеспечивается автоматически через Alembic. При запуске бэкенд выполняет alembic upgrade head, поэтому все ожидающие миграции между вашей текущей схемой и новой версией применяются — по порядку — до того, как приложение начнёт обслуживать трафик.

Миграции пронумерованы последовательно и накапливаются, поэтому «прыжки» через версии безопасны: если вы обновляетесь, скажем, с 2.10 до 2.23, все промежуточные миграции выполняются по очереди. Проходить каждый минорный релиз по отдельности не нужно.

Несколько особенностей, которые стоит знать:

Ситуация	Что происходит при запуске
Новая база данных	Таблицы создаются напрямую, база помечается как head — без воспроизведения миграций.
Существующая база данных	Ожидающие миграции выполняются автоматически до того, как API станет доступен.
RESET_DB=true	Все таблицы удаляются, создаются заново и заполняются заново. Никогда не включайте в продакшене.

В пределах одной мажорной линии версий миграции остаются аддитивными и обратно совместимыми при обновлении — полный контракт см. в Политике совместимости.

Никогда не запускайте старый бэкенд на более новой схеме

При запуске Alembic мигрирует только вперёд. Старый код на более новой схеме — неопределённое поведение; это ключевое ограничение отката (см. ниже).

Процедура обновления

1. Прочитайте журнал изменений. Просмотрите записи CHANGELOG.md между текущей версией и целевой. Несовместимые изменения повышают мажорную версию.
2. Сделайте резервную копию базы данных и тома данных (см. ниже).

3. Поднимите тег и загрузите образы:

   TURBO_EA_TAG=2.24.0 docker compose pull
   docker compose up -d
   

4. Следите за логами запуска и убедитесь, что миграции завершились чисто до того, как API начал обслуживать запросы:

   docker compose logs -f backend
   

Окна обслуживания

Миграции обычно быстрые, но на больших инвентарях некоторые миграции данных могут занять несколько минут, в течение которых бэкенд недоступен. Планируйте обновления в окно обслуживания.

Резервные копии

Делайте резервную копию перед каждым обновлением и в любом случае автоматизируйте ежедневную ночную:

docker compose exec db pg_dump -U turboea turboea > backup-$(date +%F).sql

Скорректируйте пользователя и имя базы, если вы меняли POSTGRES_USER / POSTGRES_DB. Снимок тома postgres_data — равнозначная альтернатива. На управляемом сервисе PostgreSQL (см. раздел «Управляемый PostgreSQL» выше) предпочитайте автоматические резервные копии и восстановление на момент времени от провайдера, а не самодельные дампы — периодический pg_dump всё равно полезен как переносимая, независимая от провайдера копия.

Также делайте резервную копию тома backend_data — в нём хранятся файловые вложения, установленные расширения и бандлы переноса рабочего пространства, которых нет в PostgreSQL.

Ещё два момента о готовности к восстановлению:

• Периодически проверяйте восстановление. Резервная копия, которую ни разу не восстанавливали, — это надежда, а не план.
• Архивированные карточки удаляются мягко, с окном в 30 дней до окончательной очистки — это ваша страховка от ошибок с данными, отдельная от восстановления инфраструктуры.

Откат и восстановление

Миграции схемы в продакшене фактически односторонние: хотя Alembic технически поддерживает даунгрейды, миграции с данными не всегда можно обратить без потерь, и приложение никогда не выполняет даунгрейды автоматически. Надёжная стратегия отката такова:

1. Остановите стек.
2. Восстановите резервную копию базы, сделанную перед обновлением (на управляемом PostgreSQL — восстановление на момент времени непосредственно перед обновлением).
3. Верните TURBO_EA_TAG на предыдущую версию.
4. docker compose up -d — восстановленная база соответствует схеме старого кода, и всё согласовано.

Никогда не откатывайте только образ

Откатить образ, оставив мигрированную базу данных, — единственная комбинация, от которой система автоматических миграций защитить не может. Резервная копия базы и тег образа меняются вместе.

Окружения и управление релизами

Большинству организаций достаточно двух окружений (стейджинг + продакшен), потому что обновления — это образы, выпущенные поставщиком, а не собственные сборки: вы валидируете, а не разрабатываете. Полная цепочка Dev/SIT/UAT/Prod оправдана в основном тогда, когда вы создаёте собственные расширения или тяжёлые интеграции.

Окружение	Назначение	Примечания
Dev / песочница (опционально)	Проба изменений метамодели, демонстрации	SEED_DEMO=true для демонстрационного набора данных; RESET_DB=true даёт чистый старт.
Стейджинг	Первым валидирует новые версии	Данные, близкие к продакшену; первым получает новые теги.
Продакшен	Зафиксированный тег, резервные копии, обновления в окно обслуживания	Никогда latest, никогда RESET_DB.

Два хороших способа наполнить стейджинг реалистичными данными:

• Перенос рабочего пространства: экспортируйте продакшен-пространство как .zip-бандл и импортируйте его в стейджинг. Секреты (учётные данные SMTP, SSO, ИИ, ServiceNow) по замыслу вырезаются и никогда не покидают инстанс.
• Восстановление базы данных: восстановите продакшен-pg_dump в базу стейджинга (на управляемом сервисе хорошо работает и клон или восстановление продакшен-инстанса на момент времени). Зашифрованные секреты в базе выводятся из SECRET_KEY, поэтому стейджингу нужен либо тот же SECRET_KEY, либо повторный ввод учётных данных интеграций.

Что касается управления:

• Относитесь к файлу .env и зафиксированному TURBO_EA_TAG как к конфигурации-как-коду — храните их во внутреннем Git и делайте обновления проверяемым изменением (pull request, поднимающий тег).
• Поскольку стейджинг и продакшен тянут один и тот же зафиксированный тег GHCR, вы валидируете побайтово идентичный артефакт, который затем продвинете.
• Обновите стейджинг → дайте отстояться несколько дней → продвиньте тот же тег в продакшен.

Типичные подводные камни

1. Запуск незафиксированного latest — рутинный docker compose pull превращается в незапланированное обновление с незапланированными миграциями, по графику релизов, а не по вашему.
2. Обновление без резервной копии — миграции односторонние; резервная копия и есть ваш откат.
3. Потеря или смена SECRET_KEY — он подписывает JWT и выводит ключ шифрования сохранённых секретов (учётные данные SMTP, SSO, ServiceNow). Его смена делает сохранённые секреты нерасшифровываемыми. Относитесь к нему как к учётным данным базы: в хранилище секретов, стабильно, с резервной копией.
4. Забытый RESET_DB=true в env-файле — он делает ровно то, что написано, при каждом запуске.
5. Прямое редактирование базы данных — состояние схемы принадлежит Alembic, и ручной DDL столкнётся с будущими миграциями. То же с данными: используйте API или интерфейс, чтобы права доступа, события аудита и пересчёт качества данных оставались корректными.
6. Неперсистентные тома — postgres_data и backend_data должны переживать пересоздание контейнеров; убедитесь, что ваши инструменты снимков и резервного копирования охватывают оба.
7. Откат образа без восстановления базы данных — см. раздел «Откат и восстановление» выше.