fbmcp:安装与使用
对象是安装并运行 fbmcp 的人。本人并没有构建它。 不需要 Go 或 Firebird 的内部知识。截至 2026-11-16, 版本 2027.2.24(本地与远程模式、HQbird 安装、fbagent 桥接、 HQbird 集群、结果网格)。
不在本站上的简版:quickstart-en.md、quickstart-ru.md、
quickstart-pt.md。详细说明为英文:remote.md(远程模式)、
agent-bridge.md(fbagent)、
tool-reference.md(每个工具及其 Tier 与参数)、
claude-desktop.md(开发主机上的客户端接入)、
ADR 位于 decisions/。
1. fbmcp 是什么
fbmcp 是 Windows 与 Linux 上面向 Firebird 2.5–5.0 的 MCP 服务器。MCP
客户端(Claude Desktop、Claude Code、Cursor、Codex、ZCode 以及其他)用它
以 DBA 的方式工作:监控、备份与已验证的还原、SQL/DDL/DCL、
索引、用户与授权、firebird.conf、调度器、迁移、
HQbird 的 fbagent 以及 HQbird 集群。它有 122 个工具:只读 56 个(Tier 0),Tier 1 为 44 个,
Tier 2 为 21 个,Tier 3 为 1 个(已禁用)。fb_demo_write 只在
服务器以 FBMCP_DEMO_TOOLS=1 运行时存在。
客户端只能看到自己可以使用的工具。工具列表会隐藏:Tier 3、
高于该身份最大 Tier 的工具、只读身份的 fb_confirm 与 fb_cancel、
agents: 为空时的 fbagent 工具
(fb_agent_discover 与 fb_agent_register 仍然保留)、没有任何数据库具有 migrations_dir 时的迁移工具,
以及 fbmcp.yaml 没有 rcm: 节时的集群工具。配置重新加载改变这一
集合时,客户端会收到一份新列表。直接调用被隐藏的工具会得到
明确的拒绝。
| 二进制文件 | 角色 |
|---|---|
fbmcp |
服务器。默认:经 stdio 的 MCP(由客户端启动)。-serve:没有 stdio,作为服务运行(调度器、挂接套接字、若已配置则还有 HTTPS 监听器)。fbmcp bridge:面向远程 fbmcp 的 stdio 客户端 |
fbmcpctl |
操作员 CLI:doctor、approve、secret、apikey、tls、verify、status、ping、setup、repair、hqbird-install、gate。与 fbmcp ctl 是同一个程序 |
fbmcp-tray |
Windows 托盘:对需要操作员处理的请求弹出批准/拒绝 |
每个状态目录有一个 内核。使用同一配置的第二个客户端 不会再启动一个内核:它挂接到正在运行的那个内核。
2. 安全模型
每一次调用都经过:策略 → 人工确认 → 带审计的执行。
| Tier | 内容 | 如何确认 |
|---|---|---|
| 0 | 读取(引擎强制的只读事务) | 不需要 |
| 1 | 日常变更:DML/DDL、备份、用户、授权 | 带内:客户端显示请求 ID 和令牌,人表示同意,客户端调用 fb_confirm |
| 2 | 影响大:服务控制、还原替换、firebird.conf、独占窗口、注册、代理重启 |
仅限带外:托盘或 fbmcpctl approve。客户端永远不能批准 |
| 3 | 关键操作(fb_db_drop) |
按设计禁用 |
- Tier 2 通常需要一个已打开的维护窗口(对同一个
db调用fb_window_open),以及 不足 24 小时的已验证备份。 拒绝信息会说明缺什么。 - 待处理请求在 15 分钟后过期。走错通道的尝试
不会消耗该请求;
fb_cancel会把它去掉。 - 每个受门控的工具都接受
mode: preview:它显示影响,并且 什么都不做。 - 每一项决定(允许、待处理、已批准、已拒绝)都进入
哈希链的
audit.jsonl。 - 没有审批网页,也绝不能有:模型能够打开的页面会 破坏这一设计。
3. 选择一种部署
| 部署 | fbmcp 运行在哪里 | 何时使用 | 节 |
|---|---|---|---|
| A. 本地 stdio | 你的 PC;由客户端启动 | 一名管理员,Firebird 在这台 PC 上或在局域网内 | §6 |
| B. 本地服务 | 数据库主机上的 Windows 服务(-serve) |
没有打开客户端时计划任务也必须运行 | §7 |
| C. 远程 | 数据库服务器上的服务,HTTPS + API 密钥 | 多名管理员、远程服务器、自主代理 | §8 |
在部署 A 中,内核只在客户端运行时存在,因此计划任务也只在那时执行。无人值守的计划任务(nightly_verify)请用 B 或 C。
HQbird 中的 fbmcp。 HQbird 2027 的安装与 fbagent 默认会安装 fbmcp:
一台服务器上的所有 Firebird 产品线共用一个服务,由
fbmcp ctl hqbird-install 完成设置。在这样的服务器上不要按 §6–§8 操作,请阅读
hqbird.md(布局、带 --allow-from 的远程模式、API 密钥)。
4. 获取二进制文件
要求:Go ≥ 1.26.11(更旧的 Go 1.21 及以上会在第一次构建时自行下载 go1.26.11;这需要互联网), 不需要 CGO;Firebird 2.5–5.0;代理工具需要带 Local API 的 fbagent ≥ 2.67 (可选);集群工具需要 fbagent 3.1.0 及以上与 RCM 2027.5.11 及以上 (可选)。
git clone https://github.com/alexeykovyazin/hqbirdmcp.git
cd hqbirdmcp
$env:CGO_ENABLED = "0"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp.exe ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl.exe ./cmd/fbmcpctl
go build -trimpath -ldflags "-s -w -H=windowsgui" -o dist/fbmcp-tray.exe ./cmd/fbmcp-trayLinux 二进制文件(从 Windows 交叉编译,或不设置 GOOS 而在 Linux 上构建):
$env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -trimpath -ldflags "-s -w" -o dist/fbmcp ./cmd/fbmcp
go build -trimpath -ldflags "-s -w" -o dist/fbmcpctl ./cmd/fbmcpctl校验和:Get-FileHash dist/* 或 sha256sum dist/*。更多目标:
packaging/README.md。把二进制文件放进它们自己的文件夹
(示例使用 C:\fbmcp\):mkdir C:\fbmcp; copy dist\*.exe C:\fbmcp\
(Linux:install -m 0755 dist/fbmcp dist/fbmcpctl /usr/local/bin/)。
fbmcp ctl 与 fbmcpctl 是同一个程序。fbmcpctl help 列出
命令。读取配置的命令接受 --config <file>;不给时
依次使用 FBMCP_CONFIG、当前文件夹中的 fbmcp.yaml、程序旁边的文件,然后是
HQbird 默认位置(C:\HQbirdData\fbmcp\fbmcp.yaml、
/etc/fbmcp/fbmcp.yaml),并打印 using config <path>。
5. 配置 fbmcp.yaml
完整示例:packaging/fbmcp.yaml.example。
最小的 Windows 配置:
state:
dir: C:\ProgramData\fbmcp\state
# secrets:
# dir: C:\ProgramData\fbmcp\secrets # setups B and C
instances:
- id: fb5
addr: localhost:3050
bin_dir: C:\Program Files\Firebird\Firebird_5_0 # folder with gbak, gfix, gstat
version: "5.0"
service: FirebirdServerDefaultInstance # Linux: firebird.opt_fb50
service_user: SYSDBA # instance tools (fb_firebird_log, ...)
service_secret_env: FBMCP_FB5_SERVICE_PW
databases:
- id: main # tools and chats use the id, never the path
instance: fb5
path: D:\Data\main.fdb
backup_dir: D:\fbmcp\backups
work_dir: D:\fbmcp\work # restore tests; Linux: not under /tmp
ro_user: FBMCP_RO # a read-only Firebird user
ro_secret_env: FBMCP_MAIN_RO_PW
admin_user: SYSDBA
admin_secret_env: FBMCP_MAIN_ADMIN_PW
notify:
webhook_url: "" # optional: a chat webhook for pending requests
retention:
keep_days: 0 # 0 = never delete backups密钥。 YAML 里只有变量名。fbmcp 按以下顺序查找每个
值:环境变量 → 文件 <secrets.dir>/<NAME> →
运行 fbmcp 的账户的操作系统密钥环。
C:\fbmcp\fbmcpctl.exe secret set FBMCP_MAIN_RO_PW # keyring of the current user (setup A)
C:\fbmcp\fbmcpctl.exe secret set --dir C:\ProgramData\fbmcp\secrets FBMCP_MAIN_RO_PW # secrets dir (setups B, C)值从 stdin 读取(输入后按 Ctrl+Z,再按 Enter;Linux 为 Ctrl+D)。
服务账户(LocalSystem、NT SERVICE\...)看不到你的密钥环:
服务请使用 secrets.dir。更改后的密钥文件在几
秒内生效,无需重启。
只读用户。 为 ro_user 单独创建一个 Firebird 用户(SQL 见
quickstart-en.md:
CREATE USER FBMCP_RO,对每张表 GRANT SELECT,并且在 Firebird 4.0 及以上
创建一个带 MONITOR_ANY_ATTACHMENT 的角色,以便 fb_sessions 看到全部连接)。
把 SYSDBA 当作只读用户仅用于开发;doctor 会对此发出警告。
即时重新加载。 fbmcp 会自行应用对 fbmcp.yaml 的更改(文件
监视),也可以在 fb_config_reload 时应用。客户端和进程都不必重启。重新加载会
等待已更改数据库上的作业(30 秒),然后应用。会被拒绝的情况:
更改 state.dir、重复的数据库路径、不安全的远程配置。
检查: C:\fbmcp\fbmcpctl.exe doctor 必须以 doctor: green 结束
(远程模式:doctor --remote,没有 FAIL 行)。它会创建缺失的状态
文件夹,用两个用户登录每个数据库,并且每一行 FAIL 都以
Fix: 和要运行的命令结束。
6. 部署 A — 本地 stdio
使用绝对路径。不要设置 listen。更改配置后重启客户端:
客户端只在启动时加载服务器。
| 客户端 | 位置 | 条目 |
|---|---|---|
| Claude Desktop | Settings → Developer → Edit Config(%APPDATA%\Claude\claude_desktop_config.json) |
"mcpServers": {"fbmcp": {"command": "C:\\fbmcp\\fbmcp.exe", "args": ["-config", "C:\\fbmcp\\fbmcp.yaml"]}} |
| Claude Code | 命令行 | claude mcp add --transport stdio fbmcp -- "C:\fbmcp\fbmcp.exe" -config "C:\fbmcp\fbmcp.yaml" |
| Cursor | %USERPROFILE%\.cursor\mcp.json,或项目中的 .cursor\mcp.json |
与 Claude Desktop 相同的 JSON |
| Codex | codex mcp add fbmcp -- C:\fbmcp\fbmcp.exe -config C:\fbmcp\fbmcp.yaml,或 %USERPROFILE%\.codex\config.toml |
[mcp_servers.fbmcp] command = 'C:\fbmcp\fbmcp.exe' args = ["-config", 'C:\fbmcp\fbmcp.yaml'] |
| ZCode | 项目中的 .zcode\config.json |
"mcp": {"servers": {"fbmcp": { ...same command and args... }}} |
密码在密钥环中(§5),因此不需要 env 块。如果仍然把
密码放进客户端的 env 块,请让该文件留在 git 之外。
然后启动托盘,以便批准 Tier 2:
C:\fbmcp\fbmcp-tray.exe C:\fbmcp\fbmcp.yaml(每次登录时:
.\packaging\windows\install-tray.ps1 -Bin C:\fbmcp\fbmcp-tray.exe -Config C:\fbmcp\fbmcp.yaml)。
在客户端做冒烟测试:「调用 fb_ping」(显示服务器名称以及你的
身份及其最大 Tier),然后「fb_db_list」,然后「对 main 调用 fb_db_health」。
7. 部署 B — 本地 Windows 服务
以管理员身份打开的 PowerShell:
.\packaging\windows\install-service.ps1 -Bin C:\fbmcp\fbmcp.exe -Config C:\fbmcp\fbmcp.yaml
sc.exe start fbmcp- 服务以 LocalSystem 运行
fbmcp -serve,失败后会重启, 并在服务停止时干净地停止。 - 密码使用
secrets.dir(§5)。 - 锁定文件夹:只有 SYSTEM 和 Administrators 可以写入
C:\fbmcp(脚本会打印icacls命令)。在C:\下创建的文件夹会让 每个用户都能更改文件,而服务会以 SYSTEM 身份运行这些文件。 - 托盘用户和本地 stdio 客户端需要对状态目录有读写权限:
icacls C:\ProgramData\fbmcp\state /grant "<user>:(OI)(CI)M"。使用同一配置的 stdio 客户端随后会挂接到服务的内核。 - 就绪检查:
C:\fbmcp\fbmcpctl.exe ping --config C:\fbmcp\fbmcp.yaml。 - 日志:
<state_dir>\fbmcp.log(5 × 10 MiB;崩溃写入fbmcp-crash.log)。
管理员要通过网络访问的服务,请改用部署 C。
8. 部署 C — 远程(HTTPS + API 密钥)
完整步骤:remote.md。简要形式:
Windows 服务器(提升权限):
- 把二进制文件和
fbmcp.yaml放在C:\fbmcp\(模板:remote.md §3:listen、tls、identities、allowed_origins、secrets.dir)。 C:\fbmcp\fbmcpctl.exe tls selfsign --out C:\fbmcp\tls --dns srv1 --ip 10.0.0.5 --grant "NT SERVICE\fbmcp"— 记下 pinsha256:...。- 每个人员或代理一把密钥:
C:\fbmcp\fbmcpctl.exe apikey new alice --max-tier 2 --secrets-dir C:\ProgramData\fbmcp\secrets(只打印一次)。加上--config C:\fbmcp\fbmcp.yaml时,还会添加identities:条目并使用secrets.dir。 - 密码与代理令牌:
fbmcpctl secret set --dir C:\ProgramData\fbmcp\secrets NAME。 .\packaging\windows\install-remote.ps1 -Port 8443 -AllowFrom 10.0.0.0/24 -FirebirdService FirebirdServerDefaultInstance -WhatIf,然后再去掉-WhatIf执行。它会创建服务、防火墙规则、文件夹 ACL 和 Firebird 服务权限。C:\fbmcp\fbmcpctl.exe doctor --remote --config C:\fbmcp\fbmcp.yaml→ 没有 FAIL;curl.exe --cacert C:\fbmcp\tls\tls.crt https://srv1:8443/healthz→ok。- 批准者的托盘:
.\packaging\windows\install-tray.ps1。
Linux 服务器(root):复制 fbmcp、fbmcpctl 和 packaging/linux/,然后
install -m 0755 fbmcp fbmcpctl /usr/local/bin/
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24 --dry-run
sh packaging/linux/install-remote.sh --user firebird --port 8443 --allow-from 10.0.0.0/24脚本会创建文件夹、证书、带 admin 密钥的初始配置
(只打印一次)、systemd 单元、Firebird 单元的 sudo 规则
和 ufw 规则,然后运行 doctor --remote。把
databases: 和 agents: 加到 /etc/fbmcp/fbmcp.yaml。Linux 上的批准
(没有托盘):sudo -u firebird fbmcpctl approve [id]。它会自己找到
/etc/fbmcp/fbmcp.yaml,询问 y/N(--yes 则不询问),
--deny <id> --reason "..." 表示拒绝。
管理员 PC:
C:\fbmcp\fbmcpctl.exe secret set FBMCP_KEY_SRV1(你拿到的密钥)。- 任意 stdio 客户端(Claude Desktop、Cursor、Codex、ZCode):使用 §6 的条目,
并把
args设为:["bridge", "--url", "https://srv1:8443/mcp", "--key-env", "FBMCP_KEY_SRV1", "--pin", "sha256:<hex>"]。 pin 用来核对服务器密钥,因此自签名证书不需要配置 CA。 - Claude Code 也可以直接通过 HTTP 连接(
.mcp.json中"type": "http",请求头Authorization: Bearer ${FBMCP_KEY_SRV1}, 自签名证书使用NODE_EXTRA_CA_CERTS)。不要用claude mcp add --header传递密钥:它会以明文保存。 - 测试:
fb_ping会显示服务器名称和你的身份。
自主代理(OpenClaw 及类似系统):用
apikey new openclaw-1 --profile autonomous --allow-from 10.0.0.21/32 单独建一把密钥。
默认为只读;每个 Tier 1 请求都要等待操作员,
来自该代理的 fb_confirm 会被拒绝。限制:remote.md §6–7。
9. fbagent 桥接与 HQbird 集群(可选)
代理工具(fb_agent_status、fb_agent_job_run、……)使用同一台主机上 HQbird
fbagent 的 Local API。
在 agents: 有条目之前,它们是关闭的。
- 在客户端中:「
fb_agent_discover」。它列出本地代理,并给出base_url、instance_id和建议的令牌名。它从不 读取令牌。 - 操作员保存该代理的
local_api.token(不是agent.auth_token):fbmcpctl secret set [--dir <secrets.dir>] FBMCP_AGENT_TOKEN_P<port>。 不要把令牌输入到聊天里。 - 在客户端中:「对该代理执行
fb_agent_register」→ 在托盘中批准。 fbmcp 添加agents:条目,重新加载并检查身份。 - 测试:
fb_agent_status、fb_agent_instances。
fb_agent_config_set(更改作业设置:备份、sweep、……)还需要条目上的
config_path、对正在使用的 agent_config.json 的读取权限,
以及对其文件夹的创建权限。该文件里有令牌和 Firebird
凭据,因此是否授予这一权限由操作员决定
(agent-bridge.md)。代理检查失败时,该工具
不会写入任何内容。
HQbird 集群(RCM)。集群工具调用同一台主机上的 HQbird 集群
管理器(hqbirdrcm)。只有当
fbmcp.yaml 含有 rcm: 节(url、ca_file、user、
password_env)时才会显示。在 Linux 的 HQbird 服务器上,fbmcp ctl hqbird-install 会
根据 /opt/hqbirdrcm/rcm.json 写入该节,并把第一个 RCM 密码存入
密钥 FBMCP_RCM_PASSWORD;其他环境请手工添加该节
(tool-reference.md)。然后:
fb_cluster_rcm_password:更换第一个 RCM 密码(Tier 1)。- 新建集群:在每台主机上打开配对窗口
(
fb_agent_cluster_pairing),在主节点上启动 RCM (fb_agent_cluster_rcm),连接各主机(fb_cluster_link),建立副本 (fb_cluster_reinit,Tier 2),并比较数据 (fb_cluster_verify)。步骤:prompts/cluster-setup.md。 - 集群服务(switchover、failover、重新加入):
fb_cluster_service显示这些服务和检查项;这些移动操作是 Tier 2。 步骤:prompts/cluster-services.md。
10. 日常使用
用普通的话吩咐客户端,由它选择工具。例如:
| 任务 | 工具 |
|---|---|
| 是否都在运行 | fb_ping、fb_db_list、fb_db_health、fb_service_status |
| 读取数据 | fb_query(只读,行 + 计划 + 每表统计;在 MCP-Apps 客户端中为网格);用 fb_query_check 检查草稿 |
| 会话、长事务 | fb_sessions、fb_transactions、fb_session_kill(Tier 1) |
| 慢查询 | fb_analyze_query、fb_index_advice → 用 fb_write 应用;fb_agent_perf_report |
| 备份 | fb_backup_start → 作业 ID → fb_job_status |
| 验证备份 | fb_restore_test(还原到 work_dir,并把该备份标为已验证) |
| 每晚备份 + 验证 | 带 target=nightly_verify 的 fb_schedule_create(只需确认一次;部署 B 或 C) |
| 模式 / DDL | fb_schema_list、fb_describe、fb_write(每条语句都会被分类并定级)、fb_diff_schema |
| 迁移 | fb_migration_status、fb_migration_plan、fb_migration_apply |
| 服务器配置 | fb_config_get、fb_config_diff、fb_config_set(Tier 2) |
| 日志 | fb_firebird_log |
| 容量 | fb_trends、fb_gstat、fb_index_stats |
| 集群状态 | fb_cluster_status、fb_cluster_service |
| 移动主节点 | fb_cluster_switchover(不丢数据)或 fb_cluster_failover(主节点已丢失),然后 fb_cluster_rejoin(Tier 2) |
作业是异步的:提交 → fb_job_status。同一个数据库上的作业一次只
运行一个。作业在 fbmcp 重启之后只会以 interrupted 留下:如果仍然需要,
请再次提交。
fb_config_set 只改 firebird.conf 里它自己的那一行(注释、
缩进和行尾保持不变),把旧文件保留为 firebird.conf.prev,
并且从不会重启 Firebird。重启请用 fb_service_restart(Tier 2):它会
一直等到服务停止并再次运行。
11. 运维操作
| 任务 | 命令 |
|---|---|
| 列出 / 批准 / 拒绝请求 | fbmcpctl approve;fbmcpctl approve <id>;fbmcpctl approve --deny <id> --reason "..."(或使用托盘) |
| 轮换密钥 | fbmcpctl apikey rotate alice --config <fbmcp.yaml>(旧密钥在数秒内失效) |
| 列出密钥 | fbmcpctl apikey list(名称、来源、Tier;从不显示值) |
| 移除一个人 | 删除 identities: 条目,然后 fbmcpctl secret drop --dir <dir> NAME |
| 续订证书 | fbmcpctl tls selfsign --renew --out <dir> --dns ... --ip ...(pin 不变,无需重启) |
| 检查审计链 | fbmcpctl verify |
| 内核是否存活 | fbmcpctl ping;fbmcpctl status(离线读取状态) |
| 允许服务控制 | packaging/posture/verify.ps1 或 verify.sh,然后 fbmcpctl setup --write-posture |
| 升级 | 停止服务(或客户端),替换二进制文件,启动,运行 doctor |
| 移除 | Windows:sc.exe stop fbmcp; sc.exe delete fbmcp; Remove-NetFirewallRule -DisplayName fbmcp-remote。Linux:remote.md §10。除非所有者另有说明,否则保留状态目录(审计) |
仅开发主机:.\packaging\rebuild-install.ps1 -Force 会重新构建 dist\,
停止并替换正在运行的二进制文件(旧文件保留为 *.exe~),
合并客户端配置并运行 doctor。
12. 崩溃与重启恢复
已由混沌测试套件(internal/killharness)验证。
| 崩溃或被强行终止之后 | 重启时 | 操作员动作 |
|---|---|---|
| 作业正在运行或在队列中 | 标为 interrupted;不会继续执行 |
如果需要,再次提交 |
| 待处理请求,尚未确认 | 从 state.json 恢复(TTL 仍然有效) |
确认,或让它过期 |
fb_restore_replace 进行中 |
会完成:还原、校验、数据库恢复在线;保留 <db>.pre-restore |
检查 fb_db_health;稍后删除 .pre-restore |
fb_shutdown_window 进行中 |
完成 gfix -online 这一步 |
检查是否在线 |
过期的 instance.lock |
自动接管 | 无 |
state.json 损坏 |
内核拒绝启动;副本保留为 state.json.corrupt-<ts> |
检查;有意修复或删除 state.json(fbmcpctl repair 根据审计重建计划任务的授权) |
audit.jsonl 损坏或被截断 |
内核拒绝启动 | §13.2:把它当作篡改信号 |
| 时钟被回拨 | 调度器跳过;不会重复执行 | 无 |
| Windows 服务进程被强行终止 | SCM 大约在 5 秒内重启它 | 无 |
内核对其无法证明完好的内容失败关闭。重启 循环本身就是一条发现:请阅读日志。
13. 事故处理
13.1 数据库出了问题
fbmcpctl doctor --config <file>:配置、密钥、Firebird 登录、 文件夹、态势、计划任务。每一行 FAIL 都有Fix:。fb_db_list→fb_db_health <db>;对该实例使用fb_service_status。- 连接或 OAT 间隙问题用
fb_sessions、fb_transactions; 引擎错误用fb_firebird_log。
13.2 怀疑被篡改或损坏:先查审计
fbmcpctl verify --config <file>→audit chain OK: N entries,或带原因的BROKEN。- 如果失败:保留整个状态目录(它就是证据),然后
调查。不要为了让内核启动而删除
audit.jsonl。
13.3 还原演练(每季度)
fb_backup_start→fb_job_status= succeeded。fb_restore_test→ 该备份已验证。- 对该数据库执行
fb_window_open。 fb_restore_replace→ 带外批准。在恢复在线之前会有停机。- 检查:
fb_db_health,然后做一次真正的读取(fb_schema_list、fb_info)。 - 旧文件会以
<db>.pre-restore保留,直到你删除它。
13.4 客户端无法连接
fbmcpctl ping --config <file>、fbmcpctl status --config <file>。- 阅读客户端的 MCP 日志(stdio),或
<state_dir>\fbmcp.log/journalctl -u fbmcp(服务)。 - “another fbmcp instance is active”:每个状态目录一个内核。经管道启动的 客户端会自行挂接;第二个内核迅速失败是设计如此。
在上面的命令中,当 §4 的查找能找到该文件时,
可以省略 --config。
14. 故障排查
| 症状 | 含义 / 处理 |
|---|---|
| 工具不出现 | JSON 语法、绝对路径、完全重启客户端;查看客户端的 MCP 日志 |
| 列表里缺一个工具 | 有意隐藏(§1):高于你的最大 Tier、没有 agents: 条目、没有 migrations_dir,或没有 rcm: 节 |
| 服务器立刻退出 | fbmcpctl doctor;缺少密钥;服务读不到你的密钥环(使用 secrets.dir) |
| Tier 2 “confirmation rejected: channel policy” | 在聊天里出现是预期行为。请在托盘中或用 fbmcpctl approve 批准 |
| Tier 2 “no open maintenance window” | 对你传给该工具的同一个 db 执行 fb_window_open |
fb_restore_replace 被拒绝:前置条件 |
需要一份不足 24 小时的已验证备份:fb_backup_start + fb_restore_test,以及一个窗口 |
| 服务控制被拒绝 | 缺少 posture.verified(fbmcpctl setup --write-posture),或该账户对 Firebird 服务没有权限 |
fb_config_set:无法写入 |
该账户可能不能修改那个文件(Linux 单元 ProtectSystem=strict;Windows ACL)。手工编辑,或参见 remote.md §8 |
| 托盘什么都不显示 | 它只显示需要操作员处理的请求;检查托盘用户对状态目录的权限,以及那里的 tray.log |
| 401(远程) | 密钥错误,或服务器没有加载它:apikey list、doctor --remote |
| 403(远程) | 源 IP 不在 allow_from / 防火墙中,或 Origin 头不在 allowed_origins 中 |
| 429(远程) | 达到限制;等待 Retry-After |
| pin 不匹配 | 服务器密钥已变更;向服务器管理员索取新的 pin |
agent-unreachable |
代理服务未运行、local_api.enabled: false,或 base_url 不正确(默认 127.0.0.1:(10000 + firebird port)) |
agent-auth |
存下的令牌不是该代理的 local_api.token;请重新设置 |
重启时 agent-timeout |
agents[].timeout_seconds(130)必须大于该代理的 restart_timeout_seconds(120) |
挂接时出现 Error loading plugin MySQLEngine … |
在 HQbird 上,这通常表示数据库文件不存在;请检查路径 |
fb_write 中单独的 DROP INDEX 需要窗口 |
在那里它是 Tier 2;请用 fb_index_drop(Tier 1;会拒绝约束索引) |
| 新索引未被使用 | 运行统计(fb_index_rebuild action=statistics);ORDER BY … DESC 需要 DESCENDING 索引 |
| 工具只在一个数据库上失败 | 它处于离线状态(fb_db_health);工具按数据库降级 |
15. 状态目录参考
| 路径 | 含义 |
|---|---|
state.json(+ .tmp、.corrupt-*) |
待处理请求、作业、备份清单、工作流、计划任务。损坏 ⇒ 拒绝启动 |
audit.jsonl(+ .head) |
哈希链审计日志;.head 用于检测截断 |
events.jsonl |
作业事件(带消息的 job.succeeded、job.failed) |
approvals\、denials\ |
带外决定(托盘 / fbmcpctl approve),约在 2 秒内被使用 |
instance.lock |
单内核锁 |
attach.addr、attach.token |
供额外 stdio 客户端挂接的端点 |
fbmcp.log、fbmcp-crash.log |
服务日志(会轮转)和崩溃输出 |
query-log.jsonl |
每一次 fb_query 调用 |
trends\ |
fb_trends 的采样历史 |
config-journal\ |
fb_config_set 的历史(旧值与新值) |
posture.verified |
允许服务控制的标记 |
tray.log |
托盘错误 |
16. 演练进度
待完成(M1):只用本指南、在一台全新 Windows 主机上做的演练。
发现会写回本文件。远程模式的实验记录(Linux 主机、
全新虚拟机、Windows 服务):findings/phase12-lab-2026-11-03.md。