负载均衡策略

引用文件

本文引用的文件

• GrayLoadBalancer.java
• GrayReactiveLoadBalancerClientFilter.java
• EnvUtils.java
• EnvLoadBalancerClient.java
• application.yaml
• README.md

目录

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

简介

本文件面向 yudao-cloud 的灰度负载均衡策略，系统性阐述版本匹配算法、实例筛选逻辑与权重计算机制；深入解析 GrayLoadBalancer 的核心实现，包括请求头解析、服务实例过滤与基于 Nacos 权重的随机选择算法；说明基于 tag 的实例过滤机制与版本不匹配时的回退策略；并提供配置参数说明、使用示例与故障排查指南。

项目结构

灰度负载均衡能力由网关侧的全局过滤器与自定义负载均衡器共同实现，并复用环境标签（tag）的实例过滤逻辑。

Mermaid Diagram Code:

graph TB
subgraph "网关层"
F["GrayReactiveLoadBalancerClientFilter<br/>全局过滤器"]
L["GrayLoadBalancer<br/>灰度负载均衡器"]
end
subgraph "工具与上下文"
U["EnvUtils<br/>请求头/实例标签解析"]
E["EnvLoadBalancerClient<br/>环境标签负载均衡(参考实现)"]
end
subgraph "注册中心"
N["Nacos 注册中心<br/>实例+元数据"]
end
subgraph "下游服务"
S["ServiceInstance<br/>服务实例"]
end
F --> L
L --> U
L --> N
N --> S
E -. 参考 .-> L

图表来源

• GrayReactiveLoadBalancerClientFilter.java
• GrayLoadBalancer.java
• EnvUtils.java
• EnvLoadBalancerClient.java

章节来源

• GrayReactiveLoadBalancerClientFilter.java
• GrayLoadBalancer.java
• EnvUtils.java
• EnvLoadBalancerClient.java

核心组件

• 灰度全局过滤器：拦截 grayLb 协议的请求，注入负载均衡生命周期并委派给 GrayLoadBalancer 选择实例。
• 灰度负载均衡器：从请求头提取版本号与标签，按版本与标签双维度筛选实例，再基于 Nacos 权重进行随机选择。
• 环境标签工具：统一解析请求头 tag 与实例元数据 tag，支持特殊占位符解析为主机名。
• 环境标签负载均衡（参考）：展示仅基于 tag 的实例过滤与权重选择思路，灰度 LB 复用其 tag 过滤逻辑。

章节来源

• GrayReactiveLoadBalancerClientFilter.java
• GrayLoadBalancer.java
• EnvUtils.java
• EnvLoadBalancerClient.java

架构总览

灰度请求处理时序如下：

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant G as "GrayReactiveLoadBalancerClientFilter"
participant LB as "GrayLoadBalancer"
participant N as "Nacos 注册中心"
participant I as "ServiceInstance"
C->>G : "发起请求 (Header : version/tag)"
G->>G : "判断 URL Scheme 是否为 grayLb"
G->>LB : "调用 choose() 选择实例"
LB->>N : "获取可用实例列表(含 metadata)"
N-->>LB : "返回实例列表"
LB->>LB : "按 version 筛选(无匹配则回退)"
LB->>LB : "按 tag 过滤(无匹配则回退)"
LB->>LB : "基于 Nacos 权重随机选择"
LB-->>G : "返回目标 ServiceInstance"
G->>I : "转发请求"
I-->>C : "返回响应"

图表来源

• README.md
• GrayReactiveLoadBalancerClientFilter.java
• GrayLoadBalancer.java

组件详解

GrayLoadBalancer：灰度负载均衡器

• 请求头解析
  • 版本字段：从请求头读取 version，用于按服务元数据 version 进行实例筛选。
  • 标签字段：从请求头读取 tag，用于按服务元数据 tag 进行实例筛选。
• 实例筛选逻辑
  • 版本匹配：若请求头携带 version，仅保留元数据 version 相等的实例；若无匹配或无 version 头，则回退到全部实例。
  • 标签匹配：在版本筛选结果上进一步按 tag 过滤；若无匹配或无 tag 头，则回退到当前集合。
• 权重计算与选择
  • 在最终候选实例集中，使用 Nacos 的随机权重算法进行实例选择。
• 关键注意
  • 当前权重依赖 Nacos 的 nacos.weight；若更换注册中心，需调整权重选择逻辑。

