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

API7 网关 AI Agent Skill：蓝绿发布方案

概览​

蓝绿发布运行两个相同的生产环境。同一时间只有一个环境提供线上流量。将新版本部署到闲置环境并完成测试后，再将路由切换到新服务。如果出现问题，可以将路由切回原环境。

本方案使用当前 API7 企业版基于服务的路由模型：

  1. 为蓝色环境创建一个服务。
  2. 为绿色环境创建一个服务。
  3. 使用 service_id 将路由指向活动服务。
  4. 更新路由的 service_id，以完成切换或回滚。

前置条件​

  • API7 企业版控制面和至少一个网关组。
  • 已使用有效 Token 和服务器地址配置 a7 CLI。
  • 两个可部署的后端环境，例如蓝色环境和绿色环境。

方案 A：服务切换​

1. 创建两个服务​

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

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

2. 创建指向蓝色环境的路由​

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "api",
  "name": "api",
  "paths": ["/api/*"],
  "service_id": "blue-service"
}
EOF

3. 部署并测试绿色环境​

将新版本部署到绿色环境，然后通过内部主机名或临时测试路由直接测试，确认无误后再切换生产流量。

4. 切换到绿色环境​

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

配置传播完成后，default 网关组内所有网关的流量都会切换到绿色环境。

5. 回滚到蓝色环境​

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

方案 B：基于请求头的绿色环境测试​

当路由默认指向蓝色环境时，可使用 traffic-split 对绿色环境进行定向测试。 该路由仍使用 service_id 指定默认后端；插件只为匹配到的绿色环境请求提供内联上游。

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

使用以下命令测试绿色环境：

curl -H "x-env: green" http://gateway:9080/api/health

准备就绪后，移除插件并将路由切换到 green-service：

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

配置同步​

version: "1"
services:
  - id: blue-service
    name: blue-service
    upstream:
      type: roundrobin
      nodes:
        - host: blue-backend-1
          port: 8080
          weight: 1
        - host: blue-backend-2
          port: 8080
          weight: 1
  - id: green-service
    name: green-service
    upstream:
      type: roundrobin
      nodes:
        - host: green-backend-1
          port: 8080
          weight: 1
        - host: green-backend-2
          port: 8080
          weight: 1
routes:
  - id: api
    name: api
    paths:
      - /api/*
    service_id: blue-service # 切换时改为 green-service

预览并应用配置：

a7 config diff -f config.yaml
a7 config sync -f config.yaml

部署脚本​

#!/bin/bash
set -euo pipefail

GROUP="default"
ROUTE_ID="api"
CURRENT=$(a7 route get "$ROUTE_ID" --gateway-group "$GROUP" -o json | jq -r '.service_id')
TARGET=$([ "$CURRENT" = "blue-service" ] && echo "green-service" || echo "blue-service")

echo "Current: $CURRENT; switching to: $TARGET"

a7 route update "$ROUTE_ID" --gateway-group "$GROUP" -f - <<EOF
{"service_id": "$TARGET"}
EOF

if curl -sf http://gateway:9080/api/health > /dev/null; then
  echo "$TARGET is healthy"
else
  echo "$TARGET unhealthy; rolling back to $CURRENT"
  a7 route update "$ROUTE_ID" --gateway-group "$GROUP" -f - <<EOF
{"service_id": "$CURRENT"}
EOF
  exit 1
fi

故障排查​

现象原因解决方法
切换后返回 502新环境尚未就绪切换前测试健康检查端点；如有需要请回滚
流量仍发送到旧环境路由更新尚未传播使用 a7 route get api --gateway-group "$GROUP" -o json 验证，并在配置传播后重试
无法回滚未记录之前的服务 ID在切换前记录 service_id
命令返回 401Token 无效使用 a7 context create 刷新 Token
未找到服务网关组不同确保 --gateway-group 与创建服务和路由时使用的网关组一致

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