---
title: "配置健康检查"
description: "使用 Hurl 或自定义命令检查应用响应，配置目标、执行间隔和发布验证。"
---

> Documentation Index
> Fetch the complete documentation index at: https://cdelivery.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置健康检查

XHealth 定期运行一个检查任务，验证应用是否满足你定义的条件。它独立于容器运行状态；配置和修改需要 Operator 或 Admin。

## 立即执行

Operator 或 Admin 可以在 XHealth 页面点击 **立即执行**，调用不带请求体的 `POST /api/apps/{name}/xhealth/run`，或使用 MCP／Agent 工具 `xhealth_run` 并传入 `app`。检查必须已启用，执行使用已保存的配置，目标为当前应用。等待启动或运行中再次触发会返回 `409`；下次定时间隔从新一轮开始时起算。Guardian 的候选检查独立运行。

API 接受请求后返回 `202` 和 `{"ok":true}`，不等待检查结果。刷新页面、调用 `xhealth_get` 或查看 XHealth 日志了解当前检查。超时或响应丢失不代表提交失败，应先查询状态，再决定是否重新执行。请求不去重，一轮结束后再次调用会启动新一轮。

## 创建检查

1. 打开应用的 **XHealth** 页面。
2. 选择 Hurl 文件或自定义命令。
3. 选择检查目标，填写执行间隔；间隔至少为 1 分钟。
4. 初次配置时先保持 Guardian 关闭，确认检查本身能够稳定通过。
5. 保存后观察状态与检查日志。

目标可以来自应用已配置的域名、发布端口，或直接指定容器内部端口。域名及发布端口最终用于定位应用的目标端口，规则必须能够唯一确定它。

## Hurl 示例

为 Nginx 入门应用创建一个文本文件：

```hurl
GET {{TARGET_URL}}/
HTTP 200
```

上传该文件，选择可用的 Hurl 版本，将目标设置为内部端口 `80`，间隔设为 `1 分钟`。文件格式见 [Hurl 请求文档](https://hurl.dev/docs/request.html)。

CDelivery 通过 `HURL_VARIABLE_TARGET_URL` 提供 `TARGET_URL`。默认值使用内部 HTTP 地址和所选目标端口，因此这个示例检查应用响应，不等同于检查公网 DNS、外部 HTTPS 证书或完整客户端链路。

文件必须非空，大小不超过 1,023,999 字节。之后只调整间隔等设置时，可保留已使用的文件。

## 自定义命令

自定义检查使用应用镜像运行，镜像必须包含所需工具。平台提供：

| 环境变量 | 含义 |
| --- | --- |
| `TARGET_HOST` | 本轮检查应访问的应用主机 |
| `TARGET_PORT` | 已解析的目标端口 |

命令应以退出码 0 表示成功，非 0 表示失败。需要变量替换或管道时，显式使用镜像内存在的 shell；不要把检查任务中的 `localhost` 当作正在运行的业务容器。

例如镜像确实包含 `curl` 和 `sh` 时：

```text
sh -c 'curl --fail --silent --show-error "http://$TARGET_HOST:$TARGET_PORT/health"'
```

检查应尽量只读，避免周期性检查重复创建订单或修改业务数据。

## 与 Guardian 的关系

验证检查稳定可靠后，可以在同一页面开启 Guardian，让相关配置更新先通过候选验证。本地数据应用不支持 Guardian。完整流程见[发布验证](/docs/zh-cn/guides/release-safety/guardian/)。

删除检查会停止后续周期性验证，并影响依赖它的发布保护。修改目标、域名或端口时，应同时核对检查仍能解析到正确目标。

Source: https://cdelivery.dev/docs/zh-cn/guides/release-safety/xhealth/index.mdx