技术概述
本指南面向以太坊主网（Ethereum Mainnet）执行层的归档（archive）节点搭建。归档节点保留全历史状态，支持在任意历史区块高度查询账户余额、存储、合约代码等数据，并可执行交易/区块级的历史追踪分析。自以太坊完成合并（The Merge）后，运行执行客户端必须同时连接一个共识客户端（Beacon 节点）通过 Engine API 驱动区块头推进；因此本指南将覆盖“执行客户端 + 共识客户端”的完整组合部署。
适配的执行客户端与共识客户端（推荐优先使用容器化部署）：
- 执行层（Execution Client）：Erigon（推荐用于归档场景，资源占用更优），或 Geth（Go-Ethereum，传统但对归档资源要求极高）
- 共识层（Consensus Client）：Lighthouse、Teku、Prysm、Nimbus（本文演示 Lighthouse）
节点角色说明：
- 非验证者（非质押）：仅同步网络并提供数据与 RPC 服务，不参与区块提议与证明。
- 归档节点：保留历史状态；比“完整节点（full）”占用更多存储与 I/O，能进行历史区块状态查询与深度调试。
前置要求
硬件建议（主网归档，2025 年时序）：
- CPU：8 核以上（建议 16 线程），x86_64；支持 AES-NI
- 内存：32–64 GB（Erigon 32 GB 通常可用，Geth 归档建议≥64 GB）
- 存储：企业级 NVMe SSD，持续写入性能与耐久度高
- Erigon 归档：约 6–10+ TB（随时间增长）
- Geth 归档：常见需求 12–15+ TB 或更高（持续增长）
- 网络：稳定对等带宽（上/下行对等）≥100 Mbps，建议 1 Gbps；低丢包率
- 电源与散热：建议 UPS；长时间高 I/O 负载，需良好散热
操作系统与软件：
- Linux（建议 Ubuntu 22.04/24.04 LTS），已启用自动更新与 NTP（chrony 或 systemd-timesyncd）
- Docker 与 Docker Compose（容器化部署方式）
- 防火墙与安全：开放必要端口，禁止对外暴露敏感接口
网络与端口（默认值，可能因客户端不同略有差异）：
- 执行客户端 P2P：TCP/UDP 30303（入站/出站）
- 共识客户端 P2P：TCP/UDP 9000（入站/出站）
- 执行层 JSON-RPC：TCP 8545（仅本地或受控访问）
- 执行层 WebSocket：TCP 8546（仅本地或受控访问）
- Engine API（Auth RPC）：TCP 8551（仅共识客户端访问，切勿暴露公网）
安全与合规：
- 禁止将 8551 Auth RPC 暴露到公网
- 为 8545/8546 启用访问控制与网络隔离（防火墙、反代、IP 白名单）
- 定期备份数据与配置，尽量使用企业级 SSD，避免突发断电导致数据损坏
安装步骤
以下提供两套部署方案：
方案 A（推荐）：Docker Compose 部署 Erigon + Lighthouse（归档节点首选）
方案 B（可选）：原生安装 Geth + Lighthouse（归档模式，资源要求更高）
方案 A：Erigon + Lighthouse（Docker Compose）
- 安装 Docker 与 Compose（Ubuntu 示例）
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $USER
# 退出并重新登录，使 docker 组生效
- 准备目录与 JWT 秘钥
sudo mkdir -p /opt/eth-node/{data/erigon,data/lighthouse,secrets}
sudo chown -R $USER:$USER /opt/eth-node
openssl rand -hex 32 > /opt/eth-node/secrets/jwt.hex
chmod 600 /opt/eth-node/secrets/jwt.hex
- 创建 docker-compose.yml
请在 /opt/eth-node/docker-compose.yml 写入如下（根据实际版本选择稳定镜像标签；建议使用官方仓库并固定版本号）：
version: "3.8"
services:
erigon:
image: ghcr.io/ledgerwatch/erigon:latest
command:
- "--chain=mainnet"
- "--datadir=/data"
- "--port=30303"
- "--http"
- "--http.addr=0.0.0.0"
- "--http.port=8545"
- "--http.api=eth,net,web3,debug,erigon,trace"
- "--ws"
- "--ws.addr=0.0.0.0"
- "--ws.port=8546"
- "--authrpc.addr=0.0.0.0"
- "--authrpc.port=8551"
- "--authrpc.jwtsecret=/secrets/jwt.hex"
# 归档：Erigon 天生保留历史；不要启用任何裁剪（prune）参数
# 如在 NAT 场景可设置公网 IP（替换为你的公网地址）
# - "--nat=extip:<YOUR_PUBLIC_IP>"
volumes:
- ./data/erigon:/data
- ./secrets:/secrets:ro
ports:
- "30303:30303/tcp"
- "30303:30303/udp"
- "8545:8545/tcp"
- "8546:8546/tcp"
restart: unless-stopped
ulimits:
nofile:
soft: 100000
hard: 200000
lighthouse:
image: sigp/lighthouse:latest
command:
- "lighthouse"
- "bn"
- "--network"
- "mainnet"
- "--datadir"
- "/data"
- "--port"
- "9000"
- "--execution-endpoint"
- "http://erigon:8551"
- "--execution-jwt"
- "/secrets/jwt.hex"
# 可选：使用官方“弱主观”检查点同步以加速初始同步（请参阅对应客户端官方文档）
# - "--checkpoint-sync-url"
# - "<OFFICIAL_CHECKPOINT_URL>"
volumes:
- ./data/lighthouse:/data
- ./secrets:/secrets:ro
ports:
- "9000:9000/tcp"
- "9000:9000/udp"
# 可选暴露 REST 接口（本地或受控访问）
# - "5052:5052/tcp"
restart: unless-stopped
ulimits:
nofile:
soft: 100000
hard: 200000
- 启动
cd /opt/eth-node
docker compose pull
docker compose up -d
docker compose logs -f --tail=100
说明：
- Erigon 默认即为历史保留架构，无需另设 archive 标志；切勿启用裁剪（prune）相关参数。
- Lighthouse 通过 Engine API（8551）驱动 Erigon 同步主链头。
- 如需对外提供 JSON-RPC，请在防火墙层面限制 8545/8546 的来源 IP；生产环境建议经反向代理加访问控制。
方案 B：Geth + Lighthouse（原生安装，归档模式）
警告：Geth 归档对磁盘与 I/O 极为苛刻，长期运行需要更大容量与更高耐久度 NVMe。仅在确需 Geth 归档特性时使用。
- 安装 Geth（Ubuntu 示例）
sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:ethereum/ethereum
sudo apt update
sudo apt install -y geth
- 创建数据目录与 JWT
sudo mkdir -p /var/lib/geth /var/lib/eth-secrets
sudo chown -R geth:geth /var/lib/geth || sudo chown -R $USER:$USER /var/lib/geth
openssl rand -hex 32 | sudo tee /var/lib/eth-secrets/jwt.hex >/dev/null
sudo chmod 600 /var/lib/eth-secrets/jwt.hex
- Geth 归档模式 systemd 单元（/etc/systemd/system/geth.service）
[Unit]
Description=Go Ethereum (geth) - Archive
After=network-online.target
[Service]
User=geth
Group=geth
Type=simple
ExecStart=/usr/bin/geth \
--datadir /var/lib/geth \
--port 30303 \
--http --http.addr 0.0.0.0 \
--http.api eth,net,web3,debug,txpool \
--http.vhosts localhost \
--ws --ws.addr 0.0.0.0 \
--authrpc.addr 127.0.0.1 \
--authrpc.port 8551 \
--authrpc.jwtsecret /var/lib/eth-secrets/jwt.hex \
--gcmode archive \
--cache 4096
Restart=always
RestartSec=10
LimitNOFILE=200000
[Install]
WantedBy=multi-user.target
说明：--gcmode archive 禁用状态裁剪，产生完整历史状态。请谨慎暴露 http/ws，建议仅本地访问或经反向代理加上严格控制。
- 安装 Lighthouse（参阅官方发布渠道，或使用容器）
原生二进制或容器均可。以容器为例（避免系统依赖复杂性）：
docker run -d --name lighthouse-bn \
-v /var/lib/lighthouse:/data \
-v /var/lib/eth-secrets:/secrets:ro \
-p 9000:9000/tcp -p 9000:9000/udp \
sigp/lighthouse:latest \
lighthouse bn \
--network mainnet \
--datadir /data \
--execution-endpoint http://host.docker.internal:8551 \
--execution-jwt /secrets/jwt.hex
或将 Geth 与 Lighthouse均使用容器，以简化依赖与隔离。
配置说明
关键参数与作用（以方案 A 为例，Geth 类似）：
- --chain=mainnet：指定主网
- --datadir：数据目录；确保挂载到高性能 NVMe
- --http/--ws：启用 JSON-RPC 与 WebSocket，默认监听地址与端口可配置
- --http.api：RPC 命名空间；仅按需开放（eth, net, web3, debug, trace 等）
- --authrpc.addr/port/jwtsecret：Engine API（执行/共识通信）。仅本地或容器网络访问，不暴露公网
- 归档特性：
- Erigon：默认保留历史，不设置任何 prune 参数即可达到归档效果
- Geth：--gcmode archive 明确禁用状态裁剪；注意磁盘占用大幅提升
- P2P 端口与 NAT：--port（执行 P2P），共识 P2P 端口由共识客户端管理；如处于 NAT/云环境，可设置 --nat=extip:<公网IP> 或使用系统层端口转发
系统与文件句柄：
- ulimit nofile ≥ 100k，避免大量并发文件句柄导致错误
- 文件系统建议启用 noatime、nodiratime 挂载选项（降低额外写入开销）
运行验证
初始状态检查：
docker compose logs -f --tail=200 erigon
docker compose logs -f --tail=200 lighthouse
curl -s localhost:5052/health
同步进度：
curl -s -X POST localhost:8545 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
curl -s -X POST localhost:8545 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'
eth_syncing 返回 false 表示执行层已同步完成（仍需确保共识层同步到最新）。
归档能力验证（历史区块状态查询示例）：
- 查询某历史区块的账户余额（以区块 4,000,000 为例；十六进制为 0x3D0900）：
curl -s -X POST localhost:8545 \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"eth_getBalance",
"params":["0x0000000000000000000000000000000000000000", "0x3D0900"],
"id":1
}'
若节点非归档或数据不完整，可能返回错误（如缺失 trie 节点）；归档节点应返回余额结果。
- 历史追踪（Erigon trace 接口或 Geth debug_traceTransaction）：
- 选择一笔较早的交易哈希，调用 trace/ debug 命名空间验证能否正常返回历史执行细节。
Peer 连接数量：
curl -s -X POST localhost:8545 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'
数据健康与资源：
sudo du -sh /opt/eth-node/data/erigon
- 监控 I/O、负载与内存（如 iostat、vmstat、htop、dstat）
故障排查
常见问题与解决：
- 共识/执行连接失败（Engine API 未授权或握手失败）
- 现象：日志中出现“unauthorized engine API”、“JWT mismatch”
- 排查：确保共识与执行使用同一 jwt.hex，路径与权限正确；8551 互通但不暴露公网；网络名称与主网设置一致
- 同步停滞或回滚
- 现象：区块停在某高度不动或反复回退
- 排查：
- 检查共识客户端是否在同步（Peers 数量、finalized/justified 指标）
- 确认磁盘 I/O 是否饱和（iostat），内存是否不足（OOM）
- 检查系统时间同步（NTP）是否正常
- Peer 连接过少
- 检查 30303（执行）与 9000（共识）端口是否对外开放，防火墙或云安全组规则是否正确
- NAT 环境下配置 --nat=extip 或启用端口转发；确保公网 IP 稳定
- JSON-RPC 超时或返回错误
- 高并发查询导致 I/O 压力：限制请求速率、启用反向代理与缓存、分离读流量到单独实例
- 非归档查询：确认归档模式已启用（Geth 必须 --gcmode archive；Erigon 不要设置 prune）
- 磁盘空间耗尽或性能下降
- 使用企业级 NVMe；监控写入放大与 TBW（耐久度）
- 扩容前规划 LVM 或新盘迁移（停机后 rsync 数据目录；保证一致性）
- 文件系统建议使用 ext4/xfs，启用 noatime；避免断电造成 DB 损坏（建议 UPS）
- 数据损坏或异常退出
- 断电或硬件故障后启动报错：先备份数据目录，再按客户端官方文档执行安全的修复/重建流程；必要时重新同步
- 容器迁移：确保权限与路径一致，避免只读挂载导致写失败
优化建议
性能与稳定性：
- 存储：
- NVMe SSD，预留足够空间（至少 20–30% 空闲），避免长时间满盘运行
- 文件系统挂载选项：noatime,nodiratime，有助降低额外写入
- 系统内核与网络：
- 提高文件句柄限制（ulimit -n ≥ 100000）
- sysctl 优化（谨慎按需）：net.core.rmem_max、wmem_max；net.ipv4.tcp_congestion_control 使用现代算法（如 bbr，视环境而定）
- 客户端参数：
- Geth：--cache 4096（或更高，取决于内存，归档场景可适度提升），仅启用必要 RPC 命名空间
- Erigon：默认历史保留即可；避免使用 prune 选项；按需开启 trace API
- 监控与告警：
- 采集 CPU、内存、磁盘 I/O、空间与网络指标；为容器与主机设定告警阈值
- 审计日志访问，记录 RPC 调用与来源（反向代理层面）
安全加固：
- 仅在内网或受控网络开放 8545/8546；公共服务建议通过反向代理（Nginx/Caddy）加上
- IP 白名单
- 速率限制与超时
- TLS 加密（如需跨公网访问）
- 禁止对外开放 8551（Engine API）
- 定期更新镜像与二进制到稳定版本（在测试环境验证后再升级生产）
维护策略：
- 定期校验数据目录健康与容量趋势
- 通过客户端支持的“检查点同步”（官方提供）加速初始同步（共识层），缩短上线时间
- 为关键目录与配置做定期备份（尤其是 JWT 与服务配置文件）
—
备注与选择建议：
- 若主要用途为历史查询与分析，优先选用 Erigon 作为归档节点，资源效率更高。
- 若生态或工具链依赖 Geth 特定行为，可使用 Geth 归档，但需准备显著更高的存储与 I/O 预算。
- 生产环境务必从官方渠道获取固定版本并阅读对应发行说明；升级前在测试环境验证兼容性与性能。
