跳到主要内容

配置上游健康检查

健康检查是一种根据上游服务的响应能力来确定其健康状况的机制。启用健康检查后，APISIX 将仅将请求转发到被视为健康的上游服务，而不会将请求转发到被视为不健康的服务。

健康检查通常有两种方法：

  • 主动健康检查：APISIX 主动并定期向上游服务发送请求，并根据这些请求的响应确定其健康状况。
  • 被动健康检查：APISIX 根据上游服务对客户端请求的响应来确定其健康状况，而无需主动探测。

本指南将向你展示如何为你的上游服务配置主动和被动健康检查。

前置条件​

  • 安装 Docker。
  • 安装 cURL 以向服务发送请求进行验证。
  • 按照 快速入门教程 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。

启动示例上游服务​

在与 APISIX 相同的 Docker 网络中启动两个 NGINX 实例作为示例上游服务：

DOCKER_NETWORK=apisix-quickstart-net
docker run -d -p 8080:80 --network=${DOCKER_NETWORK} --name nginx1 nginx
docker run -d -p 8081:80 --network=${DOCKER_NETWORK} --name nginx2 nginx

验证两个 NGINX 实例都在运行：

for port in 8080 8081; do
  curl -s "http://127.0.0.1:$port" | grep -q "Welcome to nginx" &&
  echo "NGINX welcome page available on port $port."
done

你应该看到以下响应：

NGINX welcome page available on port 8080.
NGINX welcome page available on port 8081.

配置主动健康检查​

主动检查通过定期向服务发送请求或探测并查看它们的响应情况来确定上游服务的健康状况。

以下示例说明如何：

  • 在主动探测中发送自定义方法和请求体；
  • 使用主动检查检测上游状态变化；
  • 在所有上游状态均不健康时观察 APISIX 如何转发请求。

主动 HTTP 和 HTTPS 检查默认使用带空请求体的 GET。当健康端点需要请求负载时，可将 http_method 设为任意受支持的 HTTP 方法，并使用 http_req_body。非空请求体会自动添加相应的 Content-Length 头。

发送 POST 健康检查​

将第一个示例 NGINX 服务配置为仅接受 POST 的健康端点，并记录探测的方法、路径和内容长度：

docker exec nginx1 /bin/sh -c 'cat > /etc/nginx/conf.d/default.conf <<"EOF"
log_format health_probe "$request_method $uri $content_length";

server {
  listen 80;
  access_log /tmp/health-probe.log health_probe;

  location = /health {
    if ($request_method != POST) {
      return 405;
    }
    return 200 "healthy\n";
  }

  location / {
    return 200 "Welcome to nginx!\n";
  }
}
EOF
nginx -s reload'

创建一个带 JSON 请求体的 POST 主动检查路由：

curl "http://127.0.0.1:9180/apisix/admin/routes/post-health-check" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "uri": "/post-health-check",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "nginx1:80": 1
      },
      "checks": {
        "active": {
          "type": "http",
          "http_method": "POST",
          "http_path": "/health",
          "http_req_body": "{\"status\":\"check\"}",
          "req_headers": [
            "Content-Type: application/json"
          ],
          "healthy": {
            "interval": 2,
            "successes": 1
          },
          "unhealthy": {
            "interval": 1,
            "http_failures": 1
          }
        }
      }
    }
  }'

通过路由发送请求以启动健康检查器，等待一次探测后检查 NGINX access log：

curl -i "http://127.0.0.1:9080/post-health-check"
sleep 2
docker exec nginx1 /bin/sh -c "grep 'POST /health' /tmp/health-probe.log | tail -n 1"

路由请求应返回 200 OK。日志应确认主动探测使用 POST，并发送了 18 字节的请求体：

POST /health 18

示例：上游服务状态更改​

以下示例演示了 APISIX 主动健康检查如何响应健康上游服务变为：部分不可用、全部不可用以及全部恢复的情况。

创建一个指向这两个服务的路由，并配置每 2 秒运行一次的主动健康检查：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "example-hc-route",
  "uri":"/",
  "upstream": {
    "type":"roundrobin",
    "nodes": {
      "nginx1:80": 1,
      "nginx2:80": 1
    },
    "checks": {
      "active": {
        "type": "http",
        "http_path": "/",
        "healthy": {
          "interval": 2,
          "successes": 1
        },
        "unhealthy": {
          "interval": 1,
          "timeouts": 3
        }
      }
    }
  }
}'

❶ type：主动健康检查的类型。

❷ http_path：要主动探测的 HTTP 请求路径。

❸ healthy.interval：定期检查健康节点的时间间隔（以秒为单位）。

❹ healthy.successes：判定上游节点为健康的成功计数阈值。

❺ unhealthy.interval：定期检查不健康节点的时间间隔（以秒为单位）。

❻ unhealthy.timeouts：判定上游节点为不健康的超时计数阈值。

验证​

你将验证上述配置，以了解 APISIX 上游健康检查在不同场景下的响应：

