做微服务的人迟早要面对灰度发布这件事。我自己的经历是从一次大促前夜的发布事故开始的当时某个核心服务升级了底层缓存逻辑为了稳妥只灰度了入口网关的20%流量结果线上还是出了问题——订单服务调了新版用户服务用户服务又调了新版优惠券服务一条链路上新旧版本混着跑数据格式对不上直接导致一批订单异常。事后复盘问题不在某个服务而在于灰度只做了入口链路中间全是盲区。那次事故之后我花了两周时间把整个灰度方案推翻重做核心思路就是全链路流量染色。这套方案基于 Spring Cloud 生态落地原理不算复杂在网关层给请求打上一个标记染色这个标记随着调用链一路传递到各个微服务每个服务在负载均衡时根据标记把流量路由到对应的灰度实例或稳定实例。本文就把这套方案从设计、编码到踩坑完整拆解一遍适合那些已经上了微服务、正在被灰度发布折磨的团队参考。1. 灰度发布为什么这么难先看清服务拆分的连锁反应1.1 单体时代的灰度在微服务时代失效了先说说单体时代怎么做灰度。一个应用打包成WAR或者JAR前面挂Nginx灰度就是按IP、按Cookie或者按百分比把进入Nginx的流量分到新旧两个集群。请求进到应用内部之后所有逻辑都在同一个进程里不存在链路中间版本不匹配的问题。微服务拆开之后情况完全不同。一个用户请求从网关进来可能要经过四五个服务网关 → 订单服务 → 库存服务 → 优惠券服务 → 用户服务。如果我只在网关层做了灰度网关把20%流量分给新版订单服务但是新版订单服务内部调用的还是旧版库存服务然后旧版库存服务回调旧版优惠券服务……新旧版本的协议、字段、SQL逻辑一旦有差异整条链路上的数据就开始打架。更麻烦的是微服务场景下每个服务都是独立部署的可以有自己的发布节奏。A团队想灰度订单服务B团队想灰度库存服务C团队暂时不动。如果没有统一的标记传递机制灰度范围没法精确控制灰度发布就退化成部分节点更新出问题了根本定位不到是哪一段引起的。我见过不少团队的伪灰度做法新版本服务先启动几个实例注册中心里新旧实例并存但负载均衡完全随机流量到了哪个实例全凭运气。这种做法的本质是多实例部署不是灰度发布——因为它没有办法按用户、按请求、按规则去精准控制流量走向。1.2 全链路灰度到底要解决什么问题全链路灰度要解决的问题用一句话说就是让一个请求从入口到出口始终只走同一套版本的服务。如果请求被标记为灰度用户那么不管这条调用链经过多少个服务每个服务在选实例的时候都要优先选灰度版本反之如果请求没有标记或者标记为正式用户那所有服务都走正式版本。这样做的意义在于版本一致性一条链路内所有服务的版本是配套的不会出现新旧混跑。精细控制你可以按用户维度、请求维度、百分比维度决定哪些流量走灰度而且这个决定在入口做一次整条链路自动生效。快速验证和回滚新版本有问题把入口标记关掉就行灰度流量瞬间归零不用一台台重启服务。1.3 流量染色在其中的位置流量染色是实现全链路灰度的关键技术手段。染色这个词很形象想象一下给白色水流中滴入一滴红色颜料整条水管里的水都变成红色。具体到技术上就是通过HTTP Header把标记信息从网关传下去每个服务在发起下一个远程调用时把这个Header原样透传下游服务拿到Header之后结合注册中心的实例元数据做路由决策。这个方案有几个前提条件服务之间的调用框架要能支持自定义Header透传Spring Cloud生态里的OpenFeign、RestTemplate都能做到注册中心要能保存实例的自定义元数据负载均衡逻辑要支持自定义策略。这三件事Spring Cloud体系内都有成熟解法这也是为什么标题里说Spring Cloud全链路——因为这套技术栈天然具备实现条件。2. 流量染色方案设计从标记规范到路由决策2.1 染色标记规范设计做方案设计的时候第一个决策就是标记长什么样。我的建议是一个请求头KV结构值用K1V1K2V2这种格式不要搞得太复杂。我实际在项目里用的Header名是X-Gray-Tag取值大概是这样的X-Gray-Tag: uid10086channelappversionv2.1.0几个字段分别代表uid用户ID用于按用户维度的灰度比如某个内部测试账号永远走灰度。channel渠道标识比如app、web、mini-program某些渠道可以先切灰度。version目标版本号表示这个请求应该路由到哪个版本的服务实例。为什么不直接用单个值比如X-Gray-Tag: gray因为真实场景里灰度策略往往需要多维度的组合。只有gray/normal二值标记意味着每个服务只能无脑分流不够灵活。uid和channel让网关可以按规则动态决策灰度范围而version则是给下游服务路由用的比如订单服务同时存在v2.1.0和v2.0.9两套实例请求头里带了versionv2.1.0负载均衡就优先选标注了v2.1.0的实例。这个设计还有一个好处规则下沉。网关不需要知道每个服务有哪些版本它只负责在入口处根据规则给请求染色具体的版本匹配逻辑由各服务的负载均衡组件自己处理。职责分离好维护。2.2 全链路传递机制设计Header在网关层生成之后要做的就是随着调用链一路传递下去。这里有个特别容易踩的坑Spring Cloud里的远程调用默认不会透传Header。以OpenFeign为例默认情况下它只会传递自己生成的一些必要Header自定义的X-Gray-Tag根本不会被带到下游。更隐蔽的问题是Hystrix线程池隔离如果还在用会把ThreadLocal上下文清掉所以标记不仅要解决HTTP层面传递还要解决线程层面传递。我的做法是引入TransmittableThreadLocal配合Feign的RequestInterceptor来实现。思路是网关染色后把X-Gray-Tag存到当前线程的上下文里OpenFeign发送请求前通过RequestInterceptor把上下文中的X-Gray-Tag写到即将发出的请求Header里下游服务收到请求先把X-Gray-Tag从Header解析出来存到自己的上下文然后继续向下传递。这个机制本质上是请求头提取 → 上下文保存 → 请求时注入环环相扣。2.3 路由决策模型染色标记传递到了每个服务之后每个服务怎么决定把请求发给哪个实例答案在负载均衡那一层。Spring Cloud LoadBalancer新版本已经用这个替代了Ribbon允许通过ServiceInstanceListSupplier自定义实例列表的获取逻辑。我们可以写一个灰度感知的Supplier拿到注册中心返回的所有实例后读取每个实例的元数据比如version字段再结合请求头里的X-Gray-Tag过滤出目标版本实例。如果下游只有灰度实例没有稳定实例或者反过来路由策略需要有一个兜底逻辑。我当时的策略是请求带了明确版本号优先匹配同版本实例没有匹配到降级到稳定版实例即不带任何版本标记的实例保证请求不能因为没有灰度实例而失败如果稳定版也没有直接抛异常宁可快速失败也不要把请求发给错误版本。这个兜底逻辑非常重要很多灰度方案做了一半就上线崩或者灰度不生效都是因为漏了兜底处理。3. 基于Spring Cloud的实操落地从注册中心到网关到调用链3.1 注册中心元数据让实例自带版本标签全链路灰度的基础是实例能被区分。我用的是Nacos作为注册中心Consul也行原理一样在服务启动的时候给实例配置元数据。具体做法是给Spring Boot的配置文件加上自定义属性spring: cloud: nacos: discovery: server-addr: 127.0.0.1:8848 metadata: version: v2.1.0 env: gray deploy-time: 2024-11-20 10:00:00稳定版本的服务不要加version字段或者统一写成version: stable。这样在注册中心里同一个服务名下就有两类实例带版本号的灰度实例和不带版本号的稳定实例。这一步是整个方案能落地的前提如果实例本身没有版本标识负载均衡就算拿到了X-Gray-Tag也不知道该往哪里转。我强烈建议部署的时候用CI/CD自动注入这个metadata而不是写在代码里。因为同一个代码分支可能同时部署到稳定环境和灰度环境写死在配置文件里会带来很大的维护成本。用流水线参数动态生成配置文件片段或者启动时通过环境变量注入更符合实际操作习惯。3.2 网关染色全局Filter实现网关是整个染色链路的起点所有外部的HTTP请求都要从这里经过在这里决定这个请求要不要染色、染什么色。我用的是Spring Cloud Gateway实现一个GlobalFilter负责读取请求信息结合灰度规则库给请求打上X-Gray-Tag头Component public class GrayTagFilter implements GlobalFilter, Ordered { private final GrayRuleService grayRuleService; public GrayTagFilter(GrayRuleService grayRuleService) { this.grayRuleService grayRuleService; } Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); String uid request.getQueryParams().getFirst(uid); String channel request.getHeaders().getFirst(X-Channel); // 如果上游已经传了灰度标记多级网关场景直接透传 String grayTag request.getHeaders().getFirst(X-Gray-Tag); if (grayTag null) { grayTag grayRuleService.resolveGrayTag(uid, channel); } ServerWebExchange mutatedExchange exchange.mutate() .request(builder - builder.header(X-Gray-Tag, grayTag)) .build(); return chain.filter(mutatedExchange); } Override public int getOrder() { // 这个Filter要在路由之前执行但也要注意和鉴权、限流的顺序 return -100; } }这里注意几个设计细节Filter顺序灰度染色一定要放在路由转发之前但具体放在鉴权前还是后取决于你的团队怎么发布规则。如果灰度规则里包含某些内部用户直接走灰度那染色要在鉴权之前因为鉴权可能消耗额外资源。如果灰度规则依赖登录后的用户信息那就在鉴权之后。上游透传如果整条链路有二级网关比如内网网关 外网网关外层网关已经染过色内层网关就不要重新染色否则可能把规则覆盖掉。默认值兜底resolveGrayTag一定要保证永远返回一个字符串哪怕是不带任何标记的空串而不是返回null。因为builder.header()如果写入一个null值在后续处理中会出问题。3.3 OpenFeign调用链传递三行代码解决Header透传网关染好色之后请求会落到第一个微服务。接下来就是最关键的请求从这个服务往下一个服务发起OpenFeign调用时X-Gray-Tag不能被丢掉。在Spring Boot 2.x Spring Cloud Hoxton之后实现很简单写一个RequestInterceptor的Bean即可Configuration public class FeignGrayTagInterceptor implements RequestInterceptor { private static final String GRAY_TAG_HEADER X-Gray-Tag; Override public void apply(RequestTemplate template) { // 从当前请求上下文里提取灰度标记 String grayTag GrayTagContextHolder.get(); if (grayTag ! null !grayTag.isEmpty()) { template.header(GRAY_TAG_HEADER, grayTag); } } }这里的GrayTagContextHolder是我做的一个ThreadLocal封装。为什么不用RequestContextHolder直接拿因为RequestContextHolder是基于RequestAttributes的在某些异步场景下不好使。而且它保存的是整个Request对象我们只需要一个字符串没必要背那么重的上下文。每一个被调用的服务入口处都要做这样一件事Component public class GrayTagMvcInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String grayTag request.getHeader(X-Gray-Tag); if (grayTag ! null !grayTag.isEmpty()) { GrayTagContextHolder.set(grayTag); } return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { // 请求结束一定要清理不然线程池复用时灰度标记会串 GrayTagContextHolder.clear(); } }这个拦截器需要注册到Spring MVC的拦截器链中。用完清理这一点非常重要如果你的服务用到了线程池请求处理完不清理下一个请求从这个线程拿到的就是上一个请求的灰度标记产生串色故障很难排查。3.4 自定义负载均衡实现版本感知路由标记已经传到每个服务了最后一步是让负载均衡看懂这个标记。Spring Cloud LoadBalancer的扩展点是对ServiceInstanceListSupplier做二次封装。核心逻辑是从注册中心获取全部实例 → 解析当前请求的X-Gray-Tag→ 按版本过滤实例 → 如果过滤结果为空按兜底策略处理。public class GrayVersionInstanceListSupplier extends DelegatingServiceInstanceListSupplier { private static final String VERSION_METADATA_KEY version; public GrayVersionInstanceListSupplier(ServiceInstanceListSupplier delegate) { super(delegate); } Override public FluxListServiceInstance get() { return getDelegate().get().map(this::filterByVersion); } private ListServiceInstance filterByVersion(ListServiceInstance instances) { String grayTag GrayTagContextHolder.get(); // 没有灰度标记直接返回稳定实例 if (grayTag null || grayTag.isEmpty()) { return filterStableInstances(instances); } MapString, String tagMap parseGrayTag(grayTag); String targetVersion tagMap.get(version); if (targetVersion null || targetVersion.isEmpty()) { return filterStableInstances(instances); } ListServiceInstance matchedInstances instances.stream() .filter(instance - { String version instance.getMetadata().get(VERSION_METADATA_KEY); return targetVersion.equals(version); }) .collect(Collectors.toList()); if (!matchedInstances.isEmpty()) { return matchedInstances; } // 兜底没有匹配的灰度实例回退到稳定实例 return filterStableInstances(instances); } private ListServiceInstance filterStableInstances(ListServiceInstance instances) { ListServiceInstance stables instances.stream() .filter(instance - instance.getMetadata().get(VERSION_METADATA_KEY) null) .collect(Collectors.toList()); return stables.isEmpty() ? instances : stables; } }需要说明的是负载均衡看的是GrayTagContextHolder不是请求头本身——因为灰度标记在服务入口已经存进上下文了负载均衡在调用链的哪个位置执行不受控制用上下文比用Request更可靠。把自定义Supplier挂到配置里Configuration public class GrayLoadBalancerConfiguration { Bean public ServiceInstanceListSupplier grayTagSupplier( DiscoveryClient discoveryClient, Environment environment) { ServiceInstanceListSupplier delegate ServiceInstanceListSupplier.builder() .withDiscoveryClient(discoveryClient) .build(environment); return new GrayVersionInstanceListSupplier(delegate); } }然后在调用方服务上标注使用这套负载均衡配置。4. 灰度策略管理从规则配置到发布节奏4.1 规则库设计与动态刷新染色不是把灰色标记写死在代码里而是要有独立的规则库。我在网关服务里做了一个简单的灰度规则表数据源用的是配置中心Nacos Config规则本身是个JSON这样修改规则不用重新发布代码{ rules: [ { name: 内测用户全量灰度, match: { type: uid_suffix, value: 9999 }, grayTag: channelsinternalversionv2.1.0 }, { name: app渠道10%灰度, match: { type: percentage, channel: app, value: 10 }, grayTag: versionv2.1.0 } ], defaultGrayTag: versionstable }规则引擎的执行顺序很重要。我的习惯是精确匹配优先百分比策略其次默认兜底最后。因为精确匹配比如指定某个测试账号是高风险操作必须优先保障百分比灰度是基于概率的默认策略无关紧要。这里分享一个实操心得百分比灰度不要用Math.random()因为随机数不可控同一个用户两次请求可能被分到不同版本体验割裂。正确做法是对用户ID做哈希取模比如uid.hashCode() % 100 10这样同一个用户始终在灰度名单里到了全量发布阶段也不会有切换的感觉。4.2 发布节奏控制从内测到全量的四步走灰度发布本质上是一个风险逐步释放的过程我总结为四个阶段第一阶段内部验证期。灰度实例部署好之后先不要对外放量。用内部测试账号、测试手机号作为固定灰度名单走一遍核心链路。这个阶段发现的Bug要立刻修因为影响范围只有一个或几个测试账号。我一般会让核心开发人员的个人账号都在灰度名单里让他们日常开发过程中就被动使用灰度环境发现问题往往比专门测试更快。第二阶段小流量观察期。内部验证没问题后放1%到5%的真实流量。这个阶段的目的是暴露真实环境才有的问题——数据量、并发、第三方依赖的差异。监控指标要盯死错误率、响应时间、GC频率、线程池活跃度。这个阶段持续时间建议至少一个完整业务周期比如一天让流量自然覆盖各种场景。第三阶段百分比放量期。从5%逐步放到10%、30%、50%。每放一次观察20到30分钟确认指标平稳再继续。如果过程中有任何指标异常立即把百分比调回上一个安全值。不要追求一步到位灰度系统存在的意义就是让你有机会停下来调整。第四阶段全量发布。百分比放到100%把稳定实例从注册中心摘除或者直接升级稳定实例到新版本。全量发布后灰度规则清空链路恢复无标记状态。全量不等于结束接下来一个小时内还要持续观察因为全量后流量分布变化可能触发新的瓶颈。4.3 灰度期间的链路可观测性灰度发布期间看不到链路状态和没有灰度一样危险。我给这套方案配套了三个基础观测工具日志染色日志框架的输出格式里加上灰度标记字段。这样排查问题的时候看到一条报错日志立刻知道它来自灰度流量还是稳定流量判断要不要优先处理。TraceId串联确保全链路有唯一TraceIdSpring Cloud Sleuth或者Micrometer Tracing都能做灰度标记关联到Trace上在链路追踪系统里可以直接筛选灰度请求的表现。业务指标对比灰度期间我习惯在关键服务里埋点输出灰度版本处理耗时稳定版本处理耗时两个指标对比曲线。版本升级后性能变差是最常见的问题有了对比指标就能第一时间发现。5. 常见问题与排查技巧实录5.1 问题一灰度标记传到一半就丢了现象网关染了色第一个服务也拿到了X-Gray-Tag但第二次OpenFeign调用时下游服务收到的Header里没有这个标记。排查过程先确认RequestInterceptor有没有生效——在Interceptor的apply方法里打印日志看看有没有执行如果执行了再确认GrayTagContextHolder里有没有值——极有可能是上游服务的入口拦截器没有把Header解析到上下文或者解析之后被异步线程丢掉了。经验除了Feign还要检查两类调用方式。第一类是RestTemplate需要单独配置RestTemplateInterceptor第二类是异步线程池比如你用了Async或者自己提交线程池执行任务线程切换后ThreadLocal里的标记直接丢失。这个问题我用TransmittableThreadLocal解决它在创建子线程时能自动复制父线程的上下文比原生ThreadLocal适合这种场景。5.2 问题二负载均衡规则不生效灰度流量打到了稳定实例现象灰度标记正常传递ServiceInstanceListSupplier的代码也写了但是被调用的服务实例依然是稳定版。排查过程Spring Cloud LoadBalancer的ServiceInstanceListSupplier有两种加载方式一种是全局配置一种是针对某个服务的配置。如果你的配置写在了LoadBalancerClients(defaultConfiguration GrayLoadBalancerConfiguration.class)但它管不到另一个包下的FeignClient就会出现规则没挂上的情况。逐个服务、逐个FeignClient检查配置生效情况是排查这类问题的快速路径。另一个坑注册中心的实例元数据缓存。Nacos客户端默认会缓存实例列表服务实例刚启动或元数据更新后客户端不一定立即感知到。可以通过Nacos控制台看实例详情里有没有version字段没有的话大概率是启动脚本没注入元数据。5.3 问题三异步线程内灰度标记串了现象一个请求的灰度标记莫名其妙出现在另一个请求的调用链里。排查过程看日志里的TraceId和灰度标记时间线基本能定位到是哪个线程复用造成的。核心原因就是线程池的工作线程被多个请求复用前一个请求处理完没有清理GrayTagContextHolder。解决除了入口Interceptor里做clean up之外在RequestInterceptor里也要做一次安全清理——发送请求前先判断当前线程有没有标记有就写入Header无论有没有都建议先clear再set。绝对不要裸用ThreadLocal而忽略清理这是所有链路透传方案最容易翻车的地方。5.4 问题四大版本升级时数据格式不兼容现象新版服务接口字段改了灰度链路内新老服务之间调用时老服务解析不了新字段。排查过程这类问题其实不是链路路由的问题而是兼容设计问题。做全链路灰度之前一定要对接口级别的字段变更做约束新增字段用默认值兜底删除字段要提前一个版本过期。如果实在无法兼容那灰度就不能只是路由到不同实例还必须配合数据库双写、缓存双读这类方案让新旧版本各用各的数据灰度结束后再做数据迁移。经验全链路灰度解决的是流量路由问题不是数据兼容问题。它降低的是发布风险但前提是新旧版本之间对外的协议要基本兼容。协议不兼容的升级再怎么灰度都救不了。5.5 快速问题排查速查表现象可能原因排查手段标记传递中断Feign/RestTemplate未配置透传检查Interceptor日志、Context内容灰度流量打到稳定实例LoadBalancer配置未生效检查LoadBalancerClients配置、注册中心元数据异步调用丢失标记线程池清空了ThreadLocal改用TransmittableThreadLocal标记串到其他请求线程复用未清理上下文请求结束后强制clear百分比灰度用户跳变用了随机数而非哈希取模改为uid取模算法灰度实例无流量Nacos元数据未及时同步检查实例详情version字段请求失败且无兜底目标版本实例离线检查兜底逻辑、实例健康检查6. 写在最后为了这套方案我做了哪些取舍回到开头那次事故。如果当时我把方案做成全链路流量染色即使订单服务升级了缓存逻辑因为入口染色的原因整个链路都会自动走新版本服务不会出现新旧版本混跑。灰度发布不是发布工具它是风险控制工具这个定位想清楚之后整个方案设计就会围绕可控而不是快。最后说几个层面的心得。第一染色标记一定要简单。能用一个Header解决的事情不要设计成三个Header能用一个字符串搞定就不要搞成对象序列化。全链路透传本身就是复杂度标记规范越复杂传递链路越容易出问题。第二先做基础监控再做灰度。灰度方案上线之前先把链路追踪、日志集中、指标监控搭好。没有可观测性灰度规则做得再好也只是盲人摸象。我现在公司的灰度发布流程里有一条硬性要求新服务接入灰度之前必须先接入链路追踪和日志标准。第三灰度规则越晚决策越好。网关染色规则不要写死在Filter里而是要做成配置中心动态下发。这样运营同学要开灰度、要切比例一行配置改下去立刻生效不用等开发改代码重新部署。第四兜底永远比规则优先。每个服务的负载均衡逻辑必须有没有匹配实例怎么办的答案。宁可让请求快速失败到稳定实例也不能让请求在链路里不断重试最后超时。灰度期间灰度版本实例突然挂掉这种情况太常见了没有兜底就是发布事故。这套思路不只适用于Spring Cloud其他微服务技术栈比如Dubbo、Service Mesh同样有对应的实现方式。核心不是某个框架的API怎么调而是给流量打标、标记全链路透传、基于标记做路由这个思路本身。框架可以变这套逻辑是通用的。