Mermaid Diagram Code:

flowchart TD
Start(["进入 choose()"]) --> GetHdr["读取请求头: version/tag"]
GetHdr --> FetchInst["获取实例列表(来自注册中心)"]
FetchInst --> Empty{"实例为空?"}
Empty --> |是| ReturnEmpty["返回空响应"]
Empty --> |否| CheckVersion{"存在 version?"}
CheckVersion --> |否| KeepAll["保留全部实例"]
CheckVersion --> |是| FilterByVer["按 version 过滤"]
FilterByVer --> VerEmpty{"过滤后为空?"}
VerEmpty --> |是| KeepAll
VerEmpty --> |否| NextStep["继续"]
KeepAll --> NextStep["继续"]
NextStep --> FilterByTag["按 tag 过滤(若存在)"]
FilterByTag --> TagEmpty{"过滤后为空?"}
TagEmpty --> |是| UseCurrent["使用当前集合(回退)"]
TagEmpty --> |否| UseFiltered["使用过滤后集合"]
UseCurrent --> Select["基于 Nacos 权重随机选择"]
UseFiltered --> Select
Select --> Done(["返回选择结果"])
ReturnEmpty --> Done

图表来源

• GrayLoadBalancer.java

章节来源

• GrayLoadBalancer.java

GrayReactiveLoadBalancerClientFilter：灰度全局过滤器

• 功能职责
  • 识别 grayLb 协议的请求，注入负载均衡生命周期回调。
  • 直接构造 GrayLoadBalancer 并委派实例选择，替代默认的 ReactiveLoadBalancerClientFilter。
• 生命周期与错误处理
  • 正常流程：记录生命周期事件、更新请求 URL、写入响应上下文。
  • 异常流程：触发生命周期完成事件并抛出未找到实例异常。
• 回退策略
  • 若非 grayLb 协议，直接放行至后续过滤器链。

Mermaid Diagram Code:

sequenceDiagram
participant EX as "ServerWebExchange"
participant F as "GrayReactiveLoadBalancerClientFilter"
participant CF as "LoadBalancerClientFactory"
participant LB as "GrayLoadBalancer"
participant CH as "GatewayFilterChain"
EX->>F : "filter(exchange, chain)"
F->>F : "判断是否 grayLb"
alt 非 grayLb
F->>CH : "直接放行"
else grayLb
F->>CF : "获取 LoadBalancerClientFactory"
F->>LB : "构造 GrayLoadBalancer"
F->>LB : "choose(lbRequest)"
LB-->>F : "返回 Response<ServiceInstance>"
F->>EX : "更新请求 URL/上下文"
F->>CH : "继续链路"
end

图表来源

• GrayReactiveLoadBalancerClientFilter.java

章节来源

• GrayReactiveLoadBalancerClientFilter.java

基于 tag 的实例过滤机制

• 请求头与实例元数据
  • 请求头 tag：可通过特殊占位符解析为主机名，便于本地调试。
  • 实例元数据 tag：来源于服务实例的 metadata。
• 过滤策略
  • 若请求头存在 tag，仅保留元数据 tag 相等的实例；若无匹配或无 tag，则回退到全部实例。
• 与版本匹配的关系
  • tag 过滤在版本过滤之后执行，确保先按版本缩小候选集，再按环境标签进一步收敛。

章节来源

• EnvUtils.java
• GrayLoadBalancer.java
• EnvLoadBalancerClient.java

版本不匹配时的回退策略

• 版本匹配失败或缺失时，灰度 LB 会回退到全部可用实例，保证服务可用性。
• 该策略与 tag 过滤相互独立：即使版本回退，仍可按 tag 进一步筛选。

章节来源

• GrayLoadBalancer.java

权重计算机制

• 当前实现
  • 在候选实例集中，使用 Nacos 的随机权重算法进行实例选择。
• 扩展建议
  • 若更换注册中心，需替换为对应注册中心提供的权重选择实现。

章节来源

• GrayLoadBalancer.java

依赖关系分析

• 组件耦合
  • GrayReactiveLoadBalancerClientFilter 依赖 GrayLoadBalancer；GrayLoadBalancer 依赖 EnvUtils 与 Nacos 权重选择。
  • EnvLoadBalancerClient 提供了仅基于 tag 的过滤与权重选择思路，灰度 LB 复用其 tag 过滤逻辑。
