Files
MikrotikManager/docs/mcp-database-maintenance.md
T
DenozordecandClaude Opus 5.5 9ebbf036c8 chore(docs): исправления C2 — JIT, отметки попытки и maintenance-resolve после MCP
Решения владельца от 21.11 и порядок для оператора: после complete
MCP-восстановления с внешней контрольной точкой — maintenance-inspect и
maintenance-resolve; захваты каталога выключают JIT; квитанции без .used
не закрывают старт при отсутствующем журнале. Образ backend Gitea 2746.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-21 01:12:22 +07:00

15 KiB
Raw Blame History

Ручная проверка БД после неопределённого восстановления

Команды maintenance-inspect и maintenance-resolve входят в текущий собранный оператор backend/dist-operator/database-writer-profile-operator.mjs. Их Linux/POSIX и PostgreSQL-приёмка прошла через локальное подключение и TLS: 16 сценариев. Опубликованный ранее preview-образ этим отчётом не обновляется.

После неопределённого восстановления обычные HTTP/MCP-запросы, планировщик и приём NetFlow остаются закрытыми. Существующий административный путь явного восстановления доступен. Не повторяйте прежнее действие автоматически: отсутствие ответа не означает, что данные не изменились.

Этот порядок позволяет человеку принять наблюдаемое текущее состояние. Он не доказывает соответствие данных исходному архиву и не превращает старые unknown в успешные операции.

Подготовка

  1. Остановите управляемый backend штатным способом. Сохраните его состояние и параметры запуска. PostgreSQL должна остаться доступной оператору; параллельное обслуживание БД недопустимо.
  2. Выберите проверенный образ с текущими командами оператора. Используйте существующий том состояния MCP, а не новый пустой том.
  3. Запускайте оператор от фактического владельца тома, с тем же UID, что использует backend. Каталоги должны принадлежать ему и быть закрыты от других пользователей; файлы входных данных — иметь права 0600. Команда не исправляет владельцев и права автоматически.
  4. Подготовьте отдельный закрытый каталог входных данных и отдельный каталог результатов. Монтируйте их только в контейнер оператора, не в обычный backend/MCP. Пароли передаются в защищённом файле транспорта, не в аргументах команды.

Нужны два независимо проверенных файла:

  • runtime-target.json: format=database-maintenance-runtime-target-v1, databaseUrl с адресом, портом и именем настроенной БД без имени пользователя и пароля. Это конфигурация назначения backend, а не произвольная другая БД.
  • transport.json: format=database-maintenance-transport-v1, выбранный mode и connection с полями host, port, user, password, database.

Для mode=tls дополнительно нужны tls.serverName, tls.spkiSha256, защищённый CA-файл и его проверенный SHA256. TLS — режим по умолчанию; после его ошибки переключения на незашифрованное соединение нет.

Для обычной Docker-установки без TLS поддерживается явный mode=local-loopback. Отдельный контейнер оператора должен присоединиться к сетевому пространству точного проверенного контейнера PostgreSQL: --network "container:$REVIEWED_PG_ID". В connection.host допустимы только 127.0.0.1 или ::1; параметры CA в этом режиме запрещены. Host networking и Docker socket не нужны. Настроенное назначение backend в runtime-target.json при этом сохраняется.

Инспекция

В отдельном контейнере оператора выполните команду с проверенными путями и SHA256:

node backend/dist-operator/database-writer-profile-operator.mjs maintenance-inspect \
  --state-dir /app/data/mcp \
  --transport /run/review/transport.json --transport-sha256 "$TRANSPORT_SHA256" \
  --runtime-target /run/review/runtime-target.json --runtime-target-sha256 "$TARGET_SHA256" \
  --output /run/output/inspection.json

Для TLS добавьте --ca /run/review/ca.pem --ca-sha256 "$CA_SHA256". /app/data/mcp — пример: используйте фактический MCP_STATE_DIR установки.

Инспекция только читает БД. Она проверяет физическую идентичность PostgreSQL, текущие миграции и схему, внешний журнал, поколение доступа и квитанции. Необязательная служебная схема mmapp_control не требуется для обычной установки. Результат содержит частные сведения о схеме; храните его в закрытом каталоге.

Если humanApprovalRequired=false и состояние уже принято, повторное разрешение не требуется. Не создавайте вторую запись ради подтверждения потерянного ответа.

Решение человека

Человек отдельно проверяет инспекцию и создаёт защищённый approval.json со следующими полями:

{
  "format": "database-maintenance-current-state-approval-v1",
  "resolutionId": "<новый UUID>",
  "decision": "accept-observed-current-state",
  "actorId": "<идентификатор оператора>",
  "inspectionSha256": "<проверенный SHA256 inspection.json>",
  "issuedAt": "<UTC ISO timestamp>",
  "expiresAt": "<UTC ISO timestamp, не более 15 минут после issuedAt>",
  "managedBackendStopped": true,
  "historicOutcomesRemainUnknown": true,
  "automaticRestore": false
}

