# 灰度发布（金丝雀发布）

> 网关层灰度发布解决方案，支持多种灰度策略，实现平滑的服务升级。

## 概述

灰度发布（Canary Release）是一种渐进式发布策略，通过将小部分流量先路由到新版本，验证无误后再逐步扩大流量，最终完成全量发布。本方案在网关层实现，对业务服务无侵入。

## 核心特性

| 特性 | 说明 |
|------|------|
| **多策略支持** | 权重、用户白名单、IP 白名单、强制 Header |
| **多服务独立配置** | 每个服务可配置独立的灰度规则 |
| **无侵入** | 业务服务无需改动，仅通过元数据标记版本 |
| **优先级控制** | 多种策略按优先级执行，确保灰度准确性 |

## 灰度策略（按优先级排序）

### 1. 强制 Header（最高优先级）

客户端通过指定 Header 强制访问特定版本，用于测试验证。

```http
GET /user/api/info HTTP/1.1
Host: api.example.com
X-Grayscale-Version: v2
```

### 2. 用户白名单

特定用户 ID 强制走灰度版本，通常用于内部测试账号。

**识别方式**：通过 `X-User-Id` Header 识别用户身份。

### 3. IP 白名单

特定 IP 或 IP 段的请求走灰度版本，支持 CIDR 格式。

**示例**：
- `192.168.1.0/24` - 内网网段
- `10.0.0.5` - 单个 IP

### 4. 权重比例（最低优先级）

按比例分配流量，适用于全量灰度场景。

**示例**：`weight: 10` 表示 10% 的请求走灰度版本。

## 后端服务配置

### 1. 标记灰度实例

在服务的 `application.yml` 中通过 Nacos 元数据标记版本：

```yaml
spring:
  cloud:
    nacos:
      discovery:
        metadata:
          gray.version: v2    # 标记为灰度版本 v2
```

### 2. 部署多个版本

同时部署稳定版本和灰度版本：

```
服务实例列表
├── rui-service-user:v1 (稳定版本，无 gray.version 或 gray.version=v1)
├── rui-service-user:v1 (稳定版本)
└── rui-service-user:v2 (灰度版本，gray.version=v2)
```

## 网关配置

在 Nacos 的 `rui-gateway.yaml` 中配置灰度规则：

```yaml
grayscale:
  # 强制灰度 Header 名称
  force-header: X-Grayscale-Version
  # 灰度规则
  rules:
    # rui-service-user 服务的灰度规则
    rui-service-user:
      enabled: true              # 启用灰度
      version: v2                # 灰度版本标识（与实例元数据对应）
      weight: 10                 # 10% 流量走灰度
      user-ids:                  # 特定用户走灰度
        - user001
        - user002
      ip-ranges:                 # 特定 IP 走灰度
        - 192.168.1.0/24
```

### 配置项说明

| 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `enabled` | boolean | 是 | 是否启用灰度 |
| `version` | string | 否 | 灰度版本标识，默认 `gray` |
| `weight` | int | 否 | 灰度流量权重（0-100），默认 0 |
| `user-ids` | list | 否 | 用户白名单列表 |
| `ip-ranges` | list | 否 | IP 白名单列表，支持 CIDR |

## 使用场景示例

### 场景一：内部测试

仅需内部测试人员访问新版本：

```yaml
grayscale:
  rules:
    rui-service-user:
      enabled: true
      version: v2
      user-ids:
        - tester001
        - tester002
```

### 场景二：按比例灰度

对全量用户按比例灰度：

```yaml
grayscale:
  rules:
    rui-service-user:
      enabled: true
      version: v2
      weight: 5    # 先 5%，逐步提高到 10%、20%、50%、100%
```

### 场景三：内部 IP 灰度

公司内部员工先行体验：

```yaml
grayscale:
  rules:
    rui-service-user:
      enabled: true
      version: v2
      ip-ranges:
        - 192.168.0.0/16    # 公司内网
        - 10.0.0.0/8        # VPN 网段
```

### 场景四：组合策略

多种策略同时生效（按优先级匹配）：

```yaml
grayscale:
  rules:
    rui-service-user:
      enabled: true
      version: v2
      weight: 10
      user-ids:
        - vip001    # VIP 用户优先体验
      ip-ranges:
        - 192.168.1.0/24    # 办公室网络
```

**匹配逻辑**：
1. 强制 Header > 2. 用户白名单 > 3. IP 白名单 > 4. 权重

## 验证灰度是否生效

### 1. 查看网关日志

开启 DEBUG 级别日志，查看实例选择：

```
选择灰度实例: rui-service-user:v2 [v2]
选择稳定实例: rui-service-user:v1
```

### 2. 通过 Header 验证

在响应头中添加版本标识：

```java
// 后端服务在响应中添加版本信息
response.setHeader("X-Server-Version", version);
```

### 3. 使用强制 Header 测试

```bash
curl -H "X-Grayscale-Version: v2" https://api.example.com/user/api/info
```

## 最佳实践

### 1. 灰度前准备

- [ ] 新版本已通过测试环境验证
- [ ] 监控和告警已配置
- [ ] 回滚方案已准备

### 2. 灰度流程

1. **Phase 1**：内部测试（用户白名单）
2. **Phase 2**：办公网灰度（IP 白名单）
3. **Phase 3**：小流量灰度（weight=1%）
4. **Phase 4**：逐步扩大（5% → 10% → 20% → 50% → 100%）
5. **Phase 5**：全量发布，下线旧版本

### 3. 监控指标

- 错误率对比（灰度 vs 稳定）
- 响应时间对比
- 业务指标波动

### 4. 快速回滚

发现问题时立即关闭灰度：

```yaml
grayscale:
  rules:
    rui-service-user:
      enabled: false    # 关闭灰度，全部流量回稳定版本
```

## 注意事项

1. **服务发现延迟**：Nacos 服务列表更新可能有延迟（默认 5-10 秒）
2. **数据兼容性**：确保新版本与旧版本数据库兼容
3. **接口兼容性**：灰度期间避免破坏性接口变更
4. **会话一致性**：有状态服务需考虑会话粘滞或共享

## 相关文档

- [Spring Cloud Gateway 文档](https://docs.spring.io/spring-cloud-gateway/docs/current/reference/html/)
- [Spring Cloud LoadBalancer 文档](https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer)