部署 - Leafage 文档

一条链是一个独立的部署单元。本页给出三种形态：单机验证、单链生产、多链集群。

基础设施

生产部署需要三样共享基础设施：

组件	要求
Kafka	内部 topic 必须单分区（承载全序区块流）；外部 topic 可按需分区
S3	两个桶：内部桶（Header + StateDiff）、外部桶（BlockFile + Validation），可跨链共用
etcd v3	建议 3 节点；承载节点注册、Leader 选举、链高度和路由配置

多条链共用同一套基础设施：所有 Kafka topic、S3 键、etcd 键都以 chainID 开头。

形态一：单机验证

不需要 Kafka 和 S3。写节点开放 trace 命名空间，leafage-evm 用 HTTP 模式轮询。适合本地开发和适配新链时的验证。

geth --http --http.api=eth,debug,trace --http.addr=0.0.0.0 --http.port=8545

leafage-evm standalone \
  --db-path /tmp/leafage \
  --listen-addr 0.0.0.0:8659 \
  --chain-cfg 1 \
  --rpc-addr http://127.0.0.1:8545

形态二：单链生产

services:
  beacon:
    image: sigp/lighthouse:v8.0.1
    command:
      - lighthouse
      - beacon_node
      - --network=mainnet
      - --datadir=/var/data/lighthouse
      - --execution-endpoint=http://geth:8551
      - --execution-jwt=/var/data/geth/jwtsecret
      - --checkpoint-sync-url=https://mainnet.checkpoint.sigp.io

  geth:
    image: public.ecr.aws/b2h7a5c4/chaintable/ethereum-writer:v1.17.3-debank-3
    ports: ["8666:8545"]
    entrypoint:
      - /app/geth
      - --datadir=/var/data/geth
      - --syncmode=full
      - --gcmode=archive
      - --authrpc.addr=0.0.0.0
      - --authrpc.jwtsecret=/var/data/geth/jwtsecret
      - --http
      - --http.addr=0.0.0.0
      - --http.api=net,web3,eth,admin,debug,txpool,engine,trace
      - --vmtrace=pipeline
      - '--vmtrace.jsonconfig={"region":"ap-northeast-1","node_x_bucket":"nodex-internal","chain_table_bucket":"chaintable-pipeline","brokers":["kafka-1:9092"],"etcd_endpoints":["http://etcd:2379"]}'

  leafage-evm:
    image: public.ecr.aws/b2h7a5c4/chaintable/leafage-evm-x:v1.2.31
    ports: ["8659:8659"]
    environment: ["RUST_LOG=info"]
    command:
      - standalone
      - --db-path=/nodex-eth
      - --listen-addr=0.0.0.0:8659
      - --chain-cfg=1
      - --kafka-s3-config=/etc/leafage/kafka_s3.json
      - --prometheus-addr=0.0.0.0:9100

  consistency-checker:
    image: consistency-checker:latest
    command: ["-config", "/config/config.yml"]

nodex-proxy 通常独立部署，覆盖所有链：

./node-proxy -config config.yaml -listen 8663

资源规划（ETH 主网）

服务	CPU	内存
beacon（Lighthouse）	4 核	12 GB
geth（full sync + archive）	4 核	24 GB
leafage-evm	4 核	16 GB

leafage-evm 的 QPS 与 CPU 核数近似线性。要提高查询吞吐，只扩这一个服务的 CPU 和内存即可。

磁盘	容量
beacon + geth（archive）	~850 GB
leafage-evm（archive）	~450 GB
leafage-evm（state）	~150 GB

至少 3000 IOPS，推荐 SSD。AWS 上 gp3 的默认 3000 IOPS / 125 MB/s 足够稳态运行（12 秒一个区块），但首次启动的两个阶段压力更高：快照解压受顺序写吞吐限制，快照恢复后的追赶受随机读写 IOPS 限制。预留 20–30% 容量余量。

