上線別再“一刀切”！Gateway 做流量染色 + 灰度發布，告別線上事故

作者：儒猿團隊 2025-09-24 09:32:05

那咋辦？答案就是 “灰度發布”—— 先挑一小撮用戶試試水，沒問題再慢慢擴大范圍，就算出問題，影響也可控。而要實現灰度發布，第一步就得給流量 “打標簽”，也就是咱們今天的主角之一：流量染色。

兄弟們，大家有沒有過半夜被運維電話炸醒的經歷？手機屏幕一亮，看到 “線上服務大面積報錯” 的消息，腦子瞬間懵圈，頂著黑眼圈打開電腦，手指在鍵盤上亂敲，心里瘋狂吐槽 “昨天全量發布的時候明明好好的啊！”

我猜大部分人都有過這種 “渡劫” 時刻。說實話，全量發布這事兒，就像閉眼過馬路 —— 不出事是運氣，出事是必然。你永遠不知道用戶的某個奇葩操作、某個邊緣場景，會把你精心寫的代碼干到崩潰。

但自從我學會用 Gateway 做流量染色 + 灰度發布后，別說半夜被叫醒了，就連上線前的焦慮癥都治好了。今天就把這套 “保命技能” 掰開揉碎了講，保證哪怕是剛接觸微服務的兄弟，也能看得明明白白，下次上線再也不用 “一刀切”！

一、先掰扯清楚：為啥全量發布是 “自殺式操作”？

在講 Gateway 之前，咱得先統一戰線：別再迷信全量發布了！哪怕你單元測試、集成測試、壓測都跑了個遍，一到線上全是 “驚喜”。

我之前遇過一個坑：團隊開發了個商品詳情頁優化功能，壓測時 QPS 能扛 2000，結果全量發布后 5 分鐘，服務直接崩了。查了半天才發現，線上有個老用戶的收貨地址有 100 多個，頁面渲染時循環遍歷直接棧溢出 —— 這場景壓測根本模擬不到！

還有更絕的：有次全量發布支付模塊，結果發現新代碼和第三方支付接口的加密算法不兼容，用戶付了錢卻顯示 “未支付”，客服電話被打爆，最后只能回滾，光賠償損失就花了小十萬。

這些事兒不是個例，本質上全量發布有個致命缺陷：把所有用戶當成 “小白鼠”，一旦出問題，影響范圍是 100% 。就像你新學了道菜，直接端給 100 個客人試吃，萬一鹽放多了，所有人都得吐，連補救的機會都沒有。

二、Gateway：微服務里的 “交通警察”，染色 + 路由一把抓

說到流量染色和灰度路由，為啥非得選 Gateway？不能用 Nginx 嗎？

先給大家交個底：Nginx 確實能做簡單的灰度，但靈活性太差。比如你想按 “用戶等級”“設備類型” 來區分流量，Nginx 配置能寫得你懷疑人生，而且改配置還得重啟，線上操作風險高。

而 Spring Cloud Gateway 不一樣，它是基于 Java 開發的，和微服務生態天然契合，能輕松集成 Spring Boot、Spring Cloud 的各種組件，而且支持動態路由、自定義過濾器 —— 簡單說，它就像個 “智能交通警察”，既能給每輛車（流量）貼標簽（染色），又能根據標簽指揮車往哪條路（服務版本）走，還不用 “下崗培訓”（重啟）。

咱先花 2 分鐘搞懂 Gateway 的核心邏輯：所有請求都會先經過 Gateway，Gateway 里有兩類關鍵組件：

過濾器（Filter）：能在請求到達服務前、響應返回用戶前做手腳，比如加請求頭、改參數 —— 這就是用來做流量染色的關鍵；
路由（Route）：根據請求的特征（比如請求頭、參數），把請求轉發到不同的服務地址 —— 這就是灰度發布的核心。

簡單說：用 Filter 給流量 “染色”，用 Route 按 “顏色” 分發給不同版本的服務。一套組合拳下來，灰度發布就成了！

