跳到主要内容

网关与灰度发布

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 组件详解
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向 yudao-cloud 的网关与灰度发布机制，系统性解析基于 Spring Cloud Gateway 的定制化实现，重点覆盖以下方面：

  • 灰度负载均衡算法：版本匹配、实例筛选、权重选择
  • 灰度请求处理流程与时序图
  • 网关安全过滤器与跨域处理
  • 路由转发与全局过滤器链
  • 灰度发布的配置示例与最佳实践（版本控制、流量分配、监控告警）

项目结构​

yudao-cloud 的网关模块基于 Spring Cloud Gateway 构建，并引入 Nacos 作为注册与配置中心，配合自研灰度负载均衡器与跨域过滤器，形成完整的网关能力。

Mermaid Diagram Code:

graph TB
subgraph "网关模块"
GW["Spring Cloud Gateway"]
GRZ["灰度过滤器<br/>GrayReactiveLoadBalancerClientFilter"]
GLB["灰度负载均衡器<br/>GrayLoadBalancer"]
CORS["跨域过滤器<br/>CorsFilter"]
CORS_RESP["跨域响应头修复<br/>CorsResponseHeaderFilter"]
end
subgraph "注册与配置"
NACOS_DIS["Nacos 服务发现"]
NACOS_CFG["Nacos 配置中心"]
end
subgraph "下游服务"
SVC["业务服务实例"]
end
GW --> GRZ
GRZ --> GLB
GLB --> NACOS_DIS
GW --> CORS
GW --> CORS_RESP
GRZ --> SVC
GW --> SVC
NACOS_DIS --> SVC
NACOS_CFG --> GW

图表来源

章节来源

核心组件​

  • 灰度负载均衡器：根据请求头 version 与 Nacos 元数据 version 进行实例筛选，并基于 Nacos 权重进行随机选择。
  • 灰度全局过滤器：拦截以 grayLb 为 scheme 的请求，替换为自定义灰度负载均衡器，完成实例选择与 URL 重建。
  • 跨域过滤器：处理 OPTIONS 预检与标准跨域响应头设置；修复响应头重复问题。
  • 路由与转发：结合 Gateway 的 Route 定义与 LoadBalancer 能力，实现请求转发与灰度分流。

章节来源

架构总览​

下图展示灰度请求从进入网关到选择实例并转发的关键交互：

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant F as "灰度过滤器"
participant L as "灰度负载均衡器"
participant N as "Nacos 注册中心"
participant S as "服务实例"
C->>F : "请求 (grayLb : //serviceId/path)"
F->>F : "检测 scheme 是否为 grayLb"
F->>L : "调用 choose() 选择实例"
L->>N : "获取可用实例列表"
N-->>L : "返回实例列表(含 metadata)"
L->>L : "按 header.version 与 metadata.version 筛选"
L->>L : "按 tag 进一步筛选"
L->>L : "基于 Nacos 权重随机选择"
L-->>F : "返回目标实例"
F->>S : "重建 URL 并转发"
S-->>C : "返回响应"

图表来源

章节来源

组件详解​

灰度负载均衡器（GrayLoadBalancer）​

  • 功能职责
    • 从请求上下文提取 Header 中的 version 字段
    • 依据 Nacos 元数据 metadata.version 进行实例筛选
    • 支持按 tag 进一步筛选
    • 基于 Nacos 权重进行随机选择
  • 关键行为
    • 若请求未携带 version 或无匹配实例，则回退到全部可用实例
    • 若无可用实例，返回空响应
  • 依赖与限制
    • 依赖 Nacos 的权重与元数据，若更换注册中心需调整权重与元数据解析逻辑

Mermaid Diagram Code:

flowchart TD
Start(["进入 choose()"]) --> GetHdr["读取请求 Header"]
GetHdr --> HasVer{"是否存在 version?"}
HasVer --> |否| UseAll["使用全部实例"]
HasVer --> |是| FilterByVer["按 metadata.version 筛选"]
FilterByVer --> Match{"是否有匹配实例?"}
Match --> |否| UseAll
Match --> |是| UseFiltered["使用筛选后实例"]
UseAll --> FilterByTag["按 tag 进一步筛选"]
UseFiltered --> FilterByTag
FilterByTag --> WeightSel["基于 Nacos 权重随机选择"]
WeightSel --> End(["返回实例"])

图表来源

章节来源

灰度全局过滤器（GrayReactiveLoadBalancerClientFilter）​

  • 功能职责
    • 识别 grayLb scheme 的请求，替换默认负载均衡器为灰度负载均衡器
    • 重建请求 URL，将选择的实例信息注入到请求属性中
    • 记录生命周期事件，便于可观测性
  • 关键行为
    • 若请求 scheme 不为 grayLb，则直接放行
    • 通过 LoadBalancerClientFactory 获取灰度负载均衡器
    • 选择实例后更新 GATEWAY_REQUEST_URL_ATTR 并继续链路

Mermaid Diagram Code:

