consistency-checker

consistency-checker 不在 leafage-evm 的数据路径上——它消费与 leafage-evm 相同的 Kafka 通知，观察副本状态，然后做三件事：向外部消费者发布已确认的区块通知、在 S3 上标记分叉块、把节点健康状态写进 etcd。

项	值
仓库	Chaintable/consistency-checker
语言	Go 1.23+
许可证	Apache-2.0
依赖	Kafka（内外各一）、etcd v3、S3、Pebble DB

它解决什么问题

写节点发布通知的那一刻，副本还没有应用这个区块。外部消费者如果直接订阅内部 topic，就会在 leafage-evm 还查不到该区块时收到通知。 checker 在中间加了一道确认：等到足够比例的副本确实追上了这个高度，才向外部 topic 发布。外部消费者因此得到一个保证——收到通知时，去查询集群一定能读到这个区块。顺带解决的两件事：分叉块在 S3 上没有标记（谁是规范链只有观察者知道），以及 nodex-proxy 需要知道每个节点当前是否健康。

处理流程

Inner Kafka（BlockChangeNotification）
  → 消息校验 & 去重
  → 并行预取 S3（BlockValidation + 同高度键列表）
  → 轮询副本直到 ready_ratio 达标
  → 写入 Pebble DB（双索引）
  → 标记 S3 中同高度的 fork 区块
  → 发布到 Outer Kafka（先 drop，再 new）
  → 对齐 singleton topic（仅 Leader，版本模式）
  → 发布后用新鲜 LIST 复核 fork 标记

核心实现在 check/check.go 的 Process。几个设计要点：

预取与等待并行

S3 预取和副本轮询同时进行。轮询通常要几十到几百毫秒，正好覆盖 S3 往返；失败路径不等预取结束，goroutine 自行收尾。

幂等与重试

整条 Process 失败时不提交 Kafka offset，下一轮重试同一条消息。重复消息、以及“已处理到发布步骤但整条未提交”的情况会短路到对齐后直接推进，避免死锁重试。已成功投递的目的地记入 delivered，重试时跳过，因此既不重复投递也不漏投递。

副本轮询的超时语义

以 check_interval_ms（默认 20ms）为间隔轮询所有副本的 eth_blockNumber，直到 ready_ratio（默认 0.8）的副本达到目标高度。总时长上限是 check_timeout_ms（默认 2000ms），单次 RPC 上限是 rpc_node_timeout_ms（默认 5000ms）。超时判失败，Process 整体重试。配置项 check_num 已废弃，不再生效。

发布后复核

预取的同高度键列表是 Process 开头的快照，等待副本期间新上传的对象不在其中。发布通知后会用一次新鲜的 LIST 再检查一遍。这一步不在关键路径上，失败只记日志，由周期巡检兜底。

分叉标记

S3 外部桶的 BlockValidation 对象带一个 is_fork 字段，写节点上传时恒为 false——因为写节点在上传的那一刻还不知道这个块最终是否在规范链上。checker 负责回写。三条触发路径：

路径	触发时机
`dropBlocks` 重写	收到 `changeType: 2` 的重组通知
同高度扫描	每个新块处理时，列出该高度的所有对象，非规范的标记为 fork
周期巡检	每 `fork_scan_interval_sec`（默认 60 秒）回看 `fork_scan_lookback`（默认 64）个高度

pipeline_fork_scan_rewrites_total 不为零说明标记曾被覆盖或此前失败，值得关注。

leafage-evm 在 S3 追赶时依赖这个标记来把高度解析成规范哈希。checker 长时间停摆会让新节点的追赶变慢。

节点状态维护

每轮轮询后，把结果写回 etcd（一个事务提交）：

键	内容
`{chainID}[/{version}]/nodes/{ip}_{port}`	节点的 `stateType`：1 已追上、2 落后、3 离线
`{chainID}[/{version}]/lastBlockNumber`	当前确认高度

节点离线且没有租约时直接删除该键。高度只在变化时写入，避免无谓的 etcd 写放大。这两个键是 nodex-proxy 路由的全部依据：节点池成员来自前者，State / Archive 的选择阈值来自后者。

双模式

由 version 和 outer_version_new_block_topic 两个配置共同决定。

版本模式
传统模式

同时写 version topic 和 singleton topic。

etcd 键使用 {chainID}/{version}/ 前缀
S3 路径包含 version 段
singleton topic 的写入权需要通过 etcd 分布式锁（{chainID}/outer_block_notice）选举
Leader 定期比对 {chainID}/version，版本不匹配时释放锁

切换版本时，新 Leader 需要把 singleton topic 对齐到自己的进度：向前快进，或回退到共同祖先后重放。这段逻辑在 AlignOuterSingleton 和 align。

只写 singleton topic，etcd 键使用 {chainID}/ 前缀，不需要 Leader 选举。

本地存储

Pebble DB 保存已确认的区块，双索引：

h{hash}   → BlockInfo（RLP 编码）
n{number} → hash

用于对外提供区块查询，也用于分叉巡检时判断某个高度的规范哈希。

JSON-RPC 接口

监听地址由 listen 配置（默认 :8663），同一端口提供 GET /metrics。

方法	说明
`getLatestBlock`	最新已确认区块
`getBlockByHeight`	按高度查询
`getBlockById`	按哈希查询
`blockIsValid`	判断区块是否在规范链上

curl -X POST http://localhost:8663 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"getBlockByHeight","params":["0x100"],"id":1}'

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": { "id": "0x...", "num": 12345, "validation_hash": 67890, "is_fork": false }
}

错误统一返回 -39005。

指标

指标	说明
`pipeline_node_info`	节点角色信息（标签 `chain_id`、`role`）
`pipeline_block_num` / `pipeline_block_time`	最新已发布的区块高度与时间戳
`pipeline_replica_ready_wait_seconds`	等待副本就绪的时长分布
`pipeline_replica_ready_timeouts_total`	副本未在超时内就绪的次数
`pipeline_process_publish_seconds`	从开始处理到外部通知写完的耗时
`pipeline_block_ingress_to_outer_kafka_seconds`	写节点收到区块到外部 Kafka 写入成功的端到端延迟
`pipeline_fork_scan_rewrites_total` / `pipeline_fork_scan_errors_total`	分叉巡检
`pipeline_drop_block_rewrite_failures_total`	drop block 标记最终失败次数

运行

go build -o checker cmd/checker/*.go
./checker -config config.yml -listen :8663

配置项见配置参考。

开发

make build
make test
make race
make ci

check/critical_path_test.go 覆盖了关键路径的幂等与重试语义，改动 Process 流程时应先读它。

开始使用

架构

组件

指南

参考

它解决什么问题

处理流程

分叉标记

节点状态维护

双模式

本地存储

JSON-RPC 接口

指标

运行

开发

​它解决什么问题

​处理流程

​分叉标记

​节点状态维护

​双模式

​本地存储

​JSON-RPC 接口

​指标

​运行

​开发

它解决什么问题

处理流程

分叉标记

节点状态维护

双模式

本地存储

JSON-RPC 接口

指标

运行

开发