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

API7 网关 AI Agent Skill：熔断方案

概览​

熔断通过检测不健康的后端响应来防止级联故障，并暂时停止向故障服务发送请求。API7 企业版通过路由上的 api-breaker 插件实现此功能。

使用当前基于服务的路由模型：

  1. 创建承载上游后端的服务。
  2. 使用 service_id 创建路由。
  3. 在路由上启用 api-breaker。

插件配置参考​

字段是否必填说明
break_response_code是熔断开启时返回的 HTTP 状态码
break_response_body否熔断开启时返回的响应体
break_response_headers否熔断开启时返回的响应头
unhealthy.http_statuses否计为不健康的上游状态码
unhealthy.failures否开启熔断前所需的连续不健康响应次数
healthy.http_statuses否用于恢复的健康状态码
healthy.successes否关闭熔断前所需的连续健康响应次数
max_breaker_sec否熔断开启的最长时间

分步操作：启用熔断​

1. 创建受保护的服务​

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

2. 使用 api-breaker 创建路由​

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "protected-api",
  "name": "protected-api",
  "paths": ["/api/*"],
  "service_id": "backend-service",
  "plugins": {
    "api-breaker": {
      "break_response_code": 502,
      "unhealthy": {
        "http_statuses": [500, 502, 503],
        "failures": 3
      },
      "healthy": {
        "http_statuses": [200],
        "successes": 3
      },
      "max_breaker_sec": 300
    }
  }
}
EOF

连续收到三个 500/502/503 响应后，熔断器会打开并立即返回 502。在冷却期间，API7 企业版会测试恢复状态，收到足够的健康响应后关闭熔断器。

3. 自定义错误响应​

a7 route update protected-api --gateway-group default -f - <<'EOF'
{
  "id": "protected-api",
  "name": "protected-api",
  "paths": ["/api/*"],
  "service_id": "backend-service",
  "plugins": {
    "api-breaker": {
      "break_response_code": 503,
      "break_response_body": "{\"error\": \"service temporarily unavailable\", \"retry_after\": 30}",
      "break_response_headers": [
        {"key": "Content-Type", "value": "application/json"},
        {"key": "Retry-After", "value": "30"}
      ],
      "unhealthy": {
        "http_statuses": [500, 502, 503, 504],
        "failures": 5
      },
      "healthy": {
        "http_statuses": [200, 201, 204],
        "successes": 2
      },
      "max_breaker_sec": 60
    }
  }
}
EOF

4. 结合使用健康检查​

对于生产环境，请在服务上游中定义健康检查，并在路由上保留 api-breaker。健康检查负责管理节点健康状态，熔断器负责保护路由免受重复上游故障影响。

a7 service create --gateway-group default -f - <<'EOF'
{
  "id": "monitored-backend-service",
  "name": "monitored-backend-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "backend-1", "port": 8080, "weight": 1},
      {"host": "backend-2", "port": 8080, "weight": 1}
    ],
    "checks": {
      "active": {
        "type": "http",
        "http_path": "/health",
        "healthy": {"interval": 5, "successes": 2},
        "unhealthy": {"interval": 3, "http_failures": 3}
      }
    }
  }
}
EOF

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "api",
  "name": "api",
  "paths": ["/api/*"],
  "service_id": "monitored-backend-service",
  "plugins": {
    "api-breaker": {
      "break_response_code": 503,
      "unhealthy": {
        "http_statuses": [500, 502, 503],
        "failures": 3
      },
      "healthy": {
        "http_statuses": [200],
        "successes": 3
      }
    }
  }
}
EOF

配置同步​

version: "1"
services:
  - id: backend-service
    name: backend-service
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: protected-api
    name: protected-api
    paths:
      - /api/*
    service_id: backend-service
    plugins:
      api-breaker:
        break_response_code: 503
        break_response_body: '{"error": "service unavailable"}'
        break_response_headers:
          - key: Content-Type
            value: application/json
          - key: Retry-After
            value: "30"
        unhealthy:
          http_statuses: [500, 502, 503]
          failures: 3
        healthy:
          http_statuses: [200]
          successes: 3
        max_breaker_sec: 300

故障排查​

现象原因解决方法
熔断器未打开unhealthy.http_statuses 未包含实际错误码添加实际的上游错误码
熔断器保持打开时间过长max_breaker_sec 过高降低 max_breaker_sec
熔断状态反复切换间歇性错误的阈值过低提高 unhealthy.failures
熔断器之外的响应返回 502后端不可访问连接错误也会计入不健康阈值
恢复速度过慢healthy.successes 过高降低 healthy.successes
路由未使用熔断器插件附加到了错误的路由使用 a7 route get <id> -o json 验证
命令返回 403RBAC 权限问题确保 Token 有权限修改该网关组中的路由

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