配置参考

各组件的配置项汇总。完整列表以 --help 或仓库内的示例配置为准。

leafage-evm

standalone 子命令的常用参数：

基础

参数	默认	说明
`--db-path`	必填	状态数据库目录
`--db-type`	`rocksdb`	`rocksdb` 或 `mdbx`
`--db-cache`	`2048`	数据库缓存（MB）
`--listen-addr`	`0.0.0.0:8545`	JSON-RPC 监听地址
`--chain-cfg`	`1`	链 ID
`--evm-type`	`mainnet`	执行器类型
`--archive`	`false`	启用归档模式
`--node-type`	`auto`	注册到 etcd 时声明的节点类型

状态更新

参数	默认	说明
`--kafka-s3-config`	-	Kafka + S3 配置的文件路径或内联 JSON
`--rpc-addr`	-	写节点 RPC 地址，未配置 Kafka 时启用 HTTP 轮询
`--update-interval`	`100`	HTTP 模式轮询间隔（毫秒）
`--diff-depth-limit`	`64`	内存中保留的区块差异层数，同时是可处理的 reorg 深度
`--catchup-safe-depth`	`0`	S3 追赶时沿 parent-hash 回补的链头深度，应大于该链最大 reorg 深度
`--init-task-queue-size`	`256`	S3 追赶的批大小
`--genesis-number`	`0`	创世块高度

性能与并发

参数	默认	说明
`--max-connections`	`5000`	最大并发 RPC 连接
`--listen-backlog`	`4096`	TCP accept 队列，需不大于 `net.core.somaxconn`
`--rpc-timeout`	`10000`	请求超时（毫秒）
`--evm-exec-concurrency`	`0`（不限）	并发执行的 EVM 请求上限，建议为核数的 2–4 倍
`--state-read-concurrency`	`0`（不限）	并发状态读取上限，需压测确定
`--account-cache-size`	`200000`	账户缓存条目
`--storage-cache-size`	`2000000`	存储缓存条目
`--code-cache-size`	`200000`	代码缓存条目
`--warmup-blocks`	`0`	启动时预热的区块数

归档模式

参数	默认	说明
`--iterator-timeout-secs`	`0`（禁用）	迭代器超时，避免长持有阻塞 compaction
`--archive-code-cache-mb`	`256`	代码缓存大小（MB），也可用环境变量 `ARCHIVE_CODE_CACHE_MB`
`--archive-zstd-compression`	`false`	启用 zstd 压缩
`--inverted-block-encoding`	`false`	使用倒序高度编码，必须与写入时一致
`--disable-auto-compactions`	`false`	关闭自动 compaction（批量导入时使用）

历史转发与可观测性

参数	默认	说明
`--historical-rpc`	-	无 block diff 区间的外部 RPC
`--historical-height`	-	转发阈值高度
`--prometheus-addr`	空（关闭）	指标监听地址
`--readiness-addr`	空（关闭）	就绪探针地址
`--pprof-addr`	空（关闭）	pprof 地址
`--stop-wait-timeout`	`5`	优雅退出等待秒数

Kafka + S3 配置

传给 --kafka-s3-config，可以是绝对路径或内联 JSON：

{
  "topic": "nodex_pipeline_1",
  "brokers": "kafka1:9092,kafka2:9092",
  "partition": 0,
  "bucket_name": "nodex-internal",
  "outer_bucket_name": "chaintable-pipeline",
  "offset_dir": "/nodex-eth/offset",
  "s3_chain_id": "1",
  "version": ""
}

字段	说明
`topic` / `brokers` / `partition`	内部 Kafka topic 与分区
`bucket_name`	内部桶：Header 与 StateDiff
`outer_bucket_name`	外部桶：BlockFile，用于按高度索引和预热
`offset_dir`	offset 持久化目录，留空则用默认路径
`s3_chain_id`	S3 键中的链 ID 段
`version`	版本命名空间，留空表示不启用

etcd 注册

--etcd-config 接受 JSON：

{
  "endpoints": ["http://etcd:2379"],
  "keep_alive_interval_ms": 5000,
  "lease_ttl_s": 15,
  "meta": "10.0.90.11:8659"
}

meta 是注册到 etcd 的 ip:port，也可以用 --meta 单独指定。

pipeline

通过执行客户端的 tracer 配置传入（geth 的 --vmtrace.jsonconfig）：

字段	默认	说明
`region`	-	AWS 区域
`node_x_bucket`	-	内部桶名
`chain_table_bucket`	-	外部桶名
`brokers`	-	Kafka broker 列表
`topic`	`nodex_pipeline_{chainID}[_{version}]`	内部 topic
`version`	空	版本命名空间
`s3_temp_dir`	空	本地上传缓存目录
`enable_prestate_tracer`	`false`	改用 prestate tracer 采集状态差异
`is_backup`	`nil`	`nil` = etcd 选举；`true`/`false` = 手动模式
`etcd_endpoints`	-	etcd 端点，与 `is_backup` 互斥
`election_key`	`{chainID}[/{version}]/writers/leader`	选举键
`node_id`	主机名	节点标识
`grace_period`	`10`	成为 Leader 前等待秒数
`writer_registry_ttl`	`10`	写节点注册租约秒数

is_backup 与 etcd_endpoints 必须二选一。同时配置或都不配置会在启动时直接退出。

consistency-checker

