API7 网关 AI Agent Skill：健康检查方案

概览

健康检查会监控后端节点，并将不健康节点从负载 均衡中移除。在当前 API7 企业版用法中，请在服务上定义上游和健康检查配置，然后将路由通过 service_id 关联到该服务。

API7 企业版支持：

• 主动检查：网关主动探测每个节点。
• 被动检查：网关观察真实流量响应。

对于需要自动故障检测和恢复的生产服务，建议同时使用主动和被动健康检查。

健康检查配置参考

主动健康检查

字段	说明
upstream.checks.active.type	http、https 或 tcp
upstream.checks.active.http_path	要探测的 HTTP 路径
upstream.checks.active.healthy.successes	标记为健康所需的连续成功次数
upstream.checks.active.unhealthy.http_failures	标记为不健康所需的连续 HTTP 失败次数
upstream.checks.active.unhealthy.timeouts	标记为不健康所需的连续超时次数

被动健康检查

字段	说明
upstream.checks.passive.type	http、https 或 tcp
upstream.checks.passive.unhealthy.http_statuses	视为不健康的状态码
upstream.checks.passive.unhealthy.http_failures	标记为不健康所需的连续失败次数
upstream.checks.passive.healthy.successes	标记为健康所需的连续成功次数

分步操作：配置健康检查

1. 创建带主动 HTTP 健康检查的服务

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

2. 创建使用该服务的路由

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

健康检查只会对至少被一个路由引用的服务运行。 使用以下命令验证路由关联：

a7 service get backend-service --gateway-group default --output json
a7 route list --gateway-group default --service-id backend-service --output json

3. 被动健康检查

a7 service create --gateway-group default -f - <<'EOF'
{
  "id": "backend-passive-service",
  "name": "backend-passive-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "backend-1", "port": 8080, "weight": 1},
      {"host": "backend-2", "port": 8080, "weight": 1}
    ],
    "checks": {
      "passive": {
        "type": "http",
        "unhealthy": {
          "http_failures": 3,
          "http_statuses": [500, 502, 503],
          "timeouts": 3
        },
        "healthy": {
          "successes": 5,
          "http_statuses": [200, 201, 202, 203, 204]
        }
      }
    }
  }
}
EOF

发送流量前，请先将启用被动检查的服务关联到路由：

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

仅使用被动检查无法恢复没有流量的节点。请结合 被动检查和主动检查，以覆盖完整恢复场景。

4. 组合主动和被动健康检查

a7 service create --gateway-group default -f - <<'EOF'
{
  "id": "production-backend-service",
  "name": "production-backend-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "backend-1", "port": 8080, "weight": 1},
      {"host": "backend-2", "port": 8080, "weight": 1},
      {"host": "backend-3", "port": 8080, "weight": 1}
    ],
    "checks": {
      "active": {
        "type": "http",
        "http_path": "/health",
        "healthy": {
          "interval": 5,
          "successes": 2,
          "http_statuses": [200]
        },
        "unhealthy": {
          "interval": 2,
          "http_failures": 3,
          "timeouts": 2,
          "http_statuses": [500, 502, 503, 504]
        }
      },
      "passive": {
        "type": "http",
        "unhealthy": {
          "http_failures": 3,
          "http_statuses": [500, 502, 503],
          "timeouts": 3
        },
        "healthy": {
          "successes": 3,
          "http_statuses": [200, 201, 204]
        }
      }
    }
  }
}
EOF

创建或更新路由，使其关联到组合检查服务：

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

配置同步

version: "1"
services:
  - id: production-backend-service
    name: production-backend-service
    upstream:
      type: roundrobin
      nodes:
        - host: backend-1
          port: 8080
          weight: 1
        - host: backend-2
          port: 8080
          weight: 1
        - host: backend-3
          port: 8080
          weight: 1
      checks:
        active:
          type: http
          http_path: /health
          healthy:
            interval: 5
            successes: 2
            http_statuses: [200]
          unhealthy:
            interval: 2
            http_failures: 3
            timeouts: 2
            http_statuses: [500, 502, 503, 504]
        passive:
          type: http
          unhealthy:
            http_failures: 3
            http_statuses: [500, 502, 503]
            timeouts: 3
          healthy:
            successes: 3
            http_statuses: [200, 201, 204]
routes:
  - id: api
    name: api
    paths:
      - /api/*
    service_id: production-backend-service

故障排查

现象	原因	修复方式
健康检查未运行	路由未引用该服务	使用 a7 route list --gateway-group default --service-id <service> 进行确认
所有节点都被标记为不健康	健康检查端点返回了非预期状态码	确认 http_statuses 包含该响应码
节点未恢复	仅被动健康检查没有可观察的流量	添加主动健康检查
探测命中了错误端点	默认 http_path 为 /	将 http_path 设置为实际的健康检查端点
TLS 探测失败	证书校验失败	设置 https_verify_certificate: false 或修复证书
没有独立的健康检查命令	当前 a7 不公开上游健康状态	使用 a7 service get --gateway-group default 验证配置，并通过网关可观测性查看状态
命令返回 401	Token 无效	使用 a7 context create 刷新 Token
未找到服务	网关组不同	确保 --gateway-group 与创建服务的位置一致

---

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