vifo
19de7e24ec
从 docs-local 迁移以下文档： - backend/guides/: AI开发环境配置、Nacos配置、GitNexus指南、OpenCode工作流等 - backend/templates/: Superpowers设计模板、计划模板、审查清单 - backend/config-templates/: 应用配置模板、Nacos配置 - backend/design/: 数据库表结构规划 - backend/specs/: 项目文档治理、MQ统一推送设计 - backend/: 代码分析报告、Feign分析报告、文档治理报告 - frontend/design/: Admin-UI分模块打包设计
243 lines
5.9 KiB
Markdown
243 lines
5.9 KiB
Markdown
# 灰度发布（金丝雀发布）
|
||
|
||
> 网关层灰度发布解决方案，支持多种灰度策略，实现平滑的服务升级。
|
||
|
||
## 概述
|
||
|
||
灰度发布（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)
|