4. 全局限流参数详解：rate_limit_service gRPC 配置、descriptor 与 descriptor_list 的匹配逻辑

全局限流是 Envoy 冷启动削峰的核心手段之一。与本地限流不同，全局限流依赖一个外部的 rate_limit_service（通常为基于 gRPC 协议的限流服务器，如 Lyft 的 ratelimit 或自研实现）来聚合所有 Envoy 实例的请求计数，从而在集群粒度上精确控制流量峰值。本节将深入解析 rate_limit_service 的 gRPC 配置结构、descriptor 的设计原则以及 descriptor_list 的匹配逻辑。

4.1 rate_limit_service gRPC 配置结构

在 Envoy 的 HTTP 连接管理器（HttpConnectionManager）或网络过滤器（Network Filter）中，通过 rate_limit_service 字段指定全局限流服务的 gRPC 端点。其核心配置参数如下表所示：

一个典型的 gRPC 配置片段如下：

rate_limit_service:
  grpc_service:
    envoy_grpc:
      cluster_name: rate_limit_cluster
    timeout: 0.5s
  transport_api_version: V3
  rate_limited_as_resource_exhausted: true

4.2 descriptor 的设计与编码

descriptor 是 Envoy 发送给限流服务的核心数据结构，本质是一个 Descriptor 消息，包含一组 entries（键值对列表）。每个 entry 由 key 和 value 组成，用于描述请求的特征，例如：

• 请求来源：source_cluster、source_principal
• 请求目标：destination_cluster、destination_service
• 请求路径：request_headers["x-request-path"]
• 请求方法：request_headers["x-http-method"]
• 自定义标签：generic_key、metadata

在冷启动削峰中，descriptor 的设计应遵循以下原则：

一个完整的 descriptor 配置示例：

descriptors:
  - entries:
      - key: destination_cluster
        value: "service-b"
      - key: request_headers
        header_name: "x-request-path"
        descriptor_key: "api_path"
      - key: generic_key
        value: "cold_start_phase_1"

4.3 descriptor_list 的匹配逻辑

Envoy 在发送限流请求时，会构造一个 descriptor_list（Descriptor 列表）。限流服务收到后，按照以下优先级顺序进行匹配：

1. 精确匹配：限流服务查找与 descriptor_list 完全匹配的限流规则（所有 entries 的 key-value 完全一致）。
2. 通配符匹配：如果精确匹配失败，查找包含通配符 * 或正则表达式的规则（如 destination_cluster: "*"）。
3. 默认匹配：如果前两者均失败，使用全局默认规则（通常为 generic_key: "default"）。
4. 拒绝匹配：如果没有任何规则匹配，限流服务返回 OVER_LIMIT（安全模式）或 OK（宽松模式），取决于服务端配置。

下图展示了 descriptor_list 在 Envoy 与限流服务之间的匹配流程：

4.4 冷启动削峰中的 descriptor 动态调整策略

在冷启动阶段，全局限流的 descriptor 不应是静态的。通过动态调整 descriptor 的 value 或增加新的 entry，可以实现流量爬坡。常见的策略包括：

4.5 常见匹配问题与排错

在实际工程中，descriptor_list 匹配失败是导致全局限流失效的主要原因。以下列出典型问题及排查思路：

• descriptor 顺序敏感：限流服务通常按 descriptor_list 的顺序进行匹配。如果精确规则放在通配符规则之后，精确规则永远不会被命中。建议将精确度高的规则放在列表前面。
• key 值大小写不一致：Envoy 发送的 destination_cluster 与限流服务配置的 Destination_Cluster 不匹配。所有 key 应统一使用小写+下划线格式。
• header 值缺失：当 descriptor 引用 request_headers 时，如果请求中不包含该 header，Envoy 会跳过该 entry，导致 descriptor 结构不完整。建议使用 default_value 或 fallback 机制。
• 限流服务缓存过期：部分限流服务会缓存匹配结果。如果规则更新后缓存未刷新，会导致旧规则继续生效。建议设置合理的缓存 TTL（如 10s）。