• 外部依赖
  • Nacos 注册中心提供服务实例列表与元数据（version/tag）。
  • Spring Cloud LoadBalancer 提供基础的负载均衡抽象与生命周期回调。

Mermaid Diagram Code:

classDiagram
class GrayReactiveLoadBalancerClientFilter {
+filter(exchange, chain)
-choose(lbRequest, serviceId, processors)
}
class GrayLoadBalancer {
+choose(request)
-getInstanceResponse(instances, headers)
-filterTagServiceInstances(instances, headers)
}
class EnvUtils {
+getTag(headers)
+getTag(instance)
}
class EnvLoadBalancerClient {
+choose(request)
-getInstanceResponse(instances, tag)
}
GrayReactiveLoadBalancerClientFilter --> GrayLoadBalancer : "构造并委派"
GrayLoadBalancer --> EnvUtils : "解析 tag/version"
EnvLoadBalancerClient ..> GrayLoadBalancer : "tag 过滤逻辑参考"

图表来源

• GrayReactiveLoadBalancerClientFilter.java
• GrayLoadBalancer.java
• EnvUtils.java
• EnvLoadBalancerClient.java

章节来源

• GrayReactiveLoadBalancerClientFilter.java
• GrayLoadBalancer.java
• EnvUtils.java
• EnvLoadBalancerClient.java

性能考量

• 选择策略复杂度
  • 版本与 tag 过滤均为线性扫描，时间复杂度 O(n)；在实例规模较大时，建议控制候选集大小（通过路由或网关规则）。
• 权重选择
  • 基于 Nacos 的权重随机选择，避免额外计算开销；若更换注册中心，需评估新实现的性能与一致性。
• 日志与可观测性
  • 灰度 LB 在回退与空实例时输出警告日志，便于定位问题；结合 SkyWalking/Prometheus 可观测性体系进行监控。

[本节为通用性能讨论，无需列出具体文件来源]

故障排查指南

• 常见问题与定位
  • 未命中版本实例：确认请求头 version 是否正确传递，以及服务实例元数据 version 是否一致。
  • 未命中标签实例：确认请求头 tag 是否正确传递，以及服务实例元数据 tag 是否一致；注意特殊占位符解析为主机名的情况。
  • 实例为空：检查注册中心健康状态与服务发现配置。
  • 未走灰度路径：确认请求 URL Scheme 是否为 grayLb。
• 关键日志位置
  • 版本回退与标签回退均有明确警告日志，便于快速定位。
• 相关配置
  • Nacos 地址与命名空间：确保网关侧配置正确，以便获取正确的服务实例列表。

章节来源

• GrayLoadBalancer.java
• GrayLoadBalancer.java
• application.yaml

结论

yudao-cloud 的灰度负载均衡通过“版本 + 标签”的双维筛选与 Nacos 权重随机选择，实现了可控、可回退的灰度流量分配。其核心在于：

• 明确的版本匹配与回退策略；
• 可扩展的标签过滤机制；
• 与注册中心紧密耦合的权重选择。

在生产环境中，建议：

• 明确版本与标签的语义边界；
• 控制候选实例规模；
• 做好灰度开关与回退策略的治理。

[本节为总结性内容，无需列出具体文件来源]

附录

配置参数说明

• 网关与注册中心
  • Nacos 服务地址与命名空间：确保网关能正确拉取服务实例与元数据。
• 灰度请求头
  • version：用于按元数据 version 进行实例筛选。
  • tag：用于按元数据 tag 进行实例筛选；支持特殊占位符解析为主机名。
• 回退策略
  • 版本不匹配或缺失时，自动回退到全部实例。
  • 标签不匹配或缺失时，自动回退到当前集合。

章节来源

• application.yaml
• GrayLoadBalancer.java
• GrayLoadBalancer.java
• EnvUtils.java

使用示例

• 启用灰度
  • 将上游请求的 URL Scheme 设置为 grayLb，使过滤器进入灰度路径。
• 指定版本
  • 在请求头添加 version 字段，值为期望的元数据版本号。
• 指定标签
  • 在请求头添加 tag 字段，值为期望的元数据标签；支持特殊占位符解析为主机名。
• 结果验证
  • 通过响应与日志观察实例选择是否符合预期；若无匹配，将自动回退。

章节来源

• README.md
• GrayReactiveLoadBalancerClientFilter.java
• GrayLoadBalancer.java
• EnvUtils.java