Envoy 集群 TCP 健康检查Health Checking完整指南配置、模糊匹配原理与实战【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读本文以 Envoy 官方文档中 集群健康检查cluster_hc.rst 为骨架聚焦其中最为常用的TCP 健康检查L3/L4 health checking机制包括send/receive的字节载荷配置、独特的模糊匹配fuzzy matching语义、以及仅连接connect only探测模式。文章结合仓库内的 HealthCheck 协议定义、健康检查架构概述 与 健康检查器实现源码从配置到源码逐一拆解读完你将能够独立为任意 TCP 协议如 MySQL、PostgreSQL、自定义 RPC 等的 upstream 集群配置可靠的主动健康检查。一、健康检查在 Envoy 集群中的位置在 Envoy 中主动健康检查active health checking是面向每个 upstream 集群cluster独立配置的它决定了一个主机host何时从负载均衡池中被摘除或被恢复。正如 服务发现架构文档 所述主动健康检查与 EDS 服务发现类型配合最为紧密但它同样适用于STATIC、STRICT_DNS等其他服务发现场景。Envoy 的 HealthCheck 消息 在oneof health_checker中定义了多种健康检查器见health_check.proto第 317-331 行检查器类型配置字段行为概述HTTPhttp_health_check发送 HTTP 请求默认期待 200 响应支持自定义预期/可重试状态码TCPL3/L4tcp_health_check发送字节载荷期待响应中按序出现指定字节块也支持仅连接探测gRPCgrpc_health_check发送 gRPC 健康检查请求默认期待 200Redisredis_health_check发送 PING 期待 PONG或对指定 key 执行EXISTS自定义custom_health_check通过扩展机制接入自定义健康检查器这些检查器在源码层面注册于envoy.health_checkers扩展分类下见 架构文档 与 扩展配置其中 TCP 检查器的实例化入口位于 health_checker_impl.cc 的HealthCheckerImplBase创建逻辑中根据HealthCheckerCase::kTcpHealthCheck分支构建。注意无论选择哪种检查器健康检查流量都复用集群配置的传输套接字transport socket。若集群启用了 TLS健康检查也会在 TLS 上进行可通过HealthCheck.TlsOptions单独指定健康检查连接使用的 ALPN 协议见 health_check.proto。二、TCP 健康检查的核心配置TCP 健康检查的完整配置结构定义在 TcpHealthCheck 消息 中包含三个字段字段类型说明sendPayload单数健康检查周期内发送给目标服务器的字节载荷。留空即表示仅连接模式receiverepeated Payload响应中需要匹配到的字节块列表按顺序进行模糊匹配proxy_protocol_configProxyProtocolConfig若设置则健康检查请求先携带 ProxyProtocol 头send内容随后发送未设置send时只发送 ProxyProtocol 头其中Payload支持两种编码见 health_check.prototext十六进制Hex编码的字符串例如0101表示字节0x01 0x01binary原始二进制字节。官方文档给出的最小示例cluster_hc.rsttcp_health_check: send: {text: 0101} receive: [{text: 02}, {text: 03}]该配置的行为是每个健康检查周期内向目标服务器一次性发送全部send字节即0x01 0x01然后在响应中按顺序查找0x02与0x03两个字节块。2.1 完整的集群级配置示例将 TCP 健康检查挂载到集群上需要结合HealthCheck的公共字段。一个完整可运行的示例clusters: - name: tcp_backend connect_timeout: 0.25s type: STRICT_DNS lb_policy: ROUND_ROBIN load_assignment: cluster_name: tcp_backend endpoints: - lb_endpoints: - endpoint: address: socket_address: address: backend.example.com port_value: 3306 health_checks: - timeout: 1s # 等待健康检查响应的超时时间超过即判定失败 interval: 5s # 两次健康检查之间的间隔 unhealthy_threshold: 3 # 连续失败 3 次后标记为不健康 healthy_threshold: 2 # 连续成功 2 次后标记为健康 tcp_health_check: send: {text: 0101} receive: [{text: 02}, {text: 03}]这些公共字段均定义于 HealthCheck 消息timeout等待响应的时间必填且必须大于 0interval健康检查周期必填且必须大于 0unhealthy_threshold标记主机不健康所需的连续失败次数healthy_threshold标记主机健康所需的连续成功次数启动期间仅需一次成功即可标记健康见 proto 第 306-309 行注释reuse_connection是否在健康检查之间复用连接默认trueproto 第 314-315 行此外还有initial_jitter、interval_jitter、unhealthy_interval、healthy_edge_interval、no_traffic_interval等高级调度参数用于控制检查节奏proto 第 282-378 行。2.2 仅连接Connect Only健康检查当receive为空数组、同时未设置send时Envoy 执行仅连接式 TCP 健康检查每个周期内尝试连接 upstream 主机连接成功即视为健康。每个健康检查周期都会建立一条新连接除非启用reuse_connection。这一模式非常适合那些只需确认端口可达的场景如基础设施探活、对探测内容无要求的 TCP 服务tcp_health_check: {}在 proto 定义中send字段的注释明确写着Empty payloads imply a connect-only health checkhealth_check.proto。同时该模式也是 MongoDB 等基于自定义握手协议的健康检查退路当协议握手过于复杂时可直接降级为端口探活。三、模糊匹配Fuzzy Matching机制详解TCP 健康检查的响应匹配是本文档的核心语义值得深入理解检查响应时执行模糊匹配每个字节块必须被找到且必须按指定顺序出现但不必是连续的not necessarily contiguous。也就是说对于示例receive: [{text: 02}, {text: 03}]即使服务器在0x02与0x03之间插入了0x04例如协议中夹带时间戳等非确定性数据健康检查依然通过。这是为了支持那些会在响应中插入非确定数据如时间、随机数、会话信息的协议。3.1 源码层面的匹配实现该匹配逻辑在源码中由PayloadMatcher类实现定义于 health_checker_impl.hloadProtoBytes将Payload列表中每个textHex 字符串或binary字段解码为独立的二进制块MatchSegments std::liststd::vectoruint8_tmatch对期望块列表与接收缓冲区执行顺序匹配。源码注释health_checker_impl.h进一步印证During each health check cycle, all of the send bytes are sent to the target server. Each binary block can be of arbitrary length and is just concatenated together when sent. On the receive side, fuzzy matching is performed such that each binary block must be found, and in the order specified, but not necessary contiguous.即发送侧所有块只是简单拼接后一次发出接收侧每个块可任意长度、按序查找、允许中间插入其他字节。这决定了 TCP 健康检查非常适合客户端发送挑战、服务器回显式应答这类协议。3.2 复杂模式的限制文档明确声明send/receive/send/receive 这种多轮交互的复杂匹配模式目前不受支持。PayloadMatcher仅支持一次发送、一次匹配因此对于需要两次握手往返的协议如 TLS 握手、部分数据库认证流程TCP 健康检查无法覆盖完整握手应改用 HTTP/gRPC 检查器或自定义健康检查扩展。3.3 与 HTTP 检查器模糊匹配的一致性值得注意模糊匹配语义并非 TCP 检查器独有。HTTP 健康检查器的receive字段同样采用按顺序、不要求连续的匹配规则见 health_check.proto且建议根据载荷总大小设置response_buffer_size默认 1024 字节来平衡匹配效率。这种设计使两类检查器在字节级校验响应内容的能力上保持一致。四、ProxyProtocol 支持TcpHealthCheck还支持在健康检查连接上附加 ProxyProtocol 头health_check.proto设置proxy_protocol_config后Envoy 会先发送 ProxyProtocol 头若同时设置了sendsend载荷在 ProxyProtocol 头之后发送若未设置send则只发送 ProxyProtocol 头同时支持 V1携带 L3/L4 地址与 V2LOCAL命令不携带 L3/L4 信息两种版本。该能力用于让处于 ProxyProtocol 后的上游如四层负载均衡器后面的服务能够正确识别健康检查连接的真实来源。相关配置结构定义于 proxy_protocol.proto。五、健康检查触发后的集群行为5.1 主机状态与统计指标一旦健康检查判定主机不健康该主机将从负载均衡池中被移除恢复健康后重新加入。为便于观测集群启用健康检查后会额外输出一系列统计指标详见 cluster_stats.rst。其中与健康检查直接相关的常用指标包括位于cluster.name.health_check.*统计树指标类型含义health_check.attemptCounter健康检查尝试次数health_check.successCounter健康检查成功次数health_check.failureCounter健康检查失败次数health_check.healthyGauge当前健康主机数health_check.degradedGauge当前降级主机数membership_healthyGauge健康成员占比配合cluster_manager.cluster_added、cluster.updated等集群管理指标见 cluster_stats.rst可以完整监控集群健康状况。5.2 每成员级别的健康检查配置除集群级配置外Envoy 还支持为每个集群成员endpoint单独指定健康检查的地址和端口。例如在load_assignment中让健康检查走独立的管理端口load_assignment: endpoints: - lb_endpoints: - endpoint: health_check_config: port_value: 8080 address: socket_address: address: 127.0.0.1 port_value: 80 address: socket_address: address: localhost port_value: 80该示例来自 架构文档数据流量走localhost:80而健康检查流量则发往127.0.0.1:8080。这在业务端口与健康检查端口分离的生产架构中非常实用。5.3 健康检查事件日志Envoy 还支持将每次剔除/加入事件以 JSON 形式写入日志HealthCheckEvent消息便于审计与排障旧方式HealthCheck.event_log_path直接指定日志文件路径该字段已弃用将于 3.0 版本移除见 health_check.proto新方式通过HealthCheck.event_logger配置envoy.health_check.event_sinks扩展例如filesink 的event_log_path字段设置always_log_health_check_failures: true可记录所有失败事件而非仅记录首次失败。详见 架构文档中的健康检查事件日志小节。六、与其他健康检查机制的配合6.1 与被动健康检查异常点检测互补主动健康检查本文所述与被动健康检查outlier detection即异常点检测通常是搭配使用的前者按固定间隔主动探测后者根据实时请求的成功/失败率被动判定。当两者结合时常会调大主动检查的interval以减少探测流量同时依赖被动检测快速摘除故障主机。详见 异常点检测架构文档。6.2 快速失败机制若上游主机在响应中设置x-envoy-immediate-health-check-fail头HTTP 检查器场景或通过管理接口/healthcheck/fail将 Envoy 自身标记为失败则健康检查器会立即将该主机标记为失败并从负载均衡中排除无需等待unhealthy_threshold累积。该机制的前提是集群已配置主动健康检查详见 架构文档中的快速失败小节。6.3 HTTP 健康检查过滤器当 Envoy 网格中集群间大量互做健康检查时会产生可观的控制面流量。envoy.filters.http.health_check过滤器可在 HTTP 监听器上直接应答健康检查请求200/503支持 no pass through、按上游集群健康度计算、pass through、pass through with caching 四种模式其中带缓存的 pass through是大规模网格的推荐模式。详见 架构文档 与 健康检查过滤器配置。七、实战排查建议先确认协议适配性TCP 健康检查适合请求-应答一次往返即定生死的协议。若上游协议需要多轮握手才能确认存活应评估仅连接模式、HTTP 检查器或自定义检查器text是 Hex 编码配置send: {text: 0101}时务必确认字节内容正确误将 ASCII 字符串当 Hex 写入是常见错误模糊匹配不要求连续利用这一特性容忍响应中的时间戳等动态字节但也要注意它可能掩盖部分响应顺序错乱问题——匹配只验证按序出现不验证无多余内容合理设置阈值unhealthy_threshold过小会导致网络抖动误摘主机过大则故障摘除变慢配合timeout interval避免探测相互叠加善用统计与日志通过cluster.name.health_check.*统计和健康检查事件日志event sink快速定位主机为何被剔除。参考资料集群健康检查官方文档cluster_hc.rst健康检查架构总览health_checking.rst协议定义health_check.proto匹配与检查器实现health_checker_impl.h、health_checker_impl.cc集群统计指标cluster_stats.rst【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考