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

概览

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

本方案使用：

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

前置条件

• API7 企业版控制面和至少一个网关组。
• 已使用有效 Token 和服务器地址配置 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

可选：将 stable 服务更新为指向已提升的后端，以便在下一次发布中复用相同的服务 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
命令返回 403	RBAC 权限问题	确保 Token 有权限修改该网关组中的路由

---

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