Приложение и модель не создают это решение за человека. Проверенный SHA256 разрешения передаётся отдельно. Инспекция и разрешение должны оставаться действительными до публикации решения.

Вызовите maintenance-resolve с теми же параметрами назначения и транспорта, добавив --inspection FILE --inspection-sha256 SHA --approval FILE --approval-sha256 SHA. Параметр --output здесь не используется.

Оператор повторно читает текущее состояние, сверяет его с инспекцией и разрешением, завершает SQL-владельца и публикует неизменяемую fsync-запись решения вне PostgreSQL. Исходные журнал, квитанции и поколение доступа не переписываются. DDL, восстановление архива и выдача дополнительных SQL-прав не выполняются.

Возобновление и повторная проверка

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

Если ответ maintenance-resolve потерян, начните с новой инспекции: существующее историческое решение должно быть прочитано, а не опубликовано повторно. Не удаляйте lease или записи решения по возрасту/PID. Подтверждённое историческое решение сохраняет силу после истечения срока использованного разрешения; новое решение требует нового разрешения.

Исторические unknown остаются такими в квитанциях. В SQL-аудит импортируются только действительно подтверждённые квитанции applied; при неизвестном исходном авторе используется отдельная служебная запись сверки.

Подтверждённое восстановление с подписанным профилем source58

Для этой процедуры нужен активированный источник PostgreSQL, проверенный логический SHA-256 схемы, подписанный профиль source58 и внешняя контрольная точка. restore-profile-enroll на остановленном backend проверяет прежний source57, утверждённый текущий head и оба SHA-256 каталога. Затем оператор публикует source58 командой upgrade с разрешением формата application-writer-upgrade57-to58-approval-v1. Роль приложения читает карантин и подписанные записи реестра. Для pg_dump и db:inspect-schema --data используется пароль отдельной роли чтения из DATABASE_ARCHIVE_PASSWORD_FILE и утверждённый самоподписанный серверный сертификат без права CA.

  1. Получите архив и независимый SHA-256 его данных из согласованного состояния источника. При раздельном экспорте и db:inspect-schema --data исключите изменения данных между двумя операциями. Передайте утверждённые DATABASE_RESTORE_ARCHIVE_SHA256 и DATABASE_RESTORE_DATA_SHA256.
  2. Зафиксируйте допуск командой db:stage-restore-checkpoint <sha256-файла-sealed>. Операторский db:serve-restore-claims выдаёт одноразовый допуск уже работающему backend через локальный сокет. Выполните одно утверждённое восстановление. Проверьте db:inspect-restore-checkpoint и дождитесь состояния applied-consumed перед дальнейшими действиями. При неопределённом ответе начните с инспекции.
  3. На остановленном backend выполните source-catalogue-inspect в защищённом операторском процессе. Используйте те же --bootstrap, --transport и --definition с соответствующими SHA-256, а также --ca, --source-registry, --source-spki-sha256, --activation-directory и --activation-sha256. Команда возвращает headSha256, previousCatalogSha256 из подписанной записи и catalogSha256 фактического каталога. Утвердите результаты отдельно. Передайте их в upgrade с разрешением application-writer-rebind58-after-restore-approval-v1, используя headSha256 как expectedHeadSha256. Публикация создаёт новый подписанный head на том же источнике и сохраняет предыдущую запись.
  4. С тем же UUID операции и SHA-256 применённого журнала выполните db:seal-restore-checkpoint, затем db:complete-restore. Запустите backend штатно и проверьте готовность. Сверка данных, новый подписанный head и завершение контрольной точки подтверждаются независимо.
  5. Если восстановление выполнялось через MCP, после db:complete-restore старт backend остаётся закрытым (EXTERNAL_OPERATION_UNRESOLVED). Причина: внешняя квитанция applied содержит предупреждение maintenanceError о сохранённом до внешней записи карантине. На остановленном backend выполните maintenance-inspect, проверьте результат, оформите одобрение формата database-maintenance-current-state-approval-v1 и выполните maintenance-resolve. Только после этого запускайте backend. Восстановление через REST внешней квитанции не создаёт, и этот шаг для него не нужен.

Захваты каталога продукта (runtime и операторские команды) выключают JIT PostgreSQL на время своего сеанса. На PostgreSQL 18 с настройками по умолчанию одна компиляция запросов каталога могла превысить фиксированный лимит 5 с. Настраивать jit на сервере для этого не нужно.

Первая отклонённая MCP-попытка восстановления (blocked) или прерванная до захвата архива (running без .used) не блокирует старт при отсутствующем журнале. Отметкой попытки при отсутствии журнала считаются только .used и квитанции applied/unknown.

Локальная приёмка на одноразовой PostgreSQL подтверждает конкретные SQL- и TLS-проверки. Для рабочей установки отдельно сверяются источник, операторская активация, учётные записи и журнал.