This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new e2d0f0b16 docs: refactor health check doc (#8129)
e2d0f0b16 is described below
commit e2d0f0b16bb157412684a38b129d12acb4628d39
Author: Fei Han <[email protected]>
AuthorDate: Tue Oct 25 10:11:37 2022 +0800
docs: refactor health check doc (#8129)
---
CHANGELOG.md | 2 +-
README.md | 2 +-
docs/en/latest/admin-api.md | 2 +-
docs/en/latest/config.json | 7 +-
docs/en/latest/control-api.md | 2 +-
docs/en/latest/terminology/upstream.md | 2 +-
docs/en/latest/{ => tutorials}/health-check.md | 66 ++++++++--
docs/zh/latest/CHANGELOG.md | 2 +-
docs/zh/latest/README.md | 2 +-
docs/zh/latest/admin-api.md | 2 +-
docs/zh/latest/config.json | 7 +-
docs/zh/latest/control-api.md | 2 +-
docs/zh/latest/health-check.md | 114 -----------------
docs/zh/latest/tutorials/health-check.md | 161 +++++++++++++++++++++++++
14 files changed, 230 insertions(+), 143 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8da19cb39..c849c9b40 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1222,7 +1222,7 @@ This release brings many new features such as health
check and circuit breaker,
### Core
-- :sunrise: **[Health Check and Circuit
Breaker](https://github.com/apache/incubator-apisix/blob/master/docs/en/latest/health-check.md)**:
Enable health check on the upstream node, and will automatically filter
unhealthy nodes during load balancing to ensure system stability.
[#249](https://github.com/apache/incubator-apisix/pull/249)
+- :sunrise: **[Health Check and Circuit
Breaker](https://github.com/apache/incubator-apisix/blob/master/docs/en/latest/tutorials/health-check.md)**:
Enable health check on the upstream node, and will automatically filter
unhealthy nodes during load balancing to ensure system stability.
[#249](https://github.com/apache/incubator-apisix/pull/249)
- Anti-ReDoS(Regular expression Denial of Service).
[#252](https://github.com/apache/incubator-apisix/pull/250)
- supported debug mode.
[#319](https://github.com/apache/incubator-apisix/pull/319)
- allowed to use different router.
[#364](https://github.com/apache/incubator-apisix/pull/364)
diff --git a/README.md b/README.md
index ee401d93b..1ee2093e1 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,7 @@ A/B testing, canary release, blue-green deployment, limit
rate, defense against
- [Response Rewrite](docs/en/latest/plugins/response-rewrite.md): Set
customized response status code, body and header to the client.
- Dynamic Load Balancing: Round-robin load balancing with weight.
- Hash-based Load Balancing: Load balance with consistent hashing sessions.
- - [Health Checks](docs/en/latest/health-check.md): Enable health check on
the upstream node and will automatically filter unhealthy nodes during load
balancing to ensure system stability.
+ - [Health Checks](docs/en/latest/tutorials/health-check.md): Enable health
check on the upstream node and will automatically filter unhealthy nodes during
load balancing to ensure system stability.
- Circuit-Breaker: Intelligent tracking of unhealthy upstream services.
- [Proxy Mirror](docs/en/latest/plugins/proxy-mirror.md): Provides the
ability to mirror client requests.
- [Traffic Split](docs/en/latest/plugins/traffic-split.md): Allows users to
incrementally direct percentages of traffic between various upstreams.
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
index f024ffb51..ecdd046c7 100644
--- a/docs/en/latest/admin-api.md
+++ b/docs/en/latest/admin-api.md
@@ -651,7 +651,7 @@ In addition to the equalization algorithm selections,
Upstream also supports pas
| discovery_type | required, if `service_name` is used |
The type of service [discovery](discovery.md).
[...]
| hash_on | optional |
Only valid if the `type` is `chash`. Supports Nginx variables (`vars`), custom
headers (`header`), `cookie` and `consumer`. Defaults to `vars`.
[...]
| key | optional |
Only valid if the `type` is `chash`. Finds the corresponding node `id`
according to `hash_on` and `key` values. When `hash_on` is set to `vars`, `key`
is a required parameter and it supports [Nginx
variables](http://nginx.org/en/docs/varindex.html). When `hash_on` is set as
`header`, `key` is a required parameter, and `header name` can be customized.
When `hash_on` is set to `cookie`, `key` is also a required p [...]
-| checks | optional |
Configures the parameters for the [health check](health-check.md).
[...]
+| checks | optional |
Configures the parameters for the [health check](./tutorials/health-check.md).
[...]
| retries | optional |
Sets the number of retries while passing the request to Upstream using the
underlying Nginx mechanism. Set according to the number of available backend
nodes by default. Setting this to `0` disables retry.
[...]
| retry_timeout | optional |
Timeout to continue with retries. Setting this to `0` disables the retry
timeout.
[...]
| timeout | optional |
Sets the timeout (in seconds) for connecting to, and sending and receiving
messages to and from the Upstream.
[...]
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 5a0d6e586..0bbbd062d 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -20,7 +20,8 @@
"tutorials/expose-api",
"tutorials/protect-api",
"tutorials/observe-your-api",
- "tutorials/cache-api-responses"
+ "tutorials/cache-api-responses",
+ "tutorials/health-check"
]
},
{
@@ -285,10 +286,6 @@
"type": "doc",
"id": "deployment-modes"
},
- {
- "type": "doc",
- "id": "health-check"
- },
{
"type": "doc",
"id": "router-radixtree"
diff --git a/docs/en/latest/control-api.md b/docs/en/latest/control-api.md
index 7dd55e24f..c6944f2b5 100644
--- a/docs/en/latest/control-api.md
+++ b/docs/en/latest/control-api.md
@@ -94,7 +94,7 @@ Returns the JSON schema used by the APISIX instance:
Introduced in [v2.3](https://github.com/apache/apisix/releases/tag/2.3).
-Returns a [health check](health-check.md) of the APISIX instance.
+Returns a [health check](./tutorials/health-check.md) of the APISIX instance.
```json
[
diff --git a/docs/en/latest/terminology/upstream.md
b/docs/en/latest/terminology/upstream.md
index 20101552b..b559735d6 100644
--- a/docs/en/latest/terminology/upstream.md
+++ b/docs/en/latest/terminology/upstream.md
@@ -124,7 +124,7 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-You can learn more about health checks [here](../health-check.md).
+You can learn more about health checks [here](../tutorials/health-check.md).
The examples below show configurations that use different `hash_on` types.
diff --git a/docs/en/latest/health-check.md
b/docs/en/latest/tutorials/health-check.md
similarity index 76%
rename from docs/en/latest/health-check.md
rename to docs/en/latest/tutorials/health-check.md
index 5e0f7a26a..ca407e700 100644
--- a/docs/en/latest/health-check.md
+++ b/docs/en/latest/tutorials/health-check.md
@@ -1,5 +1,10 @@
---
title: Health Check
+keywords:
+ - APISIX
+ - API Gateway
+ - Health Check
+description: This article describes how to use the health check feature of API
Gateway Apache APISIX to check the health status of upstream nodes.
---
<!--
@@ -21,22 +26,39 @@ title: Health Check
#
-->
-## Health Checks for Upstream
+## Description
-Health Check of Apache APISIX is based on
[lua-resty-healthcheck](https://github.com/api7/lua-resty-healthcheck).
+This article mainly introduces the health check function of Apache APISIX. The
health check function can proxy requests to healthy nodes when the upstream
node fails or migrates, avoiding the problem of service unavailability to the
greatest extent. The health check function of APISIX is implemented using
[lua-resty-healthcheck](https://github.com/api7/lua-resty-healthcheck), which
is divided into active check and passive check.
-Note:
+## Active check
-* We only start the health check when the upstream is hit by a request.
-There won't be any health check if an upstream is configured but isn't in used.
-* If there is no healthy node can be chosen, we will continue to access the
upstream.
-* We won't start the health check when the upstream only has one node, as we
will access
-it whether this unique node is healthy or not.
-* Active health check is required so that the unhealthy node can recover.
+Active health check mainly means that APISIX actively detects the
survivability of upstream nodes through preset probe types. APISIX supports
three probe types: `HTTP`, `HTTPS`, and `TCP`.
+
+When N consecutive probes sent to healthy node `A` fail, the node will be
marked as unhealthy, and the unhealthy node will be ignored by APISIX's load
balancer and cannot receive requests; if For an unhealthy node, if M
consecutive probes are successful, the node will be re-marked as healthy and
can be proxied.
+
+## Passive check
+
+Passive health check refers to judging whether the corresponding upstream node
is healthy by judging the response status of the request forwarded from APISIX
to the upstream node. Compared with the active health check, the passive health
check method does not need to initiate additional probes, but it cannot sense
the node status in advance, and there may be a certain amount of failed
requests.
+
+If `N` consecutive requests to a healthy node A fail, the node will be marked
as unhealthy.
+
+:::note
+
+Since unhealthy nodes cannot receive requests, nodes cannot be re-marked as
healthy using the passive health check strategy alone, so combining the active
health check strategy is usually necessary.
+
+:::
+
+:::tip
+
+- We only start the health check when the upstream is hit by a request. There
won't be any health check if an upstream is configured but isn't in used.
+- If there is no healthy node can be chosen, we will continue to access the
upstream.
+- We won't start the health check when the upstream only has one node, as we
will access it whether this unique node is healthy or not.
+
+:::
### Configuration instructions
-| Configuration item | Configuration type
| Value type | Value option | Defaults
| Description
|
+| Name | Configuration type
| Value type | Valid values | Default
| Description
|
| ----------------------------------------------- |
------------------------------- | ---------- | -------------------- |
---------------------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------------------
|
| upstream.checks.active.type | Active check
| string | `http` `https` `tcp` | http
| The type of active
check.
|
| upstream.checks.active.timeout | Active check
| integer | | 1
| The timeout period
of the active check (unit: second).
|
@@ -63,6 +85,8 @@ it whether this unique node is healthy or not.
### Configuration example
+You can enable health checks in routes via the Admin API:
+
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
@@ -113,4 +137,26 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
+If APISIX detects an unhealthy node, the following logs will be output in the
error log:
+
+```shell
+enabled healthcheck passive while logging request
+failed to receive status line from 'nil (127.0.0.1:1980)': closed
+unhealthy TCP increment (1/2) for '(127.0.0.1:1980)'
+failed to receive status line from 'nil (127.0.0.1:1980)': closed
+unhealthy TCP increment (2/2) for '(127.0.0.1:1980'
+```
+
+:::tip
+
+To observe the above log information, you need to adjust the error log level
to `info`.
+
+:::
+
The health check status can be fetched via `GET /v1/healthcheck` in [Control
API](./control-api.md).
+
+```shell
+
+curl http://127.0.0.1:9090/v1/healthcheck/upstreams/healthycheck -s | jq .
+
+```
diff --git a/docs/zh/latest/CHANGELOG.md b/docs/zh/latest/CHANGELOG.md
index a7907fd2d..5405f4042 100644
--- a/docs/zh/latest/CHANGELOG.md
+++ b/docs/zh/latest/CHANGELOG.md
@@ -1202,7 +1202,7 @@ title: CHANGELOG
### Core
-- :sunrise:
**[健康检查和服务熔断](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest//health-check.md)**:
对上游节点开启健康检查，智能判断服务状态进行熔断和连接。[#249](https://github.com/apache/incubator-apisix/pull/249)
+- :sunrise:
**[健康检查和服务熔断](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest/tutorials/health-check..md)**:
对上游节点开启健康检查，智能判断服务状态进行熔断和连接。[#249](https://github.com/apache/incubator-apisix/pull/249)
- 阻止 ReDoS(Regular expression Denial of Service).
[#252](https://github.com/apache/incubator-apisix/pull/250)
- 支持 debug 模式。[#319](https://github.com/apache/incubator-apisix/pull/319)
- 允许自定义路由。[#364](https://github.com/apache/incubator-apisix/pull/364)
diff --git a/docs/zh/latest/README.md b/docs/zh/latest/README.md
index d8062b77b..3adff87a0 100644
--- a/docs/zh/latest/README.md
+++ b/docs/zh/latest/README.md
@@ -89,7 +89,7 @@ A/B 测试、金丝雀发布（灰度发布）、蓝绿部署、限流限速、
- [Serverless](plugins/serverless.md)：在 APISIX 的每一个阶段，你都可以添加并调用自己编写的函数。
- 动态负载均衡：动态支持有权重的 round-robin 负载平衡。
- 支持一致性 hash 的负载均衡：动态支持一致性 hash 的负载均衡。
- - [健康检查](health-check.md)：启用上游节点的健康检查，将在负载均衡期间自动过滤不健康的节点，以确保系统稳定性。
+ -
[健康检查](./tutorials/health-check.md)：启用上游节点的健康检查，将在负载均衡期间自动过滤不健康的节点，以确保系统稳定性。
- 熔断器：智能跟踪不健康上游服务。
- [代理镜像](plugins/proxy-mirror.md)：提供镜像客户端请求的能力。
- [流量拆分](plugins/traffic-split.md)：允许用户逐步控制各个上游之间的流量百分比。
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index b588583c3..070800bf7 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -657,7 +657,7 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
| service_name | 必需，不能和 `nodes` 一起用 | string |
服务发现时使用的服务名，见[集成服务发现注册中心](./discovery.md)
| `a-bootiful-client` |
| discovery_type | 必需，如果设置了 `service_name` | string | 服务发现类型，见
[集成服务发现注册中心](./discovery.md)
| `eureka` |
| key | 条件必需 | 匹配类型 | 该选项只有类型是
`chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id，目前支持的 Nginx
内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr,
query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，[Nginx
变量列表](http://nginx.org/en/docs/varindex.html) |
|
-| checks | 可选 | health_checker |
配置健康检查的参数，详细可参考[health-check](health-check.md)
| |
+| checks | 可选 | health_checker |
配置健康检查的参数，详细可参考[health-check](./tutorials/health-check.md)
| |
| retries | 可选 | 整型 | 使用底层的
Nginx 重试机制将请求传递给下一个上游，默认启用重试且次数为后端可用的 node 数量。如果指定了具体重试次数，它将覆盖默认值。`0`
代表不启用重试机制。
|
|
| retry_timeout | 可选 | number |
限制是否继续重试的时间，若之前的请求和重试请求花费太多时间就不再继续重试。`0` 代表不启用重试超时机制。
| |
| timeout | 可选 | 超时时间对象 |
设置连接、发送消息、接收消息的超时时间，以秒为单位
| |
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index da96eb5da..4a6a486eb 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -19,7 +19,8 @@
"items": [
"tutorials/expose-api",
"tutorials/protect-api",
- "tutorials/observe-your-api"
+ "tutorials/observe-your-api",
+ "tutorials/health-check"
]
},
{
@@ -247,10 +248,6 @@
"discovery/kubernetes"
]
},
- {
- "type": "doc",
- "id": "health-check"
- },
{
"type": "doc",
"id": "router-radixtree"
diff --git a/docs/zh/latest/control-api.md b/docs/zh/latest/control-api.md
index 541034b0c..5594a73c7 100644
--- a/docs/zh/latest/control-api.md
+++ b/docs/zh/latest/control-api.md
@@ -92,7 +92,7 @@ APISIX 中一些插件添加了自己的 control API。如果你对他们感兴
引入自 2.3 版本
-使用以下格式返回当前的 [health check](health-check.md) 状态
+使用以下格式返回当前的 [health check](./tutorials/health-check.md) 状态
```json
[
diff --git a/docs/zh/latest/health-check.md b/docs/zh/latest/health-check.md
deleted file mode 100644
index b165ad561..000000000
--- a/docs/zh/latest/health-check.md
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: 健康检查
----
-
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
--->
-
-## Upstream 的健康检查
-
-Apache APISIX 的健康检查使用
[lua-resty-healthcheck](https://github.com/api7/lua-resty-healthcheck) 实现。
-
-注意：
-
-* 只有在 `upstream` 被请求时才会开始健康检查，如果 `upstream` 被配置但没有被请求，不会触发启动健康检查。
-* 如果没有健康的节点，那么请求会继续发送给上游。
-* 如果 `upstream` 中只有一个节点时不会触发启动健康检查，该唯一节点无论是否健康，请求都将转发给上游。
-* 主动健康检查是必须的，这样不健康的节点才会恢复。
-
-### 配置说明
-
-| 配置项 | 配置类型 | 值类型 | 值选项
| 默认值
| 描述
|
-| ----------------------------------------------- | ---------------------- |
------- | -------------------- |
---------------------------------------------------------------------------------------------
| ------------------------------------------------------------------------- |
-| upstream.checks.active.type | 主动检查 | string |
`http` `https` `tcp` | http
| 主动检查的类型。
|
-| upstream.checks.active.timeout | 主动检查 | integer |
| 1
| 主动检查的超时时间（单位：秒）。
|
-| upstream.checks.active.concurrency | 主动检查 | integer |
| 10
| 主动检查时同时检查的目标数。
|
-| upstream.checks.active.http_path | 主动检查 | string |
| /
| 主动检查的 HTTP 请求路径。
|
-| upstream.checks.active.host | 主动检查 | string |
| ${upstream.node.host}
| 主动检查的 HTTP 请求主机名。
|
-| upstream.checks.active.port | 主动检查 | integer |
`1` 至 `65535` | ${upstream.node.port}
| 主动检查的 HTTP 请求主机端口。
|
-| upstream.checks.active.https_verify_certificate | 主动检查 | boolean |
| true
| 主动检查使用 HTTPS 类型检查时，是否检查远程主机的 SSL 证书。 |
-| upstream.checks.active.req_headers | 主动检查 | array |
| []
| 主动检查使用 HTTP 或 HTTPS 类型检查时，设置额外的请求头信息。 |
-| upstream.checks.active.healthy.interval | 主动检查（健康节点）| integer | `>=
1` | 1
| 主动检查（健康节点）检查的间隔时间（单位：秒）|
-| upstream.checks.active.healthy.http_statuses | 主动检查（健康节点）| array |
`200` 至 `599` | [200, 302]
| 主动检查（健康节点）HTTP 或 HTTPS 类型检查时，健康节点的 HTTP
状态码。 |
-| upstream.checks.active.healthy.successes | 主动检查（健康节点）| integer | `1`
至 `254` | 2
| 主动检查（健康节点）确定节点健康的次数。 |
-| upstream.checks.active.unhealthy.interval | 主动检查（非健康节点）| integer | `>=
1` | 1
| 主动检查（非健康节点）检查的间隔时间（单位：秒）|
-| upstream.checks.active.unhealthy.http_statuses | 主动检查（非健康节点）| array |
`200` 至 `599` | [429, 404, 500, 501, 502, 503, 504, 505]
| 主动检查（非健康节点）HTTP 或 HTTPS 类型检查时，非健康节点的 HTTP
状态码。 |
-| upstream.checks.active.unhealthy.http_failures | 主动检查（非健康节点）| integer | `1`
至 `254` | 5
| 主动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
-| upstream.checks.active.unhealthy.tcp_failures | 主动检查（非健康节点）| integer | `1`
至 `254` | 2
| 主动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
-| upstream.checks.active.unhealthy.timeouts | 主动检查（非健康节点）| integer | `1`
至 `254` | 3
| 主动检查（非健康节点）确定节点非健康的超时次数。 |
-| upstream.checks.passive.healthy.http_statuses | 被动检查（健康节点）| array |
`200` 至 `599` | [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300,
301, 302, 303, 304, 305, 306, 307, 308] | 被动检查（健康节点）HTTP 或 HTTPS 类型检查时，健康节点的
HTTP 状态码。 |
-| upstream.checks.passive.healthy.successes | 被动检查（健康节点）| integer | `0`
至 `254` | 5
| 被动检查（健康节点）确定节点健康的次数。 |
-| upstream.checks.passive.unhealthy.http_statuses | 被动检查（非健康节点）| array |
`200` 至 `599` | [429, 500, 503]
| 被动检查（非健康节点）HTTP 或 HTTPS 类型检查时，非健康节点的 HTTP
状态码。 |
-| upstream.checks.passive.unhealthy.tcp_failures | 被动检查（非健康节点）| integer | `0`
至 `254` | 2
| 被动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
-| upstream.checks.passive.unhealthy.timeouts | 被动检查（非健康节点）| integer | `0`
至 `254` | 7
| 被动检查（非健康节点）确定节点非健康的超时次数。 |
-| upstream.checks.passive.unhealthy.http_failures | 被动检查（非健康节点）| integer | `0`
至 `254` | 5
| 被动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
-
-### 配置示例：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/index.html",
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1,
- "127.0.0.1:1970": 1
- },
- "type": "roundrobin",
- "retries": 2,
- "checks": {
- "active": {
- "timeout": 5,
- "http_path": "/status",
- "host": "foo.com",
- "healthy": {
- "interval": 2,
- "successes": 1
- },
- "unhealthy": {
- "interval": 1,
- "http_failures": 2
- },
- "req_headers": ["User-Agent: curl/7.29.0"]
- },
- "passive": {
- "healthy": {
- "http_statuses": [200, 201],
- "successes": 3
- },
- "unhealthy": {
- "http_statuses": [500],
- "http_failures": 3,
- "tcp_failures": 3
- }
- }
- }
- }
-}'
-```
-
-健康检查信息可以通过 [控制接口](./control-api.md) 中的 `GET /v1/healthcheck` 接口得到。
diff --git a/docs/zh/latest/tutorials/health-check.md
b/docs/zh/latest/tutorials/health-check.md
new file mode 100644
index 000000000..55ddcfe57
--- /dev/null
+++ b/docs/zh/latest/tutorials/health-check.md
@@ -0,0 +1,161 @@
+---
+title: 健康检查
+keywords:
+ - APISIX
+ - API 网关
+ - 健康检查
+description: 本文介绍了如何使用 API 网关 Apache APISIX 的健康检查功能来检查上游节点的健康状态。
+---
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+本文主要介绍了 Apache APISIX
的健康检查功能。健康检查功能可以在上游节点发生故障或者迁移时，将请求代理到健康的节点上，最大程度避免服务不可用的问题。APISIX 的健康检查功能使用
[lua-resty-healthcheck](https://github.com/api7/lua-resty-healthcheck)
实现，并分为主动检查和被动检查。
+
+## 主动健康检查
+
+主动健康检查主要是指 APISIX 通过预设的探针类型，主动探测上游节点的存活性。目前 APISIX 支持 `HTTP`、`HTTPS`、`TCP`
三种探针类型。
+
+当发向健康节点 A 的 N 个连续探针都失败时（取决于如何配置），则该节点将被标记为不健康，不健康的节点将会被 APISIX
的负载均衡器忽略，无法收到请求；若某个不健康的节点，连续 M 个探针都成功，则该节点将被重新标记为健康，进而可以被代理。
+
+## 被动健康检查
+
+被动健康检查是指，通过判断从 APISIX
转发到上游节点的请求响应状态，来判断对应的上游节点是否健康。相对于主动健康检查，被动健康检查的方式无需发起额外的探针，但是也无法提前感知节点状态，可能会有一定量的失败请求。
+
+若发向健康节点 A 的 N 个连续请求都被判定为失败（取决于如何配置），则该节点将被标记为不健康。
+
+:::note 注意
+
+由于不健康的节点无法收到请求，仅使用被动健康检查策略无法重新将节点标记为健康，因此通常需要结合主动健康检查策略。
+
+:::
+
+:::tip 提示
+
+- 只有在 `upstream` 被请求时才会开始健康检查，如果 `upstream` 被配置但没有被请求，不会触发启动健康检查。
+- 如果没有健康的节点，那么请求会继续发送给上游。
+- 如果 `upstream` 中只有一个节点时不会触发启动健康检查，该唯一节点无论是否健康，请求都将转发给上游。
+
+:::
+
+## 属性
+
+| 名称 | 配置类型 | 类型 |
有效值 | 默认值
| 描述
|
+| ----------------------------------------------- | ------------------ |
------- | -------------------- |
---------------------------------------------------------------------------------------------
| ------------------------------------------------------------------------- |
+| upstream.checks.active.type | 主动检查 | string
| `http` `https` `tcp` | http
| 主动检查的类型。
|
+| upstream.checks.active.timeout | 主动检查 | integer
| | 1
| 主动检查的超时时间（单位为秒）。
|
+| upstream.checks.active.concurrency | 主动检查 | integer
| | 10
| 主动检查时同时检查的目标数。
|
+| upstream.checks.active.http_path | 主动检查 | string
| | /
| 主动检查的 HTTP 请求路径。
|
+| upstream.checks.active.host | 主动检查 | string
| | ${upstream.node.host}
| 主动检查的 HTTP 请求主机名。
|
+| upstream.checks.active.port | 主动检查 | integer
| `1` 至 `65535` | ${upstream.node.port}
| 主动检查的 HTTP 请求主机端口。
|
+| upstream.checks.active.https_verify_certificate | 主动检查 | boolean
| | true
| 主动检查使用 HTTPS 类型检查时，是否检查远程主机的 SSL 证书。 |
+| upstream.checks.active.req_headers | 主动检查 | array
| | []
| 主动检查使用 HTTP 或 HTTPS 类型检查时，设置额外的请求头信息。
|
+| upstream.checks.active.healthy.interval | 主动检查（健康节点）| integer | `>=
1` | 1
| 主动检查（健康节点）检查的间隔时间（单位为秒）|
+| upstream.checks.active.healthy.http_statuses | 主动检查（健康节点）| array |
`200` 至 `599` | [200, 302]
| 主动检查（健康节点）HTTP 或 HTTPS 类型检查时，健康节点的 HTTP
状态码。 |
+| upstream.checks.active.healthy.successes | 主动检查（健康节点）| integer | `1`
至 `254` | 2
| 主动检查（健康节点）确定节点健康的次数。 |
+| upstream.checks.active.unhealthy.interval | 主动检查（非健康节点）| integer | `>=
1` | 1
| 主动检查（非健康节点）检查的间隔时间（单位为秒）|
+| upstream.checks.active.unhealthy.http_statuses | 主动检查（非健康节点）| array |
`200` 至 `599` | [429, 404, 500, 501, 502, 503, 504, 505]
| 主动检查（非健康节点）HTTP 或 HTTPS 类型检查时，非健康节点的
HTTP 状态码。 |
+| upstream.checks.active.unhealthy.http_failures | 主动检查（非健康节点）| integer | `1`
至 `254` | 5
| 主动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
+| upstream.checks.active.unhealthy.tcp_failures | 主动检查（非健康节点）| integer | `1`
至 `254` | 2
| 主动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
+| upstream.checks.active.unhealthy.timeouts | 主动检查（非健康节点）| integer | `1`
至 `254` | 3
| 主动检查（非健康节点）确定节点非健康的超时次数。 |
+| upstream.checks.passive.healthy.http_statuses | 被动检查（健康节点）| array |
`200` 至 `599` | [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300,
301, 302, 303, 304, 305, 306, 307, 308] | 被动检查（健康节点）HTTP 或 HTTPS 类型检查时，健康节点的
HTTP 状态码。 |
+| upstream.checks.passive.healthy.successes | 被动检查（健康节点）| integer | `0`
至 `254` | 5
| 被动检查（健康节点）确定节点健康的次数。 |
+| upstream.checks.passive.unhealthy.http_statuses | 被动检查（非健康节点）| array |
`200` 至 `599` | [429, 500, 503]
| 被动检查（非健康节点）HTTP 或 HTTPS 类型检查时，非健康节点的
HTTP 状态码。 |
+| upstream.checks.passive.unhealthy.tcp_failures | 被动检查（非健康节点）| integer | `0`
至 `254` | 2
| 被动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
+| upstream.checks.passive.unhealthy.timeouts | 被动检查（非健康节点）| integer | `0`
至 `254` | 7
| 被动检查（非健康节点）确定节点非健康的超时次数。 |
+| upstream.checks.passive.unhealthy.http_failures | 被动检查（非健康节点）| integer | `0`
至 `254` | 5
| 被动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
+
+## 配置示例
+
+你可以通过 Admin API 在路由中启用健康检查功能：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1970": 1
+ },
+ "type": "roundrobin",
+ "retries": 2,
+ "checks": {
+ "active": {
+ "timeout": 5,
+ "http_path": "/status",
+ "host": "foo.com",
+ "healthy": {
+ "interval": 2,
+ "successes": 1
+ },
+ "unhealthy": {
+ "interval": 1,
+ "http_failures": 2
+ },
+ "req_headers": ["User-Agent: curl/7.29.0"]
+ },
+ "passive": {
+ "healthy": {
+ "http_statuses": [200, 201],
+ "successes": 3
+ },
+ "unhealthy": {
+ "http_statuses": [500],
+ "http_failures": 3,
+ "tcp_failures": 3
+ }
+ }
+ }
+ }
+}'
+```
+
+启用成功后，如果 APISIX 探测到不健康的节点，将会在错误日志中输出如下日志：
+
+```shell
+enabled healthcheck passive while logging request
+failed to receive status line from 'nil (127.0.0.1:1980)': closed
+unhealthy TCP increment (1/2) for '(127.0.0.1:1980)'
+failed to receive status line from 'nil (127.0.0.1:1980)': closed
+unhealthy TCP increment (2/2) for '(127.0.0.1:1980'
+```
+
+:::tip 提示
+
+需要将错误日志的级别调整为 `info` 才可以观测到上述日志信息
+
+:::
+
+你可以通过[控制接口](../control-api.md) 中的 `GET /v1/healthcheck` 接口获取健康检查信息。如下所示：
+
+```shell
+
+curl http://127.0.0.1:9090/v1/healthcheck/upstreams/healthycheck -s | jq .
+
+```
