服务注册与分布式协调 / 系统课时
管理服务版本与最新指针
管理服务版本与最新指针
同一个 MCP Server 可以保留多个可独立查询的版本,同时再用“最新”指针决定未指定版本时默认返回哪一份定义。本节用 Admin API 建立两个版本并切换指针,验证版本实体与默认版本并不是一回事。
学习目标
- 理解 MCP Server 身份、版本实体与最新指针之间的关系
- 创建新版本,并控制它是否立即成为最新版本
- 通过显式版本查询和默认查询验证灰度与回滚基础
版本实体和最新指针是两层信息
在一个命名空间内,MCP Server 先由稳定的服务身份承载,再保存多个版本。详情接口的 allVersions 展示版本集合,is_latest 标记当前最新版本;查询详情时不传 version,返回最新版本,显式传入 version 则读取指定版本。
这意味着“发布了 1.1.0”与“默认使用 1.1.0”不是同一件事。你可以先把 1.1.0 写入目录但保持 1.0.0 为最新,验证完成后再移动指针;需要回滚时,也可以把默认选择重新指回旧版本,而不用删除新版本。

创建新版本并切换默认版本
下面的实验使用默认 Nacos 鉴权插件,通过管理员账号登录后调用 Admin API。脚本先创建 1.0.0,再用更新接口写入 1.1.0 且暂不设为最新,最后把同一 1.1.0 切为最新。需要 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}"
: "${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")
NAME="catalog-demo-$(date +%s)"
# 建立稳定服务身份,并先发布 1.0.0。
create_spec=$(jq -nc --arg name "$NAME" '{
protocol:"stdio",
frontProtocol:"stdio",
name:$name,
description:"catalog version demo",
versionDetail:{version:"1.0.0"},
enabled:true,
localServerConfig:{($name):{}}
}')
create_resp=$(curl -fsS -X POST "${auth[@]}" "$BASE_URL/v3/admin/ai/mcp" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "mcpName=$NAME" --data-urlencode "serverSpecification=$create_spec")
mcp_id=$(printf '%s' "$create_resp" | jq -r '.data')
printf 'created=%s\n' "$mcp_id"
# 写入第二个版本,但暂时不移动 latest。
v110_spec=$(jq -nc --arg name "$NAME" --arg id "$mcp_id" '{
protocol:"stdio",
frontProtocol:"stdio",
name:$name,
id:$id,
description:"catalog version demo v1.1",
versionDetail:{version:"1.1.0"},
enabled:true,
localServerConfig:{($name):{}}
}')
curl -fsS -X PUT "${auth[@]}" "$BASE_URL/v3/admin/ai/mcp" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "mcpName=$NAME" --data-urlencode "serverSpecification=$v110_spec" --data-urlencode "latest=false" >/dev/null
printf 'before:\n'
curl -fsS "${auth[@]}" "$BASE_URL/v3/admin/ai/mcp?namespaceId=$NAMESPACE&mcpId=$mcp_id" | jq -r '.data.allVersions[] | "\(.version) latest=\(.is_latest)"'
# 验证完成后,再把同一版本设为 latest。
curl -fsS -X PUT "${auth[@]}" "$BASE_URL/v3/admin/ai/mcp" --data-urlencode "namespaceId=$NAMESPACE" --data-urlencode "mcpName=$NAME" --data-urlencode "serverSpecification=$v110_spec" --data-urlencode "latest=true" >/dev/null
printf 'after:\n'
curl -fsS "${auth[@]}" "$BASE_URL/v3/admin/ai/mcp?namespaceId=$NAMESPACE&mcpId=$mcp_id" | jq -r '.data.allVersions[] | "\(.version) latest=\(.is_latest)"'
# 对比默认查询与显式版本查询。
default_version=$(curl -fsS "${auth[@]}" "$BASE_URL/v3/admin/ai/mcp?namespaceId=$NAMESPACE&mcpId=$mcp_id" | jq -r '.data.versionDetail.version')
explicit_version=$(curl -fsS "${auth[@]}" "$BASE_URL/v3/admin/ai/mcp?namespaceId=$NAMESPACE&mcpId=$mcp_id&version=1.0.0" | jq -r '.data.versionDetail.version')
printf 'default=%s\nexplicit=%s\n' "$default_version" "$explicit_version"预期输出
created=<ID>
before:
1.0.0 latest=true
1.1.0 latest=false
after:
1.0.0 latest=false
1.1.0 latest=true
default=1.1.0
explicit=1.0.0<ID> 是 Nacos 为服务生成的实际标识;版本的展示顺序可能不同,但切换前后应只有一个版本被标为最新。使用 OIDC、LDAP 或自定义鉴权插件时,应把登录和凭据注入部分替换为该环境认可的认证方式,不要为了跑示例关闭生产鉴权。
把版本策略用于灰度和回滚
灰度的关键不是“覆盖原版本”,而是让新版本先成为可寻址实体。验证方显式请求 version=1.1.0,默认查询仍解析到 1.0.0;确认兼容后,再把最新指针切到 1.1.0。这样新旧定义都保留,问题定位时也能复现旧行为。
回滚同样应优先移动默认指针,而不是立刻删除故障版本。删除会丢掉现场信息,也让仍然固定在该版本的调用方失去目标。先恢复默认版本,再决定是否下线或删除问题版本,目录的审计与兼容关系会更清楚。
当版本实体和最新指针被分开管理后,MCP 目录就具备了最基本的可回滚发布能力:版本负责保留历史与兼容面,指针负责控制默认解析结果。