MCP 服务器¶
BombVault 内置了模型上下文协议(MCP)服务器,Claude Code 和 Claude Desktop 这类 AI 助手用这个协议来访问外部工具。通过它,助手可以读取你的备份进展如何,并且在你允许时启动备份,或取消它自己启动的备份。在你创建密钥或开启通过 OAuth 登录之前它是关闭的:在那之前,端点 /mcp 对一切请求都返回 404。
助手能做什么、不能做什么¶
| 工具 | 作用 | 类型 |
|---|---|---|
get_health |
版本、实例名称、是否有备份在运行,以及这个密钥可以做什么 | 读取 |
get_status |
每个领域的保护状态:上次成功备份、预期间隔、验证和异地检查、接下来的计划运行、在等应用空闲的备份,以及容器最新的启动测试 | 读取 |
get_coverage |
BombVault 保护什么、不保护什么,并写明每一项的原因 | 读取 |
list_items |
每个受保护的容器、虚拟机、文件夹集、闪存和应用配置,带它的计划、对它做备份会停止什么、上次备份以及用了多久。数据库容器还带有上次转储。ZFS 数据集也会列出,带上次检查的结果。每个条目都带上次恢复检查,容器还带上次启动测试,或为什么无法测试。自上次备份以来用其他设置重新创建的容器,会列出变了什么 | 读取 |
list_runs |
运行历史,最新的在前,可以按领域、条目、状态、种类和时间筛选。被某一样东西拖慢的备份会点明是什么 | 读取 |
list_restore_points |
一个条目在其主仓库中的恢复点,容器还包括它的数据库转储。ZFS 数据集每次备份有一个恢复点,其下每个数据集都有一个快照 | 读取 |
get_activity |
现在正在运行的内容,带阶段和百分比 | 读取 |
get_storage_stats |
一个领域主仓库的大小历史及每周增长,以及它的每个仓库所在磁盘或远端的已用、可用和总空间 | 读取 |
get_size_breakdown |
一个容器、虚拟机或文件夹集的最新备份里,哪些文件夹和文件占用空间,以及最近一次备份为每一项增加了多少 | 读取 |
search_files |
在所有条目、某一个领域或某一个条目的备份里按名称查找文件和文件夹(不搜索虚拟机),并为每个结果列出包含它的所有备份 | 读取 |
list_anomalies |
BombVault 在备份中发现的异常,可以按状态、严重程度和领域筛选,附带未处理内容的摘要 | 读取 |
get_anomaly |
其中一条发现,附带确认时留下的备注 | 读取 |
start_backup |
立即备份一个条目 | 启动 |
start_domain_backup |
备份一个领域的所有受保护条目 | 启动 |
start_backup_everything |
运行全部备份这一轮 | 启动 |
cancel_backup |
取消这个密钥启动的、正在运行的备份 | 取消 |
下面这些仍然只在网页界面里进行:任何种类的恢复(包括下载、保存或导入数据库转储)、删除备份、清理、解锁、检查和演练、异地复制、设置、登录凭据和 MCP 密钥,以及取消由计划、网页界面或另一个密钥启动的备份。确认异常或把它标记为预期之内也是一样,这在异常页面上进行。原因是工具的输出里包含来自你服务器的名称和错误信息,其中任何一个都可能带着专门用来引导助手的文字。被这种文字骗到的助手,最坏也只能在下面的限制之内启动一次备份,或取消它自己启动的备份。
如果条目的主仓库是远程的(S3、REST、SFTP、rclone),list_restore_points 会去连接它,所以这个调用可能要花一点时间。异地副本无法通过 MCP 列出。search_files 只有在助手要求时才会读取远程仓库,包括异地副本,因为这样更慢,而且有些服务商会按下载的数据收费。一次搜索可能要几分钟,所以第一次调用会在后台开始搜索,之后的某次调用再取回结果。异常检查看什么,参见异常,ZFS 条目如何为每个数据集保留一个快照,参见 ZFS 数据集。
启动的备份会做什么¶
助手启动的备份和网页界面启动的备份是同一种。运行中的容器会被停止,直到它的备份完成,设为随它一起停止的容器也一样。使用正常关机方式的虚拟机会被关机再启动。ZFS 数据集会在拍快照期间停止为它设定的容器。文件夹集、闪存和配置会继续运行。之后 BombVault 应用保留策略,并可能复制到异地仓库。list_items 会告诉助手一个条目会停止什么,以及它上次备份用了多久,工具描述也要求它在启动任何东西之前先告诉你。
因为备份会停止东西,并把旧的恢复点轮换出去,所以通过 MCP 的启动是受限的:
- 每个密钥每小时最多启动 12 次备份。
- 同一个条目、领域或全部备份,两次 MCP 启动之间隔 15 分钟。
- 同一个条目 24 小时内最多通过 MCP 启动 4 次。
- 保留保护。 当一个领域保留固定数量的恢复点(只有"保留最近 N 个",没有每日、每周或每月规则,无论在本地还是异地目标),每次新的备份都会把最旧的一个挤出去。于是,如果一个条目最新的 N-1 次成功备份全都是通过 MCP 启动的,BombVault 就会拒绝再通过 MCP 启动它。这样总会至少有一个由计划或由你创建的恢复点留在保留集里。设为"保留最近 1 个"时,助手根本无法备份那个条目。下一次计划备份会再次腾出空间。单独的年度规则算作"保留最近 1 个",因为它只为当年保留一个恢复点。
启动一个领域或全部备份时,会略过被限制挡住的条目,并在回答里点名。网页界面和计划不受这些限制。每小时的额度保存在内存里,所以重启 BombVault 会重置它。
通过 API 和 Home Assistant 的启动,与通过 MCP 的启动一样,按条目计入相同的限制,也计入保留保护。
开启它¶
- 打开设置、集成、MCP 服务器,点击选择客户端,在窗口里选你的客户端。右上角的搜索可以按名称找到它。没有列出的客户端通过其他客户端连接。
- 在密钥下,保留新密钥和它建议的名称(客户端的名称),或者输入一个能说明密钥用在哪里的名称,例如"笔记本上的 Claude Code"。每个客户端一个密钥,可以撤销其中一个而不影响其他的。现有密钥会把你之前创建的密钥交给这个客户端。
- 对于需要能启动备份的密钥,开启允许启动备份。不开启的话,密钥只能读取。你以后可以在密钥的详情里更改它,更改会在助手的下一次请求时生效,不需要重新连接。
- 点击创建密钥。密钥只显示一次。BombVault 只保存它的指纹,无法再次显示,所以现在就复制下来。如果你在客户端使用密钥之前关闭了窗口,卡片会一直显示它,直到你确认已经复制。
没有登录密码时,网页界面本身对网络里的每个人都是开放的,能打开它的人也可以创建密钥。卡片会这样提示。如果你用一个看起来像公网的名称(例如通过反向代理访问的 bombvault.example.com)打开 BombVault,又没有设置登录密码,就无法从该地址创建或更换密钥,这样互联网上的任何网页都无法让你的浏览器去创建一个。请设置登录密码,或者用 IP 地址或 tower、tower.local 这样的本地名称打开 BombVault。
你的密钥和它们的日志¶
每个密钥在密钥与已登录的客户端下都有自己的一行。它显示密钥的名称、它是可以启动备份还是只能读取、密钥的最后四个字符、创建或上次更换的时间,以及客户端上次使用的时间。详情会打开一个窗口,在那里可以重命名密钥、更改它的权限、更换或撤销它,窗口里还显示它今天调用了多少次。被撤销的密钥会移到已撤销密钥的列表,历史记录里没有任何运行提到它之后,你可以把它彻底删除。
名称旁边,这一行显示创建这个密钥所针对的客户端的标记。通过其他客户端创建的密钥,或在卡片列出客户端之前创建的密钥,显示的是一把钥匙。
密钥详情里的日志显示这个密钥做过什么,被撤销的密钥保留着自己的日志按钮。它启动的备份排在最前面,每个都带状态,并带一个指向仪表盘上活动日志里那次运行的链接。下面是它的调用,最新的在前,带工具和调用的结果。拒绝会写明原因:密钥只能读取、保留保护拦下了备份、已经有另一个备份在运行、同一个条目、领域或这一轮在几分钟前于网页界面之外启动过,或者密钥发送的请求太多。取消会链接到它针对的那次运行。
BombVault 为每个密钥保留条目最长 30 天:最新的 500 次成功的启动和取消,以及此外最新的 200 次其他调用(读取、拒绝和错误)。一直轮询运行中备份的助手,或者一直重试被拒绝调用的助手,不会把那次备份的启动挤出日志。对于每次调用,它保存工具、结果,以及取消所针对的运行。它从不保存助手发送的内容,也从不保存密钥或它的指纹。诊断包只统计条目数量,设置导出会把它们去掉。
连接客户端¶
选择客户端会打开一个窗口,每个客户端是一个磁贴,分在在这台电脑上或在云端下,右上角有搜索。点击磁贴会在同一个窗口里打开该客户端的设置,分三步:密钥,该客户端的配置,包含你打开卡片时用的地址、一个复制按钮、配置存放的位置,以及在使用 BombVault 自带证书时客户端需要信任它的做法。最后是等待客户端的第一次调用。窗口会监视密钥上次的使用时间,那次调用一到就变绿。
这样的设置让密钥不出现在任何命令行里。客户端可以从环境变量(BOMBVAULT_MCP_KEY)、带掩码的提示或它自己的文件里读取时,配置里只写它的名字。客户端没有这种方式时,密钥就放在它的配置文件或设置里,设置步骤会这样说明。客户端的文档没有说明它如何对待不认识的证书时,设置步骤会把那一步写成"如果客户端拒绝 BombVault 的证书该怎么办"。
| 客户端 | 设置方式 | 密钥的来源 |
|---|---|---|
| AnythingLLM | 配置文件 | 配置文件 |
| Antigravity | 配置文件 | 环境变量 |
| Claude Code | 命令 | 密钥文件 |
| Claude Desktop | 配置文件 | 密钥文件 |
| Cline | 配置文件 | 配置文件 |
| Codex CLI | 配置文件 | 环境变量 |
| Continue | 配置文件 | ~/.continue/.env |
| Copilot CLI | 配置文件 | 配置文件 |
| Cursor | 配置文件 | 环境变量 |
| Gemini CLI | 配置文件 | 环境变量 |
| GitHub Copilot (VS Code) | 配置文件 | 带掩码的提示 |
| Goose | 配置文件 | 环境变量 |
| Jan | 应用内的表单 | 应用的设置 |
| JetBrains (AI Assistant, Junie) | 配置文件 | 配置文件 |
| Kimi Code | 配置文件 | 配置文件 |
| LM Studio | 配置文件 | 配置文件 |
| Mistral Vibe | 配置文件 | 环境变量 |
| Msty | 应用内的表单 | 应用的设置 |
| n8n | 应用内的表单 | n8n 的凭据存储 |
| Open WebUI | 应用内的表单 | 应用的设置 |
| opencode | 配置文件 | 环境变量 |
| Perplexity (Mac) | 应用内的表单 | 密钥文件 |
| Qwen Code | 配置文件 | 环境变量 |
| Roo Code | 配置文件 | 环境变量 |
| Visual Studio | 配置文件 | 配置文件 |
| Warp | 配置文件 | 配置文件 |
| Windsurf | 配置文件 | 环境变量 |
| Zed | 配置文件 | 配置文件 |
| Grok | 表单,在云端 | 服务商的服务器 |
| Le Chat | 表单,在云端 | 服务商的服务器 |
| ChatGPT | 通过 OAuth 登录,在云端 | 访问令牌,见下文 |
| Claude (claude.ai) | 通过 OAuth 登录,在云端 | 访问令牌,见下文 |
下面几节更详细地说明 Claude Code 和 Claude Desktop 的设置,并列出其他任何客户端需要的内容。
Claude Code¶
Claude Code 通过 mcp-remote 连接 BombVault,那台电脑上需要装有 Node.js。首先把密钥保存在一个单独的文本文件里,只写一行:
然后在终端里运行一次卡片上的命令,填入那个文件的路径。在你的电脑信任的证书后面,它看起来是这样的:
claude mcp add bombvault --scope user -- npx -y mcp-remote@latest https://bombvault.example.com/mcp --header-file "<path of the file with your key>"
使用 BombVault 自带的证书时(参见 TLS 和证书),命令还会让 Node.js 指向下载的证书:
claude mcp add bombvault --scope user -e "NODE_EXTRA_CA_CERTS=<path of the downloaded bombvault-cert.pem>" -- npx -y mcp-remote@latest https://192.168.1.10:3443/mcp --header-file "<path of the file with your key>"
在 Claude Code 里用 /mcp 检查连接。--scope user 让 BombVault 在你所有的项目里都可用。Claude Code 只保存密钥文件的路径,所以密钥既不会出现在命令和你的 shell 历史里,也不会出现在进程列表里。请把文件放在只有你能读取的地方,并且不要放在你会提交的文件夹里。@latest 让 npx 获取最新的 mcp-remote。否则会使用全局安装的旧版本,而它不认识 --header-file。
不要把 ${BOMBVAULT_MCP_KEY} 写进 Claude Code 的 mcp-remote 参数里。Claude Code 会在启动 mcp-remote 之前,用它自己的环境填入这样的引用,于是密钥最终会出现在那个进程的命令行上,电脑上的其他程序和用户都能读到。
没有 Node.js 时,并且只在你的电脑信任的证书后面,Claude Code 可以自己连接。在项目文件夹里放一个 .mcp.json:
{
"mcpServers": {
"bombvault": {
"type": "http",
"url": "https://bombvault.example.com/mcp",
"headers": {
"Authorization": "Bearer ${BOMBVAULT_MCP_KEY}"
}
}
}
}
在启动 Claude Code 的地方设置 BOMBVAULT_MCP_KEY,例如在 ~/.claude/settings.json 的 "env" 下,或在你的 shell 配置文件里,用文本编辑器编辑,而不是在提示符下输入。这里的引用是安全的,因为 Claude Code 不会再启动带着它的第二个进程。BombVault 自带的证书用不了这种方式:即使设置了 NODE_EXTRA_CA_CERTS,Claude Code 自己的连接也会拒绝它。千万不要提交写着密钥的 .mcp.json。
Claude Desktop¶
Claude Desktop 通过 mcp-remote 连接 BombVault,那台电脑上需要装有 Node.js。先像 Claude Code 那样,把密钥保存在一个单独的文本文件里,只写一行。在 Claude Desktop 里通过 Settings, Developer, Edit Config 打开配置文件。在 Windows 上它位于 %APPDATA%\Claude\claude_desktop_config.json,在 macOS 上位于 ~/Library/Application Support/Claude/claude_desktop_config.json。把卡片上的条目加到 "mcpServers" 里,放在已有的服务器旁边,然后重启 Claude Desktop:
{
"mcpServers": {
"bombvault": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://192.168.1.10:3443/mcp", "--header-file", "<path of the file with your key>"],
"env": {
"NODE_EXTRA_CA_CERTS": "<path of the downloaded bombvault-cert.pem>"
}
}
}
}
NODE_EXTRA_CA_CERTS只用于 BombVault 自带的证书。在你的电脑已经信任的证书后面,请去掉它。- 只有纯
http://地址才会加上--allow-http。 - 在 Windows 上,路径请用正斜杠书写,例如
C:/Users/sam/bombvault-key.txt,因为单个反斜杠不是有效的 JSON。密钥文件的路径里不要有空格:Windows 上的 Claude Desktop 会把带空格的路径拆成两段交给npx。 - 配置里只写密钥文件的名字,所以密钥既不会出现在配置里,也不会出现在进程列表里。请把文件放在只有你能读取的地方。
云端的客户端¶
ChatGPT、claude.ai 上的 Claude、Grok 和 Le Chat 从它们服务商的服务器调用 BombVault,所以 BombVault 必须能从互联网访问,并且有公开受信任的证书,例如放在反向代理后面。Le Chat 会拒绝自签名证书。代理上的登录可以保护网页界面,但 /mcp 必须不经过它直接到达 BombVault:这些服务无法登录代理,BombVault 自己检查它们的密钥或令牌。Grok 和 Le Chat 发送固定的密钥,它们的按钮和其他的一样设置它们。ChatGPT,以及大多数组织里 claude.ai 上的 Claude,只能通过 OAuth 登录连接,下面会讲。
通过 OAuth 登录¶
对于不能使用密钥的客户端,BombVault 自己就是 OAuth 授权服务器。客户端自行注册,把你带到 BombVault 的一个页面,你在那里用登录密码(如果设置了第二重验证,还有第二重验证)登录并允许它。客户端随后得到一个只对这个 BombVault 的 MCP 端点有效的令牌,并自动续期。
- 在设置、安全下设置登录密码。没有密码,BombVault 根本不提供登录,因为没有人可以征求同意。
- 让 BombVault 能通过 https 从互联网访问,并带有浏览器信任的证书,通常通过反向代理。客户端会从它自己的服务器调用
/mcp、/oauth/和/.well-known/,所以有自己登录的代理必须让这三个路径直接到达 BombVault。位于/oauth/authorize的同意页面在你自己的浏览器里打开,可以留在代理登录之后。也请在TRUSTED_PROXY里写上代理(参见配置)。BombVault 按地址限制客户端注册,没有它的话,每个客户端看起来都来自代理。 - 在 MCP 卡片上开启通过 OAuth 登录,并填写公开地址:不带路径的 https 地址,例如
https://backup.example.com。每个令牌都绑定这个地址,所以更改之后每个客户端都要重新登录。 - 在选择客户端下选 ChatGPT 或 Claude。窗口会显示连接器 URL,也就是公开地址加上
/mcp,以及它在该客户端里要填在哪里。在 ChatGPT 里,在 Settings, Apps & Connectors, Advanced settings 下开启 Developer mode,选择 Create,把连接器 URL 粘贴为 MCP 服务器 URL,并选择 OAuth 作为认证方式。在 claude.ai 上,打开 Settings, Connectors, Add custom connector,粘贴连接器 URL,OAuth 客户端 ID 和密钥留空,然后选择 Connect。 - 客户端会打开同意页面。它显示是谁在请求、你的回答会把你送回哪里,以及一开始关闭的允许启动备份开关。选择允许或拒绝。
每个已登录的客户端在同一个列表里都有自己的一行,带它的标记。它的详情里有它的日志、撤销和允许启动备份,它的限制和密钥相同。撤销会立即生效。同一个客户端再次登录时,它新的授权会取代旧的,没有人使用满 30 天的授权会过期。同一时间最多可以有 10 个客户端登录,另外还有 10 个密钥。
同意页面只接受已注册客户端的请求,而且这个请求必须与它注册过的返回地址之一完全一致:https,或者对你自己电脑上的客户端,任意端口的回环地址。只接受带 PKCE (S256) 的授权码流程,你的回答绑定在你的会话上,所以其他网站无法替你发送。访问令牌有效一小时。刷新令牌每次使用后都会被替换,在那之后再次出现的刷新令牌会撤销这项授权,因为别人持有一份副本。如果客户端因为回答没有到达而在 30 秒内重复了它最后一次刷新,它会得到新的令牌。BombVault 不会从互联网获取客户端元数据文档,所以客户端通过动态客户端注册来注册。
其他客户端¶
任何支持 Streamable HTTP 的客户端都可以使用:
- URL:网页界面的地址加上
/mcp,例如https://192.168.1.10:3443/mcp。 - 密钥放在
Authorization: Bearer <key>或X-API-Key: <key>里。如果两个都发送,它们必须带有相同的密钥。 POST,带Content-Type: application/json和Accept: application/json, text/event-stream。- 每个请求一条 JSON-RPC 消息。批量请求会被拒绝。
- 协议版本 2026-07-28、2025-11-25、2025-06-18 和 2025-03-26。
TLS 和证书¶
BombVault 用它自己生成的证书提供 HTTPS,这个证书一开始只包含 localhost、127.0.0.1 和 ::1。Claude Code 和 mcp-remote 在局域网地址上会拒绝它。绕过的办法,按适合大多数 Unraid 安装的顺序:
- 在 MCP 卡片里添加地址。 当卡片通过 HTTPS 在证书没有包含的地址上打开时,它会这样提示,并提供把这个地址加进证书。BombVault 会把这个地址加进去,重新签发证书(你的浏览器会再提醒一次,和第一次一样)。然后点击下载证书。示例配置会把
NODE_EXTRA_CA_CERTS设为下载的文件,所以客户端恰好信任这份证书。这也意味着,证书一重新签发,之前用旧下载设置好的每个客户端,在这台电脑和其他每台电脑上,都会停止连接,直到拿到新文件。 - 带受信任证书的反向代理(Nginx Proxy Manager、SWAG、Caddy、Traefik)。客户端看到的是代理的证书,不需要任何额外设置,卡片也不会对 BombVault 自带的证书发出警告。
- Tailscale。 在容器前面用
tailscale serve,或使用 Unraid 的 Tailscale 集成,就能得到一个带受信任证书的ts.net名称。 HTTP_ONLY=true,只在会终止 TLS 的代理后面,或在你完全信任的网络上使用。它把整个网页界面切换为纯 HTTP,需要更改容器设置,并且以明文发送密钥。
千万不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0。它会让那个 Node.js 进程所连接的一切都不再检查证书。
反向代理必须透传 Authorization(或 X-API-Key)头,代理通常会这样做,除非另有设置,并且不能对 /mcp 做缓冲或改写。下面是 Nginx 或 Nginx Proxy Manager 的一个 location 块,它还会检查 BombVault 的证书:
location /mcp {
proxy_pass https://192.168.1.10:3443;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /data/bombvault-cert.pem;
proxy_ssl_name localhost;
proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Host $host;
}
在代理后面,每个请求带的都是代理的地址。这样,一个配置有误的客户端发来五个错误的密钥,就会让这个代理后面的所有 MCP 客户端被锁定一分钟。请在 TRUSTED_PROXY 里写上代理(参见配置),以便按客户端计数。
安全模型¶
- 没有有效的密钥、且通过 OAuth 登录关闭时,
/mcp返回404。 - 只有设置了登录密码时才提供通过 OAuth 登录。令牌、授权码和客户端密钥只以指纹形式保存,令牌只对签发它的地址有效。
- 一个客户端同一个地址每小时最多注册 10 次,BombVault 最多保留 100 个没有人登录过的已注册客户端,每个保留一天。错误的授权码和刷新令牌,与错误的密钥计入同一个锁定。
- 恢复配置备份或
APP_KEY变化时,授权的表现和密钥一样:恢复之后每个客户端都要重新登录。 - 没有豁免的地址。来自
localhost、Unraid 主机、反向代理或tailscale serve的请求,和其他请求一样需要密钥,即使网页界面没有登录密码。 - 密钥只以指纹形式保存,只显示一次,可以重命名、更换和撤销。最多 10 个有效密钥,每个都有自己的允许启动备份开关。
- 每次创建、更换、更改权限和撤销,都会通过你的通知渠道发送一条通知,带有它来自的地址,除非通知已关闭。
- 每个地址每分钟 5 个错误的密钥,之后返回
429。每个密钥每分钟 120 个请求、每小时 12 次启动备份,再加上上面的冷却时间和保留保护。 - 来自另一个来源的浏览器页面的请求会被拒绝。
- 没有设置登录密码时,不能从看起来像公网的主机名创建密钥。
- 助手启动的每次备份,以及由此引起的清理和异地运行,都会在活动日志、错误面板和备份通知里,带着密钥的名称标记为"通过 MCP"。
- 每次工具调用都会写进容器日志,带有密钥的 ID 和最后四个字符(绝不带它的名称),并在
/metrics里计数(bombvault_mcp_requests_total、bombvault_mcp_tool_calls_total、bombvault_mcp_active_keys)。 - 恢复配置备份会撤销所有密钥,因为恢复的数据库里可能有你在保存之后撤销的密钥。请在之后创建新的密钥。
APP_KEY变化时(重新安装,或恢复到另一个容器上),密钥会停止工作。卡片会检测到并标出这个密钥,更换密钥会让它重新拥有可用的密钥。- 请把密钥当作密码对待。不能从环境变量、提示或密钥文件读取密钥的客户端,会把它以明文放在它的配置或设置里,它的设置步骤会这样说明。在你不太信任的电脑上,最好使用只读的密钥。
什么会离开这台机器¶
助手读取的一切都会发送给它背后的 AI 服务商:条目名称、计划、带错误信息的运行历史、恢复点 ID 和时间、数据库引擎名称和转储大小、当前活动、存储数据、覆盖情况和状态。文件搜索还会发送找到的文件:它们的名称、大小和在备份里的路径。BombVault 会在任何内容离开之前,去掉主机路径、仓库位置、主机名、登录凭据、钩子命令和密钥。
故障排除¶
| 你看到的 | 含义 |
|---|---|
404 |
没有有效的密钥且通过 OAuth 登录关闭,或者路径错了,例如 /api/mcp。端点是 /mcp。 |
401 |
密钥缺失、输错、已撤销或已被更换。代理可能丢掉了 Authorization 头(试试 X-API-Key)。如果卡片把密钥标为不再有效,说明 APP_KEY 变了:请更换密钥。 |
403 |
请求来自另一个来源的浏览器页面。请使用桌面或命令行客户端。 |
GET 上的 405 |
正常。端点只接受 POST。 |
400 "Accept must contain both 'application/json' and 'text/event-stream'" |
客户端太旧,不支持 Streamable HTTP。请更新它。 |
400 "batch requests are not accepted" |
客户端发送了 JSON-RPC 批量请求。请每个请求只发送一条消息。 |
429 |
这个地址发来太多错误的密钥,或者一个密钥每分钟超过 120 个请求。等一分钟,并检查助手是否卡进了循环。 |
| "certificate"、"self-signed" 或 "unable to verify" 错误 | 客户端不信任 BombVault 的证书。参见 TLS 和证书。 |
busy |
另一个备份或维护作业占用着这个领域。等它完成后再试。 |
cooldown |
这个条目、领域或全部备份在不到 15 分钟前于网页界面之外启动过。 |
retention_guard |
再多一次 MCP 备份,就会让"保留最近 N 个"窗口里只剩下 MCP 创建的恢复点,或者这个条目在过去 24 小时内已经通过 MCP 备份了 4 次,包括失败和取消的。第一种情况下,下一次计划备份会腾出空间,第二种情况下,这个条目会在其中最早那次备份的 24 小时之后重新可用。两种情况下你都可以在网页界面里启动它。 |
rate_limited |
这个密钥已经用完了本小时的 12 次启动。 |
启动时出现 not_permitted |
密钥是只读的。请在卡片里开启允许启动备份。不需要重新连接。取消时它表示这次运行不是由这个密钥启动的。 |
domain_off |
该分区在设置、常规下已关闭。 |
not_found |
这个条目没有受 BombVault 保护。请先在网页界面里添加它。MCP 从不创建配置。 |
| 客户端找不到授权服务器 | 通过 OAuth 登录已关闭、没有设置登录密码,或者代理没有让 /.well-known/ 到达 BombVault。 |
| 同意页面说返回地址未注册 | 客户端发送了一个它没有注册过的返回地址。请在客户端里移除这个连接器,再重新添加。 |
已登录的客户端得到 401 |
它的授权已被撤销、已因 30 天未使用而过期,或者公开地址变了。客户端会重新登录。 |
不要在容器上设置环境变量 MCPGODEBUG。它会改变 MCP 库的行为,格式错误的值会让 BombVault 在启动时就停下,连一行日志都不会写。