跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：灰度发布方案

概览​

灰度发布会逐步将流量从稳定版本切换到新版本。可以从小比例流量开始，先观察监控结果，再逐步增加比例，直到新版本接收全部流量。如果错误率升高，则回滚到稳定服务。

本方案使用：

  • service_id 用于路由默认的稳定后端。
  • traffic-split 使用内联上游承载临时灰度流量。
  • service update 或 route update 用于发布提升和回滚。

前置条件​

  • API7 企业版控制面和至少一个网关组。
  • 已使用有效令牌和服务器地址配置 a7 CLI。
  • 稳定版本和灰度版本的后端部署。

分步操作：灰度发布​

1. 创建稳定服务和灰度服务​

a7 service create --gateway-group default -f - <<'EOF'
{
  "id": "stable-service",
  "name": "stable-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "stable-v1", "port": 8080, "weight": 1}
    ]
  }
}
EOF

a7 service create --gateway-group default -f - <<'EOF'
{
  "id": "canary-service",
  "name": "canary-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "canary-v2", "port": 8080, "weight": 1}
    ]
  }
}
EOF

2. 从 5% 灰度流量开始​

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "api",
  "name": "api",
  "paths": ["/api/*"],
  "service_id": "stable-service",
  "plugins": {
    "traffic-split": {
      "rules": [
        {
          "weighted_upstreams": [
            {
              "upstream": {
                "type": "roundrobin",
                "nodes": [{"host": "canary-v2", "port": 8080, "weight": 1}]
              },
              "weight": 5
            },
            {
              "weight": 95
            }
          ]
        }
      ]
    }
  }
}
EOF

3. 增加到 25%​

a7 route update api --gateway-group default -f - <<'EOF'
{
  "service_id": "stable-service",
  "plugins": {
    "traffic-split": {
      "rules": [
        {
          "weighted_upstreams": [
            {
              "upstream": {
                "type": "roundrobin",
                "nodes": [{"host": "canary-v2", "port": 8080, "weight": 1}]
              },
              "weight": 25
            },
            {
              "weight": 75
            }
          ]
        }
      ]
    }
  }
}
EOF

4. 提升到 100%​

移除 traffic-split，并将路由的默认服务切换到灰度服务。

a7 route update api --gateway-group default -f - <<'EOF'
{
  "plugins": {},
  "service_id": "canary-service"
}
EOF

可选：更新稳定服务，使其指向已提升的后端，以便在下一次发布中复用相同的服务 ID：

a7 service update stable-service --gateway-group default -f - <<'EOF'
{
  "id": "stable-service",
  "name": "stable-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "canary-v2", "port": 8080, "weight": 1}
    ]
  }
}
EOF

回滚​

移除插件，并将所有流量切回稳定服务：

a7 route update api --gateway-group default -f - <<'EOF'
{
  "plugins": {},
  "service_id": "stable-service"
}
EOF

基于请求头的灰度发布​

a7 route update api --gateway-group default -f - <<'EOF'
{
  "service_id": "stable-service",
  "plugins": {
    "traffic-split": {
      "rules": [
        {
          "match": [
            {"vars": [["http_x_canary", "==", "true"]]}
          ],
          "weighted_upstreams": [
            {
              "upstream": {
                "type": "roundrobin",
                "nodes": [{"host": "canary-v2", "port": 8080, "weight": 1}]
              },
              "weight": 1
            }
          ]
        }
      ]
    }
  }
}
EOF

仅带有 x-canary: true 请求头的请求会发送到灰度版本，其他请求使用路由的默认服务 stable-service。

灰度推进脚本​

#!/bin/bash
set -euo pipefail

GROUP="default"
ROUTE_ID="api"
WEIGHTS=(5 25 50 75 100)
HEALTH_URL="http://gateway:9080/api/health"
WAIT_SECONDS=300

for w in "${WEIGHTS[@]}"; do
  if [ "$w" -eq 100 ]; then
    a7 route update "$ROUTE_ID" --gateway-group "$GROUP" -f - <<EOF
{"plugins": {}, "service_id": "canary-service"}
EOF
  else
    stable_w=$((100 - w))
    a7 route update "$ROUTE_ID" --gateway-group "$GROUP" -f - <<EOF
{
  "service_id": "stable-service",
  "plugins": {
    "traffic-split": {
      "rules": [{
        "weighted_upstreams": [
          {"upstream": {"type": "roundrobin", "nodes": [{"host": "canary-v2", "port": 8080, "weight": 1}]}, "weight": $w},
          {"weight": $stable_w}
        ]
      }]
    }
  }
}
EOF
  fi

  sleep "$WAIT_SECONDS"
  if ! curl -sf "$HEALTH_URL" > /dev/null; then
    a7 route update "$ROUTE_ID" --gateway-group "$GROUP" -f - <<EOF
{"plugins": {}, "service_id": "stable-service"}
EOF
    exit 1
  fi
done

配置同步​

version: "1"
services:
  - id: stable-service
    name: stable-service
    upstream:
      type: roundrobin
      nodes:
        - host: stable-v1
          port: 8080
          weight: 1
  - id: canary-service
    name: canary-service
    upstream:
      type: roundrobin
      nodes:
        - host: canary-v2
          port: 8080
          weight: 1
routes:
  - id: api
    name: api
    paths:
      - /api/*
    service_id: stable-service
    plugins:
      traffic-split:
        rules:
          - weighted_upstreams:
              - upstream:
                  type: roundrobin
                  nodes:
                    - host: canary-v2
                      port: 8080
                      weight: 1
                weight: 10
              - weight: 90

故障排查​

现象原因解决方法
流量比例不精确加权路由具有概率性在足够多的请求上进行测量
灰度版本未接收流量匹配条件始终不成立检查请求头或 Cookie 名称，以及 a7 route get api --gateway-group default 的输出
回滚未立即生效配置尚未传播使用 a7 route get api --gateway-group default 验证，并在配置传播后重试
灰度版本返回 502灰度后端不健康提高权重前先检查灰度服务的健康状态
权重变更无效修改了错误的路由使用 a7 route list --gateway-group default --service-id stable-service 验证路由 ID
命令返回 403RBAC 权限问题确保令牌有权限修改该网关组中的路由

本页面由 api7/a7 仓库中的 a7-recipe-canary/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。