Đối tượng: người cài đặt và chạy fbmcp, và không tự biên dịch nó. Không cần hiểu nội bộ Go hay Firebird. Tình trạng tính đến 2026-11-16, phiên bản 2027.2.24 (chế độ cục bộ và từ xa, cài đặt HQbird, cầu fbagent, cụm HQbird, lưới kết quả).

Bản ngắn, không có trên site này: quickstart-en.md, quickstart-ru.md, quickstart-pt.md. Chi tiết, bằng tiếng Anh: remote.md (chế độ từ xa), agent-bridge.md (fbagent), tool-reference.md (mọi công cụ, Tier của nó và các đối số), claude-desktop.md (đấu nối máy khách trên máy chủ phát triển), các ADR trong decisions/.


1. fbmcp là gì

fbmcp là một máy chủ MCP cho Firebird 2.5–5.0 trên Windows và Linux. Một máy khách MCP (Claude Desktop, Claude Code, Cursor, Codex, ZCode, những máy khác) dùng nó để làm việc như một DBA: giám sát, sao lưu và khôi phục đã kiểm chứng, SQL/DDL/DCL, chỉ mục, người dùng và quyền, firebird.conf, bộ lập lịch, di trú, fbagent của HQbird và cụm HQbird. Có 122 công cụ: 56 chỉ đọc (Tier 0), 44 Tier 1, 21 Tier 2, 1 Tier 3 (tắt). fb_demo_write chỉ có khi máy chủ chạy với FBMCP_DEMO_TOOLS=1.

Máy khách chỉ thấy các công cụ nó dùng được. Danh sách công cụ ẩn: Tier 3, công cụ trên Tier tối đa của danh tính, fb_confirm và fb_cancel đối với danh tính chỉ đọc, các công cụ fbagent khi agents: trống (fb_agent_discover và fb_agent_register vẫn còn), các công cụ di trú khi không cơ sở dữ liệu nào có migrations_dir, và các công cụ cụm khi fbmcp.yaml không có mục rcm:. Khi tải lại cấu hình đổi tập này, máy khách nhận danh sách mới. Lời gọi thẳng tới công cụ bị ẩn nhận một lời từ chối rõ.

Tệp nhị phân Vai trò
fbmcp Máy chủ. Mặc định: MCP qua stdio (một máy khách khởi động nó). -serve: không stdio, chạy như một dịch vụ (bộ lập lịch, socket gắn, bộ lắng nghe HTTPS nếu đã cấu hình). fbmcp bridge: máy khách stdio cho một fbmcp từ xa
fbmcpctl CLI của người vận hành: doctor, approve, secret, apikey, tls, verify, status, ping, setup, repair, hqbird-install, gate. Cùng chương trình với fbmcp ctl
fbmcp-tray Khay Windows: cửa sổ bật lên Duyệt/Từ chối cho yêu cầu cần người vận hành

Một nhân mỗi thư mục trạng thái. Máy khách thứ hai với cùng cấu hình không khởi động nhân thứ hai: nó gắn vào nhân đang chạy.

2. Mô hình an toàn

Mọi lời gọi đi qua chính sách → người xác nhận → thực thi có kiểm toán.

Tier Việc gì Cách xác nhận
0 Lần đọc (giao dịch chỉ đọc do engine bắt buộc) Không cần
1 Thay đổi thường lệ: DML/DDL, sao lưu, người dùng, quyền Trong kênh: máy khách hiện mã yêu cầu và một token; người đó đồng ý; máy khách gọi fb_confirm
2 Tác động lớn: điều khiển dịch vụ, khôi phục rồi thay, firebird.conf, cửa sổ độc quyền, đăng ký, khởi động lại tác nhân Chỉ ngoài kênh: khay hoặc fbmcpctl approve. Máy khách không bao giờ phê duyệt được
3 Nghiêm trọng (fb_db_drop) Tắt theo thiết kế
  • Tier 2 thường cần một cửa sổ bảo trì đang mở (fb_window_open, trên cùng db) và một bản sao lưu đã kiểm chứng mới hơn 24 giờ. Lời từ chối nói rõ thiếu gì.
  • Yêu cầu đang chờ hết hạn sau 15 phút. Một lần thử sai kênh không tiêu thụ yêu cầu; fb_cancel gỡ nó.
  • Mọi công cụ có cổng chấp nhận mode: preview: hiện tác động và không làm gì.
  • Mọi quyết định (cho phép, đang chờ, đã duyệt, đã từ chối) vào audit.jsonl xâu chuỗi bằng hàm băm.
  • Không có trang web phê duyệt, và không bao giờ được có: một trang mà mô hình với tới được sẽ phá thiết kế.

