Parity Ethereum 客户端完整指南:从源码构建、运行配置到快速同步
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 系统常驻运行,可按以下三步操作:
- 将 scripts/parity.service 复制到 systemd 用户目录(通常为
~/.config/systemd/user); - 把 release 二进制安装到 bin 目录:
sudo install ./target/release/parity /usr/bin/parity; - 编写
/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。