三、手把手教你：用 Gateway 給流量 “染色”，3 步搞定！

流量染色聽起來玄乎，其實就是給請求加個 “標識”—— 比如在請求頭里加個X-Traffic-Tag: gray，或者在參數里加個traffic_tag=beta。但染色不是瞎加的，得有章法，不然后續路由會亂套。

咱以 Spring Cloud Gateway 為例，一步步實現 “靠譜的流量染色”，代碼都給你們貼好了，直接抄作業就行！

3.1 第一步：確定染色維度，別瞎染！

先想清楚：你要按什么維度給流量分類？不同場景選的維度不一樣，選對了后續灰度才靈活。

常見的染色維度有這么幾種，給大家列個表，按需挑選：

染色維度	適用場景	優點	缺點
用戶 ID	精準定位用戶（比如 VIP 用戶優先體驗新功能）	粒度細，可回溯	需要知道用戶 ID，匿名用戶不適用
設備號	按設備類型（iOS/Android）或指定設備測試	穩定，設備不變標識就不變	設備號可能獲取不到
地域	按城市灰度（比如先在上海試點）	符合業務擴張邏輯	地域劃分太粗，可能覆蓋不準
自定義參數	內部測試（比如加test=1的請求）	靈活，不影響真實用戶	需要手動傳參，不方便大規模用
比例染色	隨機選 10% 用戶試錯	不用區分用戶，實現簡單	不可回溯，出問題找不到具體用戶

我個人最常用的是 “用戶 ID + 比例染色” 組合 —— 平時用比例染色做隨機灰度，遇到問題時用用戶 ID 精準定位，兩不誤。

3.2 第二步：寫個過濾器，給流量 “蓋戳”！

確定好維度后，就該在 Gateway 里寫過濾器了。這里用 Spring Cloud Gateway 的GlobalFilter（全局過濾器），所有經過 Gateway 的請求都會被攔截，然后加上染色標識。

咱先實現一個 “按用戶 ID 尾號染色” 的例子：比如用戶 ID 尾號是 1 的，染成 “gray”（灰度流量），其他的染成 “normal”（正常流量）。

代碼如下，注釋寫得明明白白，新手也能看懂：

import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.http.server.reactive.ServerHttpRequest;
import reactor.core.publisher.Mono;
@Configuration
public class TrafficDyeFilterConfig {
    // 全局過濾器，Order值越小，執行優先級越高
    @Bean
    @Order(-1) // 比默認過濾器先執行，避免染色標識被覆蓋
    public GlobalFilter trafficDyeFilter() {
        return (exchange, chain) -> {
            // 1. 獲取請求對象
            ServerHttpRequest request = exchange.getRequest();
            
            // 2. 從請求中獲取用戶ID（這里假設用戶ID存在請求頭里，key是X-User-ID）
            String userId = request.getHeaders().getFirst("X-User-ID");
            
            // 3. 定義染色標識，默認是normal
            String trafficTag = "normal";
            
            // 4. 按用戶ID尾號染色：尾號是1的歸為gray
            if (userId != null && !userId.isEmpty()) {
                // 取用戶ID最后一位字符
                char lastChar = userId.charAt(userId.length() - 1);
                if (lastChar == '1') {
                    trafficTag = "gray";
                }
            }
            
            // 5. 給請求加染色標識（放在請求頭里，key是X-Traffic-Tag）
            ServerHttpRequest modifiedRequest = request.mutate()
                    .header("X-Traffic-Tag", trafficTag)
                    .build();
            
            // 6. 把修改后的請求傳給下一個過濾器/路由
            return chain.filter(exchange.mutate().request(modifiedRequest).build())
                    // 7. 響應返回后，可做一些日志記錄（非必須，可選）
                    .then(Mono.fromRunnable(() -> {
                        System.out.println("請求URL：" + request.getURI() + "，染色標識：" + trafficTag);
                    }));
        };
    }
}

這段代碼有兩個關鍵點要注意：

