Files
MikrotikManager/docs/mcp-db-offline-bootstrap.md
T

37 KiB
Raw Blame History

Подготовка ключей установки MCP

backend/scripts/database-writer-bootstrap-operator.mjs — отдельная операторская команда подготовки ключей. Приложение её автоматически не запускает. Она не подключается к БД, не создаёт роли, не выдаёт права, не публикует политику и не переводит установку в READY.

Состояние проверки: настоящая генерация Ed25519, подпись, проверка подписи и отказ при подмене проверены. В Windows проверен отказ до создания ключей. Успешная защищённая запись в POSIX ещё требует отдельной Linux-приёмки; до неё этот путь не считается принятым для эксплуатации.

Явный вход оператора

Команда принимает три обязательных параметра:

node backend/scripts/database-writer-bootstrap-operator.mjs init --output /protected/operator/new-installation --deployment /protected/operator/approved-request.json --deployment-sha256 <утверждённый SHA256 файла>

SHA256 должен поступать из независимо утверждённого запроса. Самостоятельное вычисление хеша найденной конфигурации не подтверждает её происхождение. Все сведения запроса — ожидаемые значения оператора; команда не подтверждает их соответствие действующей БД.

Запрос содержит только следующие поля:

Поле Содержание
format application-writer-bootstrap-request-v1
installationId UUID установки
sourceHeadSha256 Утверждённый SHA256 исходного head
source systemIdentifier, databaseOid, databaseName, serverVersionNum, inRecovery
roles Все пять разных ролей: runtime, operator, capture, publisher, control; каждая содержит name и десятичную строку signedOid
tls serverName, caSha256, spkiSha256

Идентификаторы PostgreSQL передаются десятичными строками. Поддерживается заявленная версия PostgreSQL 18 и inRecovery=false. Лишние поля, недостающие роли, совпадающие роли и отсутствующие transport/head pins приводят к отказу.

Файлы и повторный запуск

Родительский каталог должен уже существовать: канонический POSIX-путь, владелец — текущий uid, без доступа группы и остальных пользователей. Запрос — обычный файл того же владельца без доступа группы и остальных, размером не более 16 КиБ. Права и предки проверяются; Windows ACL сейчас не поддерживается.

Новый каталог создаётся исключительно для этого запуска. Существующий каталог не принимается и не перезаписывается. Команда создаёт signing-private.pem, operator-public.pem и последним bootstrap.json. Файлы публикуются без замены существующих, с правами 0600 и синхронизацией записи. Незавершённый каталог сохраняется для проверки оператором; автоматического удаления или повторной попытки нет.

Само наличие bootstrap.json не подтверждает успешный запуск: при поздней ошибке синхронизации или удаления временного имени файл уже может существовать. Незавершённый запуск требует проверки оператором; устойчивость к сбою питания этой проверкой не доказана.

В stdout выводится только квитанция с публичным отпечатком, идентификатором установки и хешем запроса. Приватный ключ туда не попадает. Публичный отпечаток требуется независимо закрепить как доверенный: генерация ключа сама по себе не даёт ему полномочий.

databaseObserved, rolesAuthenticated, sourceAuthenticated, publicationAuthorized, generationAuthenticated и readyAuthorized остаются false; утверждённое определение отсутствует. Следующий этап — подключённая проверка реальной БД, пяти ролей и исходного head с закреплёнными CA/SPKI. Он этой командой не реализуется.

Целевая проверка без БД и сети:

node --test backend/scripts/database-writer-bootstrap-operator.test.mjs

Проверка источника при открытии соединений приложения

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

  • DATABASE_RUNTIME_REQUEST_FILE — абсолютный путь к approved-request.json формата application-writer-bootstrap-request-v1.
  • DATABASE_RUNTIME_REQUEST_SHA256 — утверждённый SHA-256 точных байтов запроса.
  • DATABASE_RUNTIME_CA_FILE — абсолютный путь к PEM-файлу CA с хешем из tls.caSha256 запроса.

Параметры DATABASE_URL должны содержать прямой PostgreSQL endpoint, логин runtime, пароль и имя БД. Имя сервера, логин и база сверяются с запросом. Параметры query string не принимаются. При открытии соединения пул проверяет цепочку TLS, имя сервера и ключ сертификата. Перед каждой выдачей закреплённого соединения он сверяет SESSION_USER, CURRENT_USER, OID роли, имя и OID БД, системный идентификатор, точную версию PostgreSQL и работу на primary. Отказ закрывает соединение. TLS-ключ выделяется этому endpoint. Клон с теми же SQL-идентификаторами и тем же ключом пройдёт такую проверку.

