---
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-tw/guides/release-safety/guardian/)。

刪除檢查會停止後續週期性驗證，並影響依賴它的發佈保護。修改目標、網域或連接埠時，應同時核對檢查仍能解析到正確目標。

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