Order(-1) ：必須讓染色過濾器先執行，不然其他過濾器可能會覆蓋你加的染色頭；
染色標識放在請求頭：比放在參數里安全，而且不會被 URL 編碼影響，后續跨服務傳遞也方便。

如果想做 “比例染色”（比如隨機 10% 流量染成 gray），只需改第 4 步的邏輯：

// 比例染色：10%的概率染成gray
double random = Math.random();
if (random < 0.1) {
    trafficTag = "gray";
}

是不是很簡單？這樣一來，所有經過 Gateway 的請求，都被打上了 “X-Traffic-Tag” 的標識，下一步就是按這個標識路由了。

3.3 第三步：驗證染色是否生效，別瞎忙活！

寫好過濾器后，得驗證一下染色有沒有成功，不然白忙活。這里教大家兩種簡單的驗證方法：

方法 1：用 Postman 測

發送請求時，在請求頭里加X-User-ID: 123451（尾號是 1）；
看 Gateway 的日志，或者在后續服務里打印請求頭，看有沒有X-Traffic-Tag: gray；
再換個用戶 IDX-User-ID: 123452（尾號不是 1），應該能看到X-Traffic-Tag: normal。

方法 2：用 Gateway 的 Actuator 端點看

Gateway 自帶了監控端點，配置一下就能看所有請求的詳情：

在 pom.xml 里加依賴：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

在 application.yml 里開端點：

management:
  endpoints:
    web:
      exposure:
        include: gateway,httptrace # 開放gateway和httptrace端點

訪問http://網關地址/actuator/httptrace，就能看到每個請求的請求頭，里面有沒有X-Traffic-Tag一目了然。

到這里，流量染色就搞定了。接下來就是重頭戲：怎么用這個染色標識，實現灰度發布。

四、灰度發布落地：讓不同 “顏色” 的流量走不同的服務

染色的最終目的，是讓 “gray” 標識的流量走新服務版本，“normal” 的走舊版本。這一步要靠 Gateway 的路由規則來實現。

咱先假設一個場景：

