Pilot Migration

Сервис переноса данных между контурами Pilot (прод / тест / стейдж, тест / стейдж), импорта присланных файловых баз и выгрузки базы в файлы. Интерфейс - раздел «Миграция» в веб-админке (proadmin), сам сервис только выполняет переносы и расписания.

Контейнер pilot-migration, порт 5320
Сети pilot-prod, pilot-test, pilot-stage (обращается к pilot-server-*, postgres-*, rustfs-* по именам)
Данные ./data: config.json (подключения, пароли администраторов Pilot и ключи S3 открытым текстом, права 600), schedules.json, runs/ (журналы)
Присланные базы /mnt/import (IMPORT_ROOT, по умолчанию C:/Ascon-Docker/import) - только чтение
Выгрузки /mnt/export (EXPORT_ROOT, по умолчанию C:/Ascon-Docker/export) - на запись
Доступ заголовок X-Api-Key = MIGRATION_API_KEY (один ключ на админку и сервис); после 10 неверных ключей с одного адреса за 5 минут - ответ 429 на 5 минут

Своих docker-compose.yml и .env у сервиса нет: он запускается вместе с админкой из папки proadmin.

cd ..                     # папка proadmin
copy .env.example .env    # заполнить ключ и пароли
docker compose up -d --build migration

Режимы

Полная копия. База приёмника останавливается, все таблицы схемы dbp<версия> заменяются данными источника в одной транзакции (ошибка / откат, приёмник прежний). У приёмника остаются свой идентификатор базы (databaseid) и свои файловые архивы: faslist приводится к settings.xml приёмника. Тела файлов докопируются в его архивы (сначала - пока база ещё работает, чтобы сократить простой), лишние удаляются. Затем база запускается; сервер выдаёт новую сессию, клиенты перечитывают данные.

Выборочно. Отмеченное удаляется в приёмнике и переносится из источника, остальное не меняется (кроме побочных действий галочки «Пользователи», см. таблицу). Id объектов и пользователей сохраняются.

Галочка Что происходит
Дерево объектов - всё все объекты, кроме отчётов и модулей (у них свои галочки)
Дерево объектов - по Id указанные объекты + все потомки + все родители; лишние потомки в приёмнике удаляются
Пользователи people и organisationunits; пользователи приёмника, на которых есть ссылки (история, чаты), остаются. Одноимённые пользователи приёмника с другим Id переименовываются в логин#Id, organisationunits приёмника удаляются целиком и заменяются
Клиентские / веб- / серверные модули объекты типов Extension / WebExtension / $PilotServerExtension
Отчёты объекты типов Report_… и Report_Folder_…
Автоматизации список автоматизаций в метаданных (через админский API, база не останавливается)
Файловый архив тела файлов переносимых объектов; без галочки переносятся только записи

У родителей, которые остаются в приёмнике, правится только список детей - на уровне байтов protobuf (Objects/ProtoWire.cs), остальные поля объекта не пересериализуются.

Полная копия и импорт .dbp идут со снятыми внешними ключами (Database/ForeignKeys.cs; выборочный перенос ключи не снимает): они снимаются и возвращаются в той же транзакции. Иначе таблицы вообще не загрузить - messages.chat_id ссылается на chats, а chats.last_message_id на messages, и порядок загрузки эту пару не разводит. Возврат ключа проверяет уже загруженные строки, то есть заодно это проверка ссылочной целостности переноса.

Импорт файловой базы (.dbp)

Присланную базу Pilot с файловым хранением можно залить в тест или стейдж: «Откуда» / «Файловая база (.dbp)». Переносится только целиком, как полная копия: база приёмника останавливается, все её таблицы заменяются строками из файлов в одной транзакции. В прод - запрещено, как и обычный перенос.

Файлы кладут в IMPORT_ROOT; сервис видит их как /mnt/import/… и ничего в них не пишет - открываются с immutable=1, то есть библиотека SQLite не создаёт даже -wal и -shm.

