docs: 迁移 spring-ai 通用文档到 rui-docs

从 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分模块打包设计
2026-06-04 09:31:24 +08:00
parent 2e38c53434
commit 19de7e24ec
36 changed files with 5872 additions and 0 deletions
@@ -0,0 +1,242 @@
+# 灰度发布（金丝雀发布）
+
+> 网关层灰度发布解决方案，支持多种灰度策略，实现平滑的服务升级。
+
+## 概述
+
+灰度发布（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)