Runtime получает прямые прикладные права SELECT и DML. Проверка PostgreSQL отклоняет членство в ролях в обе стороны, владение текущей БД и её объектами, CREATE/TEMP и доступ к отключению триггеров. Один SQL-запрос на выдачу проверяет в том числе изменения прав, сделанные, пока соединение простаивало. Уже выданное соединение проверяется при следующей выдаче из пула.

Если для runtime закрыта функция pg_catalog.pg_control_system(), оператор заранее выдаёт этой роли право EXECUTE только на указанную функцию и учитывает его при утверждении каталога. В приложение передаются публичный запрос и CA. Ключ подписи и операторские настройки остаются у оператора. Изменение версии PostgreSQL или ключа TLS требует нового утверждённого запроса и перезапуска пулов.

Эта проверка охватывает основные пулы приложения, worker и пулы допуска REST/MCP. Отдельные подключения резервного копирования, восстановления и операторских команд используют свои проверки. Подтверждение поколения БД и допуск READY остаются отдельными этапами.

Сверка с операторским реестром активации

После подтверждённого source-activate передайте приложению DATABASE_RUNTIME_ACTIVATION_SHA256 из квитанции и DATABASE_RUNTIME_ACTIVATION_DIRECTORY с каталогом реестра. Монтируйте целый каталог только для чтения, чтобы приложение видело замену файла и переходный .pending. У приложения должно быть право чтения записи. Операторский ключ остаётся за пределами этого монтирования. Хеш передаётся независимо через параметры развёртывания. Каталог реестра и параметры развёртывания хранятся вне контура восстановления БД.

При выдаче соединения из пула и при допуске через общие SQL-блокировки приложение проверяет статус active, хеш и совпадение установки, текущего head и TLS-ключа. Появление .pending, отзыв, смена поколения и пропажа записи закрывают новые допуски с прежним пином. Уже допущенная работа может завершиться. При смене поколения оператор останавливает и дожидается завершения работы старых потребителей перед переключением, затем развёртывает новый набор пинов. Совместный откат каталога и параметров развёртывания может восстановить прежнюю принятую пару.

Подготовка схемы отдельной ролью

До запуска приложения с проверкой источника оператор выполняет из отдельного процесса npm --prefix backend run db:prepare. В собранном backend используется node dist/scripts/prepare-database.js. В этом процессе DATABASE_URL явно указывает на подготовленную оператором целевую БД и роль с правом владения схемой. Переменные DATABASE_RUNTIME_* задаются приложению и команде сверки схемы. Для подготовки схемы сохраняются те же MCP_STATE_DIR и настройки карантина. Операторская команда применяет штатные миграции, завершает требуемый импорт SQLite и обслуживает партиции под общей блокировкой обслуживания.

При старте с ролью приложения проверяются список применённых миграций и наличие требуемых партиций. Роли приложения требуется SELECT на public.schema_migrations и чтение таблиц, из которых берутся настройки хранения и отметка импорта. Если нужен импорт SQLite, старт останавливается до его завершения оператором. Приложение продолжает писать прикладные данные с правами runtime. Оператор повторяет подготовку партиций до исчерпания запаса по датам, который создаёт штатная процедура. Обслуживание старых партиций выполняет та же операторская команда.

Для планового обслуживания используйте npm --prefix backend run db:prepare -- --partitions-only или node dist/scripts/prepare-database.js --partitions-only. Команда под общей блокировкой сверяет версию схемы, удаляет истёкшие партиции по действующим настройкам хранения и создаёт требуемые партиции. Она применяет те же проверки карантина и журнала восстановления. Применение миграций и импорт SQLite доступны при запуске db:prepare без параметра.

Установка таблиц реестра профиля записи

После подготовки схемы и SQL-защиты оператор может однократно создать пустой реестр профиля в отдельном процессе на POSIX:

node backend/dist-operator/database-writer-profile-operator.mjs registry-enroll \
  --approval /protected/operator/registry-approval.json --approval-sha256 <sha256> \
  --transport /protected/operator/control-transport.json --transport-sha256 <sha256> \
  --ca /protected/operator/postgres-ca.pem

В registry-approval.json укажите format со значением application-writer-registry-enrollment-v1, manifestSha256 текущей сборки и deploymentRequest формата application-writer-bootstrap-request-v1 из раздела выше. Файл подключения содержит host, port, user, password, database. Пользователь подключения должен совпадать с закреплённой ролью control и владеть схемой mmapp_control. Пины для файлов утверждаются отдельно от передаваемых файлов. Каталог и файлы принадлежат пользователю оператора и закрыты от других пользователей.

