Apache APISIX 上游健康检查完全指南:主动检查、被动检查与状态观测 API网关后端云原生微服务【免费下载链接】apisixThe Cloud-Native API Gateway and AI Gateway项目地址https://gitcode.com/gh_mirrors/api/apisix点击查看免费下载Apache APISIX 内置的健康检查功能用于实时监控上游upstream节点的可用性当节点发生故障或迁移时自动将请求代理到健康节点最大程度避免服务不可用。本文以官方教程 docs/zh/latest/tutorials/health-check.md 为骨架结合仓库源码apisix/healthcheck_manager.lua、apisix/schema_def.lua、apisix/control/v1.lua深入讲解两种健康检查模式、全部配置属性、状态机与计数器机制以及通过控制接口观测节点状态的具体方法帮助你掌握一套可落地的上游高可用治理方案。两种健康检查模式APISIX 的健康检查基于 lua-resty-healthcheck 库实现分为主动检查与被动检查两种模式二者可以在upstream.checks中组合使用。主动健康检查主动健康检查由 APISIX 根据预设的探针类型主动向上游节点发起探测请求以确认节点存活性。目前支持HTTP、HTTPS、TCP三种探针类型对应upstream.checks.active.type的取值见 schema_def.lua。其状态切换逻辑为当发向健康节点 A 的N 个连续探针均失败时N 由unhealthy配置决定节点被标记为不健康随后会被负载均衡器忽略不再接收请求若某个不健康节点连续M 个探针均成功M 由healthy配置决定节点被重新标记为健康恢复代理。主动检查能提前发现节点故障是保证高可用的主要手段代价是会产生额外的探测流量。被动健康检查被动健康检查不主动发起探测而是通过分析APISIX 转发到上游节点的真实请求响应状态来判断节点是否健康。它的优点是零额外探针开销但缺点是无法提前感知节点状态——节点真正出问题的那几笔请求已经失败因此会存在一定量的失败请求。同样的逻辑若发向健康节点 A 的 N 个连续请求均被判定失败该节点会被标记为不健康。:::note 注意由于不健康的节点无法再收到请求仅配置被动健康检查时节点一旦变不健康将永远无法被重新标记为健康。因此实践中必须将被动检查与主动检查组合使用由主动检查负责“恢复”节点。::::::tip 提示只有在upstream被请求时才会启动健康检查若upstream已配置但从未被请求健康检查不会触发启动。对应源码中健康检查器checker由apisix/healthcheck_manager.lua的create_checker按需创建而非随配置加载即创建。如果没有健康的节点请求会继续发送给上游即 APISIX 不会因此直接拒绝请求。:::健康检查属性详解健康检查配置位于upstream.checks之下分为active与passive两个子对象。以下属性表格完整对应 apisix/schema_def.lua 中的校验定义其中标注的默认值、有效范围均与源码中的 schema 声明一致。主动检查属性upstream.checks.active名称类型有效值默认值描述typestringhttphttpstcphttp主动检查的探针类型timeoutnumber—1主动检查的超时时间秒concurrencyinteger—10同时检查的目标节点数http_pathstring—/主动检查的 HTTP 请求路径hoststring—${upstream.node.host}主动检查的 HTTP 请求主机名Host 头portinteger1至65535${upstream.node.port}主动检查的 HTTP 请求端口https_verify_certificateboolean—trueHTTPS 类型检查时是否校验远程主机的 SSL 证书req_headersarray—[]HTTP/HTTPS 类型检查时附加的请求头如[User-Agent: curl/7.29.0]http_methodstringGETPOSTPUT等GET主动检查使用的 HTTP 方法schema 中额外支持的字段http_req_bodystring—主动检查请求体schema 中额外支持的字段说明http_method、http_req_body在 schema_def.lua 中定义方法枚举与路由方法一致属于教程属性表之外、源码确认的可用字段。健康节点判定active.healthy名称类型有效值默认值描述intervalinteger 11对健康节点的检查间隔秒http_statusesarray200至599[200, 302]HTTP/HTTPS 检查时视为健康的响应状态码successesinteger1至2542连续成功多少次后判定节点健康非健康节点判定active.unhealthy名称类型有效值默认值描述intervalinteger 11对非健康节点的检查间隔秒http_statusesarray200至599[429, 404, 500, 501, 502, 503, 504, 505]HTTP/HTTPS 检查时视为失败的状态码http_failuresinteger1至2545HTTP/HTTPS 类型连续失败多少次判定节点非健康tcp_failuresinteger1至2542TCP 类型连续失败多少次判定节点非健康timeoutsinteger1至2543连续超时多少次判定节点非健康被动检查属性upstream.checks.passive名称类型有效值默认值描述typestringhttphttpstcphttp被动检查的类型healthy.http_statusesarray200至599[200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]视为健康的响应状态码healthy.successesinteger0至2545连续成功多少次判定节点健康unhealthy.http_statusesarray200至599[429, 500, 503]视为失败的响应状态码unhealthy.tcp_failuresinteger0至2542TCP 连续失败多少次判定节点非健康unhealthy.timeoutsinteger0至2547连续超时多少次判定节点非健康unhealthy.http_failuresinteger0至2545HTTP 连续失败多少次判定节点非健康在 schema_def.lua 中checks对象使用anyOf约束至少必须配置active也可以同时配置active与passive即不允许仅配置 passive 而不配置 active——这与上文“仅被动检查无法恢复节点”的结论在 schema 层互相印证。通过 Admin API 启用健康检查可以通过 Admin API 在路由Route中为 upstream 配置健康检查。先获取admin_keyadmin_key$(yq .deployment.admin.admin_key[0].key conf/config.yaml | sed s///g)然后创建路由并启用健康检查curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $admin_key -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 } } } } }该示例同时配置了主动与被动检查主动检查以 5 秒超时、路径/status、Host 为foo.com探测两个节点健康阈值 1 次成功、非健康阈值 2 次 HTTP 失败被动检查则依据真实请求响应判定。观测探针结果日志启用成功后若 APISIX 探测到不健康节点会在错误日志中输出类似如下内容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才能观测到上述日志对应 conf/config.yaml 中的 error_log 级别配置。:::通过控制接口获取健康检查信息APISIX 的控制接口Control API默认监听127.0.0.1:9090提供了健康检查信息的查询入口该接口实现在 apisix/control/v1.lua 中。查询全部健康检查信息curl -i http://127.0.0.1:9090/v1/healthcheck响应示例[ { nodes: {}, name: /apisix/routes/1, type: http }, { nodes: [ { port: 1970, hostname: 127.0.0.1, status: healthy, ip: 127.0.0.1, counter: { tcp_failure: 0, http_failure: 0, success: 0, timeout_failure: 0 } }, { port: 1980, hostname: 127.0.0.1, status: healthy, ip: 127.0.0.1, counter: { tcp_failure: 0, http_failure: 0, success: 0, timeout_failure: 0 } } ], name: /apisix/routes/example-hc-route, type: http } ]其中status与counter是判断节点健康状况最核心的字段。按资源类型定向查询源码 control/v1.lua 显示/v1/healthcheck/{src_type}/{src_id}支持按资源定位查询src_type支持routes、services、upstreams、stream_routes还可以追加checkers子资源返回该资源拥有的全部检查器upstream 检查器 各插件实例检查器。例如curl http://127.0.0.1:9090/v1/healthcheck/upstreams/healthycheck -s | jq .节点状态机与 counter 计数器APISIX 中节点共有四种状态healthy、unhealthy、mostly_healthy、mostly_unhealthy。mostly_healthy当前判定为健康但健康检查期间并非所有探测都成功mostly_unhealthy当前判定为不健康但健康检查期间并非所有探测都失败。节点的状态转换取决于本次健康检查的成功或失败以及counter中记录的tcp_failure、http_failure、success、timeout_failure四个计数转换关系见上图状态转换图。counter 信息说明若健康检查失败counter中的success计数会被置零若健康检查成功则tcp_failure、http_failure、timeout_failure会被置零。名称描述作用success健康检查成功的次数当success大于healthy.successes配置值时节点变为healthy状态tcp_failureTCP 类型健康检查失败次数当tcp_failure大于unhealthy.tcp_failures配置值时节点变为unhealthy状态http_failureHTTP 类型健康检查失败次数当http_failure大于unhealthy.http_failures配置值时节点变为unhealthy状态timeout_failure节点健康检查超时次数当timeout_failure大于unhealthy.timeouts配置值时节点变为unhealthy状态请注意所有节点在没有初始探测的情况下以healthy状态启动且计数器仅在状态更改时重置和更新。因此当节点处于healthy状态且后续检查全部成功时success计数器不会更新保持为零——这正是上述响应示例中两个健康节点的success均为0的原因。源码视角健康检查的底层机制检查器checker的创建与复用apisix/healthcheck_manager.lua 是整个健康检查能力的核心管理模块create_checkerL86-L152负责基于up_conf.checks创建resty.healthcheck检查器并将 upstream 的每个节点通过add_target注册为探测目标。值得注意的是它会先检查 conf/config.yaml 中的全局开关disable_upstream_healthcheck——该开关默认false置为true时会全局禁用所有上游健康检查见 config.yaml.example检查器目标与节点一一对应每个目标以ip:port:hostname:hostheader为唯一键active.host或pass_host的变化会被识别为不同目标从而正确更新共享内存shm中的探测记录sync_checker_targetsL161-L223在节点列表变化而checks配置不变时对已有检查器做增量增删目标保留已累计的健康状态避免重建检查器导致状态丢失。检查器如何影响请求分发在 apisix/upstream.lua 中每次请求处理时都会通过healthcheck_manager.fetch_checker获取当前 upstream 对应的检查器并存入api_ctx.up_checker后续负载均衡在挑选节点时会查询检查器过滤掉不健康节点fetch_node_status返回 false 即视为不可用见 healthcheck_manager.lua。从源码结构看健康检查与负载均衡是同一请求路径上的协作关系健康检查维护节点可用性视图负载均衡基于该视图挑选节点。配置校验层面apisix/schema_def.lua 完整定义了active与passive两套 schema即前文属性表的校验来源并通过anyOf { {required {active}}, {required {active, passive}} }强制要求active必须存在从配置入口就杜绝了“只配置被动检查”的不可恢复陷阱。总结主动检查是节点健康治理的“探针”支持http/https/tcp三种类型能提前感知并剔除故障节点被动检查复用真实请求结果零额外开销但存在滞后二者需组合使用。所有阈值successes、http_failures、tcp_failures、timeouts与判定状态码http_statuses都可在upstream.checks中精细调优schema 层schema_def.lua强制active必配。通过 Admin API 配置、通过控制接口/v1/healthcheck观测节点status与counter配合info级别日志即可完整掌握节点健康全貌healthcheck_manager.lua 与 upstream.lua 则是理解其底层实现的最佳入口。赞分享API网关后端云原生微服务【免费下载链接】apisixThe Cloud-Native API Gateway and AI Gateway项目地址https://gitcode.com/gh_mirrors/api/apisix点击查看免费下载相关推荐Apache APISIX 健康检查Health Check完整实战指南主动检查、被动检查与节点状态监控Apache APISIX 健康检查Health Check完整实战指南主动检查、被动检查与节点状态监控 导读 本文围绕 Apache APISIXClAPI网关后端云原生微服务Apache APISIX 健康检查Health Check完全指南主动探测、被动感知与节点状态机Apache APISIX 健康检查Health Check完全指南主动探测、被动感知与节点状态机 导读 本指南以 Apache APISIX 官方教程文后端微服务云原生Apache APISIX 上游节点健康检查Health Check完整实战指南主动/被动探测、状态机与 Control API 监控Apache APISIX 上游节点健康检查Health Check完整实战指南主动/被动探测、状态机与 Control API 监控 本篇指南系统讲解后端微服务云原生上一篇Nextcloud AIO 部署上手30 分钟搭好完整自托管网盘下一篇如何3步快速解密QQ音乐加密文件qmcdump完整实战指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考