服务注册与分布式协调 / 系统课时

治理外部服务可见范围

治理外部服务可见范围

外部 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])

在外部服务进入目录前设置闸门

外部 MCP 服务从评估到团队可用再到广泛发布的治理流程

外部服务进入评估区时,先检查来源、协议、工具清单、后端端点和凭据要求。只有审核账号能读取评估命名空间,生产 Agent 不持有该命名空间的 token。通过评估后,再把资源发布到团队或生产命名空间,而不是直接放宽评估区的访问范围。

开启可见性与鉴权能力

默认可见性实现会复用鉴权上下文,因此两类能力应同时开启。下面是 application.properties 片段;如果组织使用 OIDC 或自定义鉴权,应替换对应鉴权插件,但仍保留同样的读写与可见性边界。([Nacos 官网][5])

properties
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 应看不到评估区,只能读取生产目录。

bash
#!/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

预期输出

text
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 的可用工具;真正的生产可用性由审核、命名空间、身份权限和启用状态共同决定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

治理外部服务可见范围

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通