До установки создайте пять ролей из запроса и подготовьте штатную схему с проверенными отметками миграций. Роли control, operator и publisher нужны существующие права чтения метаданных источника, а роли control нужен доступ к public.schema_migrations. Требуемые права схем и функций и проверенный SQL-профиль устанавливаются владельцами соответствующих объектов. Команда сверяет TLS, идентичность БД и ролей, берёт эксклюзивную блокировку профиля и фиксирует пустые таблицы с точными правами только после проверки их структуры. Существование любой из двух таблиц приводит к отказу. Если ответ о COMMIT потерян, сначала вручную сверьте обе таблицы и их права. После подтверждения установки публикация профиля выполняется отдельной операторской командой.

Для этой сверки запустите registry-inspect с теми же параметрами. Результат absent означает отсутствие обеих таблиц. installed содержит SHA-256 подтверждённой структуры реестра и его прав. Если присутствует одна таблица, структура изменилась или права отличаются, команда отказывает. Проверка выполняется в транзакции только для чтения и завершается ROLLBACK. Содержимое реестра и разрешение READY проверяются отдельно.

Установка защиты таблицы отметок миграций

Когда остальные объекты утверждённого профиля 57 подготовлены, используйте операторскую команду marker-fence-enroll с параметрами --approval, --approval-sha256, --transport, --transport-sha256 и --ca по образцу registry-enroll. Подключение выполняется закреплённой ролью operator, владельцем public.schema_migrations. В отдельном утверждении укажите format со значением application-writer-marker-fence-enrollment-v1, deploymentRequest, manifestSha256, definitionSha256 определения профиля 57 и catalogSha256 утверждённого итогового каталога для публикации профиля.

Команда допускает таблицу без пользовательских триггеров. В рамках одной транзакции она проверяет отметки миграций, ожидаемые права и существующую защиту DDL, устанавливает три утверждённых триггера с режимом ALWAYS и сверяет итоговый каталог с пином перед COMMIT. Частично установленные триггеры требуют ручной сверки. При потере подтверждения COMMIT сначала проверьте каталог операторским подключением. Публикация профиля выполняется отдельно.

Контроль фактической схемы при запуске

После подготовки и проверки БД оператор запускает npm --prefix backend run db:inspect-schema с тем же TLS-профилем источника и SQL-ролью, которые использует приложение. В собранном backend команда запускается как node dist/scripts/inspect-database-schema.js. Она читает каталог PostgreSQL в одном снимке под общими блокировками обслуживания и записей в партиции и выводит schemaSha256. После сверки утверждённое значение передаётся приложению через DATABASE_RUNTIME_SCHEMA_SHA256. При несовпадении старт останавливается до чтения маркеров миграции.

Хеш охватывает логическую структуру public и mmapp_control, если она есть, включая определения триггеров, вызываемые ими функции, права, владельцев, версию PostgreSQL и конкретные партиции. Для event trigger, вызывающего функцию в mmapp_control, снимок включает событие, режим, теги, владельца и ссылку на функцию. При переходе с предыдущей проверки на БД с mmapp_control оператор пересчитывает и утверждает хеш. Такое же подтверждение нужно после ротации партиций, изменения схемы или прав и обновления PostgreSQL. Данные в таблицах mmapp_control в хеш схемы не входят. История данных и полномочия READY подтверждаются отдельно.

Подписанный профиль записи с карантином

Для подписанного профиля с карантином приложение принимает DATABASE_RUNTIME_WRITER_APPROVAL_FILE и отдельно утверждённый DATABASE_RUNTIME_WRITER_APPROVAL_SHA256. Файл JSON содержит format: "database-runtime-writer-approval-v1", publicKeyPem, publicKeySpkiSha256, minimumEpoch и minimumHeadSha256 из подтверждённой квитанции публикации. minimumEpoch задаётся строкой. Храните утверждение вне контура восстановления и монтируйте его только для чтения. Режим требует активацию источника, закреплённый хеш схемы, карантин и внешний файл контрольной точки.

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

