本篇是《MCP实战手记》篇12企业级Toolbox治理的延伸篇只拆「版本灰度」一个点给可运行代码、实测输出和一条真踩过的坑。篇12 深度文讲清治理层四件事本文是 §4 的放大。深度文与代码仓库tagv12Gitee0. 为什么需要灰度v1 的 bug 不敢摘篇12 开篇列过四类事故第三类是「不敢下线」v1 有个 bugv2 修好了但谁也不敢把 v1 摘掉怕有调用方还在用。更现实的是v2 改了返回值结构这时不能直接全量切——一旦有调用方没适配新结构集体 500。正确做法是先让一小撮 caller 走 v2验证没问题再逐步扩大。这套机制就是灰度路由。本文只做caller 级灰度调用方显式指定 / 映射表路由到指定版本简单可控「按流量百分比切」是另一种模式生产可参考篇10 高可用不在本文范围。1. 灰度模型调用方身份 → 指定版本同一ToolboxId下 v1、v2 并存注册时setIfAbsent最先注册的是稳定版。灰度就是一张「caller → 版本」的覆盖表稳定版默认: v1.0.0 callercanary - v2.0.0 # 灰度覆盖 其它 caller - v1.0.0 # 走稳定版resolve(caller, scopes, id)时先看这张表有没有该 caller 的覆盖有就走覆盖版本没有走稳定版。2. 实现setGrayRoute Redis 存储灰度配置是多实例共享状态存 Redis hashtb:gray:{id}fieldcallerIdvalueversion// 把某个 caller 固定到指定版本versionnull 清除该 caller 的灰度回到稳定版// 生产增强防踩坑1变体灰度记录带 setBy/setAt 审计per-caller TTL 或定时 sweep 自动回收避免忘了摘变隐式多版本voidsetGrayRoute(ToolboxIdid,StringcallerId,Stringversion){Stringkeytb:gray:id;if(versionnull)redis.hDel(key,callerId);elseredis.hSet(key,callerId,version);redis.publish(toolbox-events,gray:id);// 触发其它实例本地缓存失效}resolve的路由逻辑发现/调用两层拦截略见篇12 §3ToolboxDefinitionresolve(StringcallerId,ListStringscopes,ToolboxIdid,StringhintVersion){Stringgrayredis.hGet(tb:gray:id,callerId);// ① caller 级灰度优先Stringtarget(gray!null)?gray:(hintVersion!null?hintVersion:stableVersion(id));ToolboxDefinitiondefversions(id).get(target);if(defnull)thrownewIllegalArgumentException(版本不存在: target);if(def.getStatus()REMOVED)thrownewIllegalStateException(已移除: id迁移见 def.getDocUrl());checkScope(callerId,scopes,def);// ② 调用层 scope 拦截returndef;}内存后端InMemoryToolboxRegistry同一张表放ConcurrentHashMap逻辑完全一致只是不经过 Redis。生产提示高 QPS 下resolve每次redis.hGet灰度表也是一跳 RTT灰度表同样可走 04 篇的本地缓存层Caffeine pub/sub 失效与治理状态共用一套缓存机制不必每请求打 Redis。灰度是高频变更配置本地缓存 TTL 建议 30s比普通工具状态 5min 短避免灰度生效延迟。3. 实测canary 命中 v2normal 命中 v1seed 实例跑registry.setGrayRoute(getReport,canary,2.0.0);ToolboxDefinitioncanaryregistry.resolve(canary,List.of(report:gen),getReport,null);// v2.0.0ToolboxDefinitionnormalregistry.resolve(normal,List.of(report:gen),getReport,null);// v1.0.0输出canary - get_report2.0.0 # 灰度命中 normal - get_report1.0.0 # 稳定版多实例验证见篇12 §8灰度写入 Redis 后另一个实例resolve(canary)也命中2.0.0——B 读到的是 A 改动后的状态pub/sub 失效事件两实例都收到。4. 回滚一行 null无需发版发现问题清掉该 caller 的灰度即刻回稳定版registry.setGrayRoute(getReport,canary,null);// canary 回到 v1.0.0不发版这是 caller 级灰度的好处回滚是配置变更不必发版。5. 踩坑灰度没小范围验证就扩大规划期列过一条坑灰度路由一配就给整个团队、没先拿一个 caller 试结果 v2 有个没自测的分支灰度 caller 直接 500。纪律后来的做法先拿一个caller如canary验证 v2 输出确认日志/结构无误再按团队逐个加灰度不一次全开回滚预案先备好setGrayRoute(id, callerId, null)随手能敲。caller 级灰度明确知道谁在试新版本不会让随机流量撞上未验代码。流量比例灰度见篇10。6. 边界声明本机已验证caller 级灰度命中 / 回滚、Redis 多实例同步Docker redis:7两实例 A 播种 / B 只读。待生产验证流量比例灰度callerId 必须来自鉴权身份篇9 身份透传禁止调用方自报——否则可伪装 canary 越权拿新版本属安全门禁非优化项。Redis 持久化灰度配置存 Redis需开 AOF/RDB 或以 DB 为源避免 Redis 重启丢灰度表、caller 回到全量稳定版。本文不重复篇12 治理层全貌只拆灰度一点灰度配置存 Redis、与弃用 / 注册同走 pub/sub治理状态一致性的设计见篇12 §8。同专题推荐MCP实战手记十二企业级Toolbox治理——从“能调用“到“敢交给生产“篇12·弃用迁移实战deprecate→removed 全链路篇12·权限评分实战scope 拦截与健康度指标篇12·多实例一致性深潜Redis 与本地缓存降级代码仓库tagv12Gitee