Parity Ethereum 客户端完整指南:从源码构建、运行配置到快速同步

原创2026-10-14 21:10:01441 阅读
文章标签:区块链

Parity Ethereum 客户端完整指南:从源码构建、运行配置到快速同步

Parity Ethereum 是由 Parity Technologies 用 Rust 编写的以太坊兼容区块链客户端,定位于为矿工、服务提供商与交易所提供快速、轻量且健壮的节点基础设施。本文以仓库 README.md 为骨架,结合 parity/cli/mod.rs 等源码,系统讲解环境准备、源码构建、启动方式、JSON-RPC/WebSockets 配置、Warp Sync 快速同步机制与测试文档工作流,帮助你独立部署一个可投入生产的 Parity 节点。

一、项目定位与技术概览

Parity Ethereum 的目标是成为最快、最轻量、最安全的以太坊客户端,其核心定位是面向任务关键型(mission-critical)场景:矿工、服务提供商和交易所需要快速同步与最大化在线时间,而 Parity Ethereum 提供了支撑高速可靠服务所需的核心基础设施。它的主要特点包括:

  • 整洁、模块化的代码库,便于按需定制;
  • 基于 CLI 的进阶客户端,参数体系完整;
  • 极小的内存与存储占用;
  • Warp Sync 快速同步,让链同步从"以天计"缩短为"以小时计";
  • 模块化设计,便于以轻量方式集成进自有服务或产品。

整个项目使用 Rust 语言开发(工作区根 Cargo.toml 中 workspace 成员涵盖客户端、EVM、密钥管理等 30 余个 crate),并以 GPLv3 协议开源。默认情况下,Parity Ethereum 会在 :8545 端口提供 JSON-RPC HTTP 服务、在 :8546 端口提供 WebSockets 服务,二者均可全面配置并支持多组 API。当前仓库版本号为 2.7.2(见 Cargo.toml),且根据 CHANGELOG.md 的说明,自 2.7.x 系列起项目已切换到单一 stable 发布轨道,此前使用 beta 轨道的客户端需要切换到 stable 轨道;同时 2.5.x/2.6.x 升级到 2.7.x 属于数据库格式变更,升级为单向过程。

二、构建环境与依赖准备

2.1 Rust 工具链

构建 Parity Ethereum 需要最新稳定版 Rust。官方推荐通过 rustup 安装:

$ curl https://sh.rustup.rs -sSf | sh

2.2 各平台系统依赖

  • Linux:需要安装 gcc、g++、pkg-config、file、make、cmake 等软件包。
  • OSX:需要 clang,它随 Xcode 命令行工具提供,也可以通过 homebrew 安装。
  • Windows:需要安装带 C++ 支持的 Visual Studio 2015,然后下载运行 rustup-init.exe(x86_64-pc-windows-msvc 版本),打开 "VS2015 x64 Native Tools Command Prompt",并执行:
$ rustup default stable-x86_64-pc-windows-msvc

2.3 附加构建工具

装好 rustup 后,还需安装并确保以下二进制在 PATH 中:

完成上述步骤后即可从源码构建。

三、从源码构建客户端

3.1 克隆与编译

# 下载 Parity Ethereum 代码
$ git clone https://gitcode.com/gh_mirrors/pa/parity-ethereum
$ cd parity-ethereum

# 以 release 模式构建
$ cargo build --release --features final

其中 final feature 会启用 parity-version/final(见 Cargo.toml),编译产物位于 ./target/release 子目录,可执行文件名为 parity(对应 <a href="https://link.gitcode.com/i/60279735be6757d723fb8a46ce42bb9e" target="_blank">[bin]] name = "parity",见 [Cargo.toml)。

3.2 分支选择与编译问题排查

  • 仓库默认分支编译的是最新 nightly 构建;如需构建 stable 或 beta,分别执行 git checkout stable 或 git checkout beta。
  • 如果 cargo 解析 manifest 失败,可尝试:
$ ~/.cargo/bin/cargo build --release
  • 如果编译某个 crate 时报错,多数情况是 Rust 版本过旧或部分 crate 需要重新编译。在最新稳定版 Rust 前提下,执行以下命令清理仓库通常能解决问题:
$ cargo clean

3.3 一行式安装脚本(macOS / Linux)

