> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leafage.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置参考

> 五个组件的启动参数与配置文件字段

各组件的配置项汇总。完整列表以 `--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：

```json theme={null}
{
  "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：

```json theme={null}
{
  "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`                                   | 写节点注册租约秒数                             |

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

## 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`    | 巡检回看高度数                                         |

<Note>
  `check_num` 已废弃，不再生效。副本轮询由 `check_timeout_ms` 限时。
</Note>

```yaml theme={null}
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`

```yaml theme={null}
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`

```yaml theme={null}
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`](https://github.com/Chaintable/nodex-proxy/blob/main/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`。