3. Chọn một phương án

Phương án fbmcp chạy ở đâu Dùng khi nào Mục
A. stdio cục bộ Máy tính của bạn; máy khách khởi động nó Một quản trị viên, Firebird trên máy này hoặc trong LAN §6
B. Dịch vụ cục bộ Dịch vụ Windows trên máy chủ cơ sở dữ liệu (-serve) Lịch phải chạy khi không có máy khách nào mở §7
C. Từ xa Dịch vụ trên máy chủ cơ sở dữ liệu, HTTPS + khóa API Nhiều quản trị viên, máy chủ ở xa, tác nhân tự trị §8

Ở phương án A, nhân chỉ sống khi một máy khách đang chạy, nên lịch chỉ kích hoạt lúc đó. Lịch không giám sát (nightly_verify) thì dùng B hoặc C.

fbmcp trong HQbird. Bản cài HQbird 2027 và fbagent mặc định cài fbmcp: một dịch vụ mỗi máy chủ cho mọi dòng Firebird, do fbmcp ctl hqbird-install thiết lập. Trên máy chủ như vậy đừng theo §6–§8; hãy đọc hqbird.md (bố cục, chế độ từ xa với --allow-from, khóa API).

4. Lấy tệp nhị phân

Yêu cầu: Go ≥ 1.26.11 (Go 1.21+ cũ hơn tự tải go1.26.11 ở lần biên dịch đầu; việc này cần internet), không cần CGO; Firebird 2.5–5.0; fbagent ≥ 2.67 với Local API cho các công cụ tác nhân (tùy chọn); fbagent 3.1.0+ và RCM 2027.5.11+ cho các công cụ cụm (tùy chọn).

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