舊服務版本（V1）：地址是http://service-product-v1:8080，處理 “normal” 流量；
新服務版本（V2）：地址是http://service-product-v2:8080，處理 “gray” 流量；
商品服務的請求路徑是/api/product/**。

接下來分兩種方式實現路由：靜態配置和動態路由（推薦）。

4.1 方式 1：靜態配置，簡單直接（適合小場景）

直接在 application.yml 里寫路由規則，Gateway 會自動加載。配置如下：

spring:
  cloud:
    gateway:
      routes:
        # 路由1：處理gray流量，轉發到V2版本
        - id: product-service-gray
          uri: http://service-product-v2:8080
          predicates:
            # 匹配路徑：/api/product/**
            - Path=/api/product/**
            # 匹配染色標識：X-Traffic-Tag=gray
            - Header=X-Traffic-Tag, gray
          filters:
            # 去掉前綴（比如請求/api/product/1，轉發到/service/product/1）
            - StripPrefix=1
            # 加個日志過濾器，方便排查
            - name: LogFilter
              args:
                logMessage: "灰度流量轉發到V2"
        
        # 路由2：處理normal流量，轉發到V1版本
        - id: product-service-normal
          uri: http://service-product-v1:8080
          predicates:
            - Path=/api/product/**
            - Header=X-Traffic-Tag, normal
          filters:
            - StripPrefix=1
            - name: LogFilter
              args:
                logMessage: "正常流量轉發到V1"
        
        # 路由3：默認路由（防止染色失敗時請求迷路）
        - id: product-service-default
          uri: http://service-product-v1:8080
          predicates:
            - Path=/api/product/**
          filters:
            - StripPrefix=1
            - name: LogFilter
              args:
                logMessage: "默認流量轉發到V1"

這里有個關鍵邏輯：路由的匹配順序。Gateway 會按 routes 里的順序匹配，所以必須把 “gray” 和 “normal” 的路由放在前面，默認路由放在最后 —— 不然所有請求都會走默認路由，灰度就失效了。測試一下：用用戶 ID 尾號 1 的請求（染色為 gray），會轉發到 V2；其他用戶的請求（normal），轉發到 V1。完美！

但這種方式有個缺點：改路由規則得改配置文件，還得重啟 Gateway—— 線上環境重啟風險高，而且不能實時調整灰度比例。所以更推薦用 “動態路由”。

4.2 方式 2：動態路由，實時調整（生產環境必備）

動態路由的核心是：路由規則存在數據庫（比如 MySQL）或配置中心（比如 Nacos/Apollo）里，Gateway 能實時讀取變更，不用重啟。

咱以 Nacos 為例，教大家實現動態路由。步驟有點多，但都是干貨，耐心看完！

第一步：集成 Nacos 配置中心

加依賴：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

配置 Nacos 地址（bootstrap.yml，比 application.yml 加載早）：

spring:
  application:
    name: gateway-service # 服務名，對應Nacos里的配置文件名
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848 # Nacos地址
        file-extension: yaml # 配置文件格式
        group: DEFAULT_GROUP # 配置分組

第二步：寫動態路由加載邏輯

核心是實現RouteDefinitionRepository接口，從 Nacos 讀取路由配置，然后注冊到 Gateway 里。

先定義一個 Nacos 路由配置類：

import com.alibaba.nacos.api.NacosFactory;
import com.alibaba.nacos.api.config.ConfigService;
import com.alibaba.nacos.api.exception.NacosException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.gateway.route.RouteDefinition;
import org.springframework.cloud.gateway.route.RouteDefinitionRepository;
import org.springframework.cloud.gateway.support.NotFoundException;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.TypeReference;
import javax.annotation.PostConstruct;
import java.util.List;
import java.util.Properties;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
@Component
public class NacosRouteDefinitionRepository implements RouteDefinitionRepository {
    // 存儲路由定義的Map
    private final ConcurrentMap<String, RouteDefinition> routes = new ConcurrentHashMap<>();
    // Nacos配置服務
    private ConfigService configService;
    // 從配置文件讀取Nacos地址
    @Value("${spring.cloud.nacos.config.server-addr}")
    private String nacosServerAddr;
    // 路由配置在Nacos里的DataId（格式：服務名+擴展名）
    private static final String DATA_ID = "gateway-service.yaml";
    // 路由配置在Nacos里的Group
    private static final String GROUP = "DEFAULT_GROUP";
    // 初始化：加載Nacos配置，并監聽配置變更
    @PostConstruct
    public void init() {
        try {
            // 初始化Nacos ConfigService
            Properties properties = new Properties();
            properties.put("serverAddr", nacosServerAddr);
            configService = NacosFactory.createConfigService(properties);
            // 1. 首次加載配置
            loadRouteConfig();
            // 2. 監聽配置變更（Nacos里改了配置，Gateway實時更新）
            configService.addListener(DATA_ID, GROUP, configInfo -> {
                System.out.println("Nacos路由配置變更，重新加載：" + configInfo);
                loadRouteConfig();
            });
        } catch (NacosException e) {
            throw new RuntimeException("初始化Nacos路由失敗", e);
        }
    }
    // 加載Nacos里的路由配置
    private void loadRouteConfig() {
        try {
            // 從Nacos獲取配置
            String config = configService.getConfig(DATA_ID, GROUP, 5000);
            if (config == null || config.isEmpty()) {
                System.out.println("Nacos里沒有路由配置");
                return;
            }
            // 把配置JSON轉成List<RouteDefinition>（Nacos里的配置格式要和這個對應）
            List<RouteDefinition> routeDefinitions = JSON.parseObject(
                    config, new TypeReference<List<RouteDefinition>>() {}
            );
            // 清空舊路由，加載新路由
            routes.clear();
            for (RouteDefinition route : routeDefinitions) {
                routes.put(route.getId(), route);
            }
        } catch (NacosException e) {
            throw new RuntimeException("加載Nacos路由配置失敗", e);
        }
    }
    // 讀取所有路由（Gateway會調用這個方法獲取路由）
    @Override
    public Flux<RouteDefinition> getRouteDefinitions() {
        return Flux.fromIterable(routes.values());
    }
    // 保存路由（按需實現，這里用不到）
    @Override
    public Mono<Void> save(Mono<RouteDefinition> route) {
        return route.flatMap(routeDefinition -> {
            routes.put(routeDefinition.getId(), routeDefinition);
            return Mono.empty();
        });
    }
    // 刪除路由（按需實現，這里用不到）
    @Override
    public Mono<Void> delete(Mono<String> routeId) {
        return routeId.flatMap(id -> {
            routes.remove(id);
            return Mono.empty();
        });
    }
}

第三步：在 Nacos 里寫路由配置

登錄 Nacos 控制臺（http://127.0.0.1:8848/nacos），新建配置：

Data ID：gateway-service.yaml（和代碼里的 DATA_ID 一致）
Group：DEFAULT_GROUP
配置內容：和之前的靜態配置類似，寫成 JSON 數組格式（因為代碼里是轉 List）：

[
  {
    "id": "product-service-gray",
    "uri": "http://service-product-v2:8080",
    "predicates": [
      {
        "name": "Path",
        "args": {
          "_genkey_0": "/api/product/**"
        }
      },
      {
        "name": "Header",
        "args": {
          "_genkey_0": "X-Traffic-Tag",
          "_genkey_1": "gray"
        }
      }
    ],
    "filters": [
      {
        "name": "StripPrefix",
        "args": {
          "_genkey_0": "1"
        }
      },
      {
        "name": "LogFilter",
        "args": {
          "logMessage": "灰度流量轉發到V2"
        }
      }
    ]
  },
  {
    "id": "product-service-normal",
    "uri": "http://service-product-v1:8080",
    "predicates": [
      {
        "name": "Path",
        "args": {
          "_genkey_0": "/api/product/**"
        }
      },
      {
        "name": "Header",
        "args": {
          "_genkey_0": "X-Traffic-Tag",
          "_genkey_1": "normal"
        }
      }
    ],
    "filters": [
      {
        "name": "StripPrefix",
        "args": {
          "_genkey_0": "1"
        }
      }
    ]
  },
  {
    "id": "product-service-default",
    "uri": "http://service-product-v1:8080",
    "predicates": [
      {
        "name": "Path",
        "args": {
          "_genkey_0": "/api/product/**"
        }
      }
    ],
    "filters": [
      {
        "name": "StripPrefix",
        "args": {
          "_genkey_0": "1"
        }
      }
    ]
  }
]

保存后，Gateway 會自動加載這個配置。如果想調整灰度比例，比如把 “gray” 的比例從 10% 調到 20%，只需改一下染色過濾器的邏輯，或者在 Nacos 里改路由規則（比如加個新的染色標識gray2），不用重啟 Gateway—— 實時生效，這才是生產環境該有的樣子！

五、進階技巧：別踩這些坑！染色 + 灰度的 “避坑指南”

講到這里，基礎的染色和灰度已經能跑通了，但線上環境比 demo 復雜得多，我踩過的坑，你們就別再踩了！

5.1 坑 1：染色標識在跨服務調用時丟了！

問題場景：Gateway 給請求加了X-Traffic-Tag: gray，轉發到服務 A，服務 A 又調用服務 B，結果服務 B 的請求頭里沒有這個標識了 —— 導致服務 B 不知道該走哪個版本。

原因：跨服務調用時（比如 Feign、Dubbo），默認不會傳遞自定義請求頭。

解決方案：

（1）Feign 調用傳遞染色標識

寫個 Feign 攔截器，把請求頭里的X-Traffic-Tag傳遞下去：

import feign.RequestInterceptor;
import feign.RequestTemplate;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;

@Component
publicclass FeignTrafficTagInterceptor implements RequestInterceptor {

    @Override
    public void apply(RequestTemplate template) {
        // 獲取當前請求的上下文
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        if (attributes == null) {
            return;
        }

        HttpServletRequest request = attributes.getRequest();
        // 從請求頭獲取染色標識，傳遞到Feign調用的請求頭里
        String trafficTag = request.getHeader("X-Traffic-Tag");
        if (trafficTag != null && !trafficTag.isEmpty()) {
            template.header("X-Traffic-Tag", trafficTag);
        }
    }
}

（2）Dubbo 調用傳遞染色標識

Dubbo 可以用過濾器傳遞標識，配置dubbo.provider.filter和dubbo.consumer.filter：

寫個 Dubbo 過濾器：

import org.apache.dubbo.common.constants.CommonConstants;
import org.apache.dubbo.common.extension.Activate;
import org.apache.dubbo.rpc.*;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;

@Activate(group = {CommonConstants.PROVIDER, CommonConstants.CONSUMER})
publicclass DubboTrafficTagFilter implements Filter {

    @Override
    public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
        // 消費者端：把染色標識放到Dubbo的attachment里
        if (CommonConstants.CONSUMER_SIDE.equals(invoker.getUrl().getParameter(CommonConstants.SIDE_KEY))) {
            ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
            if (attributes != null) {
                HttpServletRequest request = attributes.getRequest();
                String trafficTag = request.getHeader("X-Traffic-Tag");
                if (trafficTag != null) {
                    invocation.getAttachments().put("X-Traffic-Tag", trafficTag);
                }
            }
        }

        // 提供者端：從attachment里獲取染色標識，放到ThreadLocal里（后續服務可用）
        if (CommonConstants.PROVIDER_SIDE.equals(invoker.getUrl().getParameter(CommonConstants.SIDE_KEY))) {
            String trafficTag = invocation.getAttachment("X-Traffic-Tag");
            if (trafficTag != null) {
                // 用ThreadLocal存儲，服務里可以隨時獲取
                TrafficTagHolder.set(trafficTag);
            }
        }

        try {
            return invoker.invoke(invocation);
        } finally {
            // 清除ThreadLocal，避免內存泄漏
            if (CommonConstants.PROVIDER_SIDE.equals(invoker.getUrl().getParameter(CommonConstants.SIDE_KEY))) {
                TrafficTagHolder.remove();
            }
        }
    }
}

在META-INF/dubbo/org.apache.dubbo.rpc.Filter文件里注冊過濾器：

dubboTrafficTagFilter=com.xxx.filter.DubboTrafficTagFilter

在 application.yml 里配置：

dubbo:
  provider:
    filter: dubboTrafficTagFilter
  consumer:
    filter: dubboTrafficTagFilter

5.2 坑 2：部分請求沒經過 Gateway，染色失效！

問題場景：有些請求直接調用后端服務（比如運維調試、第三方接口調用），沒走 Gateway，導致沒有染色標識，可能會訪問到錯誤的服務版本。

解決方案：

所有服務只允許 Gateway 訪問：在服務的防火墻或 Nginx 里配置，只放行 Gateway 的 IP；
加鑒權攔截：在每個服務里加攔截器，如果請求沒有X-Traffic-Tag標識，直接返回 403；

import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

publicclass TrafficTagAuthInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String trafficTag = request.getHeader("X-Traffic-Tag");
        // 沒有染色標識，返回403
        if (trafficTag == null || trafficTag.isEmpty()) {
            response.setStatus(403);
            response.getWriter().write("No Traffic Tag, Forbidden");
            returnfalse;
        }
        returntrue;
    }
}

網關層加白名單：如果確實有特殊請求需要直接訪問服務，在 Gateway 里加白名單，手動給這些請求加染色標識。

5.3 坑 3：灰度切換時，新服務扛不住流量！

問題場景：突然把 20% 的流量切到新服務，新服務沒經過壓測，直接被打崩，導致灰度用戶報錯。

解決方案：

先小比例灰度：剛開始只給 1%~5% 的流量，觀察新服務的 QPS、CPU、內存，沒問題再慢慢加；
加限流熔斷：在 Gateway 或新服務里加限流，比如用 Sentinel，當新服務 QPS 超過閾值時，自動把流量切回舊服務；
快速回滾機制：一旦發現新服務有問題，在 Nacos 里改路由規則，把 gray 流量重新指向舊服務，10 秒內就能生效。

5.4 坑 4：染色標識被覆蓋！

問題場景：后端服務里有代碼也用了X-Traffic-Tag這個請求頭，把 Gateway 加的標識覆蓋了，導致路由混亂。

解決方案：

統一標識前綴：規定所有染色相關的標識都用X-Gray-開頭，比如X-Gray-Tag，避免和業務代碼沖突；
文檔化標識：把染色標識的定義、用途寫進開發文檔，提醒所有開發人員不要用這些標識；
網關層鎖定標識：在 Gateway 的過濾器里，給染色標識加 “鎖定”，后續過濾器不能修改這個標識（可以用request.mutate().header()時，先判斷是否已有該標識，有就不修改）。

六、實際案例：某電商平臺用 Gateway 灰度發布的全過程

光說理論不夠，給大家講個我參與過的實際案例，看看這套方案在生產環境怎么用。

去年幫一個電商客戶做 “618” 活動前的灰度發布，他們要上線一個商品推薦新算法，擔心直接全量出問題，所以用 Gateway 做灰度。

步驟 1：確定染色維度

選了 “用戶等級 + 比例” 組合：

VIP 用戶（等級 >=5）：100% 走新算法（V2）；
普通用戶：先給 5% 的流量走 V2，沒問題再加到 20%，最后全量。

步驟 2：實現染色過濾器

在 Gateway 里寫了過濾器，邏輯如下：

// 獲取用戶等級（從JWT令牌里解析）
Integer userLevel = getUserLevelFromJwt(request);
if (userLevel != null && userLevel >= 5) {
    trafficTag = "gray-vip"; // VIP用戶的染色標識
} else {
    // 普通用戶5%概率走灰度
    if (Math.random() < 0.05) {
        trafficTag = "gray-normal";
    } else {
        trafficTag = "normal";
    }
}

步驟 3：配置動態路由

在 Nacos 里配置路由：

gray-vip和gray-normal的流量轉發到 V2（新算法）；
normal的流量轉發到 V1（舊算法）。

步驟 4：監控與調整

上線后，用 Prometheus+Grafana 監控新服務的指標：

前 2 小時：新服務 QPS 穩定在 500，錯誤率 0.1%，沒問題；
第 3 小時：把普通用戶的灰度比例調到 10%，QPS 升到 1000，CPU 使用率 40%，還能扛；
第 6 小時：發現新服務的推薦接口響應時間從 50ms 升到 150ms，排查后發現是 Redis 緩存沒命中，加了緩存后恢復正常；
第 12 小時：把普通用戶比例調到 20%，觀察 12 小時沒問題，最后在 “618” 前 2 天全量發布。

整個過程沒出任何線上事故，灰度用戶也沒感知到切換，完美！

七、總結：Gateway 灰度發布的核心價值

講了這么多，最后總結一下：Gateway 做流量染色 + 灰度發布，不是什么高深技術，但能解決線上發布的大問題。它的核心價值在于：

風險可控：把問題限制在小范圍用戶，避免全量崩潰；
靈活調整：動態路由支持實時調整灰度比例，不用重啟服務；
成本低：和 Java 微服務生態無縫集成，不用引入額外中間件；
可回溯：染色標識能跟蹤到具體用戶，方便排查問題。

最后給大家一個建議：別等出了線上事故再想起灰度發布，現在就把這套方案落地到你的項目里。下次上線時，你會發現：原來上線也能這么安心，再也不用半夜起來 “渡劫” 了！

責任編輯：武曉燕來源：石杉的架構筆記

Gateway 流量灰度發布