sequenceDiagram
participant EX as "ServerWebExchange"
participant FIL as "灰度过滤器"
participant FAC as "LoadBalancerClientFactory"
participant LB as "灰度负载均衡器"
participant INS as "ServiceInstance"
EX->>FIL : "filter(exchange, chain)"
FIL->>FIL : "判断 scheme 是否为 grayLb"
alt 是
FIL->>FAC : "获取 LazyProvider(serviceId)"
FAC-->>FIL : "返回 Provider"
FIL->>LB : "new GrayLoadBalancer(...).choose()"
LB-->>FIL : "返回 ServiceInstance"
FIL->>EX : "更新 GATEWAY_REQUEST_URL_ATTR"
FIL-->>EX : "chain.filter(exchange)"
else 否
FIL-->>EX : "chain.filter(exchange)"
end

图表来源

章节来源

跨域过滤器（CorsFilter 与 CorsResponseHeaderFilter）​

  • CorsFilter
    • 识别跨域请求，设置 Access-Control-Allow-* 响应头
    • 对 OPTIONS 预检请求直接返回 200
  • CorsResponseHeaderFilter
    • 在响应写出后，修复重复的 Origin/Credentials 响应头，避免浏览器跨域异常

Mermaid Diagram Code:

flowchart TD
A["收到请求"] --> B{"是否跨域请求?"}
B --> |否| D["直接放行"]
B --> |是| C["设置跨域响应头"]
C --> E{"是否为 OPTIONS?"}
E --> |是| F["返回 200"]
E --> |否| G["继续链路"]

图表来源

章节来源

网关安全过滤器与路由转发​

  • 安全过滤器
    • 可在网关层接入鉴权、限流、参数校验等全局过滤器，建议置于灰度过滤器之前，确保灰度场景下的安全策略一致
  • 路由转发
    • 结合 Gateway 的 Route 定义与 LoadBalancer 能力，将请求转发至选定的服务实例
    • 灰度场景通过 grayLb scheme 触发灰度负载均衡器

章节来源

依赖关系分析​

  • 网关模块依赖
    • Spring Cloud Gateway：提供路由与过滤器链能力
    • Spring Cloud LoadBalancer：提供负载均衡客户端工厂与生命周期事件
    • Nacos Discovery/Config：提供服务发现与配置中心能力
    • Knife4j Gateway Starter：提供网关接口文档聚合能力
  • 灰度实现依赖
    • NacosBalancer：基于 Nacos 元数据与权重进行实例选择
    • ServiceInstanceListSupplier：拉取可用实例列表

Mermaid Diagram Code:

graph LR
POM["yudao-gateway/pom.xml"] --> GW["spring-cloud-starter-gateway"]
POM --> LB["spring-cloud-starter-loadbalancer"]
POM --> DIS["spring-cloud-starter-alibaba-nacos-discovery"]
POM --> CFG["spring-cloud-starter-alibaba-nacos-config"]
POM --> DOC["knife4j-gateway-spring-boot-starter"]
GLB["GrayLoadBalancer"] --> NACOS["NacosBalancer"]
GRZ["GrayReactiveLoadBalancerClientFilter"] --> FAC["LoadBalancerClientFactory"]
GRZ --> GLB

图表来源

章节来源

性能考量​

  • 灰度筛选复杂度
    • 版本与 tag 筛选为 O(n) 遍历，实例较多时建议控制筛选范围
  • 权重选择
    • 基于 Nacos 权重的随机选择，具备较好的均匀性；若实例权重分布不均，建议在注册时规范权重配置
  • 过滤器链顺序
    • 建议将耗时的全局过滤器（如鉴权、限流）前置，减少对灰度选择的额外开销
  • 响应头修复
    • CorsResponseHeaderFilter 在响应写出后处理，避免阻塞主链路

故障排查指南​

  • 灰度未生效
    • 检查请求 scheme 是否为 grayLb
    • 确认请求 Header 是否包含 version
    • 核对服务实例 metadata.version 是否与请求 version 一致
  • 无可用实例
    • 查看日志中“服务实例列表为空”的警告
    • 检查 Nacos 服务健康状态与实例数量
  • 跨域异常
    • 确认 CorsFilter 与 CorsResponseHeaderFilter 是否正确加载
    • 检查响应头是否出现重复的 Access-Control-Allow-Origin/Credentials

章节来源

结论​

yudao-cloud 的网关通过灰度过滤器与灰度负载均衡器实现了基于请求头版本号与标签的精细化流量控制，结合 Nacos 的元数据与权重，能够灵活地进行灰度发布与流量分配。配合跨域过滤器与可扩展的全局过滤器链，网关在保证安全性的同时，提供了良好的可观测性与运维体验。

附录​

灰度发布配置示例与最佳实践​

  • 版本控制
    • 在服务实例注册时，通过 Nacos 元数据设置 version 与 tag
    • 客户端请求时携带 Header: version=xxx
  • 流量分配
    • 使用 Nacos 权重对不同版本实例进行流量分配
    • 建议先小流量灰度，逐步提升权重
  • 路由与转发
    • 网关 Route 使用 grayLb://serviceId 形式触发灰度负载均衡
  • 监控与告警
    • 借助 SkyWalking 与 Prometheus 对网关与服务实例进行全链路观测
    • 关注灰度实例的响应时间、错误率与流量占比

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答