Для первой sealed контрольной точки этого профиля запишите writerHead с полями epoch и sha256 из подтверждённой публикации. Стадия pending сохраняет голову, которую приложение увидело перед восстановлением. После подтверждённого applied издатель сверяет восстановленный каталог и публикует следующую эпоху. db:seal-restore-checkpoint проверяет, что подпись новой эпохи выпущена после applied, и записывает её в sealed. Снятие карантина и следующий старт сверяют сохранённую эпоху с действующей подписанной политикой.

Сверка данных после восстановления

Оператор получает ожидаемый снимок из проверенного воспроизведения архива в изолированной БД после применения требуемых миграций. Команда npm --prefix backend run db:inspect-schema -- --data выводит dataSha256 для настроенного и подтверждённого TLS-источника. Роли для этой проверки требуется читать таблицы и последовательности приложения. Ожидаемый снимок привязан к той же логической схеме, версии PostgreSQL, владельцам и правам, что и целевая БД.

Укажите SHA-256 точных байтов архива в DATABASE_RESTORE_ARCHIVE_SHA256 и отдельно утверждённый хеш снимка в DATABASE_RESTORE_DATA_SHA256. Для режима также нужны DATABASE_RESTORE_QUARANTINE=true и отдельная роль восстановления через DATABASE_RESTORE_URL_FILE. Несовпадение архива останавливает операцию до замены БД. После восстановления и миграций операторская роль сверяет под общей блокировкой строки и состояния последовательностей public. Определения mmapp_control входят в хеш схемы. Строки и последовательности этой схемы сохраняются отдельно от архива. При несовпадении данных операция записывается как unconfirmed и карантин остаётся.

Один снимок ограничен миллионом строк, 128 МиБ представления данных и 60 секундами. Выход за пределы оставляет проверку неподтверждённой. Для старого архива с миграциями, создающими недетерминированные данные, требуется отдельное доказательство преобразования.

В этом режиме начало и итог восстановления записываются во внешний журнал с одним ID операции, той же парой хешей, отпечатком цели и отпечатком активации, если она настроена. Для каждой подписанной записи при чтении проверяется HMAC с отдельным производным ключом от encryption-key состояния MCP. Операция сохраняет длину и SHA-256 подтверждённого журнала в строке карантина mmapp_control вместе с постановкой и снятием карантина. При запуске, резервном копировании и следующем восстановлении PostgreSQL и файл журнала должны совпасть. Сохраняйте каталог состояния и ключ вместе. Если прервалась запись итога, сохраните файл и точный ID карантина для ручной сверки.

Для новой установки используйте DDL контрольной таблицы. На существующей установке роль владельца контрольной схемы выполняет при остановленных потребителях:

ALTER TABLE mmapp_control.database_restore_quarantine
  ADD COLUMN journal_prefix_bytes integer,
  ADD COLUMN journal_prefix_sha256 text,
  ADD CONSTRAINT database_restore_quarantine_journal_head CHECK (
    (journal_prefix_bytes IS NULL) = (journal_prefix_sha256 IS NULL)
    AND journal_prefix_bytes BETWEEN 1 AND 8388608
    AND journal_prefix_sha256 ~ '^[a-f0-9]{64}$'
  );

Роли приложения требуется SELECT на контрольную таблицу. Роли восстановления предоставьте UPDATE только на operation_id, journal_prefix_bytes и journal_prefix_sha256 в дополнение к необходимому SELECT. После изменения определения и прав заново получите утверждённый хеш схемы и снимок данных. Для старого журнала только с неподписанными записями допустима пустая контрольная запись. Если есть подписанная история без контрольной записи, запуск требует операторской сверки. Нужна отдельная процедура для совместного отката PostgreSQL и каталога состояния.

Снятие карантина после прерванного подтверждения

Если PostgreSQL ещё хранит ID операции и контрольную запись intent, а журнал заканчивается подписанным applied той же операции, остановите backend и сохраните файл журнала. Сверьте operationId последней записи и SHA-256 точных байтов всего database-maintenance.jsonl. С прежним подключением приложения, файлом подключения владельца, каталогом состояния, пинами архива, данных и активации выполните:

npm --prefix backend run db:complete-restore -- <operation-id> <sha256-журнала>

В собранном backend используйте node dist/scripts/complete-database-restore.js с теми же аргументами. Команда повторно сверяет данные PostgreSQL, подписанные записи и сохранённый карантин под блокировками, синхронизирует файл журнала с диском и фиксирует завершение одной транзакцией. Архив повторно не применяется. История журнала и внешняя квитанция MCP сохраняются как есть. Если итог команды неизвестен, перед следующим запуском проверьте строку карантина и контрольную запись журнала. Для unconfirmed или пропавшей записи applied требуется отдельное расследование.

