Files

T

vifo 19de7e24ec 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:34:03 +08:00

5.9 KiB

Raw Blame History

灰度发布（金丝雀发布）

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

概述

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

核心特性

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

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

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

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

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 元数据标记版本：

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 中配置灰度规则：

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

使用场景示例

场景一：内部测试

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

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

场景二：按比例灰度

对全量用户按比例灰度：

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

场景三：内部 IP 灰度

公司内部员工先行体验：

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

场景四：组合策略

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

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

匹配逻辑：

强制 Header > 2. 用户白名单 > 3. IP 白名单 > 4. 权重

验证灰度是否生效

1. 查看网关日志

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

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

2. 通过 Header 验证

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

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

3. 使用强制 Header 测试

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

最佳实践

1. 灰度前准备

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

2. 灰度流程

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

3. 监控指标

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

4. 快速回滚

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

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

注意事项

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

5.9 KiB Raw Blame History Unescape Escape