fbmcp: cài đặt và sử dụng
Đố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ùngdb) 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_cancelgỡ 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.jsonlxâ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).
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-trayTệ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):
$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/fbmcpctlGiá 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:
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 backupsBí 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.
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:
.\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 -servedưới LocalSystem, khởi động lại khi lỗi, và dừng sạch khi dịch vụ dừng. - Dùng
secrets.dircho mật khẩu (§5). - Khóa thư mục: chỉ SYSTEM và Administrators được ghi vào
C:\fbmcp(script in lệnhicacls). Thư mục tạo dướiC:\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ố trongfbmcp-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):
- Tệp nhị phân và
fbmcp.yamltrongC:\fbmcp\(mẫu: 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"— ghi lại pinsha256:....- 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.yamlnó cũng thêm mụcidentities:và dùngsecrets.dir. - Mật khẩu và token của tác nhân:
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, 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.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.- 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
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/24Script 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ị:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(khóa bạn đã nhận).- Bất kỳ máy khách stdio nào (Claude Desktop, Cursor, Codex, ZCode): mục ở §6
với các
argsnà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. - 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_CERTScho chứng chỉ tự ký). Đừng truyền khóa bằngclaude mcp add --header: nó được lưu dạng văn bản thuần. - Thử:
fb_pinghiệ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.
- Trong máy khách: “
fb_agent_discover”. Nó liệt kê các tác nhân cục bộ vớibase_url,instance_idvà tên token gợi ý. Không bao giờ đọc token. - Người vận hành lưu
local_api.tokencủa tác nhân (không phảiagent.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. - Trong máy khách: “
fb_agent_registercho tác nhân đó” → phê duyệt trong khay. fbmcp thêm mụcagents:, tải lại và kiểm tra danh tính. - 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:
fb_cluster_rcm_password: thay mật khẩu RCM đầu tiên (Tier 1).- 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. - Dịch vụ cụm (switchover, failover, rejoin):
fb_cluster_servicehiệ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
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ộtFix:.fb_db_list→fb_db_health <db>;fb_service_statuscho instance.fb_sessions,fb_transactionscho sự cố attachment hoặc khoảng OAT;fb_firebird_logcho lỗi engine.
13.2 Nghi ngờ bị can thiệp hoặc hỏng: kiểm toán trước
fbmcpctl verify --config <file>→audit chain OK: N entrieshoặcBROKENkèm lý do.- 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ý)
fb_backup_start→fb_job_status= succeeded.fb_restore_test→ bản sao lưu đã được kiểm chứng.fb_window_opencho cơ sở dữ liệu.fb_restore_replace→ phê duyệt ngoài kênh. Gián đoạn cho đến khi trực tuyến.- Kiểm tra:
fb_db_health, rồi một lần đọc thật (fb_schema_list,fb_info). - Tệp cũ giữ nguyên dạng
<db>.pre-restorecho đến khi bạn xóa.
13.4 Máy khách không kết nối được
fbmcpctl ping --config <file>,fbmcpctl status --config <file>.- Đọc nhật ký MCP của máy khách (stdio) hoặc
<state_dir>\fbmcp.log/journalctl -u fbmcp(dịch vụ). - “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.