Каждый файл выбирается отдельно - у присланных выгрузок имена и раскладка по папкам бывают любые. GET /api/import/sources перечисляет все .dbp каталога импорта (на любой глубине) и говорит, чем каждый оказался - по набору таблиц, а не по имени: objects + metadata / основная база, chats + messages / чаты, user_actions / журнал. В админке на каждую роль свой список: сверху подходящие по виду файлы, ниже - «прочие».

Роль Что внутри Когда нужен
Основная база объекты, метаданные (типы), пользователи, права, история, индекс файлового архива всегда
Чаты чаты и сообщения по выбору; пусто - чаты в приёмнике будут пустыми
Журнал действий журнал действий пользователей по выбору; обычно в разы больше самой базы, поэтому по умолчанию не переносится

Таблицы, которых нет в PostgreSQL, отбрасываются сознательно: files (остаток старых версий) и колонка faslist.mask. Таблица relations в PostgreSQL называется message_relations. У приёмника, как и при полной копии, остаются свой идентификатор базы и свои файловые архивы.

Версии сверяются по структуре. В файловой базе нет номера версии сервера, поэтому вместо сравнения версий карта импорта (Database/DbpToPgMap.cs) сверяется со схемой приёмника и с присланными файлами: лишняя или отсутствующая таблица либо колонка с любой стороны - блокирующая ошибка со списком расхождений. Карта - источник истины. Тест PgSchemaSnapshot сверяет её с зашитым в тесты снимком схемы dbp26.13.0.62219, а не с живой схемой: при смене версии Pilot-Server снимок надо обновить, а карту проверить на стенде.

Тела файлов в .dbp не лежат - в базе только их индекс (famediator). Где их взять, указывается рядом: папка внутри каталога импорта или S3 с ключами. Раскладка та же, что у архивов Pilot: {байт 14 Id}/{байт 15 Id}/{Id}. Дальше всё как при полной копии: сначала докопирование, пока приёмник работает, потом остановка, загрузка таблиц и дельта файлов, лишние тела удаляются.

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

Строки с битыми ссылками удаляются. SQLite объявленные внешние ключи не проверяет (PRAGMA foreign_keys сервер не включает), поэтому в файловой базе встречаются, например, участники чатов без пользователя. В PostgreSQL схема Pilot эти связи требует, так что после загрузки такие строки удаляются (повторами, пока есть что удалять: вместе со строкой сиротами становятся её дети), и только потом возвращаются ключи. Сколько и каких строк удалено - в журнале запуска.

Импорт по расписанию не ставится - это разовый перенос. Настройки сервера с файловым источником не копируются: settings.xml у присланной базы нет.

Выгрузка в файлы

Обратный путь импорта: база контура (в том числе прода) выгружается в файлы, чтобы залить её на другом компьютере. «Куда» / «Файлы (выгрузка .dbp)». Выгружается только целиком; источник не останавливается и не меняется - все таблицы читаются в одной транзакции REPEATABLE READ READ ONLY, то есть на один момент времени.

Каталог выгрузок /mnt/export (EXPORT_ROOT, по умолчанию C:/Ascon-Docker/export) - на запись
Список GET /api/export/list и таблица «Выгрузки в файлы» на странице «Миграция»
<имя>/
  base.dbp        объекты, типы, пользователи, права, история, индекс файлов (famediator, faslist)
  chats.dbp       чаты и сообщения (галочка, по умолчанию включена)
  journal.dbp     журнал действий (галочка, по умолчанию выключена)
  FileArchive/    тела файлов в раскладке Pilot {байт 14}/{байт 15}/{Id}
  manifest.json   контур, база, databaseid, версия сервера и схема, строки по таблицам, сколько тел скопировано

Формат - тот, что читает импорт, а не полная копия файловой базы Pilot: таблицы и колонки ровно по карте DbpToPgMap, плюс databaseid. Присоединить такую выгрузку в myAdmin нельзя - только импортировать через этот сервис. Значения пишутся так, как их читает импорт (DbpValue.ToSqlite - обратное к DbpValue.Convert): Guid - 16 байт Guid.ToByteArray, даты - строка 2015-11-07 14:38:29.120443Z, faslist.creation_date - тики .NET, булевы - 0/1. Обратный путь закреплён тестом DbpExportTests.