如果你使用 快速入门 在 Docker 中启动 APISIX，Control API 端口 9090 已经映射 (-p 9090:9090)。

验证两个上游服务都健康​

向路由发送请求以开始健康检查：

curl "http://127.0.0.1:9080/"

要查看上游健康状态，请向 Control API 中的健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到类似以下的响应：

[
  {
    "name": "/apisix/routes/example-hc-route",
    "type": "http",
    "nodes": [
      {
        "port": 80,
        "counter": {
          "http_failure": 0,
          "tcp_failure": 0,
          "timeout_failure": 0,
          "success": 0
        },
        "ip": "172.24.0.5",
        "status": "healthy"
      },
      {
        "port": 80,
        "counter": {
          "http_failure": 0,
          "tcp_failure": 0,
          "timeout_failure": 0,
          "success": 0
        },
        "ip": "172.24.0.4",
        "status": "healthy"
      }
    ]
  }
]

验证当一个上游服务不可用时​

使一个上游服务暂时不可用，以验证 APISIX 是否报告其中一个上游服务不健康：

docker container stop nginx1

等待几秒钟，然后向健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到类似以下的响应，显示其中一个上游节点有 3 次超时失败并被标记为不健康：

[
  {
    "name": "/apisix/routes/example-hc-route",
    "type": "http",
    "nodes": [
      {
        "port": 80,
        "counter": {
          "http_failure": 0,
          "tcp_failure": 0,
          "timeout_failure": 0,
          "success": 0
        },
        "ip": "172.24.0.5",
        "status": "healthy"
      },
      {
        "port": 80,
        "counter": {
          "http_failure": 0,
          "tcp_failure": 0,
          "timeout_failure": 3,
          "success": 0
        },
        "ip": "172.24.0.4",
        "status": "unhealthy"
      }
    ]
  }
]

向路由发送请求，查看 APISIX 是否将请求转发到另一个健康节点：

curl -i "http://127.0.0.1:9080/"

你应该收到 HTTP/1.1 200 OK 响应。

验证两个上游服务都不可用​

使另一个上游服务暂时不可用，以验证 APISIX 是否报告两个上游服务都不健康：

docker container stop nginx2

等待几秒钟，然后向健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到类似以下的响应，显示两个上游节点都有 3 次超时失败并被标记为不健康：

[
  {
    "name": "/apisix/routes/example-hc-route",
    "type": "http",
    "nodes": [
      {
        "port": 80,
        "counter": {
          "http_failure": 0,
          "tcp_failure": 0,
          "timeout_failure": 3,
          "success": 0
        },
        "ip": "172.24.0.5",
        "status": "unhealthy"
      },
      {
        "port": 80,
        "counter": {
          "http_failure": 0,
          "tcp_failure": 0,
          "timeout_failure": 3,
          "success": 0
        },
        "ip": "172.24.0.4",
        "status": "unhealthy"
      }
    ]
  }
]

向路由发送请求：

curl -i "http://127.0.0.1:9080/"

你应该收到 HTTP/1.1 502 Bad Gateway 响应。

验证两个上游服务都已恢复​

使两个服务再次可用，以验证 APISIX 是否报告两个上游服务都健康：

docker container start nginx1 nginx2

等待几秒钟，然后向健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到显示两个上游节点都健康的响应，类似于 开始时两个服务都健康的情况。

示例：当状态不健康时转发请求​

以下示例演示了即使所有上游健康状态都不健康，APISIX 仍会将客户端请求转发到上游服务。

创建一个指向这两个服务的路由，并配置每 2 秒运行一次的主动健康检查：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "example-hc-route",
  "uri":"/",
  "upstream": {
    "type":"roundrobin",
    "nodes": {
      "nginx1:80": 1,
      "nginx2:80": 1
    },
    "checks": {
      "active": {
        "type": "http",
        "http_path": "/404",
        "healthy": {
          "interval": 2,
          "successes": 1
        },
        "unhealthy": {
          "interval": 1,
          "http_failures": 2
        }
      }
    }
  }
}'

❶ type：主动健康检查的类型。

❷ http_path：要主动探测的 HTTP 请求路径。为方便演示，这里设置为 /404，这是一个上游服务中不存在的路径。因此，主动健康检查应始终认为这两个服务不健康。

❸ unhealthy.http_failures：判定上游节点为不健康的 HTTP 失败计数阈值。

验证​

如果你使用 快速入门 在 Docker 中启动 APISIX，Control API 端口 9090 已经映射 (-p 9090:9090)。

向路由发送请求以开始健康检查：

curl -i "http://127.0.0.1:9080/"

你应该收到 HTTP/1.1 200 OK 响应。

向健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到类似以下的响应：

[
  {
    "name": "/apisix/routes/example-hc-route",
    "nodes": [
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 2,
          "success": 0,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.5",
        "status": "unhealthy"
      },
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 2,
          "success": 0,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.4",
        "status": "unhealthy"
      }
    ],
    "type": "http"
  }
]