Независимая контрольная точка журнала

DATABASE_RESTORE_CHECKPOINT_FILE указывает на канонический абсолютный путь файла, которым управляет оператор. Смонтируйте его каталог только для чтения и храните на стороне хоста отдельно от PGDATA, архива и MCP_STATE_DIR. Независимость от их совместного отката зависит от этого размещения. Путь внутри MCP_STATE_DIR отклоняется. При отсутствии параметра приложение использует прежний режим карантина.

Если результат предыдущего шага неизвестен, оператор может сверить файл, журнал и строку карантина под блокировкой обслуживания:

npm --prefix backend run db:inspect-restore-checkpoint

Команда возвращает статус, ID операции и хеши без записей в PostgreSQL или во внешний файл. matches-sealed и matches-pending означают совпадение указателей при открытом карантине. applied-consumed и applied-sealed указывают на точный подписанный applied при сохранённом карантине. inspection-required сохраняет расхождения для проверки. Текущее содержимое PostgreSQL повторно проверяют команды публикации и снятия карантина.

Файл формата database-restore-checkpoint-v1 содержит runtimeTargetSha256, activationSha256 (или null) и head ({ "bytes": 123, "sha256": "…" } либо null до первой подписанной записи). runtimeTargetSha256 формируется тем же способом, что в привязке подписанного журнала. При status: "sealed" приложение требует совпадения контрольной точки, журнала и PostgreSQL.

Перед восстановлением проверьте SHA-256 точных байтов внешнего файла sealed. На операторском хосте с утверждёнными переменными DATABASE_RESTORE_ARCHIVE_SHA256 и DATABASE_RESTORE_DATA_SHA256 выполните:

npm --prefix backend run db:stage-restore-checkpoint -- <sha256-файла-sealed>

В сборке используйте node dist/scripts/stage-database-restore-checkpoint.js. Команда сверяет sealed с PostgreSQL и журналом, затем публикует pending с прежним head, новым operationId и утверждённой парой хешей. Выполните штатное восстановление через уже запущенный backend, поскольку pending блокирует запуск нового процесса.

На стороне хоста запустите операторский процесс с правом записи в независимый каталог. В собранном backend эквивалент команды — node dist/scripts/serve-restore-checkpoint-claims.js:

npm --prefix backend run db:serve-restore-claims -- <путь-к-файлу> <локальный-сокет>

Укажите тот же локальный сокет в DATABASE_RESTORE_CHECKPOINT_CLAIM_SOCKET работающего backend. На POSIX сокет имеет права 0660. Ограничьте доступ к каталогу сокета хостом и backend. При замене точки операторский процесс сохраняет UID, GID и обычные POSIX-права исходного файла. Дайте backend доступ на чтение и монтируйте сам каталог точки только для чтения. Перед первой записью журнала backend запрашивает одноразовый переход pending → consumed. Операторский процесс сравнивает весь прежний допуск, синхронизирует замену файла и возвращает подтверждение. pending и consumed блокируют обычный старт и резервное копирование. Новый запрос восстановления при consumed отклоняется, даже если PostgreSQL и журнал вернулись к прежней паре. Уже подтверждённый вызов сохраняет карантин после подписанного applied.

При потере ответа, наличии .lock или .pending рядом с файлом либо неопределённом завершении сохраните контрольную точку и журнал для проверки. Для записи с подтверждённой синхронизацией каталога нужен POSIX. Windows-тесты используют именованный канал и проверяют логику перехода.

После applied остановите backend. Сверьте operationId и SHA-256 всего database-maintenance.jsonl. Запустите команду на хосте с доступом к PostgreSQL, прежним пинам восстановления и активации, журналу и правом записи во внешний каталог:

npm --prefix backend run db:seal-restore-checkpoint -- <operation-id> <sha256-журнала>
npm --prefix backend run db:complete-restore -- <operation-id> <sha256-журнала>

В собранном backend первая команда доступна как node dist/scripts/seal-database-restore-checkpoint.js. Она сверяет исходный указатель, точный consumed.claimId в обеих подписанных записях и текущие данные под блокировками, затем атомарно публикует sealed. PostgreSQL остаётся в карантине. Вторая команда повторно проверяет данные и новую контрольную точку перед снятием карантина. При неподтверждённом applied или неопределённом исходе публикации сохраните текущие свидетельства для проверки. Совпадение старого журнала и PostgreSQL возможно после совместного отката, поэтому его недостаточно для восстановления предшествующего sealed.