На другом компьютере: папку выгрузки скопировать в его IMPORT_ROOT и выбрать «Откуда / Файловая база (.dbp)» с файлами base.dbp, chats.dbp, journal.dbp. Если папка архива не указана, а рядом с основной базой лежит FileArchive, импорт берёт тела оттуда сам.

Проверка Почему
вся схема источника есть в карте (DbpToPgMap.ExportDifferences) иначе новая таблица или колонка молча не попала бы в файлы
свободного места в каталоге выгрузок не меньше, чем занимают таблицы тела файлов - сверх этого, их объём заранее не известен
архивы источника доступны на чтение (если отмечен «Файловый архив») иначе выгрузка вышла бы без части тел
имя папки годится и такой выгрузки ещё нет готовые выгрузки не перезаписываются

faslist в base.dbp приводится к архивам settings.xml источника, а файлы из архивов, которых там уже нет (папочный архив, перенесённый в S3), относятся к записываемому архиву - как при полной копии. Пока выгрузка идёт, папка называется <имя>.partial; при ошибке или отмене она удаляется. Следующий запуск удаляет оставшуюся от сбоя папку только с тем же именем; имя по умолчанию содержит дату и время, поэтому .partial, оставшуюся после жёсткого обрыва (перезапуск контейнера, отключение питания), удалите из каталога выгрузок вручную. По расписанию выгрузка не ставится.

В выгрузке все данные базы, в том числе пользователи с хешами паролей, - обращаться с ней как с резервной копией.

Настройки сервера

Настройки settings.xml (админка / «Серверы») - не данные базы, поэтому по умолчанию не переносятся ни в каком режиме: settings.xml приёмника, в том числе при полной копии, не меняется.

Параметры При переносе
Логирование автоматизаций, расширенное логирование, журнал чтения файлов, отладка C# никогда - свои у каждого контура (на проде логирование автоматизаций выключено, на тесте и стейдже включено, иначе пропадёт статистика)
Проверка автора изменений, запрет параллельных изменений, снимки только с отметкой «Настройки сервера»: значения берутся из settings.xml источника и пишутся в server-settings.conf приёмника

Скопированное вступает в силу после перезапуска контейнера приёмника (docker restart pilot-server-<контур>) - это пишется в журнал запуска. У кластера - после перезапуска всех узлов контура (см. «Кластерный Pilot-Server»). Каталоги C:/Ascon-Docker/<контур>/server-settings смонтированы в сервис как /mnt/<контур>/server-settings (рядом с settings), прод - только на чтение.

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

Кластерный Pilot-Server

Контур считается кластерным, если админский API отдаёт у его базы непустой RedisConnectionString (у монолита он пуст). Для такого контура:

Монолит Кластер
Настройки сервера (архивы, строка PostgreSQL, параметры поведения) settings.xml по пути из подключений XML из таблицы config.settings (строка id = 1) базы конфигурации на том же сервере PostgreSQL; имя базы - Migration__ConfigurationDatabase (по умолчанию configurationdb)
Путь к settings.xml нужен не используется: если задан, в проверке предупреждение «очистите путь»
Пароль PostgreSQL из строки в settings.xml в настройках он зашифрован (EncryptedPassword), поэтому берётся из окружения сервиса: Migration__PgPasswords__<контур> (test, stage, prod)
Каталог server-settings приёмника рядом с папкой settings.xml /mnt/<контур>/server-settings
«Настройки сервера» вступают в силу после перезапуска контейнера pilot-server-<контур> после перезапуска всех узлов контура: остановите все, затем запустите. Пока не перезапущены все узлы, остановка или запуск базы на оставшемся узле может вернуть прежние значения

Пароль в compose задаётся из .env: PROD_PILOT_PG_PASSWORD, TEST_PILOT_PG_PASSWORD, STAGE_PILOT_PG_PASSWORD (в комплекте установки - тот же пароль pilotuser, что и у PostgreSQL контура). Задаётся окружением, а не страницей «Подключения», поэтому PUT /api/config его не стирает. У монолита это значение запасное: сначала используется пароль из settings.xml. Без пароля кластерный контур не подключится, в проверке будет ошибка с именем переменной.

