Odbiorca: osoba, która instaluje i uruchamia fbmcp, a nie kompilowała go. Znajomość wewnętrznej budowy Go ani Firebird nie jest potrzebna. Stan na 2026-11-16, wersja 2027.2.24 (tryb lokalny i zdalny, instalacja HQbird, mostek fbagent, klaster HQbird, siatka wyników).

Krótkie wersje, nie na tej stronie: quickstart-en.md, quickstart-ru.md, quickstart-pt.md. Szczegóły, po angielsku: remote.md (tryb zdalny), agent-bridge.md (fbagent), tool-reference.md (każde narzędzie, jego Tier i argumenty), claude-desktop.md (podłączenie klienta na hoście deweloperskim), ADR-y w decisions/.


1. Czym jest fbmcp

fbmcp to serwer MCP dla Firebird 2.5–5.0 na Windows i Linuksie. Klient MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode i inne) używa go, aby pracować jak DBA: monitorowanie, kopie zapasowe i zweryfikowane odtworzenia, SQL/DDL/DCL, indeksy, użytkownicy i uprawnienia, firebird.conf, harmonogram, migracje, fbagent HQbird i klaster HQbird. Ma 122 narzędzia: 56 tylko do odczytu (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3 (wyłączone). fb_demo_write jest dostępne tylko wtedy, gdy serwer działa z FBMCP_DEMO_TOOLS=1.

Klient widzi tylko te narzędzia, których może użyć. Lista narzędzi ukrywa: Tier 3, narzędzia powyżej maksymalnego Tier tożsamości, fb_confirm i fb_cancel dla tożsamości tylko do odczytu, narzędzia fbagent, dopóki agents: jest puste (fb_agent_discover i fb_agent_register zostają), narzędzia migracji, dopóki żadna baza nie ma migrations_dir, oraz narzędzia klastra, dopóki fbmcp.yaml nie ma sekcji rcm:. Gdy przeładowanie konfiguracji zmienia ten zestaw, klient dostaje nową listę. Bezpośrednie wywołanie ukrytego narzędzia kończy się wyraźną odmową.

Plik binarny Rola
fbmcp Serwer. Domyślnie: MCP przez stdio (uruchamia go klient). -serve: bez stdio, działa jako usługa (harmonogram, gniazdo dołączenia, nasłuch HTTPS, jeśli jest skonfigurowany). fbmcp bridge: klient stdio dla zdalnego fbmcp
fbmcpctl CLI operatora: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Ten sam program co fbmcp ctl
fbmcp-tray Zasobnik Windows: wyskakujące okno Zatwierdź/Odrzuć dla żądań, które wymagają operatora

Jedno jądro na folder stanu. Drugi klient z tą samą konfiguracją nie uruchamia drugiego jądra: dołącza się do działającego.

2. Model bezpieczeństwa

Każde wywołanie przechodzi przez politykę → potwierdzenie przez człowieka → wykonanie zapisane w audycie.

Tier Co Jak jest potwierdzane
0 Odczyty (transakcje tylko do odczytu wymuszone przez silnik) Niepotrzebne
1 Zmiany rutynowe: DML/DDL, kopia zapasowa, użytkownicy, uprawnienia W kanale: klient pokazuje identyfikator żądania i token; osoba się zgadza; klient wywołuje fb_confirm
2 Wysoki wpływ: sterowanie usługą, odtworzenie z podmianą, firebird.conf, okno na wyłączność, rejestracja, restarty agenta Tylko poza kanałem: zasobnik albo fbmcpctl approve. Klient nigdy nie może tego zatwierdzić
3 Krytyczne (fb_db_drop) Wyłączone z założenia
  • Tier 2 zwykle wymaga otwartego okna konserwacji (fb_window_open, na tej samej db) i zweryfikowanej kopii zapasowej młodszej niż 24 godziny. Odmowa mówi, czego brakuje.
  • Oczekujące żądanie wygasa po 15 minutach. Próba niewłaściwym kanałem go nie zużywa; fb_cancel je usuwa.
  • Każde narzędzie objęte zatwierdzeniem przyjmuje mode: preview: pokazuje skutek i nic nie robi.
  • Każda decyzja (zezwolenie, oczekiwanie, zatwierdzenie, odmowa) trafia do audit.jsonl z łańcuchem haszy.
  • Strony WWW do zatwierdzania nie ma i nigdy jej być nie może: strona, do której model może sięgnąć, złamałaby ten zamysł.

3. Wybór wariantu

Wariant Gdzie działa fbmcp Kiedy go używać Sekcja
A. Lokalne stdio Twój komputer; klient go uruchamia Jeden administrator, Firebird na tym komputerze albo w sieci LAN §6
B. Usługa lokalna Usługa Windows na hoście bazy (-serve) Harmonogramy muszą działać, gdy żaden klient nie jest otwarty §7
C. Zdalny Usługa na serwerze bazy, HTTPS + klucze API Kilku administratorów, odległy serwer, autonomiczni agenci §8

W wariancie A jądro żyje tylko wtedy, gdy działa klient, więc harmonogramy uruchamiają się tylko wtedy. Do harmonogramów bez nadzoru (nightly_verify) użyj B albo C.

fbmcp w HQbird. Instalacje HQbird 2027 i fbagent instalują fbmcp domyślnie: jedna usługa na serwer dla wszystkich linii Firebird, ustawiana przez fbmcp ctl hqbird-install. Na takim serwerze nie postępuj według §6–§8; czytaj hqbird.md (układ, tryb zdalny z --allow-from, klucze API).

4. Pobranie plików binarnych

Wymagania: Go ≥ 1.26.11 (starszy Go 1.21+ sam pobiera go1.26.11 przy pierwszej kompilacji; potrzebny jest internet), CGO nie jest potrzebne; Firebird 2.5–5.0; fbagent ≥ 2.67 z Local API dla narzędzi agenta (opcjonalnie); fbagent 3.1.0+ i RCM 2027.5.11+ dla narzędzi klastra (opcjonalnie).

Command
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

Pliki binarne dla Linuksa (kompilacja krzyżowa z Windows albo kompilacja na Linuksie bez GOOS):

Command
$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

Sumy kontrolne: Get-FileHash dist/* albo sha256sum dist/*. Więcej celów: packaging/README.md. Umieść pliki binarne we własnym folderze (przykłady używają C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\ (Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).

fbmcp ctl i fbmcpctl to ten sam program. fbmcpctl help wypisuje polecenia. Polecenia, które czytają konfigurację, przyjmują --config <file>; bez niego używają FBMCP_CONFIG, potem fbmcp.yaml w bieżącym folderze, potem obok programu, potem domyślnej ścieżki HQbird (C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml) i wypisują using config <path>.

5. Konfiguracja fbmcp.yaml

Pełny przykład: packaging/fbmcp.yaml.example. Minimalna konfiguracja Windows:

yaml
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

Sekrety. YAML trzyma tylko nazwy zmiennych. fbmcp szuka każdej wartości w tej kolejności: zmienna środowiskowa → plik <secrets.dir>/<NAME> → magazyn kluczy systemu operacyjnego konta, na którym działa fbmcp.

Command
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)

Wartość jest czytana ze stdin (wpisz ją, potem Ctrl+Z, Enter; w Linuksie Ctrl+D). Konto usługi (LocalSystem, NT SERVICE\...) nie widzi Twojego magazynu kluczy: dla usług użyj secrets.dir. Zmieniony plik sekretu zaczyna obowiązywać po kilku sekundach, bez restartu.

Użytkownik tylko do odczytu. Utwórz osobnego użytkownika Firebird dla ro_user (SQL: quickstart-en.md: CREATE USER FBMCP_RO, GRANT SELECT na każdej tabeli, a w Firebird 4.0+ rola z MONITOR_ANY_ATTACHMENT, aby fb_sessions widział wszystkie połączenia). SYSDBA jako użytkownik RO jest tylko do prac deweloperskich; doctor o tym ostrzega.

Przeładowanie na żywo. fbmcp sam stosuje zmiany w fbmcp.yaml (obserwator pliku) albo na fb_config_reload. Bez restartu klienta ani procesu. Przeładowanie czeka na zadania na zmienionych bazach (30 s), potem stosuje zmiany. Odmowa: zmiana state.dir, zdublowane ścieżki baz, niezabezpieczona konfiguracja zdalna.

Sprawdzenie: C:\fbmcp\fbmcpctl.exe doctor musi zakończyć się doctor: green (tryb zdalny: doctor --remote, bez linii FAIL). Tworzy brakujący folder stanu, loguje się do każdej bazy oboma użytkownikami, a każda linia FAIL kończy się Fix: i poleceniem do uruchomienia.

6. Wariant A — lokalne stdio

Używaj ścieżek bezwzględnych. Nie ustawiaj listen. Po zmianie konfiguracji uruchom klienta ponownie: klienci ładują serwery tylko przy starcie.

Klient Gdzie Wpis
Claude Desktop Ustawienia → Deweloper → Edytuj konfigurację (%APPDATA%\Claude\claude_desktop_config.json) "mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}}
Claude Code wiersz poleceń claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml"
Cursor %USERPROFILE%\.cursor\mcp.json albo .cursor\mcp.json w projekcie ten sam JSON co Claude Desktop
Codex codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml albo %USERPROFILE%\.codex\config.toml [mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml']
ZCode .zcode\config.json w projekcie "mcp": {"servers": {"fbmcp": { ...same command and args... }}}

Hasła są w magazynie kluczy (§5), więc blok env nie jest potrzebny. Jeśli mimo to wpiszesz hasło do bloku env klienta, trzymaj ten plik poza gitem.

Potem uruchom zasobnik do zatwierdzeń Tier 2: C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (przy każdym logowaniu: .\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).

Test dymny w kliencie: „wywołaj fb_ping” (pokazuje nazwę serwera i Twoją tożsamość z jej maksymalnym Tier), potem „fb_db_list”, potem „fb_db_health dla main”.

7. Wariant B — lokalna usługa Windows

PowerShell z podniesionymi uprawnieniami:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • Usługa uruchamia fbmcp -serve jako LocalSystem, restartuje się po awarii i zatrzymuje się czysto przy zatrzymaniu usługi.
  • Hasła przez secrets.dir (§5).
  • Zablokuj folder: zapisywać do C:\fbmcp mogą tylko SYSTEM i Administrators (skrypt wypisuje polecenie icacls). Folder utworzony pod C:\ pozwala każdemu użytkownikowi zmieniać pliki, a usługa uruchamia je jako SYSTEM.
  • Użytkownik zasobnika i lokalni klienci stdio potrzebują odczytu i zapisu w folderze stanu: icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Klient stdio z tą samą konfiguracją dołącza się wtedy do jądra usługi.
  • Gotowość: C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml.
  • Dziennik: <state_dir>\fbmcp.log (5 × 10 MiB; awarie w fbmcp-crash.log).

Dla usługi, do której administratorzy łączą się przez sieć, użyj wariantu C.

8. Wariant C — zdalny (HTTPS + klucze API)

Pełna procedura: remote.md. Skrót:

Serwer Windows (z podniesionymi uprawnieniami):

  1. Pliki binarne i fbmcp.yaml w C:\fbmcp\ (szablon: remote.md §3: listen, tls, identities, allowed_origins, secrets.dir).
  2. C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp" — zanotuj pin sha256:....
  3. Jeden klucz na osobę albo agenta: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets (wypisywany raz). Z --config C:\fbmcp\fbmcp.yaml dodaje też wpis identities: i używa secrets.dir.
  4. Hasła i tokeny agenta: fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME.
  5. .\packaging\windows\install-remote.ps1 -Port 8443 -AllowFrom 10.0.0.0/24 -FirebirdService FirebirdServerDefaultInstance -WhatIf, potem bez -WhatIf. Tworzy usługę, regułę zapory, listy ACL folderów i prawa do usługi Firebird.
  6. C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml → bez FAIL; curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz → ok.
  7. Zasobnik dla osoby zatwierdzającej: .\packaging\windows\install-tray.ps1.

Serwer Linux (root): skopiuj fbmcp, fbmcpctl i packaging/linux/, potem

Command
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

Skrypt tworzy foldery, certyfikat, pierwszą konfigurację z kluczem admin (wypisywanym raz), jednostkę systemd, regułę sudo dla jednostki Firebird i regułę ufw, potem uruchamia doctor --remote. Dodaj databases: i agents: do /etc/fbmcp/fbmcp.yaml. Zatwierdzenia w Linuksie (bez zasobnika): sudo -u firebird fbmcpctl approve [id]. Sam znajduje /etc/fbmcp/fbmcp.yaml, pyta y/N (--yes nie pyta), a --deny <id> --reason "..." odmawia.

Komputer administratora:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (klucz, który dostałeś).
  2. Dowolny klient stdio (Claude Desktop, Cursor, Codex, ZCode): wpis z §6 z tymi args: ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Pin sprawdza klucz serwera, więc certyfikat samopodpisany nie wymaga konfiguracji CA.
  3. Claude Code może też łączyć się bezpośrednio przez HTTP (.mcp.json "type": "http", nagłówek Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS dla certyfikatu samopodpisanego). Nie przekazuj klucza przez claude mcp add --header: jest zapisywany jawnym tekstem.
  4. Test: fb_ping pokazuje nazwę serwera i Twoją tożsamość.

Autonomiczni agenci (OpenClaw i podobne): osobny klucz przez apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32. Domyślnie tylko do odczytu; każde żądanie Tier 1 czeka na operatora, a fb_confirm od agenta jest odrzucane. Limity: remote.md §6–7.

9. Mostek fbagent i klaster HQbird (opcjonalnie)

Narzędzia agenta (fb_agent_status, fb_agent_job_run, …) używają Local API fbagent HQbird na tym samym hoście. Są wyłączone, dopóki agents: nie ma wpisu.

  1. W kliencie: „fb_agent_discover”. Wypisuje lokalnych agentów z base_url, instance_id i sugerowaną nazwą tokenu. Nigdy nie czyta tokenów.
  2. Operator zapisuje local_api.token agenta (nie agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Nigdy nie wpisuj tokenu do czatu.
  3. W kliencie: „fb_agent_register dla tego agenta” → zatwierdź w zasobniku. fbmcp dodaje wpis agents:, przeładowuje i sprawdza tożsamość.
  4. Test: fb_agent_status, fb_agent_instances.

fb_agent_config_set (zmiana ustawień zadań: kopia zapasowa, sweep, …) wymaga też config_path we wpisie oraz odczytu żywego agent_config.json i prawa tworzenia w jego folderze. Ten plik trzyma token i poświadczenia Firebird, więc to nadanie uprawnień jest decyzją operatora (agent-bridge.md). Gdy sprawdzenie agenta się nie powiedzie, narzędzie nic nie zapisuje.

Klaster HQbird (RCM). Narzędzia klastra wywołują menedżera klastra HQbird (hqbirdrcm) na tym samym hoście. Są pokazywane tylko wtedy, gdy fbmcp.yaml ma sekcję rcm: (url, ca_file, user, password_env). Na serwerze Linux z HQbird fbmcp ctl hqbird-install zapisuje ją z /opt/hqbirdrcm/rcm.json i zapisuje pierwsze hasło RCM w sekrecie FBMCP_RCM_PASSWORD; gdzie indziej dodaj sekcję ręcznie (tool-reference.md). Następnie:

  1. fb_cluster_rcm_password: zastąp pierwsze hasło RCM (Tier 1).
  2. Nowy klaster: otwórz okno parowania na każdym hoście (fb_agent_cluster_pairing), uruchom RCM na masterze (fb_agent_cluster_rcm), połącz hosty (fb_cluster_link), utwórz repliki (fb_cluster_reinit, Tier 2) i porównaj dane (fb_cluster_verify). Kroki: prompts/cluster-setup.md.
  3. Usługi klastra (przełączenie, przejęcie awaryjne, ponowne dołączenie): fb_cluster_service pokazuje je i kontrole; ruchy są Tier 2. Kroki: prompts/cluster-services.md.

10. Codzienne użycie

Pytaj klienta zwykłymi słowami; sam wybiera narzędzia. Przykłady:

Zadanie Narzędzia
Czy wszystko działa? fb_ping, fb_db_list, fb_db_health, fb_service_status
Odczyt danych fb_query (tylko do odczytu, wiersze + plan + statystyki per tabela; siatka w klientach MCP-Apps); szkic sprawdź przez fb_query_check
Sesje, długie transakcje fb_sessions, fb_transactions, fb_session_kill (Tier 1)
Wolne zapytanie fb_analyze_query, fb_index_advice → zastosuj przez fb_write; fb_agent_perf_report
Kopia zapasowa fb_backup_start → identyfikator zadania → fb_job_status
Weryfikacja kopii fb_restore_test (odtwarza do work_dir, oznacza kopię jako zweryfikowaną)
Nocna kopia + weryfikacja fb_schedule_create z target=nightly_verify (potwierdzane raz; wariant B albo C)
Schemat / DDL fb_schema_list, fb_describe, fb_write (każda instrukcja jest klasyfikowana i dostaje Tier), fb_diff_schema
Migracje fb_migration_status, fb_migration_plan, fb_migration_apply
Konfiguracja serwera fb_config_get, fb_config_diff, fb_config_set (Tier 2)
Dzienniki fb_firebird_log
Pojemność fb_trends, fb_gstat, fb_index_stats
Stan klastra fb_cluster_status, fb_cluster_service
Przeniesienie mastera fb_cluster_switchover (bez utraty danych) albo fb_cluster_failover (utrata mastera), potem fb_cluster_rejoin (Tier 2)

Zadania są asynchroniczne: wyślij → fb_job_status. Zadania na jednej bazie wykonują się po jednym naraz. Zadanie przeżywa restart fbmcp tylko jako interrupted: wyślij je ponownie, jeśli nadal jest potrzebne.

fb_config_set zmienia tylko własną linię w firebird.conf (komentarze, wcięcia i końce linii zostają), zachowuje stary plik jako firebird.conf.prev i nigdy nie restartuje Firebird. Restart przez fb_service_restart (Tier 2): czeka, aż usługa zostanie zatrzymana i znów działa.

11. Zadania operatora

Zadanie Polecenie
Lista / zatwierdzenie / odmowa żądań fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (albo zasobnik)
Rotacja klucza fbmcpctl apikey rotate alice --config <fbmcp.yaml> (stary klucz przestaje działać w kilka sekund)
Lista kluczy fbmcpctl apikey list (nazwy, źródła, poziomy; nigdy wartości)
Usunięcie osoby usuń wpis identities:, potem fbmcpctl secret drop --dir <dir> NAME
Odnowienie certyfikatu fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin bez zmian, bez restartu)
Sprawdzenie łańcucha audytu fbmcpctl verify
Czy jądro żyje? fbmcpctl ping; fbmcpctl status (odczyt stanu w trybie offline)
Zezwolenie na sterowanie usługą packaging/posture/verify.ps1 albo verify.sh, potem fbmcpctl setup --write-posture
Aktualizacja zatrzymaj usługę (albo klientów), podmień pliki binarne, uruchom, doctor
Usunięcie Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Zachowaj folder stanu (audyt), chyba że właściciel powie inaczej

Tylko host deweloperski: .\packaging\rebuild-install.ps1 -Force przebudowuje dist\, zatrzymuje i podmienia działające pliki binarne (stare zostają jako *.exe~), scala konfiguracje klientów i uruchamia doctor.

12. Odzyskiwanie po awarii i restarcie

Zweryfikowane przez test chaosu (internal/killharness).

Po awarii albo zabiciu procesu Przy restarcie Działanie operatora
Zadanie działało albo było w kolejce Oznaczone interrupted; nigdy nie wznawiane Wyślij ponownie, jeśli potrzeba
Oczekujące żądanie, niepotwierdzone Przywrócone z state.json (TTL nadal obowiązuje) Potwierdź albo pozwól wygasnąć
fb_restore_replace w toku Kończy: odtworzenie, walidacja, baza online; <db>.pre-restore zostaje Sprawdź fb_db_health; .pre-restore usuń później
fb_shutdown_window w toku Kończy krok gfix -online Sprawdź, czy jest online
Nieaktualny instance.lock Przejmowany automatycznie Brak
state.json uszkodzony Jądro odmawia startu; kopia zostaje jako state.json.corrupt-<ts> Sprawdź; napraw albo celowo usuń state.json (fbmcpctl repair odbudowuje zatwierdzenia harmonogramów z audytu)
audit.jsonl uszkodzony albo obcięty Jądro odmawia startu §13.2: traktuj to jako sygnał manipulacji
Zegar cofnięty Harmonogram pomija; bez podwójnego uruchomienia Brak
Proces usługi Windows zabity SCM restartuje go po około 5 s Brak

Jądro przyjmuje stan zamknięty wobec wszystkiego, czego integralności nie potrafi dowieść. Pętla restartów to sygnał: czytaj dziennik.

13. Scenariusze incydentów

13.1 Coś jest nie tak z bazą

  1. fbmcpctl doctor --config <file>: konfiguracja, sekrety, logowania Firebird, foldery, postura, harmonogramy. Każda linia FAIL ma Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status dla instancji.
  3. fb_sessions, fb_transactions przy problemach z połączeniami albo luką OAT; fb_firebird_log przy błędach silnika.

13.2 Podejrzenie manipulacji albo uszkodzenia: najpierw audyt

  1. fbmcpctl verify --config <file> → audit chain OK: N entries albo BROKEN z powodem.
  2. Jeśli się nie powiedzie: zachowaj cały folder stanu (to dowód), potem badaj. Nie usuwaj audit.jsonl, żeby zmusić jądro do startu.

13.3 Ćwiczenie odtworzenia (co kwartał)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → kopia jest zweryfikowana.
  3. fb_window_open dla bazy.
  4. fb_restore_replace → zatwierdź poza kanałem. Przestój aż do stanu online.
  5. Sprawdzenie: fb_db_health, potem rzeczywisty odczyt (fb_schema_list, fb_info).
  6. Stary plik zostaje jako <db>.pre-restore, dopóki go nie usuniesz.

13.4 Klient nie może się połączyć

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Czytaj dziennik MCP klienta (stdio) albo <state_dir>\fbmcp.log / journalctl -u fbmcp (usługa).
  3. „another fbmcp instance is active”: jedno jądro na folder stanu. Klienci w potoku dołączają się sami; drugie jądro szybko kończy się błędem z założenia.

W poleceniach powyżej możesz pominąć --config, gdy wyszukiwanie z §4 znajdzie plik.

14. Rozwiązywanie problemów

Objaw Znaczenie / naprawa
Narzędzia się nie pojawiają składnia JSON, ścieżki bezwzględne, pełny restart klienta; dziennik MCP klienta
Jednego narzędzia brakuje na liście Ukryte celowo (§1): powyżej Twojego maksymalnego Tier, brak wpisu agents:, brak migrations_dir albo brak sekcji rcm:
Serwer kończy się od razu fbmcpctl doctor; brakujący sekret; usługa nie może czytać Twojego magazynu kluczy (użyj secrets.dir)
Tier 2 „confirmation rejected: channel policy” Oczekiwane w czacie. Zatwierdź w zasobniku albo przez fbmcpctl approve
Tier 2 „no open maintenance window” fb_window_open dla tej samej db, którą przekazujesz do narzędzia
fb_restore_replace odmowa: warunki wstępne Potrzebna zweryfikowana kopia < 24 h: fb_backup_start + fb_restore_test oraz okno
Odmowa sterowania usługą brak posture.verified (fbmcpctl setup --write-posture) albo konto nie ma praw do usługi Firebird
fb_config_set: nie może zapisać Konto nie może zmienić tego pliku (jednostka Linux ProtectSystem=strict; ACL Windows). Edytuj ręcznie albo zobacz remote.md §8
Zasobnik nic nie pokazuje Pokazuje tylko żądania, które wymagają operatora; sprawdź prawa użytkownika zasobnika do folderu stanu i tray.log w nim
401 (zdalny) Zły klucz albo serwer go nie załadował: apikey list, doctor --remote
403 (zdalny) Źródłowy adres IP nie jest w allow_from / zaporze albo nagłówek Origin nie jest w allowed_origins
429 (zdalny) Limity; czekaj na Retry-After
Niezgodność pinu Klucz serwera się zmienił; weź nowy pin od administratora serwera
agent-unreachable Usługa agenta nie działa, local_api.enabled: false albo zły base_url (domyślnie 127.0.0.1:(10000 + firebird port))
agent-auth Zapisany token nie jest local_api.token agenta; ustaw go ponownie
agent-timeout przy restartach agents[].timeout_seconds (130) musi być większe niż restart_timeout_seconds agenta (120)
Error loading plugin MySQLEngine … przy dołączeniu W HQbird zwykle oznacza to, że plik bazy nie istnieje; sprawdź ścieżkę
Gołe DROP INDEX w fb_write wymaga okna Tam jest to Tier 2; użyj fb_index_drop (Tier 1; odmawia indeksów więzów)
Nowy indeks nieużywany Uruchom statystyki (fb_index_rebuild action=statistics); ORDER BY … DESC wymaga indeksu DESCENDING
Narzędzia zawodzą tylko dla jednej bazy Jest offline (fb_db_health); narzędzia degradują się osobno dla każdej bazy

15. Opis folderu stanu

Ścieżka Znaczenie
state.json (+ .tmp, .corrupt-*) Oczekujące żądania, zadania, katalog kopii, przepływy pracy, harmonogramy. Uszkodzenie ⇒ odmawia startu
audit.jsonl (+ .head) Dziennik audytu z łańcuchem haszy; .head wykrywa obcięcie
events.jsonl Zdarzenia zadań (job.succeeded, job.failed z komunikatem)
approvals\, denials\ Decyzje poza kanałem (zasobnik / fbmcpctl approve), używane w ciągu ~2 s
instance.lock Blokada jednego jądra
attach.addr, attach.token Punkt dołączenia dla dodatkowych klientów stdio
fbmcp.log, fbmcp-crash.log Dziennik usługi (rotowany) i wyjście awarii
query-log.jsonl Każde wywołanie fb_query
trends\ Historia próbkowania dla fb_trends
config-journal\ Historia fb_config_set (stara i nowa wartość)
posture.verified Znacznik, który zezwala na sterowanie usługą
tray.log Błędy zasobnika

16. Status przejścia

Oczekuje (M1): przejście na świeżym hoście Windows wyłącznie według tego przewodnika. Ustalenia wracają do tego pliku. Wyniki laboratorium dla trybu zdalnego (host Linux, świeża maszyna wirtualna, usługa Windows): findings/phase12-lab-2026-11-03.md.