mcp 工具发现失败重试 3 次(2s/20s/1min)+ MCP 服务健康检查

This commit is contained in:
2026-10-20 15:20:19 +08:00
parent 741839f5a7
commit 722db2681e
4 changed files with 122 additions and 54 deletions
+3
View File
@@ -108,6 +108,8 @@ mcp_servers:
接入栈外的 MCP 服务:在设置页添加 `url` / `headers`,或在 `config.yml` 的 `mcp_servers` 追加一项。服务不可达时 core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。 接入栈外的 MCP 服务:在设置页添加 `url` / `headers`,或在 `config.yml` 的 `mcp_servers` 追加一项。服务不可达时 core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。
工具发现只在启动时做一次,因此发现失败后会自动按 **2s / 20s / 1min 重试 3 次**(覆盖 compose 并行拉起与宿主机重启后的容器乱序);成功后工具在下一轮请求即可用,三次都失败则需重启 core。三个 MCP 服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。
--- ---
## 使用 ## 使用
@@ -389,6 +391,7 @@ curl -s http://127.0.0.1:8090/api/health
| 技能依赖缺失 | 重新 `docker compose up -d --build agent-executor`;或检查 `skills/deps` | | 技能依赖缺失 | 重新 `docker compose up -d --build agent-executor`;或检查 `skills/deps` |
| 微信设置页显示未连接 | wxbot 未启动,或 `WXBOT_TOKEN` 两侧不一致 | | 微信设置页显示未连接 | wxbot 未启动,或 `WXBOT_TOKEN` 两侧不一致 |
| 图生视频拉不到参考图 | `public_link.base_url` 未配置,或公网不可达 | | 图生视频拉不到参考图 | `public_link.base_url` 未配置,或公网不可达 |
| 启动日志出现 `xxx 工具发现失败` | 当时服务未就绪,core 会按 2s/20s/1min 重试 3 次;仍失败则重启 `agent-core` |
--- ---
+62 -20
View File
@@ -1,7 +1,7 @@
// 极简 MCP 客户端(Streamable HTTP:JSON-RPC over HTTP,无状态,响应可能是 SSE 帧包裹的 JSON)。 // 极简 MCP 客户端(Streamable HTTP:JSON-RPC over HTTP,无状态,响应可能是 SSE 帧包裹的 JSON)。
// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, enable?, timeout_ms?, tools_allow?, tools_deny?}。 // MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, enable?, timeout_ms?, tools_allow?, tools_deny?}。
// 启动时 init() 对每个服务调 tools/list 发现工具(enable: false 的服务跳过加载;配了 tools_allow/tools_deny // 启动时 init() 对每个服务调 tools/list 发现工具(enable: false 的服务跳过加载;配了 tools_allow/tools_deny
// 时按名单过滤),转成 OpenAI function 格式, // 时按名单过滤),发现失败的服务按 2s / 20s / 1min 再试 3 次(容器并行启动/重启后的乱序兜底),转成 OpenAI function 格式,
// 追加在内置工具(definitions.json)之后一起随 system prompt 发给模型; // 追加在内置工具(definitions.json)之后一起随 system prompt 发给模型;
// 工具调用经 tools/call 转发给对应服务。 // 工具调用经 tools/call 转发给对应服务。
// 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名, // 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名,
@@ -108,25 +108,14 @@ async function rpc(server, method, params, timeoutMs, extraHeaders) {
} }
} }
// 发现所有 MCP 服务的工具。单个服务失败只警告,不影响其他服务与内置工具。 // 启动发现失败后的重试阶梯(毫秒):2s / 20s / 1min,共 3 次。
// 对要求会话的服务,先发 initialize 拿到 Mcp-Session-Id,再发 notifications/initialized + tools/list。 // 动机:compose 并行拉起容器、宿主机重启后容器顺序也不保证,而工具发现只在启动时跑一次;
async function init(cfg) { // 不重试的话该服务会在这个进程的整个生命周期里缺席,只能重启 core 才能恢复。
toolDefs = []; const DISCOVERY_RETRY_DELAYS_MS = [2000, 20000, 60000];
toolIndex.clear();
PUBLIC_BASE = (cfg && cfg.public_link && cfg.public_link.base_url) || '';
try {
for (const d of require('./tools/definitions.json')) {
if (d.function && d.function.name) builtinNames.add(d.function.name);
}
} catch (_) { /* 内置定义读不到就不做重名保护 */ }
const servers = (cfg && cfg.mcp_servers) || []; // 发现单个服务的工具并并入工具表:成功返回 true,失败返回 false(不抛)。
for (const s of servers) { // 对要求会话的服务,先发 initialize 拿到 Mcp-Session-Id,再发 notifications/initialized + tools/list。
// enable: false 时启动不加载该服务(不建工具表;配置保留,改回 true 重启后恢复) async function loadServer(s) {
if (s.enable === false) {
log.info('mcp', s.name + ': enable=false,跳过工具加载');
continue;
}
// 清理上次会话 id(重启后服务端会拒绝旧 id;不清理会一直 400) // 清理上次会话 id(重启后服务端会拒绝旧 id;不清理会一直 400)
s.sessionId = null; s.sessionId = null;
try { try {
@@ -175,10 +164,63 @@ async function init(cfg) {
log.warn('mcp', s.name + ': 名单过滤后剩 0 个工具,请核对 tools_allow/tools_deny 与 ' + log.warn('mcp', s.name + ': 名单过滤后剩 0 个工具,请核对 tools_allow/tools_deny 与 ' +
'服务端实际工具名(如 ' + all.slice(0, 3).map(t => t.name).join(', ') + ' …)'); '服务端实际工具名(如 ' + all.slice(0, 3).map(t => t.name).join(', ') + ' …)');
} }
return true;
} catch (err) { } catch (err) {
log.warn('mcp', s.name + ' 工具发现失败(本轮运行该服务不可用): ' + (err && err.message || err)); log.warn('mcp', s.name + ' 工具发现失败(' + (err && err.message || err) + ')');
return false;
} }
} }
// 对启动时发现失败的服务按阶梯重试;成功后工具立即并入工具表,模型的下一轮请求即可见。
function retryFailed(failed) {
let pending = failed.slice();
const attempt = (i) => {
const timer = setTimeout(async () => {
if (!pending.length) return;
log.info('mcp', '重试工具发现 第 ' + (i + 1) + '/' + DISCOVERY_RETRY_DELAYS_MS.length + ' 次: ' +
pending.map(s => s.name).join(', '));
const still = [];
for (const s of pending) {
if (!(await loadServer(s))) still.push(s);
}
pending = still;
if (!pending.length) {
log.info('mcp', '重试成功:失败服务的工具已并入');
} else if (i + 1 < DISCOVERY_RETRY_DELAYS_MS.length) {
attempt(i + 1);
} else {
log.warn('mcp', '重试结束仍不可用: ' + pending.map(s => s.name).join(', ') +
'(服务恢复后需重启 core 才能加载其工具)');
}
}, DISCOVERY_RETRY_DELAYS_MS[i]);
// 不因待重试的定时器拖住进程退出(测试、一次性脚本里尤其明显)
if (timer.unref) timer.unref();
};
attempt(0);
}
// 发现所有 MCP 服务的工具。单个服务失败只警告,不影响其他服务与内置工具,并进入重试阶梯。
async function init(cfg) {
toolDefs = [];
toolIndex.clear();
PUBLIC_BASE = (cfg && cfg.public_link && cfg.public_link.base_url) || '';
try {
for (const d of require('./tools/definitions.json')) {
if (d.function && d.function.name) builtinNames.add(d.function.name);
}
} catch (_) { /* 内置定义读不到就不做重名保护 */ }
const servers = (cfg && cfg.mcp_servers) || [];
const failed = [];
for (const s of servers) {
// enable: false 时启动不加载该服务(不建工具表;配置保留,改回 true 重启后恢复)
if (s.enable === false) {
log.info('mcp', s.name + ': enable=false,跳过工具加载');
continue;
}
if (!(await loadServer(s))) failed.push(s);
}
if (failed.length) retryFailed(failed);
} }
// 随请求发送的 MCP 工具定义(追加在内置工具之后)。 // 随请求发送的 MCP 工具定义(追加在内置工具之后)。
+23
View File
@@ -152,11 +152,22 @@ services:
# 同栈 MCP 服务(./mcp/):三个 Model Context Protocol 适配器,由 core 按容器名调用。 # 同栈 MCP 服务(./mcp/):三个 Model Context Protocol 适配器,由 core 按容器名调用。
# 全部不占宿主机端口、无服务端鉴权,**永远不要**把 ports 映射出去(会被白嫖额度)。 # 全部不占宿主机端口、无服务端鉴权,**永远不要**把 ports 映射出去(会被白嫖额度)。
# 工具说明、header 覆盖项与 curl 调试见 mcp/README.md 及各子目录 README。 # 工具说明、header 覆盖项与 curl 调试见 mcp/README.md 及各子目录 README。
#
# 刻意不写 depends_on / 不等 healthy:MCP 是可选能力,core 不该因它们缺席而拒绝启动
# (构建失败、单个服务被删都不影响 Web 主流程)。启动瞬间的竞态由 core 侧的工具发现重试
# 兜底(2s / 20s / 1min × 3),healthcheck 只用于 docker ps 判态。
# ---------------------------------------------------------------- # ----------------------------------------------------------------
mcp_web_search: mcp_web_search:
build: ./mcp/web_search build: ./mcp/web_search
container_name: mcp_web_search container_name: mcp_web_search
restart: unless-stopped restart: unless-stopped
# 供 core 的启动顺序参考与 docker ps 判态(core 侧的发现失败重试不依赖它)
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
interval: 10s
timeout: 5s
retries: 5
start_period: 5s
# 调试用(默认关): # 调试用(默认关):
# ports: # ports:
# - "${WEB_SEARCH_PORT:-8081}:3000" # - "${WEB_SEARCH_PORT:-8081}:3000"
@@ -167,6 +178,12 @@ services:
build: ./mcp/image_task build: ./mcp/image_task
container_name: mcp_image_task container_name: mcp_image_task
restart: unless-stopped restart: unless-stopped
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
interval: 10s
timeout: 5s
retries: 5
start_period: 5s
# 调试用(默认关): # 调试用(默认关):
# ports: # ports:
# - "${IMAGE_TASK_PORT:-8082}:3000" # - "${IMAGE_TASK_PORT:-8082}:3000"
@@ -177,6 +194,12 @@ services:
build: ./mcp/video_task build: ./mcp/video_task
container_name: mcp_video_task container_name: mcp_video_task
restart: unless-stopped restart: unless-stopped
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
interval: 10s
timeout: 5s
retries: 5
start_period: 5s
# 调试用(默认关;这里映的是 MCP 端口,会暴露 /mcp,仅本机短时调试用): # 调试用(默认关;这里映的是 MCP 端口,会暴露 /mcp,仅本机短时调试用):
# ports: # ports:
# - "${VIDEO_TASK_PORT:-8083}:3000" # - "${VIDEO_TASK_PORT:-8083}:3000"
+1 -1
View File
@@ -33,7 +33,7 @@ mcp_servers:
url: "http://mcp_video_task:3000/mcp" url: "http://mcp_video_task:3000/mcp"
``` ```
服务没起来时,core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。 服务没起来时,core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。工具发现只在启动时做一次,失败后会自动按 2s / 20s / 1min 重试 3 次;三次都失败则需重启 core。三个服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。
> 从旧的「agent + mcp 双仓库」部署升级:先在旧 mcp 仓库目录 `docker compose down`(只需一次,否则同名容器与网络会冲突),再 `up` 本栈。 > 从旧的「agent + mcp 双仓库」部署升级:先在旧 mcp 仓库目录 `docker compose down`(只需一次,否则同名容器与网络会冲突),再 `up` 本栈。