Tệp nhị phân Linux (biên dịch chéo từ Windows, hoặc biên dịch trên Linux không có 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

Giá trị kiểm tra: Get-FileHash dist/* hoặc sha256sum dist/*. Thêm đích biên dịch: packaging/README.md. Đặt các tệp nhị phân vào một thư mục riêng (ví dụ dùng C:\fbmcp\): mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\ (Linux: install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/).

fbmcp ctl và fbmcpctl là cùng một chương trình. fbmcpctl help liệt kê các lệnh. Lệnh đọc cấu hình nhận --config <file>; không có thì chúng dùng FBMCP_CONFIG, rồi fbmcp.yaml trong thư mục hiện tại, rồi cạnh chương trình, rồi mặc định của HQbird (C:\HQbirdData\fbmcp\fbmcp.yaml, /etc/fbmcp/fbmcp.yaml), và in using config <path>.

5. Cấu hình fbmcp.yaml

Ví dụ đầy đủ: packaging/fbmcp.yaml.example. Cấu hình Windows tối thiểu:

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

Bí mật. YAML chỉ giữ tên biến. fbmcp tra từng giá trị theo thứ tự này: biến môi trường → tệp <secrets.dir>/<NAME> → móc khóa hệ điều hành của tài khoản chạy 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)

Giá trị được đọc từ stdin (gõ vào, rồi Ctrl+Z, Enter; Linux Ctrl+D). Tài khoản dịch vụ (LocalSystem, NT SERVICE\...) không thấy móc khóa của bạn: dịch vụ thì dùng secrets.dir. Tệp bí mật đã đổi được áp dụng sau vài giây, không cần khởi động lại.

Người dùng chỉ đọc. Tạo một người dùng Firebird riêng cho ro_user (SQL: quickstart-en.md: CREATE USER FBMCP_RO, GRANT SELECT trên mọi bảng, và trên Firebird 4.0+ một vai trò có MONITOR_ANY_ATTACHMENT để fb_sessions thấy mọi kết nối). SYSDBA làm người dùng RO chỉ dành cho môi trường phát triển; doctor cảnh báo về điều đó.

Tải lại trực tiếp. fbmcp tự áp dụng thay đổi của fbmcp.yaml (bộ theo dõi tệp), hoặc khi fb_config_reload. Không khởi động lại máy khách hay tiến trình. Lần tải lại chờ các việc trên cơ sở dữ liệu đã đổi (30 s), rồi áp dụng. Bị từ chối: đổi state.dir, đường dẫn cơ sở dữ liệu trùng, cấu hình từ xa không an toàn.

Kiểm tra: C:\fbmcp\fbmcpctl.exe doctor phải kết thúc bằng doctor: green (chế độ từ xa: doctor --remote, không có dòng FAIL). Nó tạo thư mục trạng thái còn thiếu, đăng nhập mọi cơ sở dữ liệu bằng cả hai người dùng, và mỗi dòng FAIL kết thúc bằng Fix: cùng lệnh cần chạy.

6. Phương án A — stdio cục bộ

Dùng đường dẫn tuyệt đối. Đừng đặt listen. Khởi động lại máy khách sau khi đổi cấu hình: máy khách chỉ nạp máy chủ lúc khởi động.

Máy khách Ở đâu Mục
Claude Desktop Cài đặt → Nhà phát triển → Sửa cấu hình (%APPDATA%\Claude\claude_desktop_config.json) "mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}}
Claude Code dòng lệnh claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml"
Cursor %USERPROFILE%\.cursor\mcp.json hoặc .cursor\mcp.json trong dự án cùng JSON như Claude Desktop
Codex codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml hoặc %USERPROFILE%\.codex\config.toml [mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml']
ZCode .zcode\config.json trong dự án "mcp": {"servers": {"fbmcp": { ...same command and args... }}}

Mật khẩu nằm trong móc khóa (§5), nên không cần khối env. Nếu bạn vẫn đưa mật khẩu vào khối env của máy khách, hãy giữ tệp đó ngoài git.

Rồi khởi động khay cho các phê duyệt Tier 2: C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml (mỗi lần đăng nhập: .\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml).

Kiểm tra khói trong máy khách: “gọi fb_ping” (hiện tên máy chủ và danh tính của bạn cùng Tier tối đa), rồi “fb_db_list”, rồi “fb_db_health cho main”.

7. Phương án B — dịch vụ Windows cục bộ

PowerShell với quyền nâng cao:

Command
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp
  • Dịch vụ chạy fbmcp -serve dưới LocalSystem, khởi động lại khi lỗi, và dừng sạch khi dịch vụ dừng.
  • Dùng secrets.dir cho mật khẩu (§5).
  • Khóa thư mục: chỉ SYSTEM và Administrators được ghi vào C:\fbmcp (script in lệnh icacls). Thư mục tạo dưới C:\ cho mọi người dùng sửa tệp, và dịch vụ chạy chúng với tư cách SYSTEM.
  • Người dùng khay và các máy khách stdio cục bộ cần đọc/ghi trên thư mục trạng thái: icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M". Máy khách stdio với cùng cấu hình khi đó gắn vào nhân của dịch vụ.
  • Sẵn sàng: C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml.
  • Nhật ký: <state_dir>\fbmcp.log (5 × 10 MiB; sự cố trong fbmcp-crash.log).

Với dịch vụ mà quản trị viên truy cập qua mạng, hãy dùng phương án C.

8. Phương án C — từ xa (HTTPS + khóa API)

Quy trình đầy đủ: remote.md. Dạng ngắn:

Máy chủ Windows (quyền nâng cao):

  1. Tệp nhị phân và fbmcp.yaml trong C:\fbmcp\ (mẫu: 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" — ghi lại pin sha256:....
  3. Một khóa cho mỗi người hoặc tác nhân: C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets (in ra một lần). Với --config C:\fbmcp\fbmcp.yaml nó cũng thêm mục identities: và dùng secrets.dir.
  4. Mật khẩu và token của tác nhân: 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, rồi bỏ -WhatIf. Script tạo dịch vụ, quy tắc tường lửa, ACL thư mục và quyền dịch vụ Firebird.
  6. C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml → không có FAIL; curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz → ok.
  7. Khay cho người phê duyệt: .\packaging\windows\install-tray.ps1.

Máy chủ Linux (root): chép fbmcp, fbmcpctl và packaging/linux/, rồi

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

Script tạo các thư mục, chứng chỉ, cấu hình đầu với khóa admin (in một lần), unit systemd, quy tắc sudo cho unit Firebird và quy tắc ufw, rồi chạy doctor --remote. Thêm databases: và agents: vào /etc/fbmcp/fbmcp.yaml. Phê duyệt trên Linux (không có khay): sudo -u firebird fbmcpctl approve [id]. Nó tự tìm /etc/fbmcp/fbmcp.yaml, hỏi y/N (--yes không hỏi), và --deny <id> --reason "..." từ chối.

Máy tính quản trị:

  1. C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1 (khóa bạn đã nhận).
  2. Bất kỳ máy khách stdio nào (Claude Desktop, Cursor, Codex, ZCode): mục ở §6 với các args này: ["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]. Pin kiểm tra khóa máy chủ, nên chứng chỉ tự ký không cần thiết lập CA.
  3. Claude Code cũng có thể kết nối thẳng qua HTTP (.mcp.json "type": "http", tiêu đề Authorization: Bearer ${FBMCP_KEY_SRV1}, NODE_EXTRA_CA_CERTS cho chứng chỉ tự ký). Đừng truyền khóa bằng claude mcp add --header: nó được lưu dạng văn bản thuần.
  4. Thử: fb_ping hiện tên máy chủ và danh tính của bạn.

Tác nhân tự trị (OpenClaw và tương tự): một khóa riêng với apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32. Mặc định chỉ đọc; mọi yêu cầu Tier 1 chờ người vận hành, và fb_confirm từ tác nhân bị từ chối. Giới hạn: remote.md §6–7.

9. Cầu fbagent và cụm HQbird (tùy chọn)

Các công cụ tác nhân (fb_agent_status, fb_agent_job_run, …) dùng Local API của fbagent HQbird trên cùng máy chủ. Chúng tắt cho đến khi agents: có một mục.

  1. Trong máy khách: “fb_agent_discover”. Nó liệt kê các tác nhân cục bộ với base_url, instance_id và tên token gợi ý. Không bao giờ đọc token.
  2. Người vận hành lưu local_api.token của tác nhân (không phải agent.auth_token): fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>. Không bao giờ gõ token vào cuộc trò chuyện.
  3. Trong máy khách: “fb_agent_register cho tác nhân đó” → phê duyệt trong khay. fbmcp thêm mục agents:, tải lại và kiểm tra danh tính.
  4. Thử: fb_agent_status, fb_agent_instances.

fb_agent_config_set (đổi thiết lập việc: sao lưu, sweep, …) cũng cần config_path trên mục và quyền đọc agent_config.json đang dùng, cùng quyền tạo trên thư mục của nó. Tệp đó giữ token và thông tin đăng nhập Firebird, nên việc cấp quyền này là quyết định của người vận hành (agent-bridge.md). Khi kiểm tra tác nhân thất bại, công cụ không ghi gì.

Cụm HQbird (RCM). Các công cụ cụm gọi trình quản lý cụm HQbird (hqbirdrcm) trên cùng máy chủ. Chúng chỉ hiện khi fbmcp.yaml có mục rcm: (url, ca_file, user, password_env). Trên máy chủ HQbird Linux, fbmcp ctl hqbird-install ghi mục đó từ /opt/hqbirdrcm/rcm.json và lưu mật khẩu RCM đầu vào bí mật FBMCP_RCM_PASSWORD; nơi khác hãy thêm mục bằng tay (tool-reference.md). Rồi:

  1. fb_cluster_rcm_password: thay mật khẩu RCM đầu tiên (Tier 1).
  2. Cụm mới: mở cửa sổ ghép cặp trên mỗi máy chủ (fb_agent_cluster_pairing), khởi động RCM trên master (fb_agent_cluster_rcm), nối các máy chủ (fb_cluster_link), tạo các replica (fb_cluster_reinit, Tier 2) và so sánh dữ liệu (fb_cluster_verify). Các bước: prompts/cluster-setup.md.
  3. Dịch vụ cụm (switchover, failover, rejoin): fb_cluster_service hiện chúng và các kiểm tra; các bước chuyển là Tier 2. Các bước: prompts/cluster-services.md.

10. Dùng hằng ngày

Hỏi máy khách bằng lời thường; nó chọn công cụ. Ví dụ:

Việc Công cụ
Mọi thứ đã chạy chưa? fb_ping, fb_db_list, fb_db_health, fb_service_status
Đọc dữ liệu fb_query (chỉ đọc, các dòng + kế hoạch + thống kê từng bảng; một lưới trong máy khách MCP-Apps); kiểm tra bản nháp bằng fb_query_check
Phiên, giao dịch dài fb_sessions, fb_transactions, fb_session_kill (Tier 1)
Truy vấn chậm fb_analyze_query, fb_index_advice → áp dụng bằng fb_write; fb_agent_perf_report
Sao lưu fb_backup_start → mã việc → fb_job_status
Kiểm chứng bản sao lưu fb_restore_test (khôi phục vào work_dir, đánh dấu bản sao lưu đã kiểm chứng)
Sao lưu ban đêm + kiểm chứng fb_schedule_create với target=nightly_verify (xác nhận một lần; phương án B hoặc C)
Lược đồ / DDL fb_schema_list, fb_describe, fb_write (mỗi câu được phân loại và gán Tier), fb_diff_schema
Di trú fb_migration_status, fb_migration_plan, fb_migration_apply
Cấu hình máy chủ fb_config_get, fb_config_diff, fb_config_set (Tier 2)
Nhật ký fb_firebird_log
Dung lượng fb_trends, fb_gstat, fb_index_stats
Trạng thái cụm fb_cluster_status, fb_cluster_service
Chuyển master fb_cluster_switchover (không mất dữ liệu) hoặc fb_cluster_failover (mất master), rồi fb_cluster_rejoin (Tier 2)

Các việc chạy bất đồng bộ: gửi → fb_job_status. Các việc trên một cơ sở dữ liệu chạy từng cái một. Một việc sống sót sau lần khởi động lại fbmcp chỉ ở dạng interrupted: gửi lại nếu vẫn cần.

fb_config_set chỉ đổi dòng của chính nó trong firebird.conf (chú thích, thụt lề và ký tự cuối dòng giữ nguyên), giữ tệp cũ dưới dạng firebird.conf.prev, và không bao giờ khởi động lại Firebird. Khởi động lại bằng fb_service_restart (Tier 2): nó chờ đến khi dịch vụ đã dừng và chạy lại.

11. Việc của người vận hành

Việc Lệnh
Liệt kê / phê duyệt / từ chối yêu cầu fbmcpctl approve; fbmcpctl approve <id>; fbmcpctl approve --deny <id> --reason "..." (hoặc khay)
Xoay khóa fbmcpctl apikey rotate alice --config <fbmcp.yaml> (khóa cũ ngừng trong vài giây)
Liệt kê khóa fbmcpctl apikey list (tên, nguồn, Tier; không bao giờ giá trị)
Gỡ một người xóa mục identities:, rồi fbmcpctl secret drop --dir <dir> NAME
Gia hạn chứng chỉ fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ... (pin không đổi, không khởi động lại)
Kiểm tra chuỗi kiểm toán fbmcpctl verify
Nhân còn sống không? fbmcpctl ping; fbmcpctl status (đọc trạng thái ngoại tuyến)
Cho phép điều khiển dịch vụ packaging/posture/verify.ps1 hoặc verify.sh, rồi fbmcpctl setup --write-posture
Nâng cấp dừng dịch vụ (hoặc các máy khách), thay tệp nhị phân, khởi động, doctor
Gỡ bỏ Windows: sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote. Linux: remote.md §10. Giữ thư mục trạng thái (kiểm toán) trừ khi chủ sở hữu nói khác

Chỉ máy chủ phát triển: .\packaging\rebuild-install.ps1 -Force biên dịch lại dist\, dừng và thay các tệp nhị phân đang chạy (bản cũ giữ thành *.exe~), gộp cấu hình máy khách và chạy doctor.

12. Phục hồi sau sự cố và khởi động lại

Đã kiểm chứng bằng bộ thử chaos (internal/killharness).

Sau sự cố hoặc bị diệt Khi khởi động lại Việc của người vận hành
Việc đang chạy hoặc đang xếp hàng Đánh dấu interrupted; không bao giờ tiếp tục Gửi lại nếu cần
Yêu cầu đang chờ, chưa xác nhận Khôi phục từ state.json (TTL vẫn áp dụng) Xác nhận hoặc để hết hạn
fb_restore_replace đang chạy Hoàn tất: khôi phục, kiểm định, cơ sở dữ liệu trực tuyến; giữ <db>.pre-restore Kiểm tra fb_db_health; xóa .pre-restore sau
fb_shutdown_window đang chạy Hoàn tất bước gfix -online Kiểm tra đã trực tuyến
instance.lock cũ Được tiếp quản tự động Không
state.json hỏng Nhân từ chối khởi động; bản sao giữ thành state.json.corrupt-<ts> Xem xét; sửa hoặc cố ý xóa state.json (fbmcpctl repair dựng lại quyền lịch từ kiểm toán)
audit.jsonl hỏng hoặc bị cắt Nhân từ chối khởi động §13.2: coi đó là tín hiệu bị can thiệp
Đồng hồ bị lùi Bộ lập lịch bỏ qua; không chạy hai lần Không
Tiến trình dịch vụ Windows bị diệt SCM khởi động lại sau khoảng 5 s Không

Nhân thất bại ở trạng thái đóng với mọi thứ nó không chứng minh được còn nguyên. Vòng khởi động lại là một phát hiện: hãy đọc nhật ký.

13. Quy trình sự cố

13.1 Có gì đó không ổn với một cơ sở dữ liệu

  1. fbmcpctl doctor --config <file>: cấu hình, bí mật, đăng nhập Firebird, thư mục, posture, lịch. Mỗi dòng FAIL có một Fix:.
  2. fb_db_list → fb_db_health <db>; fb_service_status cho instance.
  3. fb_sessions, fb_transactions cho sự cố attachment hoặc khoảng OAT; fb_firebird_log cho lỗi engine.

13.2 Nghi ngờ bị can thiệp hoặc hỏng: kiểm toán trước

  1. fbmcpctl verify --config <file> → audit chain OK: N entries hoặc BROKEN kèm lý do.
  2. Nếu thất bại: giữ toàn bộ thư mục trạng thái (đó là chứng cứ), rồi điều tra. Đừng xóa audit.jsonl để ép nhân khởi động.

13.3 Diễn tập khôi phục (mỗi quý)

  1. fb_backup_start → fb_job_status = succeeded.
  2. fb_restore_test → bản sao lưu đã được kiểm chứng.
  3. fb_window_open cho cơ sở dữ liệu.
  4. fb_restore_replace → phê duyệt ngoài kênh. Gián đoạn cho đến khi trực tuyến.
  5. Kiểm tra: fb_db_health, rồi một lần đọc thật (fb_schema_list, fb_info).
  6. Tệp cũ giữ nguyên dạng <db>.pre-restore cho đến khi bạn xóa.

13.4 Máy khách không kết nối được

  1. fbmcpctl ping --config <file>, fbmcpctl status --config <file>.
  2. Đọc nhật ký MCP của máy khách (stdio) hoặc <state_dir>\fbmcp.log / journalctl -u fbmcp (dịch vụ).
  3. “another fbmcp instance is active”: một nhân mỗi thư mục trạng thái. Máy khách qua ống tự gắn; nhân thứ hai thất bại ngay theo thiết kế.

Trong các lệnh trên bạn có thể bỏ --config khi việc tìm ở §4 thấy tệp.

14. Khắc phục sự cố

Triệu chứng Ý nghĩa / cách sửa
Công cụ không xuất hiện Cú pháp JSON, đường dẫn tuyệt đối, khởi động lại toàn bộ máy khách; nhật ký MCP của máy khách
Một công cụ thiếu trong danh sách Ẩn có chủ đích (§1): trên Tier tối đa của bạn, không có mục agents:, không có migrations_dir, hoặc không có mục rcm:
Máy chủ thoát ngay fbmcpctl doctor; thiếu một bí mật; dịch vụ không đọc được móc khóa của bạn (dùng secrets.dir)
Tier 2 “confirmation rejected: channel policy” Đúng như dự kiến trong cuộc trò chuyện. Phê duyệt trong khay hoặc bằng fbmcpctl approve
Tier 2 “no open maintenance window” fb_window_open cho cùng db mà bạn truyền cho công cụ
fb_restore_replace bị từ chối: điều kiện tiên quyết Cần bản sao lưu đã kiểm chứng mới hơn 24 h: fb_backup_start + fb_restore_test, và một cửa sổ
Điều khiển dịch vụ bị từ chối Thiếu posture.verified (fbmcpctl setup --write-posture) hoặc tài khoản không có quyền trên dịch vụ Firebird
fb_config_set: không ghi được Tài khoản có thể không được đổi tệp đó (unit Linux ProtectSystem=strict; ACL Windows). Sửa bằng tay, hoặc xem remote.md §8
Khay không hiện gì Nó chỉ hiện yêu cầu cần người vận hành; kiểm tra quyền của người dùng khay trên thư mục trạng thái và tray.log ở đó
401 (từ xa) Sai khóa, hoặc máy chủ chưa nạp khóa: apikey list, doctor --remote
403 (từ xa) IP nguồn không nằm trong allow_from / tường lửa, hoặc tiêu đề Origin không nằm trong allowed_origins
429 (từ xa) Giới hạn; chờ Retry-After
Pin không khớp Khóa máy chủ đã đổi; lấy pin mới từ quản trị viên máy chủ
agent-unreachable Dịch vụ tác nhân tắt, local_api.enabled: false, hoặc sai base_url (mặc định 127.0.0.1:(10000 + firebird port))
agent-auth Token đã lưu không phải local_api.token của tác nhân; đặt lại
agent-timeout khi khởi động lại agents[].timeout_seconds (130) phải lớn hơn restart_timeout_seconds của tác nhân (120)
Error loading plugin MySQLEngine … khi gắn Trên HQbird điều này thường có nghĩa tệp cơ sở dữ liệu không tồn tại; hãy kiểm tra đường dẫn
DROP INDEX trần trong fb_write cần một cửa sổ Ở đó nó là Tier 2; dùng fb_index_drop (Tier 1; từ chối chỉ mục ràng buộc)
Chỉ mục mới không được dùng Chạy thống kê (fb_index_rebuild action=statistics); ORDER BY … DESC cần chỉ mục DESCENDING
Công cụ lỗi chỉ với một cơ sở dữ liệu Nó ngoại tuyến (fb_db_health); công cụ suy giảm theo từng cơ sở dữ liệu

15. Tham chiếu thư mục trạng thái

Đường dẫn Ý nghĩa
state.json (+ .tmp, .corrupt-*) Yêu cầu đang chờ, việc, danh mục sao lưu, luồng công việc, lịch. Hỏng ⇒ từ chối khởi động
audit.jsonl (+ .head) Nhật ký kiểm toán xâu chuỗi bằng hàm băm; .head phát hiện bị cắt cụt
events.jsonl Sự kiện việc (job.succeeded, job.failed kèm thông báo)
approvals\, denials\ Quyết định ngoài kênh (khay / fbmcpctl approve), dùng trong khoảng ~2 s
instance.lock Khóa một nhân
attach.addr, attach.token Điểm cuối gắn cho máy khách stdio thêm
fbmcp.log, fbmcp-crash.log Nhật ký dịch vụ (xoay vòng) và đầu ra sự cố
query-log.jsonl Mọi lời gọi fb_query
trends\ Lịch sử bộ lấy mẫu cho fb_trends
config-journal\ Lịch sử fb_config_set (giá trị cũ và mới)
posture.verified Dấu cho phép điều khiển dịch vụ
tray.log Lỗi khay

16. Trạng thái lần đi thử

Đang chờ (M1): một lượt đi xuyên suốt trên máy chủ Windows mới chỉ bằng hướng dẫn này. Phát hiện được đưa trở lại tệp này. Kết quả phòng thí nghiệm cho chế độ từ xa (máy chủ Linux, VM mới, dịch vụ Windows): findings/phase12-lab-2026-11-03.md.