Перенос данных из облака (cloud → on-prem)

Около 5 мин

Перенос данных из облака (cloud → on-prem)

📦 Переходите с облачного StormBPMN на собственную (on-prem) установку? Здесь — полная процедура переноса вашей команды: что подготовить, какие права выдать и как загрузить архив с данными.

Когда выполнять перенос

Перенос запускается в узком окне: после первичной развёртки по Быстрому старту, но до прохождения онбординга — то есть до создания первого администратора, команды и пользователей.

Причина — импорт работает только на пустой базе (см. главные принципы ниже). Как только вы заведёте первого пользователя или команду, база перестанет быть пустой и импорт придётся начинать с пересоздания схемы и очистки данных.

Перенос устроен так: мы на своей стороне выгружаем вашу команду из облака в самодостаточный архив-бандл (файл с расширением .storm), вы загружаете его в свежую on-prem установку через REST API приложения. Сервис сам распарсит архив, разложит строки по таблицам и зальёт файлы (аватары, превью диаграмм, вложения) в ваше объектное хранилище S3.

Кто участвует

В переносе обычно задействованы несколько ролей с вашей стороны:

Администратор сервера — выполняет шаги на сервере.
DBA / администратор БД — выдаёт временное право на одну привилегию (см. ниже).

Со стороны Storm перенос сопровождает ваш менеджер: мы готовим и передаём вам файл-бандл и помогаем на связи в реальном времени.

Главные принципы

Перенос — это снимок на момент выгрузки. После того как мы сняли .storm-бандл из облака, дальнейшие изменения в облаке в on-prem не переедут — постоянной синхронизации между облаком и on-prem нет. Поэтому окно переезда согласуйте заранее: на время миграции работу команды в облаке останавливают, дожидаются завершения импорта и продолжают работу уже в on-prem.
Импорт только на пустую базу. Импорт рассчитан на свежую базу (сразу после первичной инициализации Liquibase). Если в базе уже есть пользователи — импорт остановится с ошибкой. На первичной установке база и так пустая; если же сервис уже использовался — сохраните все необходимые данные и настройки перед сбросом базы.
Нужно временное право на одну привилегию БД. На время заливки приложение в рамках одной своей сессии отключает проверку внешних ключей (session_replication_role = replica), а после загрузки включает её обратно и проверяет связность данных. Для этого пользователю, с которым Storm подключается к БД, нужна роль SUPERUSER или точечный грант SET ON PARAMETER (PostgreSQL 14+). Право можно выдать на время переноса и сразу отозвать — оно не влияет ни на что, кроме импорт-сессии.
Перенос — операция «в один проход». Импорт идёт в одной транзакции: либо проходит целиком, либо откатывается, оставляя базу в чистом состоянии. Не запускайте импорт повторно поверх уже импортированных данных — сначала пересоздайте схему.

Чек-лист готовности

Пройдитесь по списку до того, как мы начнём выгрузку из облака. Большую часть пунктов приложение проверит ещё раз автоматически при импорте, но лучше закрыть их заранее — это экономит окно с выданным грантом.

Доступы и инфраструктура

Есть доступ к серверу, где поднят стек.
Приложение подключено к S3 (переменная S3_ENDPOINT задана).
У учётной записи S3 есть права на создание бакетов или нужные бакеты уже созданы вручную (имена дадим мы — они должны совпасть с архивом).

Часовой пояс

Часовой пояс приложения соответствует вашему (например, Europe/Moscow). Проверьте TZ и/или -Duser.timezone в JAVA_OPTS контейнера.

Почему это важно

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

Права базы данных

Проверена учётка БД, под которой работает приложение (JDBC_URL / USERNAME / PASSWORD), и согласовано окно на выдачу гранта с DBA / безопасниками.

Подключитесь к БД под учёткой приложения и выполните:

SELECT
  current_user AS me,
  rolsuper AS i_am_super,
  has_parameter_privilege(current_user, 'session_replication_role', 'SET') AS can_set,
  current_setting('server_version') AS pg_version
FROM pg_roles
WHERE rolname = current_user;

Импорт сработает, если хотя бы один из столбцов i_am_super или can_set равен t (true).

Бэкап данных (опционально)

Сохранены все необходимые данные и настройки — только если это не первичная установка и сервис уже использовался.

Процедура переноса

Шаг 1. Выдать право на привилегию БД

Если в проверке выше i_am_super и can_set оба f (false), попросите DBA (под суперюзером или admin-ролью провайдера — rds_superuser, cloudsqlsuperuser и т.п.) выполнить:

GRANT SET ON PARAMETER session_replication_role TO <db_user>;

где <db_user> — учётная запись из current_user в проверке. После этого повторите проверочный SELECT и убедитесь, что can_set стал t.

Право можно выдать в последний момент

Если безопасники не готовы держать грант долго — согласуйте узкое окно. Перенос быстрый (обычно несколько минут), грант нужен только на время самого импорта и отзывается сразу после.

Шаг 2. Сбросить базу — только если сервис уже использовался

На свежей установке пропустите этот шаг

После Быстрого старта база уже пустая — переходите сразу к Шагу 3. Сброс нужен, только если on-prem-сервис уже использовался и в базе есть пользователи/данные (импорт работает лишь на пустой базе).

Чтобы вернуть базу в пустое состояние:

Остановите контейнер stormbpmn.
Под учёткой приложения сбросьте схему:
```
DROP SCHEMA public CASCADE;
CREATE SCHEMA public;
```

Шаг 3. Обновить образ, включить импорт-профиль и развернуть

Обновите версию образа до последней (см. Changelog) и задайте/проверьте переменные окружения.