向路由发送请求以查看 APISIX 是否仍转发请求：

curl -i "http://127.0.0.1:9080/"

你应该收到 HTTP/1.1 200 OK 响应。这验证了即使两个服务都被标记为不健康，APISIX 仍会将客户端请求转发到上游服务。

配置被动健康检查​

APISIX 要求将主动健康检查与被动健康检查一起使用。当上游服务变得不健康时，主动健康检查会定期检查上游服务是否已恢复。

备注

目前已知存在一个问题，即通过 Control API 显示的健康检查数据无法准确反映实际健康状态，因此你的测试结果可能与所示示例不同。此问题正在积极解决中。但是，被动健康检查机制本身运行正常，并继续按预期路由请求。

示例：上游服务状态更改​

创建指向这两个服务的路由，并配置主动和被动健康检查：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "example-hc-route",
  "uri": "/404",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "nginx1:80": 1,
      "nginx2:80": 1
    },
    "checks": {
      "active": {
        "type": "http",
        "http_path": "/",
        "healthy": {
          "interval": 99999,
          "successes": 1
        },
        "unhealthy": {
          "interval": 30
        }
      },
      "passive": {
        "healthy": {
          "http_statuses": [200,201,202,300,301,302],
          "successes": 1
        },
        "unhealthy": {
          "http_statuses": [429,404,500,501,502,503,504,505],
          "http_failures": 3
        }
      }
    }
  }
}'

❶ uri：路由匹配的 URI 路径。为方便演示，这里设置为 /404，这是一个上游服务中不存在的路径。因此，当发出请求时，两个上游服务都应响应 404 状态代码。

❷ active.healthy.interval：定期检查健康节点的时间间隔（以秒为单位）。

❸ active.unhealthy.interval：定期检查不健康节点的时间间隔（以秒为单位）。

❹ passive.healthy.http_statuses：被视为健康的响应 HTTP 状态代码。

❺ passive.unhealthy.http_statuses：被视为不健康的响应 HTTP 状态代码。不健康的响应会计入 http_failures。

❻ passive.unhealthy.http_failures：判定上游节点为不健康的 HTTP 失败计数阈值。

验证​

如果你使用 快速入门 在 Docker 中启动 APISIX，Control API 端口 9090 已经映射 (-p 9090:9090)。

向路由发送请求以开始健康检查：

curl -i "http://127.0.0.1:9080/404"

你应该看到 HTTP/1.1 404 Not Found 响应。

向健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到类似以下的响应：

[
  {
    "name": "/apisix/routes/example-hc-route",
    "nodes": [
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 1,
          "success": 0,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.5",
        "status": "mostly_healthy"
      },
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 0,
          "success": 0,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.4",
        "status": "healthy"
      }
    ],
    "type": "http"
  }
]

❶ http_failure 的计数为 1，这是由于前一个请求的 404 响应。

❷ mostly_healthy 状态表示当前节点状态健康，但 APISIX 开始在健康检查期间收到不健康的指示。

生成连续请求以调用 404 响应：

resp=$(seq 10 | xargs -I{} curl "http://127.0.0.1:9080/404" -o /dev/null -s -w "%{http_code}\n") && \
  count=$(echo "$resp" | grep "404" | wc -l) && \
  echo "Invoked $count responses with 404 status code."

向健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到类似以下的响应：

[
  {
    "name": "/apisix/routes/example-hc-route",
    "nodes": [
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 3,
          "success": 0,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.4",
        "status": "unhealthy"
      },
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 4,
          "success": 0,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.5",
        "status": "unhealthy"
      }
    ],
    "type": "http"
  }
]

等待至少 30 秒，以便主动检查探测 / 处的上游服务并将其标记为健康。然后，向健康检查端点发送请求：

curl "http://127.0.0.1:9090/v1/healthcheck"

你应该看到类似以下的响应：

[
  {
    "name": "/apisix/routes/example-hc-route",
    "nodes": [
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 0,
          "success": 1,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.4",
        "status": "healthy"
      },
      {
        "counter": {
          "timeout_failure": 0,
          "http_failure": 0,
          "success": 1,
          "tcp_failure": 0
        },
        "port": 80,
        "ip": "172.25.0.5",
        "status": "healthy"
      }
    ],
    "type": "http"
  }
]

禁用所有健康检查​

你可以全局禁用所有上游健康检查。这在紧急维护等场景中很有用，因为健康检查可能会干扰路由或回退行为。

要禁用所有健康检查，请按如下方式更新你的 配置文件：

conf/config.yaml
apisix:
  disable_upstream_healthcheck: true

重新加载 APISIX 以使配置更改生效：

docker exec apisix-quickstart apisix reload

下一步​

你现在已经了解了如何为 APISIX 中的上游服务配置主动和被动健康检查。要了解有关上游健康检查可用配置选项的更多信息，请参阅 Admin API，Upstream。

APISIX还提供了一个api-breaker插件,该插件根据上游服务的健康情况执行断路器功能,并帮助提高应用的韧性.