服务注册与分布式协调 / 系统课时
治理外部服务可见范围
治理外部服务可见范围
外部 MCP 服务不应该一导入就进入生产 Agent 的可发现目录。本篇把外部服务分成“管理员评估、指定团队可用、广泛发布”三层,并用命名空间、读取权限、服务启用状态和发布闸门控制暴露范围。
学习目标
- 为外部 MCP 服务建立从评估到生产发布的三层可见边界。
- 组合命名空间、读取权限与
enabled状态,避免未审核服务被生产 Agent 发现。 - 用自动化验收脚本验证不同账号只能看到被允许的目录。
把可见范围设计成发布状态
本课不依赖某个单独的 scope 字段,而把“可见”拆成可审计的几层控制。外部资源先进入受限命名空间,完成校验和评估后才逐级扩大读取权限;MCP 服务本身还可以用 enabled 控制是否启用。Nacos 的 AI 资源导入会把外部资源纳入命名空间与治理体系,MCP 服务模型也包含 enabled 状态。([Nacos 官网][4])
| 阶段 | 建议命名空间 | 可读取身份 | Agent 使用边界 |
|---|---|---|---|
| 管理员评估 | mcp-external-review |
平台管理员、审核账号 | 不给生产 Agent 凭据,服务保持禁用或不进入运行目录 |
| 指定团队可用 | mcp-team-a |
指定团队 Agent、平台管理员 | 仅团队 Agent 可发现并调用 |
| 广泛发布 | mcp-prod |
生产 Agent 运行角色 | 通过发布审批后进入共享生产目录 |
这种设计的关键是扩大可见范围必须发生一次明确的发布动作,而不是通过给所有账号增加通配读取权限来“省事”。目录是否可见和是否可写也应分离;可见性负责资源是否进入查询结果,鉴权负责身份能否读写目标资源。([Nacos 官网][5])
在外部服务进入目录前设置闸门

外部服务进入评估区时,先检查来源、协议、工具清单、后端端点和凭据要求。只有审核账号能读取评估命名空间,生产 Agent 不持有该命名空间的 token。通过评估后,再把资源发布到团队或生产命名空间,而不是直接放宽评估区的访问范围。
开启可见性与鉴权能力
默认可见性实现会复用鉴权上下文,因此两类能力应同时开启。下面是 application.properties 片段;如果组织使用 OIDC 或自定义鉴权,应替换对应鉴权插件,但仍保留同样的读写与可见性边界。([Nacos 官网][5])
nacos.plugin.visibility.enabled=true
nacos.plugin.visibility.type=nacos
nacos.core.auth.system.type=nacos
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true生效行为是:目录查询先经过身份与资源边界判断,再由可见性策略决定哪些 AI 资源应进入详情、列表或搜索结果。配置本身不是发布审批的替代品;真正的治理仍要通过账号、命名空间和发布流程限定谁能看到哪一层资源。
用四个断言验收可见边界
下面脚本把可见性要求写成验收断言。替换 <PORT>、<TEAM_TOKEN> 和 <PROD_AGENT_TOKEN> 后执行;团队账号应该看不到评估区,但能读取自己的团队目录,生产 Agent 应看不到评估区,只能读取生产目录。
#!/usr/bin/env bash
set -euo pipefail
BASE="http://127.0.0.1:<PORT>"
TEAM_TOKEN="<TEAM_TOKEN>"
PROD_TOKEN="<PROD_AGENT_TOKEN>"
# 对同一目录接口做 allow/deny 断言,避免依赖具体拒绝状态码。
check_access() {
local label="$1"
local token="$2"
local namespace="$3"
local expected="$4"
local url="${BASE}/v3/console/ai/mcp/list?pageNo=1&pageSize=20&namespaceId=${namespace}&search=blur"
local status
status="$(curl -sS -o /dev/null -w '%{http_code}' \
-H "Authorization: Bearer ${token}" \
"${url}")"
# 2xx 代表该身份能看到目标目录;其他状态按拒绝处理。
if [[ "${expected}" == "allow" && "${status}" =~ ^2 ]]; then
echo "PASS: ${label}"
return
fi
if [[ "${expected}" == "deny" && ! "${status}" =~ ^2 ]]; then
echo "PASS: ${label}"
return
fi
echo "FAIL: ${label} (HTTP ${status})"
exit 1
}
# 四个断言覆盖“评估区隔离、团队可见、生产隔离、生产可见”。
check_access "team cannot read review namespace" "${TEAM_TOKEN}" "mcp-external-review" deny
check_access "team can read team namespace" "${TEAM_TOKEN}" "mcp-team-a" allow
check_access "prod agent cannot read review namespace" "${PROD_TOKEN}" "mcp-external-review" deny
check_access "prod agent can read production namespace" "${PROD_TOKEN}" "mcp-prod" allow预期输出
PASS: team cannot read review namespace
PASS: team can read team namespace
PASS: prod agent cannot read review namespace
PASS: prod agent can read production namespace只有四个断言同时通过,外部服务的可见边界才算成立。如果团队账号意外能读评估区,优先检查通配读取权限;如果生产 Agent 读不到生产目录,则检查目标命名空间授权,而不是把整个 AI Registry 放开。
发布时只扩大一层权限
从管理员评估到团队可用,再到广泛发布,每次只扩大一层读权限,并保留独立的写权限和审批主体。外部服务版本、端点或工具清单发生变化时,应重新回到评估阶段,而不是沿用旧版本的审核结论。
这样做的结果是:外部资源可以进入统一目录,但不会因为“已经被导入”就自动成为所有生产 Agent 的可用工具;真正的生产可用性由审核、命名空间、身份权限和启用状态共同决定。