fbmcp: instalacja i użycie
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 samejdb) 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_cancelje 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.jsonlz ł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).
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-trayPliki binarne dla Linuksa (kompilacja krzyżowa z Windows albo kompilacja
na Linuksie bez 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/fbmcpctlSumy 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:
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 backupsSekrety. 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.
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:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- Usługa uruchamia
fbmcp -servejako LocalSystem, restartuje się po awarii i zatrzymuje się czysto przy zatrzymaniu usługi. - Hasła przez
secrets.dir(§5). - Zablokuj folder: zapisywać do
C:\fbmcpmogą tylko SYSTEM i Administrators (skrypt wypisuje polecenieicacls). Folder utworzony podC:\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 wfbmcp-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):
- Pliki binarne i
fbmcp.yamlwC:\fbmcp\(szablon: 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"— zanotuj pinsha256:....- 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.yamldodaje też wpisidentities:i używasecrets.dir. - Hasła i tokeny agenta:
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, potem bez-WhatIf. Tworzy usługę, regułę zapory, listy ACL folderów i prawa do usługi Firebird.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.- Zasobnik dla osoby zatwierdzającej:
.\packaging\windows\install-tray.ps1.
Serwer Linux (root): skopiuj fbmcp, fbmcpctl i packaging/linux/, potem
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/24Skrypt 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:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(klucz, który dostałeś).- 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. - Claude Code może też łączyć się bezpośrednio przez HTTP (
.mcp.json"type": "http", nagłówekAuthorization: Bearer ${FBMCP_KEY_SRV1},NODE_EXTRA_CA_CERTSdla certyfikatu samopodpisanego). Nie przekazuj klucza przezclaude mcp add --header: jest zapisywany jawnym tekstem. - Test:
fb_pingpokazuje 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.
- W kliencie: „
fb_agent_discover”. Wypisuje lokalnych agentów zbase_url,instance_idi sugerowaną nazwą tokenu. Nigdy nie czyta tokenów. - Operator zapisuje
local_api.tokenagenta (nieagent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Nigdy nie wpisuj tokenu do czatu. - W kliencie: „
fb_agent_registerdla tego agenta” → zatwierdź w zasobniku. fbmcp dodaje wpisagents:, przeładowuje i sprawdza tożsamość. - 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:
fb_cluster_rcm_password: zastąp pierwsze hasło RCM (Tier 1).- 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. - Usługi klastra (przełączenie, przejęcie awaryjne, ponowne dołączenie):
fb_cluster_servicepokazuje 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ą
fbmcpctl doctor --config <file>: konfiguracja, sekrety, logowania Firebird, foldery, postura, harmonogramy. Każda linia FAIL maFix:.fb_db_list→fb_db_health <db>;fb_service_statusdla instancji.fb_sessions,fb_transactionsprzy problemach z połączeniami albo luką OAT;fb_firebird_logprzy błędach silnika.
13.2 Podejrzenie manipulacji albo uszkodzenia: najpierw audyt
fbmcpctl verify --config <file>→audit chain OK: N entriesalboBROKENz powodem.- 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ł)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ kopia jest zweryfikowana.fb_window_opendla bazy.fb_restore_replace→ zatwierdź poza kanałem. Przestój aż do stanu online.- Sprawdzenie:
fb_db_health, potem rzeczywisty odczyt (fb_schema_list,fb_info). - Stary plik zostaje jako
<db>.pre-restore, dopóki go nie usuniesz.
13.4 Klient nie może się połączyć
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Czytaj dziennik MCP klienta (stdio) albo
<state_dir>\fbmcp.log/journalctl -u fbmcp(usługa). - „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.