运行端点健康检查（测试版）

Magic Transit 使用端点健康检查来确定您的网际连接的整体健康状况。探测器源自 Cloudflare 基础设施、客户网络命名空间之外，并以您网络内部、超出隧道终端边界路由器的 IP 地址为目标。这些“长距离”探测纯粹用于诊断目的。

在选择通过健康检查监控哪些端点 IP 地址时，请遵循以下准则：

为 Cloudflare 广播的每个前缀提供一个 IP 地址。
通过相同 ISP（互联网服务提供商）和基础结构路由的冗余 IP 不是必需的，但在排查故障时非常有用。

Cloudflare 会从已发布的 Cloudflare IP 范围 ↗中 ping 健康检查 IP，也可以通过 Cloudflare API 获取该范围。

在为 IP 前缀配置端点健康检查时，请选择该 IP 前缀范围内的 IP 地址。有关端点健康检查配置的示例，请参考下表。

前缀	端点 IP 地址
`103.21.244.0/24`	`103.21.244.100`
`103.21.245.0/24`	`103.21.245.100`

有关更多信息，请参考隧道健康检查。

配置端点健康检查（测试版）

您只能通过 Cloudflare API 配置端点健康检查。仪表板中不提供此功能。目前，配置健康检查是一项测试版功能。

请参考 API 文档以了解如何创建、列出和删除端点健康检查。以下示例创建了一个新的端点健康检查。

curl "https://api.cloudflare.com/client/v4/accounts/account_id/diagnostics/endpoint-healthchecks" \
	--request POST \
	--json '{
		"check_type": "icmp",
		"endpoint": "8.31.160.1",
		"name": "Datacenter 1 - primary"
	}'

{
    "result": {
        "id": "<HEALTH_CHECK_ID>",
        "check_type": "icmp",
        "endpoint": "8.31.160.1",
        "name": "Datacenter 1 - primary"
    },
    "success": true,
    "errors": [],
    "messages": []
}

使用 GraphQL 查询端点健康检查

使用 GraphQL Analytics API 查询您账户的终端节点健康检查结果。magicEndpointHealthCheckAdaptiveGroups 数据集返回按您指定的维度和时间间隔聚合的探测结果。

将所有 GraphQL 查询作为 HTTP POST 请求发送到 https://api.cloudflare.com/client/v4/graphql。

前提条件

您需要以下各项来查询终端节点健康检查数据：

您的账户 ID。
具有 Account > Account Analytics > Read 权限的 API 令牌。有关详细信息，请参阅配置 Analytics API 令牌。

查询参数

以下参数是 filter 对象中一些最常用的参数：

参数	描述
`date_geq`	`YYYY-MM-DD` 格式的查询开始日期（例如，`2026-01-01`）。与基于日期的截断维度一起使用时，将返回此日期之后（含此日期）的结果。您还可以使用完整的 ISO 8601 时间戳（例如，`2026-01-01T00:00:00Z`）。
`date_leq`	（可选）查询的结束日期。使用与 `date_geq` 相同的格式。
`datetime_geq`	（可选） ISO 8601 格式的开始时间戳（例如，`2026-01-01T00:00:00Z`）。对于基于时间的截断维度，请用来代替 `date_geq`。
`datetime_leq`	（可选） ISO 8601 格式的结束时间戳。
`limit`	要返回的结果组的最大数量。

您还可以根据可用维度表中列出的任何维度进行过滤。在维度名称后附加运算符后缀以创建过滤器 —— 例如，endpoint_in 用于按终端节点列表进行过滤，或者 checkType_neq 用于排除特定的检查类型。使用不带后缀的维度名称可过滤等值情况。有关支持的运算符的完整列表，请参阅过滤。

可用维度

您可以在 dimensions 字段中查询以下维度：

维度	描述
`checkId`	已配置健康检查的唯一 ID。
`checkType`	健康检查的类型（例如，`icmp`）。
`endpoint`	正在检查的终端节点的 IP 地址。
`name`	配置时分配给健康检查的名称（如果未设置则可能为空）。
`date`	截断到天的时间戳事件。
`datetime`	完整的时间戳事件。
`datetimeMinute`	截断到分钟的时间戳事件。
`datetimeFiveMinutes`	截断到五分钟间隔的时间戳事件。
`datetimeFifteenMinutes`	截断到 15 分钟间隔的时间戳事件。
`datetimeHalfOfHour`	截断到 30 分钟间隔的时间戳事件。
`datetimeHour`	截断到小时的时间戳事件。

