服务注册与分布式协调 / 系统课时
设计稳定版与灰度指针
设计稳定版与灰度指针
多版本只解决“旧版本还在”,并没有定义谁应该默认使用哪个版本。本篇把固定版本、灰度指针和生产默认指针拆开,建立先灰度、再提升、可回滚的切换规则,避免一次发布同时改变目录契约和全部流量。
学习目标
- 区分固定版本、灰度指针与生产默认指针的职责
- 设计从 canary 验证到 stable 提升的发布流程
- 在回滚时同时恢复目录元数据与后端实例状态
先区分原生 latest 与平台指针
当前 MCP 管理 API 暴露的是版本列表以及 latest/is_latest 语义,查询时不传 version 会读取最新版本。stable、canary 在本篇中是发布平台自己的治理指针,不把它们误认为 MCP 服务原生的通用版本标签;Nacos 的 Prompt、Skill 等资源另有自定义标签能力,但 MCP 管理接口的公开模型不同。([Nacos 官网][2])
可以把三者这样分工:canary 指向正在验证的新版本,stable 指向已经通过验收的生产版本,而 Nacos 的 latest 只在准备改变默认读取结果时同步到 stable。固定版本调用方则始终直接请求具体版本号,不跟随任何指针。
{"service":"order-tools","stable":"1.0.0","canary":"1.1.0"}这是平台侧发布元数据示例,不是 Nacos MCP 管理 API 的原生请求体。验证方法是检查平台指针解析出的版本,再用 Nacos 详情接口读取对应固定版本。

规定提升与回滚顺序
推荐把一次发布拆成两个阶段。第一阶段只发布 1.1.0 并让 canary 指向它,测试客户端必须显式读取 1.1.0;此时 stable 和 Nacos latest 仍指向 1.0.0。第二阶段在契约、权限和后端调用都通过后,才同时提升 stable 与 latest。
回滚顺序要反过来思考:先阻止新的默认流量进入故障版本,再恢复平台 stable 指针和 Nacos latest,最后确认后端实例、路由和健康状态已经回到旧版本能够承接流量的状态。只改目录指针而旧实例已被下线,回滚仍然会失败。
提升默认版本并立即验证
假设 1.1.0 已经完成灰度验证。MCP 更新接口支持通过 latest 参数控制版本是否成为最新版本;提交时应使用目标版本对应的完整服务描述,避免在切换指针时意外改变协议或服务属性。([Nacos 官网][2])
下面示例依赖 curl 与 Python 3,把 1.1.0 提升为默认版本,并立刻用“不传 version”的查询验证默认读取结果。示例中的工具和端点没有变化,因此省略对应的可选参数;若目标版本修改过它们,应按目标版本原值一并提交。
NACOS="http://<HOST>:<PORT>"
MCP_ID="<ID>"
# 提升已验证版本为默认 latest
curl -sS -X PUT "${NACOS}/nacos/v3/admin/ai/mcp" \
-d 'namespaceId=public' \
--data-urlencode 'serverSpecification={"id":"<ID>","name":"order-tools","protocol":"streamable","frontProtocol":"streamable","description":"Order query tools","versionDetail":{"version":"1.1.0"},"enabled":true}' \
-d 'latest=true'
printf '\n'
# 不传 version,验证默认读取结果
curl -sS --get "${NACOS}/nacos/v3/admin/ai/mcp" \
--data-urlencode 'namespaceId=public' \
--data-urlencode "mcpId=${MCP_ID}" \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["data"]["versionDetail"]["version"])'预期输出:
{"code":0,"message":"success","data":"ok"}
1.1.0这里的关键验收条件是更新接口返回成功,随后默认查询得到 1.1.0。<HOST>、<PORT>、<ID> 的实际值可能不同。
回滚要恢复一组状态
把回滚目标预先写成发布记录,比故障发生后临时回忆可靠。至少保存下面四类信息:
- 目录版本:故障前的
stable、canary与 Nacoslatest指向 - 契约内容:旧版本的工具定义、输入 Schema、权限与安全方案
- 端点关系:MCP 版本对应的后端服务引用或直接地址
- 实例状态:旧实例是否仍在线、健康检查是否通过、路由是否能重新接流量
如果 1.1.0 出现问题,将同一切换命令中的目标版本改回 1.0.0,并同步恢复平台 stable 指针;之后再次不带 version 查询,确认默认版本已经回到 1.0.0。只有目录与实例两层都恢复,回滚才算完成。