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

从外部 Registry 导入服务

从外部 Registry 导入服务

外部 MCP Registry 里已经存在大量可复用服务时,不必逐项手工重建。Nacos 的统一 AI 资源导入流程先选择受管来源,再搜索候选、校验冲突并执行导入;本节用内置官方来源跑通完整链路,并划清外部信息与本地治理的边界。

学习目标

  • 按“来源、搜索、校验、执行”的顺序导入 MCP Server
  • 理解 sourceId、外部候选信息与 Nacos 本地资源身份的职责边界
  • 在导入前识别冲突、无效项与不安全的任意 URL 入口

导入不是直接复制一个 URL

统一导入接口从已配置的 sourceId 开始。用户请求选择来源,但来源的 Registry endpoint、认证引用、超时和网络策略由运维侧配置;请求不应把任意 endpoint、IP 或凭证当成导入参数。内置官方 MCP Registry 来源通常以 mcp-official 暴露。

导入器只负责发现外部资源并转换成可校验的导入项。真正写入后,资源进入 Nacos 的命名空间、版本、可见性与生命周期体系;外部 Registry 仍是来源,不会取代 Nacos 的本地治理身份。

外部 MCP Registry 到 Nacos 的统一导入链路

跑通搜索、校验和导入

下面使用 Admin API,适合在可控实验环境验证流程。Admin API 默认需要管理员权限;若改用 Console API,则调用 /v3/console/ai/import/* 并按实际 Console 地址与命名空间权限完成认证。

脚本先确认 mcp-official 来源可用,再搜索候选;它选择搜索结果中的第一项,先获取校验令牌,再执行一次不覆盖已有资源、也不跳过无效项的导入。需要 curl 与 jq,运行前把管理员密码放入 NACOS_PASSWORD 环境变量。

bash
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)"'

预期输出

text
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 中的资源为准;外部来源出现新版本时,应重新走搜索、校验和导入流程,而不是假设目录会自动同步。

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

目录与阅读设置

阅读设置

17

记录一个想法

从外部 Registry 导入服务

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

登录哪都通