Источник - база конфигурации читается по тому же серверу PostgreSQL, что и база Pilot (хост и порт - из админского API), под пользователем из строки подключения API. После запуска базы приёмника-кластера в журнал пишется напоминание: если на каком-то узле не загрузились серверные расширения, перезапустите этот узел (известный сбой Pilot-Server). POST /api/config/check для кластера пишет «кластер» и показывает, что настройки взяты из базы конфигурации.

Файловые архивы

Архивы берутся из settings.xml сервера Pilot (смонтирован только на чтение: админский API не отдаёт адрес S3); у кластера - из его конфигурации в базе. Общее хранилище определяется по совпадению адреса и пробным объектом: он пишется в архив приёмника и ищется в архивах источника. Хранилище контура - RustFS, адрес в новых настройках http://rustfs-<контур>:9000. Адреса сравниваются текстом, а общее хранилище в любом случае находит пробный объект.

Ситуация Что делает сервис
Архив приёмника - то же хранилище, что у источника, в приёмнике «только чтение» файлы не переносятся, пользователю показывается пояснение
То же хранилище: в приёмнике запись разрешена, в источнике «только чтение» не блокируется: тела не копируются, пишется пояснение
То же хранилище, записываемое в обеих базах перенос блокируется
Отдельное хранилище недостающие тела копируются, при полной копии лишние удаляются

Защиты

  • В прод переносить нельзя; источник и приёмник - разные контуры. Запрет держится на метках контуров, поэтому приёмник (тест, стейдж) не должен ссылаться на адрес Pilot, settings.xml или папку архива прода - такой перенос блокируется (адреса сравниваются по хосту, порту и пути, пути нормализуются; другое имя хоста или IP того же сервера и бакеты S3 не распознаются: это защита от очевидной ошибки). Файловые тома прода смонтированы только на чтение (:ro), но учётные данные прода (пароль администратора Pilot, ключи S3, строка PostgreSQL из settings.xml) в сервисе есть, поэтому ключ MIGRATION_API_KEY защищайте как ключ к проду.
  • Приёмник не прод и без пути к settings.xml. Перед изменением приёмника сервис запрашивает у сервера сведения о базе прода и блокирует перенос, если у приёмника тот же идентификатор базы или та же база PostgreSQL (хост:порт/база из админского API, сравнение нормализованное: порт внутри хоста, регистр). Если прод недоступен, перенос тоже блокируется: проверить, что приёмник - не прод, нечем (если прод в подключениях не настроен, проверка не выполняется). Прод-источник запрашивать повторно не нужно.
  • Устаревший settings.xml. Если путь задан и файл прочитан, он сверяется с админским API: идентификатор базы, множество файловых архивов, хост:порт/база PostgreSQL. Расхождение - блокирующая ошибка «settings.xml не соответствует серверу: очистите путь или обновите файл»: иначе миграция тихо писала бы в старую базу PostgreSQL (после переноса базы в кластер) или переписывала faslist по чужим архивам.
  • Версии баз и структура таблиц должны совпадать.
  • Разные кластеры PostgreSQL. Если у источника и приёмника одинаковые идентификатор кластера и контрольная точка в pg_control, значит, два контейнера работают на одной папке данных - перенос блокируется (27.09.2026 так был затёрт прод: postgres-test был смонтирован на C:/Ascon-Docker/prod/postgres). Проверка работает только при праве на pg_control_* (роль pg_monitor или суперпользователь). Без него защита не срабатывает: в проверке остаётся предупреждение, перенос не блокируется. Роль pilotuser по умолчанию создаётся без этого права: выдайте его (GRANT pg_monitor TO pilotuser) или укажите в подключениях другого пользователя.
  • Одновременно идёт только один перенос; расписание, попавшее на занятый сервис, пропускается.
  • База приёмника запускается при любой ошибке и при отмене.

Подключения (Миграция / Подключения)