Переменная	Значение
`S3_BUCKET_UPLOADS`	storm-prod-uploads
`S3_BUCKET_USERS`	storm-prod-users
`S3_BUCKET_IMPORTS`	storm-prod-imports
`S3_SINGLE_USERS_BUCKET`	`true`
`SPRING_PROFILES_ACTIVE`	`prod,handover-import`

Имена бакетов должны совпасть с архивом

Архив переносит файлы, сохраняя исходные имена бакетов. Если имена в S3_BUCKET_* не совпадут с теми, что зашиты в бандле, импорт остановится и подскажет, какое имя ожидается. Используйте ровно те значения, что мы передадим.

Примените изменения и дождитесь в логах строки Started BackendApplicationKt in … seconds.

Шаг 4. Дождаться файла и гранта, проверить доступность

Дождитесь от менеджера Storm файла-бандла (*.storm).
Убедитесь, что грант на привилегию выдан (повторный SELECT, can_set = t).
Зайдите по SSH на сервер и проверьте, что сервис отвечает локально:
```
curl http://localhost:8080/api/health/liveness
# ожидаемый ответ: {"status":"UP"}
```

Без гранта ручка отобьёт запрос

Импорт начинается с проверки прав. Если грант ещё не выдан — приложение вернёт ошибку, не загружая данные. Поэтому дождитесь подтверждения от DBA, прежде чем отправлять файл.

Шаг 5. Загрузить архив

Скопируйте полученный .storm-файл на сервер (например, по scp):

scp Команда-20260429-101020.storm <user>@<STORM_HOST>:/tmp/

Затем с самого сервера отправьте файл в локально поднятый сервис.

curl -# -X POST \
  -F "bundle=@/tmp/Команда-20260429-101020.storm" \
  http://localhost:8080/api/v1/handover/import

После того как файл загрузится, сервис ещё несколько минут раскладывает данные и льёт файлы в S3 — за этим можно следить в логах контейнера.

Успешный ответ — 200 OK с JSON-сводкой: сколько строк по каждой таблице загружено, сколько файлов залито в S3 и сколько времени занял импорт. Сохраните sourceTeamId из ответа — он понадобится на Шаге 8.

{
    "ok": true,
    "errors": [],
    "sourceTeamId": "7d8fc07d-ced8-4615-9d33-a83364e42ae5",
    "sourceTeamName": "Команда ...",
    "blobsDeclared": 282,
    "blobsUploaded": 282,
    "blobsFailed": 0,
    "userSetSize": 20,
    "durationMs": 34294
}

Если ответ пришёл с "ok": false или с HTTP-статусом 422 — смотрите раздел с ошибками ниже: в поле errors приложение подробно пишет, что именно не так и как починить.

Шаг 6. Пройти онбординг и проверить данные

Откройте Storm в браузере по адресу вашей установки. Пройдите онбординг по стандартному сценарию, в рамках которого вы создадите команду и учётную запись администратора сервера.

Под этой учёткой откройте раздел Администрирование и проверьте:

Управление пользователями — число пользователей и активных учёток совпадает с ожидаемым (бывшие участники облачной команды переносятся отключёнными и не занимают места в лицензии).
Попросите кого-то из коллег зайти в Storm под их привычным облачным логином-паролем и проверить, что все данные на месте: диаграммы, роли, элементы архитектуры, оргструктура и т.д.
Проверьте работу S3: у перенесённых из облака пользователей отображается своя аватарка, превью диаграмм при наведении на них, а также скачивание файлов в Настройки приложения → Шаблоны документов.

Шаг 7. Завершить перенос (откат временных настроек)

После того как коллеги подтвердят, что данные на месте:

Попросите DBA отозвать грант на привилегию, если была необходимость в выдаче.
Уберите handover-import из SPRING_PROFILES_ACTIVE (оставьте только prod) и перезапустите контейнер.

Шаг 8. Пост-настройка

Под учёткой администратора в Администрирование → Настройки приложения:

Общие настройки — пропишите baseUrl системы (ваш DNS).
Бизнес-логика → Онбординг и команды — задайте autoJoinTeamId равным UUID перенесённой команды (это sourceTeamId из ответа на Шаге 5; его же видно в Управление командами).
(Опционально) Если на этапе подготовки вы сохраняли предыдущие настройки сервиса — верните их в соответствующих разделах панели администрирования.

Данные перенесены

Дальше доведите инсталляцию до промышленного состояния по инструкции Production-установка — SSL/HTTPS, SSO, мониторинг, резервное копирование и остальная обвязка.

Устранение неполадок

Ошибка про права на session_replication_role

Грант не выдан или выдан не той учётке. Повторите проверочный SELECT под учёткой приложения и убедитесь, что i_am_super = t или can_set = t. На managed-Postgres грант выдаёт admin-роль провайдера.

«В on-prem уже есть N пользователей»

База не пустая — импорт работает только на свежей схеме. Выполните DROP SCHEMA public CASCADE; CREATE SCHEMA public;, перезапустите контейнер (Liquibase накатит схему заново) и повторите импорт.

Ошибка про имена бакетов S3

Имена в S3_BUCKET_UPLOADS / S3_BUCKET_USERS / S3_BUCKET_IMPORTS не совпадают с теми, что зашиты в архиве. В тексте ошибки указано ожидаемое имя — выставьте его в соответствующую переменную и перезапустите импорт.

ok=false и список «orphan-FK связей»

После загрузки приложение нашло нарушения связности и откатило импорт целиком — база осталась чистой. Это значит, что архив повёз неконсистентные данные или схемы облака и on-prem разошлись. Передайте ответ сервиса со списком ошибок менеджеру Storm — разберёмся на нашей стороне.