bash <(curl https://get.parity.io -L)

该脚本默认安装最新 beta 版本;如需安装 stable 版本:

bash <(curl https://get.parity.io -L) -r stable

四、启动 Parity Ethereum

4.1 手动启动

直接运行编译产物即可启动并开始同步以太坊区块链:

$ ./target/release/parity

从源码结构看,二进制入口位于 parity/main.rs 对应配置的 bin 目标,其内部通过 parity_ethereum::start 拉起客户端主循环,并支持更新器(updater)自我更新与重启逻辑(详见 parity/main.rs)。

4.2 使用 systemd 服务文件

若希望以普通用户身份、借助 systemd init 系统常驻运行,可按以下三步操作:

  1. 将 scripts/parity.service 复制到 systemd 用户目录(通常为 ~/.config/systemd/user);
  2. 把 release 二进制安装到 bin 目录:sudo install ./target/release/parity /usr/bin/parity;
  3. 编写 /etc/parity/config.toml 配置文件以配置客户端(详见下文第五节)。

仓库自带的 scripts/parity.service 服务单元完整内容如下,可作为参考模板:

[Unit]
Description=Parity Ethereum Daemon
After=network.target

[Service]
# run as root, set base_path in config.toml
ExecStart=/usr/bin/parity --config /etc/parity/config.toml
# To run as user, comment out above and uncomment below, fill in user and group
# picks up users default config.toml in $HOME/.local/share/io.parity.ethereum/
# User=username
# Group=groupname
# ExecStart=/usr/bin/parity
Restart=on-failure

# Specifies which signal to use when killing a service. Defaults to SIGTERM.
# SIGHUP gives parity time to exit cleanly before SIGKILL (default 90s)
KillSignal=SIGHUP

[Install]
WantedBy=default.target

要点:默认以 root 运行并显式指定 --config /etc/parity/config.toml;若以普通用户运行,则取消注释 User/Group 并去掉 --config 参数,此时客户端会自动读取该用户默认路径($HOME/.local/share/io.parity.ethereum/)下的 config.toml。Restart=on-failure 保证进程异常退出后自动拉起,KillSignal=SIGHUP 则给 Parity 留出优雅退出的时间(默认 SIGKILL 宽限期 90 秒)。

五、核心运行配置:CLI 参数与 config.toml

Parity Ethereum 的全部参数集中定义在 parity/cli/mod.rs 中,每个参数均以 "参数名 + 默认值 + 对应配置项 + 帮助文本" 的形式声明,并通过 TOML 配置、CLI 参数与预设(preset)三种方式加载。以下按主题整理常用配置。

5.1 链与运行模式

  • --chain=<a href="https://link.gitcode.com/i/6b55a7837174ab32d24f0a1249eb50b7" target="_blank">CHAIN]:指定区块链类型(默认 foundation)。CHAIN 可以是 JSON 链规格文件,或以下内置链之一:ethereum、classic、poacore、xdai、volta、ewc、musicoin、ellaism、mix、callisto、ethercore、morden、mordor、ropsten、kovan、rinkeby、goerli、kotti、poasokol、testnet、evantestcore、evancore、dev(对应源码见 [parity/cli/mod.rs)。仓库 ethcore/res/ethereum 目录下存放了 foundation、classic、goerli、kovan、morden、mordor、rinkeby、ropsten、xdai、poacore 等链的完整 JSON 链规格文件。
  • --mode=[MODE]:运行模式,默认为 last。可选值:last(沿用上次使用的模式,无则 active)、active(持续同步)、passive(先同步,之后周期性唤醒重新同步)、dark(仅当 JSON-RPC 活跃时同步)、offline(不同步)。配合 --mode-timeout=[SECS](默认 300 秒,dark/passive 模式下的空闲超时)与 --mode-alarm=[SECS](默认 3600 秒,passive 模式自动唤醒周期)使用。
  • --light:实验性的轻客户端模式,只同步最少数据并随时按需向网络获取数据,存储占用极低、带宽可能更高;配合 --no-hardcoded-sync 可关闭默认的硬编码跳转同步。

5.2 JSON-RPC HTTP 服务器(默认端口 8545)

源码定义见 parity/cli/mod.rs,常用参数:

参数 默认值 说明
--jsonrpc-port=[PORT] 8545 HTTP JSON-RPC 服务端口
--jsonrpc-interface=[IP] local 监听地址,可为 local、all 或具体 IP
--jsonrpc-apis=[APIS] web3,eth,pubsub,net,parity,private,parity_pubsub,traces,rpc,parity_transactions_pool 逗号分隔的可用 API 列表;可用名称:all, safe, debug, web3, net, eth, pubsub, personal, signer, parity, parity_pubsub, parity_accounts, parity_set, traces, rpc, secretstore;可用 - 前缀禁用某项,如 all,-personal;safe 等价于 web3,net,eth,pubsub,parity,parity_pubsub,traces,rpc
--jsonrpc-hosts=[HOSTS] none 允许的 Host 头取值,防止浏览器攻击向量;特殊值 all、none
--jsonrpc-cors=[URL] none 响应的 CORS 头,特殊值 all、none
--jsonrpc-server-threads=[NUM] 4 HTTP JSON-RPC 服务器处理线程数
--jsonrpc-max-payload=[MB] 无 单次 HTTP JSON-RPC 请求的最大体积(MB)
--poll-lifetime=[S] 60 RPC filter 生命周期(秒),超时未轮询则被移除
--no-jsonrpc 关闭 禁用 HTTP JSON-RPC 服务
--jsonrpc-allow-missing-blocks 关闭 远古区块同步未完成时,RPC 返回 null 而非报错
--jsonrpc-no-keep-alive 关闭 禁用 HTTP/1.1 keep-alive
--jsonrpc-experimental 关闭 开启实验性 RPC(访问所有命名空间中未最终定稿的 EIP 方法)

5.3 WebSockets 服务器(默认端口 8546)

源码定义见 parity/cli/mod.rs,常用参数:

参数 默认值 说明
--ws-port=[PORT] 8546 WebSockets JSON-RPC 服务端口
--ws-interface=[IP] local 监听地址
--ws-apis=[APIS] web3,eth,pubsub,net,parity,parity_pubsub,private,traces,rpc,parity_transactions_pool 可用 API 名称与 JSON-RPC 一致,同样支持 - 前缀禁用
--ws-origins=[URL] parity://*,chrome-extension://*,moz-extension://* 允许连接的 Origin 头取值,特殊值 all、none
--ws-hosts=[HOSTS] none 允许的 Host 头取值
--ws-max-connections=[CONN] 100 最大并发 WebSockets 连接数
--no-ws 关闭 禁用 WebSockets JSON-RPC 服务

5.4 网络与同步配置

  • --port=[PORT]:节点 P2P 监听端口,默认 30303。
  • --interface=[IP]:网络接口,all、local 或具体 IP,默认 all。
  • --min-peers=<a href="https://link.gitcode.com/i/2970a14d18024bb892ba2e87454ded9d" target="_blank">NUM] / --max-peers=[NUM]:维持的最少/最多对等节点数;源码中还包含 min_peers > max_peers 时的参数校验(见 [parity/cli/mod.rs)。
  • --bootnodes=[NODES]:覆盖链默认的 bootnodes,逗号分隔的 enode 列表。
  • --reserved-peers=[FILE]:提供每行一个 enode 的文件,这些节点始终保留专用槽位;--reserved-only 则只连接保留节点。
  • --no-discovery:禁用新节点发现;--nat=[METHOD]:公网地址探测方式,取值 any, none, upnp, extip:<IP>。
  • --no-warp:禁用从网络快照同步(Warp Sync 默认开启,见第六节);--warp-barrier=[NUM] 则强制在 Warp 到区块 NUM 之前不做常规同步。

5.5 便利与安全选项

  • -c, --config=[CONFIG]:指定配置文件,可为配置文件路径或预设:dev、insecure、dev-insecure、mining、non-standard-ports(默认路径 $BASE/config.toml)。
  • -d, --base-path=[PATH]:基础数据存储路径;--db-path=[PATH] 指定数据库目录。
  • --unsafe-expose:将所有服务器(ws/jsonrpc/ipfs-api/secretstore/stratum/dapps)的 interface 与 hosts 全部设为 all,使节点对外可达。该选项不安全,务必谨慎使用。
  • --ports-shift=[SHIFT]:为所有监听端口(含 P2P、HTTP JSON-RPC、WebSockets、IPFS、SecretStore)统一加上偏移量。

5.6 完整 config.toml 示例

仓库测试配置 parity/cli/tests/config.full.toml 展示了 TOML 配置的完整结构,关键片段如下:

[rpc]
disable = false
port = 8545
interface = "local"
cors = ["null"]
apis = ["web3", "eth", "net", "parity", "traces", "rpc", "secretstore"]
hosts = ["none"]
allow_missing_blocks = false

[websockets]
disable = false
port = 8546
interface = "local"
origins = ["none"]
apis = ["web3", "eth", "net", "parity", "traces", "rpc", "secretstore"]
hosts = ["none"]

[ipc]
chmod = "660"
disable = false
path = "$HOME/.parity/jsonrpc.ipc"
apis = ["web3", "eth", "net", "parity", "parity_accounts", "personal", "traces", "rpc", "secretstore"]

配置项与 CLI 参数一一对应([rpc] 对应 --jsonrpc-*,[websockets] 对应 --ws-*,[ipc] 对应 --ipc-*),路径中的 $BASE 会被替换为基础数据目录。实际部署时可按上述结构编写 /etc/parity/config.toml(systemd 方式)或用户目录下的 config.toml。

六、Warp Sync:数小时而非数天完成同步

Warp Sync 是 Parity Ethereum 的核心能力之一。它允许节点从网络中下载一个经过验证的状态快照(snapshot)而非逐块重放全部历史交易,从而将首次同步时间从数天级压缩到数小时级。README 明确将其列为 "Synchronise in hours, not days"。

从源码角度看,Warp Sync 的状态机定义在 ethcore/sync/src/api.rs 中:

  • WarpSync 枚举包含三种状态:Enabled(启用)、Disabled(禁用)、OnlyAndAfter(_)(仅允许 Warp 同步且在指定区块号之后),后者对应 --warp-barrier 的语义;
  • SyncConfig 中的 warp_sync 字段控制该能力(默认 WarpSync::Disabled,由上层配置决定是否开启);
  • 同步服务通过 snapshot_service: Arc<dyn SnapshotService> 接入快照服务,且在握手阶段若对端支持 warp 协议则优先进行 warp 握手(见 ethcore/sync/src/api.rs)。

操作上:Warp Sync 默认开启,无需任何参数;若需关闭请使用 --no-warp。历史上用于显式开启的 --warp 参数已被标记为 legacy("Does nothing; warp sync is enabled by default",见 parity/cli/mod.rs)。快照恢复后可配合 --no-ancient-blocks 决定是否继续下载恢复点之前的旧区块(默认会下载,不推荐关闭)。

七、运行测试

运行测试前需先下载所需测试文件:

git submodule update --init --recursive
  • 运行全部包测试:
cargo test --all
  • 运行指定包测试:
cargo test --package <spec>

将 <spec> 替换为下方包列表中的名称(例如 cargo test --package evmbin)。若希望在测试输出中显示日志,追加 -- --nocapture(例如 cargo test --package evmbin -- --nocapture)。

八、生成与阅读文档

8.1 rustdoc 文档生成

可以用 rustdoc(配合 Cargo)生成包文档并自动在浏览器打开:

  • 全部包:
cargo doc --document-private-items --open
  • 指定包:
cargo doc --package <spec> -- --document-private-items --open

其中 --document-private-items 用于同时查看私有文档,--no-deps 用于排除依赖项文档构建。

8.2 仓库包清单

README 中的包列表(<spec> 的可选值)完整如下:

Parity Ethereum (EthCore) Client Application

parity-ethereum

Account Management、Key Management Tool 与 Keys Generator

ethcore-accounts, ethkey-cli, ethstore, ethstore-cli

Parity Chain Specification

chainspec

Parity CLI Signer Tool 与 RPC Client

cli-signer parity-rpc-client

Parity Ethereum Ethash 与 ProgPoW 实现

ethash

Parity (EthCore) Library

ethcore
  • 区块链数据库、测试生成器、配置、缓存、区块导入与区块信息:ethcore-blockchain
  • 合约调用、区块链服务与注册信息:ethcore-call-contract
  • 数据库访问与工具、数据库缓存管理器:ethcore-db
  • EVM Rust 实现:evm
  • 轻客户端实现:ethcore-light
  • 基于智能合约的节点过滤与网络连接权限管理:node-filter
  • 私有交易:ethcore-private-tx
  • 客户端与网络服务创建、注册(I/O 子系统):ethcore-service
  • 区块链同步:ethcore-sync
  • 公共类型:common-types
  • VM 支持库:vm
  • WASM 解释器:wasm
  • WASM 测试运行器:pwasm-run-test
  • Parity EVM 实现:evmbin
  • IPFS 兼容 API:parity-ipfs-api
  • JSON 反序列化:ethjson
  • 共识引擎的状态机泛化:parity-machine

Parity Ethereum (EthCore) Miner Interface

ethcore-miner parity-local-store price-info ethcore-stratum using_queue

Parity Ethereum (EthCore) Logger Implementation

ethcore-logger

C bindings library for the Parity Ethereum client

parity-clib

Parity Ethereum JSON-RPC Servers

parity-rpc

Parity Ethereum (EthCore) Secret Store

ethcore-secretstore

Parity Updater Service

parity-updater parity-hash-fetch

Parity Core Libraries (Parity Util)

ethcore-bloom-journal blooms-db dir eip-712 fake-fetch fastmap fetch ethcore-io
journaldb keccak-hasher len-caching-lock macros memory-cache memzero
migration-rocksdb ethcore-network ethcore-network-devp2p panic_hook
patricia-trie-ethereum registrar rlp_compress rlp_derive parity-runtime stats
time-utils triehash-ethereum unexpected parity-version

8.3 贡献包文档

可通过在源码中添加文档注释来为各包补充文档,遵循标准 rustdoc 注释格式(/// 行,含 Summary、Description、# Panics、# Errors、# Safety、# Examples 等分节),示例如下:

/// Summary
///
/// Description
///
/// # Panics
///
/// # Errors
///
/// # Safety
///
/// # Examples
///
/// Summary of Example 1
///
/// ```rust
/// // insert example 1 code here for use with documentation as tests
/// ```

九、仓库配套工具链

除客户端本体外,仓库内还包含若干独立工具,均可从源码构建使用:

9.1 evmbin —— 独立 EVM 解释器

evmbin 是 Parity Ethereum 的独立 EVM 实现二进制。README 说明它不随正式发行版分发,需要自行构建运行(用法见 evmbin/src/main.rs):

cargo build -p evmbin --release
./target/release/parity-evm --help

其支持 state-test(运行状态测试 JSON 文件)、stats(执行 EVM 运行时码并返回统计)、stats-jsontests-vm(按 VMTests 格式运行标准 json-tests 并输出 TSV 时序统计)三个子命令,并提供 --code、--to、--from、--input、--gas、--gas-price、--chain、--json、--std-json 等交易与输出选项。

9.2 ethstore —— 密钥管理

ethstore 提供 Parity Ethereum 的密钥管理能力,支持 JSON 密钥文件(keystore)的创建、导入、导出与账户管理,对应 ethstore-cli 提供命令行界面。

9.3 ethkey —— 密钥生成器

ethkey 是 Parity Ethereum 的密钥生成工具,其 CLI 用法定义在 accounts/ethkey/cli/src/main.rs:

ethkey info <secret-or-phrase> [options]
ethkey generate random [options]
ethkey generate prefix <prefix> [options]
ethkey sign <secret> <message>
ethkey verify public <public> <signature> <message>
ethkey verify address <address> <signature> <message>
ethkey recover <address> <known-phrase>

支持 -s/--secret、-p/--public、-a/--address、-b/--brain 等输出选项,其中 brain 钱包算法(由短语推导密钥)在帮助文本中被标注为 "Not recommended"。

9.4 其他独立工具

仓库还包含 chainspec(链规格生成工具)、cli-signer(CLI 签名工具与 RPC 客户端)等 workspace 成员;此外 README 还提到 ethabi(函数调用编码)与 whisper(Whisper-v2 PoC)位于独立仓库维护。

十、社区、贡献与许可证

  • 安全相关报告:请遵循仓库 SECURITY.md 中的安全策略。
  • 版本变更:完整的版本间变更清单见 CHANGELOG.md。
  • 贡献指南:项目提供面向核心开发者的入门介绍与 CONTRIBUTING 指南,并要求贡献者遵守 CODE_OF_CONDUCT。
  • 许可证:项目以 GPLv3 授权,全文见 LICENSE。
登录后查看全文
parity-ethereum