На каждый контур: адрес Pilot с базой и администратор сервера, PostgreSQL (пусто - из строки подключения в settings.xml; пароль кластерного контура - из окружения, см. «Кластерный Pilot-Server»), путь к settings.xml в контейнере (у кластера не нужен), соответствие путей архивов-папок (/usr/share/ascon/databases / /mnt/test/databases) и ключи S3. «Сохранить и проверить» проверяет всё по очереди; слабый пароль администратора Pilot (короче 8 символов или равный логину) попадает в проверку как предупреждение.

Пароли и ключи S3 хранятся в data/config.json открытым текстом (в Linux-контейнере файл создаётся с правами 600; права существующего файла сужаются до 600 при старте; на томе Windows-хоста Docker эти права не действуют, поэтому каталог ./data закройте от остальных пользователей средствами хоста, копии файла храните как секрет). Проверка подключений предупреждает о слабом пароле администратора Pilot. Наружу API отдаёт их только маской ••••••. Если маска приходит обратно, пароль остаётся прежним только при неизменных адресе Pilot и логине (для S3 - адресе хранилища и реальном адресе подключения); при смене адреса пароль надо ввести заново. Адреса S3 принимаются только http:// и https://. Тексты ошибок PostgreSQL в журналы идут без значений строк (Detail отключён), заголовок X-User очищается от управляющих символов.

API

GET /api/status, GET|PUT /api/config, POST /api/config/check, GET /api/import/sources, GET /api/export/list, POST /api/plan, POST /api/runs, GET /api/runs[/{id}], POST /api/runs/{id}/cancel, GET|POST /api/schedules, GET|DELETE /api/schedules/{id}. GET /health работает без ключа.

POST /api/plan («проверка») данные не меняет, но пишет в архив приёмника пробный объект .pilot-migration-probe-* (определение общего хранилища) и тут же удаляет его; одновременно выполняется не больше двух проверок.

Ключ S3 присланного архива приходит в запросе на перенос, но в журналы data/runs и наружу не отдаётся: там он заменён на маску (MigrationRequest.WithoutSecrets).

Что делает сервис с приёмником

Кроме замены данных, сервис может: останавливать и запускать базу приёмника; удалять из архива приёмника файлы, которых нет в источнике (FileTransfer.PruneAsync, FullCopy.PruneAsync); заменять метаданные и автоматизации (PilotAdmin.ReplaceAutomationsAsync); писать server-settings.conf (ServerSettingsCopy.Apply); перестраивать индекс атрибутов (AttrSearchRebuildIndexAsync); писать пробные объекты в архивы; выгружать базу в файлы вместе с хешами паролей пользователей.

Разработка

Нужен .NET SDK 10. Сборка и тесты сервиса - из этой папки, по своему решению (dotnet test в корне proadmin запускает только PilotProAdmin.sln):

dotnet build PilotMigration.sln -c Release
dotnet test PilotMigration.sln -c Release

Тесты на настоящем PostgreSQL (PostgresIntegrationTests: полная копия таблиц между двумя базами со схемой Pilot, внешние ключи и откат при битой ссылке, чистка сирот, SamePgDatabase, защита от общей папки данных, настройки кластера из config.settings). Без переменной окружения они пропускаются с указанием причины. Нужен одноразовый PostgreSQL 16 - тесты создают и удаляют свои базы (mig_it_*), а проверке прав на pg_control_* отзывают их у PUBLIC только в этих базах:

docker run -d --name mig-it-pg -e POSTGRES_PASSWORD=<пароль> -p 127.0.0.1:55432:5432 postgres:16
$env:PILOT_IT_PG = "Host=127.0.0.1;Port=55432;Username=postgres;Password=<пароль>;Database=postgres"
dotnet test PilotMigration.sln -c Release
docker rm -f mig-it-pg

Тест «базы на разных серверах не блокируются» ждёт ещё и PILOT_IT_PG_OTHER (второй такой же контейнер на другом порту); без неё он пропущен. Схема в тестах - снимок PgSchemaSnapshot с типами колонок, подобранными так, чтобы сходились внешние ключи; это не выгрузка настоящей схемы Pilot. Часть с админским API Pilot и файловыми архивами тестами на PostgreSQL не покрыта (таблица famediator в них пуста).

Время расписаний - местное время контейнера (TZ=Europe/Moscow в Dockerfile).