企业官网建设流程全解析

• 后端
• API网关
• 微服务

registry.consul.checksRequired是 fabio 在 Consul 注册中心模式下，决定"一个服务实例需要多少健康检查通过才算可用"的关键开关。它只有one和all两个取值，却直接决定了故障实例是否会进入 fabio 的路由表。读完本文，你将掌握该配置的语义、默认行为、底层过滤逻辑（passingServices），以及它与registry.consul.service.status配合使用时的实战取舍。

配置作用：定义服务的"可用"标准

fabio 从 Consul 读取服务健康状态并生成路由表时，一个服务实例可能同时挂载多个健康检查（例如 HTTP 探活、TCP 端口探测、脚本检查等）。registry.consul.checksRequired用来规定：这个实例至少要有多少个健康检查通过，fabio 才会把它视为可用并纳入路由。

可选的取值只有两个（见 registry.consul.checksRequired 参考文档）：

默认值是：

registry.consul.checksRequired = one

从源码看，该字段定义在 config/config.go 的Consul配置结构中，类型为字符串；默认值在 config/default.go 中被初始化为"one"。配置文件模板 fabio.properties 中同样保留了完整的注释说明。

三种配置方式：配置文件、环境变量与命令行参数

与 fabio 的其他配置项一致（见 参考索引），registry.consul.checksRequired可以分别通过配置文件、环境变量和命令行参数指定，优先级依次为命令行 > 环境变量 > 配置文件：

# fabio.properties registry.consul.checksRequired = all

# 环境变量（下划线形式，支持 FABIO_ 前缀） FABIO_registry_consul_checksRequired=all ./fabio FABIO_REGISTRY_CONSUL_CHECKSREQUIRED=all ./fabio # 命令行参数 ./fabio -registry.consul.checksRequired all

命令行参数的注册位于 config/load.go，其帮助文本为 "number of checks which must pass: one or all"，与参考文档语义一致。

底层实现：passingServices 的两种判定模式

该配置的消费点在 registry/consul/service.go：NewServiceMonitor构造函数将其转换为一个布尔标志：

strict: config.ChecksRequired == "all",

也就是说，取值all对应"严格模式"（strict），取值one对应"宽松模式"。随后在Watch循环中，fabio 拉取 Consul 全部健康检查状态，调用passingServices(prefixedChecks, w.config.ServiceStatus, w.strict)筛选出可用实例（见 registry/consul/service.go）。

真正的判定逻辑在 registry/consul/passing.go：

1. 按Node与ServiceID分组，统计每个实例的健康检查总数total与通过数passing；
2. 若passing == 0，该实例直接排除；
3. 若strict为 true 且total != passing（存在任一未通过检查），该实例同样排除；
4. 其余情况（即宽松模式下至少一个通过、严格模式下全部通过）才进入候选集合。

同时，该函数会跳过三类 Consul 内部检查：serfHealth（Agent 本身宕机）、_node_maintenance（节点维护模式）、_service_maintenance:前缀（服务维护模式），并会输出 DEBUG 日志记录被跳过的实例。

与 registry.consul.service.status 的配合

checksRequired只决定"通过的数量"，而"什么样的状态算通过"由另一个配置项registry.consul.service.status决定（见 registry.consul.service.status 参考文档）。它接受passing、warning、critical、unknown的逗号分隔列表，默认只认passing。

两者组合后的实际行为：

• service.status = passing+checksRequired = one：只要有一个检查是passing，实例即进入路由表，容忍其他检查处于 warning/critical；
• service.status = passing,warning+checksRequired = all：所有检查都必须处于passing或warning之一才算可用，此时 warning 被当作"软通过"；
• service.status = passing+checksRequired = all：最严格，任何一个检查不通过实例即被摘除流量。

状态匹配由hasStatus实现（registry/consul/passing.go），即使用slices.Contains判断检查状态是否落在配置的合法状态集合内。

测试用例印证两种模式的行为差异

registry/consul/passing_test.go 用完全相同的输入验证了两种模式的差别：

• 非严格模式下：同一服务的检查一个passing、一个warning，两个检查都会被保留（"in non-strict mode, expect that checks which belong to same service are passing, if at least one of them is passing"）；
• 严格模式下：同样的输入返回空集，实例被整体排除（"in strict mode, expect that no checks which belong to same service are passing, if not all of them are passing"）；
• 严格模式配合status = passing,warning：两个检查（一个 passing、一个 warning）全部落入合法状态，实例重新变为可用。

此外测试还覆盖了实例之间互不影响（某实例的失败检查不会拖垮同服务在另一节点上的健康实例）、维护模式与 Agent 宕机时实例被整体跳过等边界场景，可作为理解该配置实际生效范围的依据。

实战建议

• 追求高可用、容忍单点探测抖动：保持默认one。fabio 自带 HTTP 健康检查、业务侧另有自定义检查的场景下，宽松模式可避免单个探针瞬时失败导致实例被频繁摘除和恢复。
• 追求流量质量、多重检查互为保障：设为all。当实例同时挂载多个独立探针（如进程存活 + 端口连通 + 自定义脚本），要求全部通过能更可靠地过滤"半死"实例。
• 变更配置后，可通过 fabio 管理 UI 的路由表（ui.addr配置）实时观察哪些实例被纳入路由，验证判定结果是否符合预期。
• 若希望 warning 状态也不进入路由，保持registry.consul.service.status = passing；若希望 warning 被视为可用，需同时放宽该配置，否则严格模式下所有检查都要严格passing。

参考文档

• registry.consul.checksRequired 参考文档
• registry.consul.service.status 参考文档
• 配置参考索引（配置文件/环境变量/命令行参数说明）
• 配置结构定义
• 默认配置
• 命令行参数注册
• ServiceMonitor 构造与调用链
• passingServices 过滤实现
• 行为差异测试
• fabio.properties 中的完整注释

• 后端
• API网关
• 微服务