服务注册与分布式协调 / 系统课时
从外部 Registry 导入服务
从外部 Registry 导入服务
外部 MCP Registry 里已经存在大量可复用服务时,不必逐项手工重建。Nacos 的统一 AI 资源导入流程先选择受管来源,再搜索候选、校验冲突并执行导入;本节用内置官方来源跑通完整链路,并划清外部信息与本地治理的边界。
学习目标
- 按“来源、搜索、校验、执行”的顺序导入 MCP Server
- 理解
sourceId、外部候选信息与 Nacos 本地资源身份的职责边界 - 在导入前识别冲突、无效项与不安全的任意 URL 入口
导入不是直接复制一个 URL
统一导入接口从已配置的 sourceId 开始。用户请求选择来源,但来源的 Registry endpoint、认证引用、超时和网络策略由运维侧配置;请求不应把任意 endpoint、IP 或凭证当成导入参数。内置官方 MCP Registry 来源通常以 mcp-official 暴露。
导入器只负责发现外部资源并转换成可校验的导入项。真正写入后,资源进入 Nacos 的命名空间、版本、可见性与生命周期体系;外部 Registry 仍是来源,不会取代 Nacos 的本地治理身份。

跑通搜索、校验和导入
下面使用 Admin API,适合在可控实验环境验证流程。Admin API 默认需要管理员权限;若改用 Console API,则调用 /v3/console/ai/import/* 并按实际 Console 地址与命名空间权限完成认证。
脚本先确认 mcp-official 来源可用,再搜索候选;它选择搜索结果中的第一项,先获取校验令牌,再执行一次不覆盖已有资源、也不跳过无效项的导入。需要 curl 与 jq,运行前把管理员密码放入 NACOS_PASSWORD 环境变量。
set -euo pipefail
BASE_URL="${BASE_URL:-http://127.0.0.1:8848/nacos}"
NAMESPACE="${NAMESPACE:-public}"
NACOS_USER="${NACOS_USER:-nacos}"
SOURCE_ID="${SOURCE_ID:-mcp-official}"
: "${NACOS_PASSWORD:?export NACOS_PASSWORD first}"
login_resp=$(curl -fsS -X POST "$BASE_URL/v3/auth/user/login" --data-urlencode "username=$NACOS_USER" --data-urlencode "password=$NACOS_PASSWORD")
access_token=$(printf '%s' "$login_resp" | jq -r '.accessToken')
auth=(-H "Authorization: Bearer $access_token")
# 先确认来源由服务端配置并已启用。
sources=$(curl -fsS "${auth[@]}" "$BASE_URL/v3/admin/ai/import/sources?resourceType=mcp")
printf '%s' "$sources" | jq -e --arg source "$SOURCE_ID" '.data[] | select(.sourceId == $source)' >/dev/null
printf 'source=%s\n' "$SOURCE_ID"
# 搜索只返回候选,尚未改变本地目录。
search_resp=$(curl -fsS -X POST "${auth[@]}" "$BASE_URL/v3/admin/ai/import/search" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "resourceType=mcp" --data-urlencode "sourceId=$SOURCE_ID" --data-urlencode "limit=5")
count=$(printf '%s' "$search_resp" | jq '.data.items | length')
test "$count" -gt 0 || { echo "no candidates"; exit 1; }
printf 'candidate_count=%s\n' "$count"
selected_items=$(printf '%s' "$search_resp" | jq -c '[.data.items[0]]')
# 校验冲突与依赖,并保存本次校验令牌。
validate_resp=$(curl -fsS -X POST "${auth[@]}" "$BASE_URL/v3/admin/ai/import/validate" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "resourceType=mcp" --data-urlencode "sourceId=$SOURCE_ID" --data-urlencode "selectedItems=$selected_items" --data-urlencode "overwriteExisting=false")
validation_token=$(printf '%s' "$validate_resp" | jq -r '.data.validationToken')
test -n "$validation_token" && test "$validation_token" != "null"
printf 'validation_token=%s\n' "$validation_token"
# 只有执行阶段才真正把资源写入 Nacos。
execute_resp=$(curl -fsS -X POST "${auth[@]}" "$BASE_URL/v3/admin/ai/import/execute" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "resourceType=mcp" --data-urlencode "sourceId=$SOURCE_ID" --data-urlencode "selectedItems=$selected_items" --data-urlencode "overwriteExisting=false" --data-urlencode "skipInvalid=false" --data-urlencode "validationToken=$validation_token")
printf '%s' "$execute_resp" | jq -r '"success=\(.data.success) total=\(.data.totalCount) imported=\(.data.successCount) failed=\(.data.failedCount) skipped=\(.data.skippedCount)"'预期输出
source=mcp-official
candidate_count=<COUNT>
validation_token=<TOKEN>
success=true total=1 imported=1 failed=0 skipped=0<COUNT> 由当时 Registry 返回的候选数量决定,<TOKEN> 是本次校验产生的令牌。如果搜索结果为空,应更换查询条件或检查来源状态,而不是绕过校验直接构造导入对象。使用 OIDC、LDAP 或自定义鉴权时,应换成对应的认证方式。
校验阶段决定能不能安全落库
搜索返回的是候选摘要,不等于已经可以写入。校验阶段会拉取导入所需内容,并检查资源类型、冲突和依赖;执行阶段才把有效 artifact 交给对应资源的 Operator。把这两步分开,可以在真正改变目录前看到风险。
overwriteExisting=false 更适合第一次接入,因为同名资源不会被静默覆盖。只有确认外部候选与本地对象的身份、版本和治理策略一致时,才考虑覆盖。skipInvalid=false 则让任何无效项直接暴露问题,便于首次接入时完整修正。
分清外部来源和本地治理
外部 Registry 提供的是“候选从哪里来”以及候选携带的规范、端点和元数据;Nacos 决定的是“导入后它在本地是谁、属于哪个命名空间、保留哪些版本、谁可见以及后续如何发布”。来源标识应保留用于追踪,但不能拿外部 ID 代替本地治理规则。
因此,导入更接近一次受控的“接入与纳管”,而不是把 Nacos 变成外部 Registry 的透明代理。后续版本切换、权限、可见性和生命周期操作都应以 Nacos 中的资源为准;外部来源出现新版本时,应重新走搜索、校验和导入流程,而不是假设目录会自动同步。