Выбор варианта установки

Для версии 0.5.15 доступны три независимых варианта установки. Выберите архив, соответствующий целевой системе,  и выполните для него соответствующий раздел этой инструкции.

Python на целевой машине не требуется. Linux-архив предназначен для x86_64 с glibc 2.36 или новее. Для Alpine/musl, ARM64 и более старой glibc этот бинарник не подходит.

В каждом архиве есть README.md и .env.example. README описывает установку только выбранного варианта. Этот документ содержит полную инструкцию по разворачиванию всех трёх вариантов приложения. В Windows-архив также включены WinSW 2.12.0 и его MIT-лицензия. Исходники сервиса, рабочая БД, пароли и Git-модель для установки не нужны.

Используйте только один вариант для одного набора данных и Git-модели. Не запускайте одновременно консольный экземпляр, службу и контейнер с общей БД/моделью.

Windows: установка, запуск и остановка

Нужен Git for Windows, установленный для всех пользователей. Python не нужен. Для службы требуется .NET Framework 4.6.1+; WinSW включён в архив.

1. Полностью распакуйте Windows ZIP в отдельный постоянный каталог, например C:\ModusBI\MigrationService.
2. Дважды нажмите Setup.cmd. Выберите 1 — обычное приложение,  2 — Windows-служба. Для службы подтвердите системный запрос прав администратора.
3. Сценарий сам проверит зависимости и порт, создаст конфигурацию со случайным токеном, рабочие каталоги и Git-модель, а также настроит права. Существующие настройки и данные сохраняются. Вводить команды PowerShell вручную не нужно.
4. Сохраните показанный в окне токен входа. Он также хранится в .env в строке MMS_API_TOKEN. Откроется браузер с приложением.

Для следующих запусков используйте Run.cmd. Обычное приложение работает в консольном окне, остановка — Ctrl+C. Stop.cmd останавливает установленную здесь службу. Служба запускается автоматически и восстанавливается после сбоя; журналы находятся в logs.

Перед переходом из обычного режима в службу остановите консольный экземпляр. Служба устанавливается автоматически, только если приложение лежит в отдельном каталоге, а рабочие подкаталоги находятся внутри него. Если в старой конфигурации пути ведут наружу или пароли записаны прямо в .env, такую установку должен отдельно настроить администратор. Подробности и сообщения ошибок описаны в Windows README внутри архива.

Linux: первый запуск

На Debian 12/Ubuntu с glibc 2.36+ установите Git и CA-сертификаты:

sudo apt-get update
sudo apt-get install -y git ca-certificates curl
sudo useradd --system --user-group --home-dir /var/lib/modus-migration \
  --create-home --shell /usr/sbin/nologin modus-migration
sudo install -d -m 0755 /opt/modus-migration
sudo install -m 0755 modus-migration-service /opt/modus-migration/
sudo install -m 0640 -o root -g modus-migration .env.example /opt/modus-migration/.env
sudo install -d -o modus-migration -g modus-migration -m 0700 \
  /var/lib/modus-migration/state /var/lib/modus-migration/model-repository
sudo -u modus-migration git -C /var/lib/modus-migration/model-repository init
sudo -u modus-migration git -C /var/lib/modus-migration/model-repository \
  config user.name 'ModusBI Migration'
sudo -u modus-migration git -C /var/lib/modus-migration/model-repository \
  config user.email 'modusbi-migration@example.local'
sudoedit /opt/modus-migration/.env

Задайте собственный MMS_API_TOKEN. Пути в Linux-примере уже абсолютные. При существующей учётной записи повторно выполнять useradd не нужно.

Для проверки в консоли:

cd /opt/modus-migration
sudo -u modus-migration ./modus-migration-service
# В другой консоли:
curl --fail http://127.0.0.1:8080/health

Ожидается {"status":"ok","version":"0.5.15","database":"ok"}. После проверки остановите процесс Ctrl+C.

systemd

Из каталога распакованного пакета:

sudo install -m 0644 modus-migration.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now modus-migration
sudo systemctl status modus-migration --no-pager
curl --fail http://127.0.0.1:8080/health
sudo journalctl -u modus-migration -n 100 --no-pager

Управление: sudo systemctl stop|start|restart modus-migration. Изменение .env применяется после перезапуска. Для удаления регистрации: sudo systemctl disable --now modus-migration, затем удалите только /etc/systemd/system/modus-migration.service и выполните daemon-reload. Каталоги состояния, конфигурация и Git-модель при этом сохраняются.

Unit использует /opt/modus-migration и учётную запись modus-migration. Если пути или имя пользователя отличаются, исправьте unit перед установкой.

Docker: готовый образ без сборки

Распакуйте Docker ZIP в отдельный постоянный каталог. Исходный репозиторий не нужен. Интернет во время docker load и запуска не требуется.

docker load --input image.tar
cp .env.example .env

До ввода секретов ограничьте доступ к каталогу поставки. На Linux:

chmod 700 .
chmod 600 .env
mkdir -p state model-repository
chmod 700 state model-repository

В Windows вместо cp можно использовать Copy-Item. В PowerShell из нового выделенного каталога выполните:

$migrationOperatorSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
icacls . /inheritance:r /grant:r "*${migrationOperatorSid}:(OI)(CI)F" '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-18:(OI)(CI)F'
if ($LASTEXITCODE -ne 0) { throw 'Не удалось ограничить доступ к каталогу' }

Не применяйте эти команды к общим каталогам. Если у каталога уже заданы отдельные права, проверьте их заранее. Docker Desktop должен работать от учётной записи с доступом к этому каталогу. В .env задайте собственный MMS_API_TOKEN. Затем:

docker compose run --rm --no-deps --entrypoint git modus-migration init /workspace
docker compose run --rm --no-deps --entrypoint git modus-migration -C /workspace config user.name 'ModusBI Migration'
docker compose run --rm --no-deps --entrypoint git modus-migration -C /workspace config user.email 'modusbi-migration@example.local'
docker compose up -d --wait
docker compose ps
docker compose logs --tail=100 modus-migration

Git находится внутри образа. Compose создаёт каталоги state и model-repository на хосте; они сохраняются при пересоздании контейнера. Порт опубликован только на 127.0.0.1:8080. Если он занят, измените левую часть маппинга, например 127.0.0.1:18080:8080, и используйте этот порт в браузере. Правая часть остаётся 8080. Проверка: curl --fail http://127.0.0.1:8080/health. В Windows используйте Invoke-RestMethod.

Остановка: docker compose down. Не удаляйте каталоги state, model-repository и .env. Команда restart не перечитывает .env. Если вы изменили .env, выполните docker compose up -d --force-recreate --wait. Docker Engine/Desktop должен автоматически запускаться после перезагрузки хоста. Если администратор остановил контейнер вручную, restart: unless-stopped его не запустит.

Настройка сервиса после установки

1. Откройте адрес сервиса и войдите с MMS_API_TOKEN.
2. В разделе Порталы добавьте источник и приёмник: адрес, логин, пароль. Проверьте TLS-сертификаты и подключение.
3. В разделе Проекты укажите каталог отдельного Git-репозитория модели и портал-источник. При стандартной установке этот репозиторий уже создаётся: в Windows его подготавливает Setup.cmd, а команды для Linux и Docker приведены выше в соответствующих разделах. Если используется другой каталог, предварительно выполните в нём git init и предоставьте учётной записи приложения права на чтение и запись. Удалённый Git-сервер для работы сервиса не обязателен.
4. Используйте Перенос → Обновить с портала. Перед переносом проверьте план. Первый перенос выполните на тестовом контуре.

Пошаговая работа с объектами описана в разделе «Сервис переноса отчетов Migration Service. Руководство пользователя».

Обновление, резервное копирование и восстановление

1. Дождитесь завершения всех заданий. После остановки незавершённые задания помечаются interrupted. Проверьте журнал и состояние приёмника; перед повторным переносом заново проверьте план.

2. Остановите приложение, службу или контейнер. Скопируйте перечисленные ниже файлы и каталоги целиком в отдельный защищённый каталог резервной копии, расположенный вне каталога установки:

   Вариант	Что сохранить
   Windows	.env, каталоги state и model-repository из каталога приложения, а также все дополнительно подключённые Git-модели
   Linux	/opt/modus-migration/.env, весь /var/lib/modus-migration и все Git-модели, находящиеся в других каталогах
   Docker	.env, state и model-repository из каталога с compose.yaml

   
   В таблице указаны стандартные пути. Если в .env изменены MMS_STATE_DIR, MMS_ENV_FILE, MMS_GIT_ROOT, MMS_MODEL_DIR, MMS_ENVIRONMENTS_DIR или каталоги томов в compose.yaml, сохраняйте фактически настроенные файлы и каталоги. Каталог state сохраняйте полностью: при стандартной конфигурации в нём находятся service.db, резервные копии заданий и portal-credentials.env. Не помещайте резервную копию внутрь заменяемого каталога приложения. Ограничьте доступ к ней так же, как к рабочей .env: копия содержит токены и учётные данные порталов. Если в вашей сборке настроена внешняя БД и установлен необходимый SQLAlchemy-драйвер, одновременно создайте её резервную копию штатными средствами СУБД.

3. Распакуйте новую поставку в отдельный каталог.
4. Для Windows/Linux замените только основной бинарник. Не копируйте .env.example поверх существующего .env. Файлы настроек службы (XML в Windows и unit в Linux) проверяйте вручную: в них могут быть указаны ваша учётная запись и пути.
5. Для Docker загрузите новый образ, измените тег image в compose.yaml, сохраните монтирования, запустите docker compose up -d --wait.
6. Проверьте /health, версию, вход, список проектов и журнал заданий.

Для отката остановите новый процесс и верните прежний бинарник/образ. Если версия меняла схему БД или формат модели, одного возврата бинарника недостаточно: до запуска приложения верните сохранённые .env, state и Git-модели в те же пути, из которых они были скопированы, и восстановите согласованную копию внешней БД, если она используется. Не объединяйте содержимое старого и нового state.

Типовые проблемы

По умолчанию сервис доступен только на этом компьютере через 127.0.0.1. Для доступа с других машин настройте HTTPS reverse proxy и сетевые правила. Запускайте один экземпляр сервиса для одного набора состояния и Git-модели.