3. 灰度准入策略：基于用户标识、基于IP/地域、基于请求头、基于随机百分比

灰度准入策略是灰度发布系统的“第一道关卡”，决定了哪些流量可以进入灰度环境。不同的策略适用于不同的业务场景和风险等级。本章详细解析四种核心策略的实现原理、适用场景与配置要点。

3.1 策略分类与对比

四种策略在粒度、可控性、实现复杂度上各有差异，下表从关键维度进行横向对比：

3.2 基于用户标识的灰度策略

该策略通过用户唯一标识（如 user_id、手机号、邮箱）进行哈希取模或白名单匹配，实现“同一用户始终命中或始终不命中”的确定性灰度。

3.2.1 实现方式

• 哈希取模法：对 user_id 进行一致性哈希（如 MurmurHash），对灰度比例取模，结果落入灰度区间则命中。
• 白名单法：维护一个灰度用户名单（如内测用户表），请求携带的 user_id 在名单内则直接放行。
• 标签法：用户画像系统打标（如“灰度体验用户”），网关根据标签路由。

3.2.2 关键配置项

3.2.3 代码示例（网关层策略判断）

// 基于用户标识的灰度判断（Go 伪代码）
func shouldRouteToGray(userID string, grayPercent int) bool {
    // 1. 白名单优先
    if isInWhiteList(userID) {
        return true
    }
    // 2. 哈希取模
    hash := murmur3.Sum32([]byte(userID))
    return hash % 100 < grayPercent
}

3.3 基于 IP/地域的灰度策略

该策略根据请求来源 IP 地址或解析出的地理区域（国家、省份、城市）决定是否进入灰度环境。常用于区域性功能上线、合规性验证或网络延迟测试。

3.3.1 实现方式

• IP 段匹配：配置 CIDR 列表（如 10.0.0.0/8），请求源 IP 匹配则命中。
• 地域解析：通过 IP 库（如 GeoIP）将 IP 转换为地域编码，匹配配置的地域白名单。
• CDN 头部：利用 CDN 携带的 X-Forwarded-For 或 CloudFront-Viewer-Country 等头部。

3.3.2 注意事项

3.4 基于请求头的灰度策略

该策略通过读取 HTTP 请求头中的自定义字段（如 X-Gray-Tag、X-Canary）进行路由决策。灵活性高，常用于 A/B 测试、客户端版本控制、金丝雀发布。

3.4.1 典型配置

# 网关灰度规则配置（YAML 格式）
gray_rules:
  - name: "canary-by-header"
    header: "X-Gray-Version"
    operator: "equals"
    value: "v2.1.0"
    action: "route-to-gray"

3.4.2 常见头部设计

3.5 基于随机百分比的灰度策略

该策略不依赖任何请求特征，直接对流量进行随机采样。实现最简单，但无法保证同一用户多次请求的一致性，适合无状态、幂等的后端服务。

3.5.1 实现方式

• 随机数法：生成 [0, 100) 的随机数，小于灰度比例则命中。
• 请求 ID 取模：对全局唯一请求 ID（如 trace_id）取模，保证同一请求在重试时结果一致。

3.5.2 代码示例

// 基于随机百分比的灰度判断
func shouldRouteToGrayByPercent(percent int) bool {
    // 使用 crypto/rand 保证随机性
    n, _ := rand.Int(rand.Reader, big.NewInt(100))
    return n.Int64() < int64(percent)
}

3.6 策略组合与优先级

生产环境中通常组合多种策略，并定义优先级顺序。以下是一个典型的策略链执行流程：

3.7 策略配置示例（完整 YAML）

# 灰度准入策略完整配置
gray_release:
  enabled: true
  strategies:
    - name: "user-id-based"
      type: "user_id"
      priority: 1
      config:
        hash_key: "user_id"
        hash_algorithm: "murmur3_32"
        gray_percentage: 10
        white_list: ["1001", "1002", "1003"]
    
    - name: "ip-based"
      type: "ip"
      priority: 2
      config:
        cidr_whitelist: ["10.0.0.0/8", "172.16.0.0/12"]
        geo_whitelist: ["CN", "HK"]
    
    - name: "header-based"
      type: "header"
      priority: 3
      config:
        header: "X-Gray-Tag"
        operator: "in"
        values: ["canary", "internal-test"]
    
    - name: "random-percent"
      type: "random"
      priority: 4
      config:
        percentage: 5
        min_percent: 1
        max_percent: 50