# 海外仓网关服务-Gateway

**Repository Path**: coudyhou/cd-gateway-services

## Basic Information

- **Project Name**: 海外仓网关服务-Gateway
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gray Release Gateway（灰度发布网关）

基于 **Spring Cloud Gateway** 的生产级灰度发布实现，支持多种灰度路由策略。

---

## 架构图

```
                        ┌─────────────────────────────────────────────────┐
                        │              Spring Cloud Gateway                │
                        │                                                 │
  Client Request  ──►  │  GrayMetricsFilter (order: MAX+50)              │
                        │       ↓                                         │
                        │  GrayRoutingFilter (order: MAX+100)             │
                        │   ├─ 解析 userId / clientIP                    │
                        │   ├─ 查询 Redis 灰度规则（本地缓存10s）          │
                        │   └─ GrayStrategyRouter                        │
                        │       ├─ WeightStrategy      (权重随机)         │
                        │       ├─ UserWhitelistStrategy (用户白名单)      │
                        │       ├─ HeaderStrategy       (请求头匹配)       │
                        │       ├─ IpStrategy           (IP段匹配)        │
                        │       └─ CompositeStrategy    (任一命中)         │
                        │       ↓                                         │
                        │  写入 Exchange Attributes: GrayContext          │
                        │       ↓                                         │
                        │  GrayLoadBalancer                               │
                        │   ├─ hitGray=true  → 灰度实例池 (metadata)      │
                        │   └─ hitGray=false → 稳定实例池                 │
                        └─────────────────────────────────────────────────┘
                                    │                    │
                              ┌─────▼─────┐      ┌──────▼──────┐
                              │  Stable   │      │    Gray     │
                              │ Instance  │      │  Instance   │
                              │ v1.0.0    │      │  v2.0.0     │
                              │ gray=false│      │  gray=true  │
                              └───────────┘      └─────────────┘
```

---

## 灰度策略说明

| 策略 | 说明 | 适用场景 |
|------|------|---------|
| `WEIGHT` | 按百分比随机分流 | AB测试、平滑上线 |
| `USER_WHITELIST` | 指定用户ID走灰度 | 内部测试、特定用户体验 |
| `HEADER` | 请求头匹配（AND逻辑） | 客户端版本控制 |
| `IP` | 客户端IP段匹配（CIDR） | 办公网/内网测试 |
| `COMPOSITE` | 任一子策略命中即走灰度（OR逻辑） | 多维度组合控制 |

---

## 快速开始

### 1. 依赖服务

```bash
# Redis
docker run -d -p 6379:6379 redis:7

# Nacos（可替换为 Eureka）
docker run -d -p 8848:8848 nacos/nacos-server:latest -e MODE=standalone
```

### 2. 注册服务实例

在 Nacos 中注册服务实例时，灰度实例需设置 metadata：

```yaml
# 灰度实例 bootstrap.yml
spring:
  cloud:
    nacos:
      discovery:
        metadata:
          gray: "true"        # 标记为灰度实例
          version: "v2.0.0"   # 版本标识
```

```yaml
# 稳定实例 bootstrap.yml
spring:
  cloud:
    nacos:
      discovery:
        metadata:
          gray: "false"
          version: "v1.0.0"
```

### 3. 配置灰度规则

**权重策略（10% 流量走灰度）：**
```bash
curl -X POST http://localhost:8080/gray/rules \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "user-service",
    "grayVersion": "v2.0.0",
    "enabled": true,
    "strategyType": "WEIGHT",
    "grayWeightPercent": 10,
    "grayMetaKey": "gray",
    "grayMetaValue": "true"
  }'
```

**用户白名单策略：**
```bash
curl -X POST http://localhost:8080/gray/rules \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "order-service",
    "grayVersion": "v2.0.0",
    "enabled": true,
    "strategyType": "USER_WHITELIST",
    "whitelistUserIds": ["user_001", "user_002", "tester_001"]
  }'
```

**请求头策略：**
```bash
curl -X POST http://localhost:8080/gray/rules \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "user-service",
    "grayVersion": "v2.0.0",
    "enabled": true,
    "strategyType": "HEADER",
    "headerMatchers": {
      "X-App-Version": "2.0.0",
      "X-Platform": "ios"
    }
  }'
```

**IP策略（支持CIDR）：**
```bash
curl -X POST http://localhost:8080/gray/rules \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "user-service",
    "grayVersion": "v2.0.0",
    "enabled": true,
    "strategyType": "IP",
    "grayIpRanges": ["192.168.1.0/24", "10.0.0.100"]
  }'
```

**组合策略（白名单 OR 权重 OR 请求头）：**
```bash
curl -X POST http://localhost:8080/gray/rules \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "user-service",
    "grayVersion": "v2.0.0",
    "enabled": true,
    "strategyType": "COMPOSITE",
    "grayWeightPercent": 5,
    "whitelistUserIds": ["admin_001"],
    "headerMatchers": {"X-Beta": "true"}
  }'
```

### 4. 发起请求

```bash
# 用户请求（携带用户ID）
curl http://localhost:8080/api/user/profile \
  -H "X-User-Id: user_001"

# 带版本请求头
curl http://localhost:8080/api/user/profile \
  -H "X-App-Version: 2.0.0" \
  -H "X-Platform: ios"
```

---

## API 管理接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/gray/rules` | 创建/更新灰度规则 |
| GET | `/gray/rules/{serviceId}` | 查询规则 |
| DELETE | `/gray/rules/{serviceId}` | 删除规则（关闭灰度） |
| POST | `/gray/rules/{serviceId}/refresh` | 立即刷新本地缓存 |

---

## 请求头约定

| Header | 说明 |
|--------|------|
| `X-User-Id` | 用户ID，用于白名单匹配 |
| `X-Real-IP` | 真实客户端IP（Nginx 透传） |
| `X-Forwarded-For` | 代理链IP |
| `X-Gray-Tag` | 网关向下游透传的灰度标记 |
| `X-Gray-Version` | 网关向下游透传的灰度版本 |

---

## 扩展性

- **规则存储**：默认 Redis，可替换为 Nacos Config、数据库等
- **注册中心**：支持 Nacos、Eureka、Consul（修改依赖即可）
- **新增策略**：实现 `GrayStrategy` 接口并注册为 Spring Bean，自动被 `GrayStrategyRouter` 识别
- **指标监控**：`GrayMetricsFilter` 中接入 Micrometer/Prometheus 即可

---

## 关键依赖版本

| 组件 | 版本         |
|------|------------|
| Spring Boot | 3.2.0      |
| Spring Cloud | 2023.0.0   |
| Spring Cloud Alibaba | 2022.0.0.0 |
| Redis Client | Lettuce    |
| JDK | 8+         |