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。