fbmcp: установка и использование
Аудитория: человек, который устанавливает и запускает fbmcp и не собирал его. Знание внутреннего устройства Go или Firebird не требуется. Состояние на 2026-11-16, версия 2027.2.24 (локальный и удалённый режим, установка HQbird, мост fbagent, кластер HQbird, сетка результатов).
Краткие версии, не на этом сайте: quickstart-en.md, quickstart-ru.md,
quickstart-pt.md. Подробности, на английском: remote.md (удалённый
режим), agent-bridge.md (fbagent),
tool-reference.md (каждый инструмент, его Tier и аргументы),
claude-desktop.md (подключение клиента на хосте разработки),
ADR в decisions/.
1. Что такое fbmcp
fbmcp — сервер MCP для Firebird 2.5–5.0 на Windows и Linux. Клиент
MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode и другие) использует его,
чтобы работать как DBA: мониторинг, резервные копии и проверенные
восстановления, SQL/DDL/DCL, индексы, пользователи и права, firebird.conf,
планировщик, миграции, fbagent HQbird и кластер HQbird. В нём 122 инструмента:
56 только для чтения (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3 (отключён).
fb_demo_write есть только тогда, когда сервер запущен с FBMCP_DEMO_TOOLS=1.
Клиент видит только те инструменты, которыми может пользоваться. Список инструментов скрывает:
Tier 3, инструменты выше максимального Tier идентичности, fb_confirm и
fb_cancel для идентичности только для чтения, инструменты fbagent, пока
agents: пуст (fb_agent_discover и fb_agent_register остаются),
инструменты миграций, пока ни у одной базы нет migrations_dir, и инструменты
кластера, пока в fbmcp.yaml нет секции rcm:. Когда перезагрузка
конфигурации меняет этот набор, клиент получает новый список. Прямой
вызов скрытого инструмента заканчивается явным отказом.
| Двоичный файл | Роль |
|---|---|
fbmcp |
Сервер. По умолчанию: MCP через stdio (его запускает клиент). -serve: без stdio, работает как служба (планировщик, сокет подключения, прослушиватель HTTPS, если настроен). fbmcp bridge: клиент stdio для удалённого fbmcp |
fbmcpctl |
CLI оператора: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Та же программа, что и fbmcp ctl |
fbmcp-tray |
Трей Windows: всплывающее окно Подтвердить/Отклонить для запросов, которым нужен оператор |
Одно ядро на папку состояния. Второй клиент с той же конфигурацией не запускает второе ядро: он подключается к уже работающему.
2. Модель безопасности
Каждый вызов проходит политику → подтверждение человеком → выполнение с записью в аудит.
| Tier | Что | Как подтверждается |
|---|---|---|
| 0 | Чтения (транзакции только для чтения, принудительно заданные движком) | Не нужно |
| 1 | Обычные изменения: DML/DDL, резервная копия, пользователи, права | В канале: клиент показывает идентификатор запроса и токен; человек соглашается; клиент вызывает fb_confirm |
| 2 | Высокое воздействие: управление службой, восстановление с заменой, firebird.conf, монопольное окно, регистрация, перезапуски агента |
Только вне канала: трей или fbmcpctl approve. Клиент никогда не может это подтвердить |
| 3 | Критическое (fb_db_drop) |
Отключено по замыслу |
- Tier 2 обычно требует открытого окна обслуживания (
fb_window_open, на той жеdb) и проверенной резервной копии моложе 24 часов. Отказ сообщает, чего не хватает. - Ожидающий запрос истекает через 15 минут. Попытка по неверному каналу
его не расходует;
fb_cancelего удаляет. - Каждый инструмент, требующий подтверждения, принимает
mode: preview: показывает последствия и ничего не делает. - Каждое решение (разрешение, ожидание, подтверждение, отказ) попадает в
audit.jsonlс цепочкой хешей. - Веб-страницы подтверждения нет, и её никогда не должно быть: страница, до которой может добраться модель, сломала бы замысел.
3. Выбор схемы
| Схема | Где работает fbmcp | Когда использовать | Раздел |
|---|---|---|---|
| A. Локальный stdio | Ваш ПК; клиент его запускает | Один администратор, Firebird на этом ПК или в локальной сети | §6 |
| B. Локальная служба | Служба Windows на хосте БД (-serve) |
Расписания должны выполняться, когда ни один клиент не открыт | §7 |
| C. Удалённый | Служба на сервере БД, HTTPS + ключи API | Несколько администраторов, удалённый сервер, автономные агенты | §8 |
В схеме A ядро живёт только пока работает клиент, поэтому расписания
срабатывают только тогда. Для расписаний без присмотра (nightly_verify)
используйте B или C.
fbmcp в HQbird. Установки HQbird 2027 и fbagent устанавливают fbmcp
по умолчанию: одна служба на сервер для всех линеек Firebird, её настраивает
fbmcp ctl hqbird-install. На таком сервере не следуйте §6–§8; читайте
hqbird.md (раскладка, удалённый режим с --allow-from, ключи API).
4. Получение двоичных файлов
Требования: Go ≥ 1.26.11 (более старый Go 1.21+ сам скачивает go1.26.11 при первой сборке; для этого нужен интернет), CGO не нужен; Firebird 2.5–5.0; fbagent ≥ 2.67 с Local API для инструментов агента (необязательно); fbagent 3.1.0+ и RCM 2027.5.11+ для инструментов кластера (необязательно).
git clone https://github.com/alexeykovyazin/hqbirdmcp.git
cd hqbirdmcp
$env:CGO_ENABLED = "0"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp.exe ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl.exe ./cmd/fbmcpctl
go build -trimpath -ldflags "-s -w -H=windowsgui" -o dist/fbmcp-tray.exe ./cmd/fbmcp-trayДвоичные файлы для Linux (кросс-сборка из Windows или сборка
на Linux без GOOS):
$env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl ./cmd/fbmcpctlКонтрольные суммы: Get-FileHash dist/* или sha256sum dist/*. Другие цели:
packaging/README.md. Положите двоичные файлы в отдельную папку (в примерах
C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\
(Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).
fbmcp ctl и fbmcpctl — одна и та же программа. fbmcpctl help перечисляет
команды. Команды, которые читают конфигурацию, принимают --config <file>;
без него они используют FBMCP_CONFIG, затем fbmcp.yaml в текущей папке,
затем рядом с программой, затем путь HQbird по умолчанию (C:\HQbirdData\fbmcp\fbmcp.yaml,
/etc/fbmcp/fbmcp.yaml) и печатают using config <path>.
5. Настройка fbmcp.yaml
Полный пример: packaging/fbmcp.yaml.example.
Минимальная конфигурация Windows:
state:
dir: C:\ProgramData\fbmcp\state
# secrets:
# dir: C:\ProgramData\fbmcp\secrets # setups B and C
instances:
- id: fb5
addr: localhost:3050
bin_dir: C:\Program Files\Firebird\Firebird_5_0 # folder with gbak, gfix, gstat
version: "5.0"
service: FirebirdServerDefaultInstance # Linux: firebird.opt_fb50
service_user: SYSDBA # instance tools (fb_firebird_log, ...)
service_secret_env: FBMCP_FB5_SERVICE_PW
databases:
- id: main # tools and chats use the id, never the path
instance: fb5
path: D:\Data\main.fdb
backup_dir: D:\fbmcp\backups
work_dir: D:\fbmcp\work # restore tests; Linux: not under /tmp
ro_user: FBMCP_RO # a read-only Firebird user
ro_secret_env: FBMCP_MAIN_RO_PW
admin_user: SYSDBA
admin_secret_env: FBMCP_MAIN_ADMIN_PW
notify:
webhook_url: "" # optional: a chat webhook for pending requests
retention:
keep_days: 0 # 0 = never delete backupsСекреты. YAML хранит только имена переменных. fbmcp ищет каждое
значение в таком порядке: переменная среды → файл <secrets.dir>/<NAME> →
связка ключей ОС учётной записи, от которой работает fbmcp.
C:\fbmcp\fbmcpctl.exe secret set FBMCP_MAIN_RO_PW # keyring of the current user (setup A)
C:\fbmcp\fbmcpctl.exe secret set --dir C:\ProgramData\fbmcp\secrets FBMCP_MAIN_RO_PW # secrets dir (setups B, C)Значение читается из stdin (введите его, затем Ctrl+Z, Enter; в Linux Ctrl+D).
Учётная запись службы (LocalSystem, NT SERVICE\...) не видит вашу связку ключей:
для служб используйте secrets.dir. Изменённый файл секрета применяется
через несколько секунд без перезапуска.
Пользователь только для чтения. Создайте отдельного пользователя Firebird для
ro_user (SQL: quickstart-en.md:
CREATE USER FBMCP_RO, GRANT SELECT на каждую таблицу, а в Firebird 4.0+
роль с MONITOR_ANY_ATTACHMENT, чтобы fb_sessions видел все соединения).
SYSDBA в качестве пользователя RO — только для разработки; doctor предупреждает об этом.
Живая перезагрузка. fbmcp сам применяет изменения fbmcp.yaml (наблюдатель
файла) или по fb_config_reload. Без перезапуска клиента или процесса. Перезагрузка
ждёт задания на изменённых базах (30 с), затем применяет. Отказ:
смена state.dir, повторяющиеся пути баз, небезопасная удалённая конфигурация.
Проверка: C:\fbmcp\fbmcpctl.exe doctor должен закончиться на doctor: green
(удалённый режим: doctor --remote, без строк FAIL). Он создаёт отсутствующую папку
состояния, входит в каждую базу обоими пользователями, и каждая строка FAIL
заканчивается на Fix: и команду, которую надо выполнить.
6. Схема A — локальный stdio
Используйте абсолютные пути. Не задавайте listen. После смены конфигурации
перезапустите клиент: клиенты загружают серверы только при старте.
| Клиент | Где | Запись |
|---|---|---|
| Claude Desktop | Настройки → Разработчик → Изменить конфигурацию (%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | командная строка | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json или .cursor\mcp.json в проекте |
тот же JSON, что у Claude Desktop |
| Codex | codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml или %USERPROFILE%\.codex\config.toml |
[mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml'] |
| ZCode | .zcode\config.json в проекте |
"mcp": {"servers": {"fbmcp": { ...same command and args... }}} |
Пароли лежат в связке ключей (§5), поэтому блок env не нужен. Если
вы всё же поместите пароль в блок env клиента, держите этот файл вне git.
Затем запустите трей для подтверждений Tier 2:
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (при каждом входе:
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).
Дымовой тест в клиенте: «вызовите fb_ping» (показывает имя сервера и вашу
идентичность с её максимальным Tier), затем «fb_db_list», затем «fb_db_health для main».
7. Схема B — локальная служба Windows
PowerShell с повышенными правами:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Служба запускает
fbmcp -serveот LocalSystem, перезапускается при сбое и чисто останавливается при остановке службы. - Пароли через
secrets.dir(§5). - Закройте папку: писать в
C:\fbmcpмогут только SYSTEM и Administrators (скрипт печатает командуicacls). Папка, созданная подC:\, позволяет любому пользователю менять файлы, а служба запускает их как SYSTEM. - Пользователю трея и локальным клиентам stdio нужны чтение и запись
в папке состояния:
icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Клиент stdio с той же конфигурацией тогда подключается к ядру службы. - Готовность:
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml. - Журнал:
<state_dir>\fbmcp.log(5 × 10 MiB; сбои вfbmcp-crash.log).
Для службы, к которой администраторы обращаются по сети, используйте схему C.
8. Схема C — удалённый (HTTPS + ключи API)
Полная процедура: remote.md. Кратко:
Сервер Windows (с повышенными правами):
- Двоичные файлы и
fbmcp.yamlвC:\fbmcp\(шаблон: remote.md §3:listen,tls,identities,allowed_origins,secrets.dir). C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp"— запишите pinsha256:....- Один ключ на человека или агента:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(печатается один раз). С--config C:\fbmcp\fbmcp.yamlон также добавляет записьidentities:и используетsecrets.dir. - Пароли и токены агента:
fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME. .\packaging\windows\install-remote.ps1 -Port 8443 -AllowFrom 10.0.0.0/24 -FirebirdService FirebirdServerDefaultInstance -WhatIf, затем без-WhatIf. Он создаёт службу, правило брандмауэра, ACL папок и права на службу Firebird.C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ без FAIL;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok.- Трей для подтверждающего:
.\packaging\windows\install-tray.ps1.
Сервер Linux (root): скопируйте fbmcp, fbmcpctl и packaging/linux/, затем
install -m 0755 fbmcp fbmcpctl /usr/local/bin/
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24 --dry-run
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24Скрипт создаёт папки, сертификат, первую конфигурацию с ключом
admin (печатается один раз), юнит systemd, правило sudo для юнита
Firebird и правило ufw, затем запускает doctor --remote. Добавьте
databases: и agents: в /etc/fbmcp/fbmcp.yaml. Подтверждения в Linux
(без трея): sudo -u firebird fbmcpctl approve [id]. Он сам находит
/etc/fbmcp/fbmcp.yaml, спрашивает y/N (--yes не спрашивает), а
--deny <id> --reason "..." отказывает.
ПК администратора:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(ключ, который вы получили).- Любой клиент stdio (Claude Desktop, Cursor, Codex, ZCode): запись из §6
с такими
args:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Pin проверяет ключ сервера, поэтому самоподписанному сертификату не нужна настройка CA. - Claude Code может также подключаться напрямую по HTTP (
.mcp.json"type": "http", заголовокAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSдля самоподписанного сертификата). Не передавайте ключ черезclaude mcp add --header: он сохраняется открытым текстом. - Проверка:
fb_pingпоказывает имя сервера и вашу идентичность.
Автономные агенты (OpenClaw и подобные): отдельный ключ через
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32.
По умолчанию только для чтения; каждый запрос Tier 1 ждёт оператора, а
fb_confirm от агента отклоняется. Ограничения: remote.md §6–7.
9. Мост fbagent и кластер HQbird (необязательно)
Инструменты агента (fb_agent_status, fb_agent_job_run, …) используют
Local API fbagent HQbird на том же хосте.
Они выключены, пока в agents: нет записи.
- В клиенте: «
fb_agent_discover». Он перечисляет локальных агентов сbase_url,instance_idи предлагаемым именем токена. Токены он не читает. - Оператор сохраняет
local_api.tokenагента (неagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Никогда не вводите токен в чат. - В клиенте: «
fb_agent_registerдля этого агента» → подтвердите в трее. fbmcp добавляет записьagents:, перезагружается и проверяет идентичность. - Проверка:
fb_agent_status,fb_agent_instances.
fb_agent_config_set (изменение настроек заданий: резервная копия, sweep, …)
также требует config_path в записи и доступа на чтение к живому agent_config.json
плюс права создания в его папке. В этом файле лежат токен и учётные данные
Firebird, поэтому такое предоставление прав — решение оператора
(agent-bridge.md). Если проверка агента не проходит, инструмент
ничего не записывает.
Кластер HQbird (RCM). Инструменты кластера вызывают менеджер кластера
HQbird (hqbirdrcm) на том же хосте. Они показываются только когда
в fbmcp.yaml есть секция rcm: (url, ca_file, user,
password_env). На сервере Linux с HQbird fbmcp ctl hqbird-install записывает
её из /opt/hqbirdrcm/rcm.json и сохраняет первый пароль RCM в секрете
FBMCP_RCM_PASSWORD; в остальных случаях добавьте секцию вручную
(tool-reference.md). Затем:
fb_cluster_rcm_password: замените первый пароль RCM (Tier 1).- Новый кластер: откройте окно сопряжения на каждом хосте
(
fb_agent_cluster_pairing), запустите RCM на мастере (fb_agent_cluster_rcm), свяжите хосты (fb_cluster_link), создайте реплики (fb_cluster_reinit, Tier 2) и сравните данные (fb_cluster_verify). Шаги:prompts/cluster-setup.md. - Службы кластера (переключение, аварийный переход, повторное присоединение):
fb_cluster_serviceпоказывает их и проверки; перемещения — Tier 2. Шаги:prompts/cluster-services.md.
10. Ежедневная работа
Просите клиента обычными словами; он сам выбирает инструменты. Примеры:
| Задача | Инструменты |
|---|---|
| Всё ли работает? | fb_ping, fb_db_list, fb_db_health, fb_service_status |
| Чтение данных | fb_query (только для чтения, строки + план + статистика по таблицам; сетка в клиентах MCP-Apps); черновик проверьте через fb_query_check |
| Сеансы, длинные транзакции | fb_sessions, fb_transactions, fb_session_kill (Tier 1) |
| Медленный запрос | fb_analyze_query, fb_index_advice → примените через fb_write; fb_agent_perf_report |
| Резервная копия | fb_backup_start → идентификатор задания → fb_job_status |
| Проверка резервной копии | fb_restore_test (восстанавливает в work_dir, помечает копию проверенной) |
| Ночная копия + проверка | fb_schedule_create с target=nightly_verify (подтверждается один раз; схема B или C) |
| Схема / DDL | fb_schema_list, fb_describe, fb_write (каждый оператор классифицируется и получает Tier), fb_diff_schema |
| Миграции | fb_migration_status, fb_migration_plan, fb_migration_apply |
| Конфигурация сервера | fb_config_get, fb_config_diff, fb_config_set (Tier 2) |
| Журналы | fb_firebird_log |
| Ёмкость | fb_trends, fb_gstat, fb_index_stats |
| Состояние кластера | fb_cluster_status, fb_cluster_service |
| Перенос мастера | fb_cluster_switchover (без потери данных) или fb_cluster_failover (мастер потерян), затем fb_cluster_rejoin (Tier 2) |
Задания асинхронны: отправьте → fb_job_status. Задания на одной базе
выполняются по одному. Задание переживает перезапуск fbmcp только как
interrupted: отправьте его снова, если оно всё ещё нужно.
fb_config_set меняет только свою строку в firebird.conf (комментарии,
отступы и концы строк остаются), сохраняет старый файл как firebird.conf.prev
и никогда не перезапускает Firebird. Перезапуск через fb_service_restart (Tier 2):
он ждёт, пока служба не остановится и не заработает снова.
11. Задачи оператора
| Задача | Команда |
|---|---|
| Список / подтверждение / отказ по запросам | fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (или трей) |
| Ротация ключа | fbmcpctl apikey rotate alice --config <fbmcp.yaml> (старый ключ перестаёт действовать за секунды) |
| Список ключей | fbmcpctl apikey list (имена, источники, уровни; никогда значения) |
| Удаление человека | удалите запись identities:, затем fbmcpctl secret drop --dir <dir> NAME |
| Обновление сертификата | fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin без изменений, без перезапуска) |
| Проверка цепочки аудита | fbmcpctl verify |
| Ядро живо? | fbmcpctl ping; fbmcpctl status (чтение состояния офлайн) |
| Разрешить управление службой | packaging/posture/verify.ps1 или verify.sh, затем fbmcpctl setup --write-posture |
| Обновление версии | остановите службу (или клиентов), замените двоичные файлы, запустите, doctor |
| Удаление | Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Сохраните папку состояния (аудит), если владелец не скажет иное |
Только хост разработки: .\packaging\rebuild-install.ps1 -Force пересобирает dist\,
останавливает и заменяет работающие двоичные файлы (старые сохраняются как *.exe~),
сливает конфигурации клиентов и запускает doctor.
12. Восстановление после сбоя и перезапуска
Проверено хаос-тестом (internal/killharness).
| После сбоя или принудительного завершения | При перезапуске | Действие оператора |
|---|---|---|
| Задание выполнялось или стояло в очереди | Помечено interrupted; никогда не возобновляется |
Отправьте снова, если нужно |
| Ожидающий запрос, не подтверждён | Восстановлен из state.json (TTL по-прежнему действует) |
Подтвердите или дайте истечь |
fb_restore_replace в процессе |
Завершает: восстановление, проверка, база онлайн; <db>.pre-restore сохраняется |
Проверьте fb_db_health; .pre-restore удалите позже |
fb_shutdown_window в процессе |
Завершает шаг gfix -online |
Проверьте, что база онлайн |
Устаревший instance.lock |
Перехватывается автоматически | Нет |
state.json повреждён |
Ядро отказывается запускаться; копия сохраняется как state.json.corrupt-<ts> |
Осмотрите; почините или намеренно удалите state.json (fbmcpctl repair заново собирает разрешения расписаний из аудита) |
audit.jsonl повреждён или обрезан |
Ядро отказывается запускаться | §13.2: считайте это сигналом вмешательства |
| Часы переведены назад | Планировщик пропускает; двойного запуска нет | Нет |
| Процесс службы Windows завершён принудительно | SCM перезапускает его примерно через 5 с | Нет |
Ядро переходит в состояние закрыто для всего, целостность чего оно не может доказать. Цикл перезапусков — это сигнал: читайте журнал.
13. Сценарии инцидентов
13.1 С базой что-то не так
fbmcpctl doctor --config <file>: конфигурация, секреты, входы Firebird, папки, защитная позиция, расписания. У каждой строки FAIL естьFix:.fb_db_list→fb_db_health <db>;fb_service_statusдля экземпляра.fb_sessions,fb_transactionsпри проблемах с подключениями или разрывом OAT;fb_firebird_logпри ошибках движка.
13.2 Подозрение на вмешательство или повреждение: сначала аудит
fbmcpctl verify --config <file>→audit chain OK: N entriesилиBROKENс причиной.- Если проверка не проходит: сохраните всю папку состояния (это улика), затем
разбирайтесь. Не удаляйте
audit.jsonl, чтобы заставить ядро запуститься.
13.3 Учебное восстановление (каждый квартал)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ копия проверена.fb_window_openдля базы.fb_restore_replace→ подтвердите вне канала. Простой до выхода в онлайн.- Проверка:
fb_db_health, затем реальное чтение (fb_schema_list,fb_info). - Старый файл остаётся как
<db>.pre-restore, пока вы его не удалите.
13.4 Клиент не может подключиться
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Читайте журнал MCP клиента (stdio) или
<state_dir>\fbmcp.log/journalctl -u fbmcp(служба). - «another fbmcp instance is active»: одно ядро на папку состояния. Клиенты через канал подключаются сами; второе ядро быстро завершается ошибкой по замыслу.
В командах выше --config можно опустить, когда поиск из §4
находит файл.
14. Устранение неполадок
| Симптом | Значение / исправление |
|---|---|
| Инструменты не появляются | синтаксис JSON, абсолютные пути, полный перезапуск клиента; журнал MCP клиента |
| Одного инструмента нет в списке | Скрыт намеренно (§1): выше вашего максимального Tier, нет записи agents:, нет migrations_dir или нет секции rcm: |
| Сервер сразу завершается | fbmcpctl doctor; отсутствует секрет; служба не может прочитать вашу связку ключей (используйте secrets.dir) |
| Tier 2 «confirmation rejected: channel policy» | Ожидаемо в чате. Подтвердите в трее или через fbmcpctl approve |
| Tier 2 «no open maintenance window» | fb_window_open для той же db, которую вы передаёте инструменту |
fb_restore_replace отказ: предусловия |
Нужна проверенная копия < 24 ч: fb_backup_start + fb_restore_test и окно |
| Отказ в управлении службой | нет posture.verified (fbmcpctl setup --write-posture) или у учётной записи нет прав на службу Firebird |
fb_config_set: не может записать |
Учётная запись не может изменить этот файл (юнит Linux ProtectSystem=strict; ACL Windows). Правьте вручную или см. remote.md §8 |
| Трей ничего не показывает | Он показывает только запросы, которым нужен оператор; проверьте права пользователя трея на папку состояния и tray.log в ней |
| 401 (удалённый) | Неверный ключ, или сервер его не загрузил: apikey list, doctor --remote |
| 403 (удалённый) | Исходный IP не в allow_from / брандмауэре, или заголовок Origin не в allowed_origins |
| 429 (удалённый) | Ограничения; ждите Retry-After |
| Несовпадение pin | Ключ сервера изменился; возьмите новый pin у администратора сервера |
agent-unreachable |
Служба агента не работает, local_api.enabled: false или неверный base_url (по умолчанию 127.0.0.1:(10000 + firebird port)) |
agent-auth |
Сохранённый токен — не local_api.token агента; задайте его снова |
agent-timeout при перезапусках |
agents[].timeout_seconds (130) должно быть больше, чем restart_timeout_seconds агента (120) |
Error loading plugin MySQLEngine … при подключении |
В HQbird это обычно значит, что файла базы не существует; проверьте путь |
Голый DROP INDEX в fb_write требует окно |
Там это Tier 2; используйте fb_index_drop (Tier 1; отказывает индексам ограничений) |
| Новый индекс не используется | Соберите статистику (fb_index_rebuild action=statistics); ORDER BY … DESC требует индекс DESCENDING |
| Инструменты отказывают только для одной базы | Она офлайн (fb_db_health); инструменты деградируют по базам |
15. Справочник папки состояния
| Путь | Значение |
|---|---|
state.json (+ .tmp, .corrupt-*) |
Ожидающие запросы, задания, каталог копий, рабочие процессы, расписания. Повреждение ⇒ отказ запуска |
audit.jsonl (+ .head) |
Журнал аудита с цепочкой хешей; .head обнаруживает обрезку |
events.jsonl |
События заданий (job.succeeded, job.failed с сообщением) |
approvals\, denials\ |
Решения вне канала (трей / fbmcpctl approve), используются в течение ~2 с |
instance.lock |
Блокировка одного ядра |
attach.addr, attach.token |
Точка подключения для дополнительных клиентов stdio |
fbmcp.log, fbmcp-crash.log |
Журнал службы (с ротацией) и вывод при сбое |
query-log.jsonl |
Каждый вызов fb_query |
trends\ |
История сэмплера для fb_trends |
config-journal\ |
История fb_config_set (старое и новое значение) |
posture.verified |
Маркер, который разрешает управление службой |
tray.log |
Ошибки трея |
16. Статус прохода
Ожидается (M1): прохождение на новом хосте Windows только по этому руководству.
Находки возвращаются в этот файл. Результаты лаборатории для удалённого режима (хост Linux,
новая ВМ, служба Windows): findings/phase12-lab-2026-11-03.md.