写节点开启 --ancient.prune 可以显著降低磁盘占用：历史区块体和收据在离开最近 90000 块窗口后被裁剪。下游消费者读 S3，不依赖写节点保留历史区块体。需要 --syncmode full。

形态三：多链集群

每条链：
  1 × 共识客户端（PoS 链）
  1–2 × 写节点（pipeline etcd 选举决定谁发 Kafka）
  1 × consistency-checker
  N × leafage-evm（State 为主，按需加 Archive）

全局共享：
  1 组 nodex-proxy（多实例，按 chainId 管理多条链）
  Kafka / S3 / etcd
  Prometheus + Grafana

写节点可以部署两个：都上传 S3，只有 Leader 发 Kafka。备节点在主节点故障时接管，避免数据链路中断。

常见运维操作

新增一个查询节点

从 S3 下载 RocksDB 快照并解压到 --db-path
启动 leafage-evm，它会自动从 Kafka offset 或 S3 追赶到链头
启动时自注册到 etcd，consistency-checker 确认追上后把 stateType 改为 1
nodex-proxy watch 到变更，健康检查通过后加入负载均衡池

整个过程通常在分钟级完成，不需要人工干预 proxy。

下线一个查询节点

停止进程即可。leafage-evm 退出时删除自己的 etcd 键；即使异常退出，consistency-checker 也会在轮询失败后把它标记为离线并删除。

切换写节点 Leader

通过 nodex-proxy 的管理接口：

curl -X POST http://proxy:8663/1/writers/switchLeader -d '{...}'
curl http://proxy:8663/1/writers/leader

也可以直接改 etcd 的 {chainID}/writers/leader。切换后新 Leader 会等待 grace_period 再开始发布。

版本切换

版本模式下，修改 etcd 的 {chainID}/version：

consistency-checker 检测到版本变化后释放或争抢 singleton topic 的发布锁，并把 topic 对齐到新版本的进度
nodex-proxy 把基础链 ID 的请求改写到 {chainId}-{version} 的节点池

客户端不需要改动。

回退并重新同步

leafage-evm 的状态出现异常时，可以把链头回退到更早的区块，再从 S3 重新同步：

leafage-evm rewind --db-path /nodex-eth --to-block 12345

排查

现象	检查顺序
查询节点不追块	Kafka 消费是否正常 → S3 拉取是否报错（`RUST_LOG=info` 看 `updater` target）→ offset 是否过期触发了全量追赶
外部消费者收不到通知	checker 的 `pipeline_replica_ready_timeouts_total` 是否增长 → 副本是否有节点长期落后拉低了 ready 比例 → 版本模式下是否持有 singleton 锁
proxy 报无可用节点	etcd 里节点键是否存在 → `stateType` 是否为 3 → 健康检查是否通过（用 `/{chainId}/getAllNodes` 查看）
历史查询失败	是否有 Archive 节点在池中 → 请求高度是否落在 `--historical-height` 以下但未配置 `--historical-rpc`
S3 上有重复高度对象	正常，reorg 会留下分叉块；确认 checker 把非规范的标记成了 `is_fork: true`（看 `pipeline_fork_scan_rewrites_total`）
写节点磁盘增长过快	是否开启 `--ancient.prune`；pipeline 的 `s3_temp_dir` 是否有残留未上传文件

参考

leafage-evm 部署指南 — 含一键脚本、快照下载、目录结构
nodex-proxy 部署指南 — Docker Compose、Kubernetes、systemd 与生产调优
consistency-checker 部署说明

开始使用

架构

组件

指南

参考

部署

基础设施

形态一：单机验证

形态二：单链生产

资源规划（ETH 主网）

形态三：多链集群

常见运维操作

排查

参考

​基础设施

​形态一：单机验证

​形态二：单链生产

​资源规划（ETH 主网）

​形态三：多链集群

​常见运维操作

​排查

​参考

基础设施

形态一：单机验证

形态二：单链生产

资源规划（ETH 主网）

形态三：多链集群

常见运维操作

排查

参考