可用指标

指标	描述
`count`	组中健康检查事件的总数。
`sum.total`	发送的健康检查探测总数。
`sum.failures`	失败的健康检查探测数。
`avg.lossPercentage`	计算得出的平均丢包百分比 (0-100)。

API 调用

以下示例查询特定账户的终端节点健康检查结果，并返回以五分钟间隔聚合的探测计数。将 <ACCOUNT_ID> 替换为您的账户 ID，将 <API_TOKEN> 替换为您的 API 令牌。

echo '{ "query":
  "query GetEndpointHealthCheckResults($accountTag: string, $datetimeStart: string) {
    viewer {
      accounts(filter: {accountTag: $accountTag}) {
        magicEndpointHealthCheckAdaptiveGroups(
          filter: {
            datetime_geq: $datetimeStart
          }
          limit: 10
        ) {
          count
          dimensions {
            checkId
            checkType
            endpoint
            datetimeFiveMinutes
          }
          sum {
            failures
            total
          }
        }
      }
    }
  }",
  "variables": {
    "accountTag": "<ACCOUNT_ID>",
    "datetimeStart": "2026-01-21T00:00:00Z"
  }
}' | tr -d '\n' | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @-

将输出通过管道传输到 jq，以格式化 JSON 响应以便于阅读：

... | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @- | jq .

示例响应

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "magicEndpointHealthCheckAdaptiveGroups": [
            {
              "count": 288,
              "dimensions": {
                "checkId": "90b478c7-bb51-4640-b94b-2c3050e9fa00",
                "checkType": "icmp",
                "datetimeFiveMinutes": "2026-01-21T12:00:00Z",
                "endpoint": "103.21.244.100"
              },
              "sum": {
                "failures": 0,
                "total": 288
              }
            },
            {
              "count": 288,
              "dimensions": {
                "checkId": "90b478c7-bb51-4640-b94b-2c3050e9fa00",
                "checkType": "icmp",
                "datetimeFiveMinutes": "2026-01-21T12:05:00Z",
                "endpoint": "103.21.244.100"
              },
              "sum": {
                "failures": 2,
                "total": 288
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}

在此响应中，sum.total 是在间隔期间发送的探测数，sum.failures 是未收到回复的数量。failures 值为 0 表示在此期间终端节点完全可达。

配置端点健康检查警报

您可以设置警报，以便当端点的健康状态低于您定义的阈值时获得通知。

发起 GET 请求以获取已配置的所有端点健康检查的 ID 列表：

curl "https://api.cloudflare.com/client/v4/accounts/account_id/diagnostics/endpoint-healthchecks" \
	--request GET

{
    "result": [
        {
            "id": "<HEALTH_CHECK_ID>",
            "check_type": "icmp",
            "endpoint": "8.31.160.1",
            "name": "Datacenter 1 - primary"
        }
    ],
    "success": true,
    "errors": [],
    "messages": []
}

记下您想要获取警报的端点的 id 值。
在 Cloudflare 仪表板中，转到 Notifications（通知） 页面。

Go to Notifications ↗

选择 Add（添加）。
在下拉菜单中，选择 Magic Transit。
选择 Magic Endpoint Health Check Alert（Magic 端点健康检查警报）。
为您的新通知提供一个名称，并根据需要提供说明。
在 Service Level Objective (SLO) (服务级别目标) 下拉菜单中，为您的通知选择 SLO 阈值。SLO 定义了必须通过的端点健康检查的百分比。如果通过的端点健康检查数量低于 SLO，Cloudflare 将生成警报：
- High（高） - 99%
- Medium（中等） - 98%
- Low（低） - 97%
在 SLO 下方的下拉菜单中，选择与您在步骤 1 中通过 API 获取的 id 相匹配的 id 值。此 id 应与您希望接收通知的端点健康检查相匹配。
选择您的首选通知方法（例如电子邮件或 Webhook）。
选择Save（保存） (Save)。

每当端点健康检查的 SLO 降至您选择的阈值以下时，您现在都将通过首选方法收到通知。