a6-recipe-health-check

概览

健康检查会监控上游后端节点，并自动将不健康节点从负载均衡池中移除。APISIX 支持两种检查方式：

主动检查：APISIX 定期使用 HTTP、HTTPS 或 TCP 请求探测每个节点。
被动检查：APISIX 分析真实流量的响应来检测故障。

生产环境建议同时使用两种检查方式，以获得更可靠的故障检测和恢复能力。

适用场景

自动将故障后端节点移出负载均衡池
检测后端故障并从中恢复,无需人工干预
确保多个后端的可用性高
通过 a6 CLI 监控后端健康状态

健康检查配置参考

主动健康检查

字段	类型	默认	描述
`checks.active.type`	字符串	`"http"`	检查类型：`"http"`、`"https"` 或 `"tcp"`
`checks.active.http_path`	字符串	`"/"`	探测的 HTTP 路径
`checks.active.host`	字符串	—	HTTP 探测器的主机头
`checks.active.port`	整数	—	探测端口（默认使用节点端口）
`checks.active.timeout`	数字	`1`	探测超时时间（秒）
`checks.active.concurrency`	整数	`10`	同时进行的探测次数
`checks.active.https_verify_certificate`	布尔	`true`	验证 HTTPS 探测器的 TLS 证书
`checks.active.req_headers`	数组[字符串]	—	探测器的额外请求头
`checks.active.healthy.interval`	整数	`1`	健康节点的探测间隔（秒）
`checks.active.healthy.successes`	整数	`2`	将节点标记为健康所需的连续成功次数
`checks.active.healthy.http_statuses`	数组[整数]	`[200, 302]`	视为健康的 HTTP 状态码
`checks.active.unhealthy.interval`	整数	`1`	不健康节点的探测间隔（秒）
`checks.active.unhealthy.http_failures`	整数	`5`	将节点标记为不健康所需的连续 HTTP 失败次数
`checks.active.unhealthy.tcp_failures`	整数	`2`	将节点标记为不健康所需的连续 TCP 失败次数
`checks.active.unhealthy.timeouts`	整数	`3`	将节点标记为不健康所需的连续超时次数
`checks.active.unhealthy.http_statuses`	数组[整数]	`[429, 404, 500, 501, 502, 503, 504, 505]`	视为不健康的 HTTP 状态码

被动健康检查

字段	类型	默认	描述
`checks.passive.type`	字符串	`"http"`	检查类型：`"http"`、`"https"` 或 `"tcp"`
`checks.passive.healthy.successes`	整数	`5`	将节点标记为健康所需的连续成功次数
`checks.passive.healthy.http_statuses`	数组[整数]	`[200, 201, 202, ..., 399]`	视为健康的 HTTP 状态码
`checks.passive.unhealthy.http_failures`	整数	`5`	将节点标记为不健康所需的连续 HTTP 失败次数
`checks.passive.unhealthy.tcp_failures`	整数	`2`	将节点标记为不健康所需的连续 TCP 失败次数
`checks.passive.unhealthy.timeouts`	整数	`7`	将节点标记为不健康所需的连续超时次数
`checks.passive.unhealthy.http_statuses`	数组[整数]	`[429, 500, 503]`	视为不健康的 HTTP 状态码

分步操作：配置健康检查

1. 配置主动 HTTP 健康检查

a6 upstream create -f - <<'EOF'
{
  "id": "backend",
  "type": "roundrobin",
  "nodes": {
    "backend-1:8080": 1,
    "backend-2:8080": 1,
    "backend-3:8080": 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

APISIX 会探测每个节点的 /health 端点：

健康节点每 5 秒探测一次
不健康节点每 3 秒探测一次
连续失败 3 次后移除节点
连续成功 2 次后恢复节点

2. 配置被动健康检查（分析真实流量）

a6 upstream create -f - <<'EOF'
{
  "id": "backend-passive",
  "type": "roundrobin",
  "nodes": {
    "backend-1:8080": 1,
    "backend-2:8080": 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

无需主动探测，APISIX 会观察真实流量的响应。节点连续返回 3 次 5xx 错误后会被移除，连续成功 5 次后恢复。

注意：仅使用被动健康检查时，被移除的节点无法接收流量，因此也无法通过真实请求恢复。建议与主动健康检查结合使用。

3. 同时配置主动和被动检查（生产环境推荐）

a6 upstream create -f - <<'EOF'
{
  "id": "production-backend",
  "type": "roundrobin",
  "nodes": {
    "backend-1:8080": 1,
    "backend-2:8080": 1,
    "backend-3:8080": 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

4. 检查上游健康状况

# View health status of all nodes
a6 upstream health backend

常见模式

TCP 健康检查（非 HTTP 服务）

{
  "checks": {
    "active": {
      "type": "tcp",
      "healthy": {
        "interval": 5,
        "successes": 2
      },
      "unhealthy": {
        "interval": 2,
        "tcp_failures": 3,
        "timeouts": 2
      }
    }
  }
}

HTTPS 健康检查及证书验证

{
  "checks": {
    "active": {
      "type": "https",
      "http_path": "/health",
      "https_verify_certificate": true,
      "healthy": {
        "interval": 10,
        "successes": 2,
        "http_statuses": [200]
      },
      "unhealthy": {
        "interval": 5,
        "http_failures": 3
      }
    }
  }
}

自定义探测请求头（用于受保护的健康检查端点）

{
  "checks": {
    "active": {
      "type": "http",
      "http_path": "/internal/health",
      "host": "health.internal",
      "req_headers": [
        "Authorization: Bearer health-check-token",
        "X-Health-Check: true"
      ],
      "healthy": {
        "interval": 10,
        "successes": 2
      },
      "unhealthy": {
        "interval": 5,
        "http_failures": 3
      }
    }
  }
}

快速检测不健康节点

{
  "checks": {
    "active": {
      "type": "http",
      "http_path": "/health",
      "timeout": 2,
      "healthy": {
        "interval": 3,
        "successes": 1
      },
      "unhealthy": {
        "interval": 1,
        "http_failures": 1,
        "timeouts": 1
      }
    }
  }
}

可在 1 秒内发现故障，并在 3 秒内确认恢复。

配置同步示例

version: "1"
upstreams:
  - id: production-backend
    type: roundrobin
    nodes:
      "backend-1:8080": 1
      "backend-2:8080": 1
      "backend-3:8080": 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
    uri: /api/*
    upstream_id: production-backend

故障排查

症状	原因	解决方法
未执行健康检查	没有路由引用该上游	健康检查仅对至少被一条路由引用的上游执行
所有节点都被标记为不健康	健康检查端点返回了错误的状态码	确认 `http_statuses` 包含健康检查端点实际返回的状态码
节点无法恢复	被动检查无法向不健康节点发送流量	添加主动健康检查以恢复节点
探测请求访问了错误端点	`http_path` 默认为 `/`	将 `http_path` 设置为实际的健康检查端点
TLS 探测失败	证书验证失败	设置`https_verify_certificate: false`或修复证书
健康检查过于敏感	阈值过低或端点不稳定	提高 `failures` 阈值并延长 `interval`
`a6 upstream health` 未显示数据	APISIX 尚未开始健康检查	等待首个探测周期完成

本文根据 api7/a6 仓库中的 a6-recipe-health-check/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。

概览​

适用场景​

健康检查配置参考​

主动健康检查​

被动健康检查​

分步操作：配置健康检查​

1. 配置主动 HTTP 健康检查​

2. 配置被动健康检查（分析真实流量）​

3. 同时配置主动和被动检查（生产环境推荐）​

4. 检查上游健康状况​

常见模式​

TCP 健康检查（非 HTTP 服务）​

HTTPS 健康检查及证书验证​

自定义探测请求头（用于受保护的健康检查端点）​

快速检测不健康节点​

配置同步示例​

故障排查​

概览