YAML 配置，-config 指定路径，-listen 可覆盖监听地址。

字段	默认	说明
`listen`	`:8663`	HTTP 监听地址
`chain_id`	必填	链 ID
`version`	-	版本标识，与 `outer_version_new_block_topic` 一起启用版本模式
`ready_ratio`	`0.8`	副本就绪比例阈值
`check_interval_ms`	`20`	副本轮询间隔
`check_timeout_ms`	`2000`	等待副本追上的总时长上限
`rpc_node_timeout_ms`	`5000`	单节点 RPC 超时
`msg_wait_timeout`	`5000`	Kafka 拉取超时
`consistency_db_path`	-	Pebble DB 目录
`outer_s3_bucket` / `outer_s3_region`	-	外部桶
`inner_brokers` / `inner_new_block_topic` / `inner_new_block_group_id`	-	内部 Kafka
`outer_brokers` / `outer_new_block_topic`	-	外部 Kafka singleton topic
`outer_version_new_block_topic`	-	外部 version topic（启用版本模式）
`etcd_endpoints`	-	etcd 端点
`etcd_lock_ttl`	`20`	分布式锁 TTL（秒）
`etcd_write_timeout_ms`	`5000`	etcd 写超时
`version_check_interval`	`5`	Leader 版本检查间隔（秒）
`commit_interval`	-	Kafka commit 间隔（秒）
`fork_scan_interval_sec`	`60`	分叉巡检间隔，`<=0` 禁用
`fork_scan_lookback`	`64`	巡检回看高度数

check_num 已废弃，不再生效。副本轮询由 check_timeout_ms 限时。

listen: "0.0.0.0:8663"
chain_id: 1
ready_ratio: 0.8
consistency_db_path: "/eth/consistency_db"
outer_s3_bucket: "chaintable-pipeline"
outer_s3_region: "ap-northeast-1"
inner_brokers: ["kafka-1:9092"]
inner_new_block_topic: "nodex_pipeline_1"
inner_new_block_group_id: "consistency-group-1"
outer_brokers: ["kafka-1:9092"]
outer_new_block_topic: "pipeline_1"
etcd_endpoints: ["http://etcd:2379"]

nodex-proxy

YAML 配置，-config 指定路径，-listen 覆盖 RPC 端口。

顶层

字段	说明
`listen`	RPC 与管理端口
`metric_listen`	Prometheus 端口
`etcd_endpoints`	etcd 端点
`log_level`	日志级别
`usage`	用量上报，空列表表示关闭

`proxy_config`

字段	默认	说明
`service_name`	-	服务名
`native_node_url`	-	Native 节点地址
`default_rpc_timeout`	`5000`	上游超时（毫秒）
`connection_pool_size`	`2000`	连接池大小
`node_select_strategy`	`random`	`random` 或 `round_robin`
`etcd_prefix`	空	etcd 键前缀
`node_health_check_timeout`	`5`	单次健康检查超时（秒）
`node_health_check_max_wait`	`300`	健康检查最长等待（秒）

`proxy_config.processor`

processor:
  observability_log:
    enable: true
    enable_error_log: true
    slow_threshold:
      default: 500
      rpc_methods:
        eth_call: 1000
        eth_getLogs: 2000
  rate_limiter:
    rpc_methods:
      eth_call: 100
      eth_getLogs: 50
  block_range_query_limit:
    enable: false
    recent_blocks: 0
    rewrite_to_latest: false
  request_mirror:
    enable: false
  method_name_checker:
    enable: false
    regexp: "^[a-zA-Z_][a-zA-Z0-9_]*$"
  method_denied:
    - eth_newPendingTransactionFilter
    - txpool_content

`proxy_config.observability`

observability:
  trace:
    enable: false
    otlp_endpoint: ""
    sampling_ratio: 0.1
  log:
    sampling:
      enable: true
      initial: 100
      thereafter: 100
  static_resource:
    service.name: "nodex-proxy"
    service.version: "1.0.0"

完整示例见仓库的 config/config.example.yaml。

写节点

以 go-ethereum 分叉为例，Leafage 附加的 flag：

Flag	说明
`--vmtrace pipeline`	启用 pipeline live tracer
`--vmtrace.jsonconfig`	tracer 配置 JSON，字段见上文 pipeline 一节
`--ancient.prune`	持续裁剪历史区块体与收据，需要 `--syncmode full`

其余 flag 与上游 geth 一致。要启用 trace_debankBlock，需在 --http.api 中包含 trace。

开始使用

架构

组件

指南

参考

leafage-evm

基础

状态更新

性能与并发

归档模式

历史转发与可观测性

Kafka + S3 配置

etcd 注册

pipeline

consistency-checker

nodex-proxy

顶层

`proxy_config`

`proxy_config.processor`

`proxy_config.observability`

写节点

​leafage-evm

​基础

​状态更新

​性能与并发

​归档模式

​历史转发与可观测性

​Kafka + S3 配置

​etcd 注册

​pipeline

​consistency-checker

​nodex-proxy

​顶层

​proxy_config

​proxy_config.processor

​proxy_config.observability

​写节点

leafage-evm

基础

状态更新

性能与并发

归档模式

历史转发与可观测性

Kafka + S3 配置

etcd 注册

pipeline

consistency-checker

nodex-proxy

顶层

`proxy_config`

`proxy_config.processor`

`proxy_config.observability`

写节点