Parity Ethereum 官方 Docker 镜像构建指南:多平台 Dockerfile、CentOS 自动化构建与端口设计详解
Parity Ethereum 官方 Docker 镜像构建指南:多平台 Dockerfile、CentOS 自动化构建与端口设计详解
Parity Ethereum 是面向以太坊类网络的快速、轻量、稳健的客户端,其官方仓库在 scripts/docker/ 目录下维护了完整的 Docker 化构建方案,覆盖 Ubuntu(含 aarch64 / ARM 交叉编译)、Alpine、CentOS 及 Docker Hub 发布流水线。本文以 scripts/docker/README.md 为主线,结合各平台 Dockerfile、构建脚本与 parity/cli/mod.rs 中定义的默认端口,系统讲解如何构建、定制与发布 Parity Ethereum 的 Docker 镜像,帮助读者在本地复现官方构建流程,并理解镜像内部端口暴露与运行时参数设计的来龙去脉。
一、仓库中的 Docker 构建体系一览
在动手构建之前,先了解 scripts/docker/ 目录下各子目录的分工,这将决定你选择哪条构建路径:
| 子目录 | 作用 | 关键文件 |
|---|---|---|
centos/ |
基于 CentOS 的两阶段构建(builder 编译 + runner 运行),产物为非 root 轻量镜像 | build.sh、Dockerfile |
alpine/ |
基于 Alpine 的 musl 静态链接构建,镜像最小化 | Dockerfile |
hub/ |
面向 Docker Hub 官方发布的镜像与配套脚本 | Dockerfile、publish-docker.sh、check_sync.sh |
ubuntu-aarch64/ |
在 Ubuntu 上交叉编译 aarch64(ARMv8)产物 | Dockerfile |
ubuntu-arm/ |
在 Ubuntu 上交叉编译 armv7(ARMHF)产物 | Dockerfile |
从源码结构看,官方针对不同场景准备了独立的构建入口:日常快速试用可以直接用 docker build;需要自动化、可定制时使用 CentOS 的 build.sh;发布到 Docker Hub 则走 hub/ 目录的脚本。下文将逐一展开。
二、最简用法:直接构建镜像
scripts/docker/README.md 开篇给出了通用构建命令,适用于任何带 Dockerfile 的目录。例如构建 Ubuntu 版本的镜像:
docker build -f docker/ubuntu/Dockerfile --tag ethcore/parity:branch_or_tag_name .
要点说明:
-f指定要使用的 Dockerfile 路径,--tag为镜像命名,建议以分支名或 Git tag 作为 tag(如ethcore/parity:master、ethcore/parity:v2.7.0),便于追溯镜像与代码版本的对应关系;- 构建上下文
.为仓库根目录,Dockerfile 中的COPY、ADD指令会基于该目录下的文件执行; - 注意此命令需要本地已安装 Docker,且构建过程会编译完整 Rust 项目,耗时较长、对内存有一定要求。
三、CentOS 自动化构建:两阶段构建与三环境变量
3.1 快速上手
README 推荐的 CentOS 路径用于"构建轻量级非 root Parity Docker 镜像",标准流程是克隆仓库后直接执行构建脚本:
git clone https://github.com/paritytech/parity-ethereum.git
cd parity-ethereum
./scripts/docker/centos/build.sh
运行结束后会生成名为 parity/parity:latest 的镜像,并打印 parity --version 的输出以验证二进制可用。
3.2 环境变量与默认值
README 明确列出了三个可用于完全定制构建的环境变量及其默认值(对应 build.sh 中的 :- 缺省展开):
| 环境变量 | 含义 | 默认值 |
|---|---|---|
PARITY_IMAGE_REPO |
镜像仓库名(image name) | parity/parity |
PARITY_BUILDER_IMAGE_TAG |
构建阶段(builder)镜像的 tag,构建后会追加 Git commit sha | build |
PARITY_RUNNER_IMAGE_TAG |
运行阶段(runner)镜像的 tag | latest |
完全定制示例(README 原文):
PARITY_IMAGE_REPO=my-personal/parity \
PARITY_BUILDER_IMAGE_TAG=build-latest \
PARITY_RUNNER_IMAGE_TAG=centos-parity-experimental \
./scripts/docker/centos/build.sh
3.3 脚本执行流程:从源码到运行镜像
结合 build.sh 源码,该脚本实际执行了以下五个步骤,属于典型的"先编译、再提取、后打包"两阶段模式:
-
构建 builder 镜像:以
scripts/docker/centos/Dockerfile.build为构建文件,用当前 Git HEAD 的 commit sha(git log -1 --format="%H")作为 tag 的一部分:docker build --no-cache -t $PARITY_IMAGE_REPO:$PARITY_BUILDER_IMAGE_TAG-$(git log -1 --format="%H") . -f scripts/docker/centos/Dockerfile.build使用
--no-cache保证每次都是全新编译,避免缓存带来的二进制陈旧问题。 -
从 builder 容器中提取编译产物:
docker create --name extract $PARITY_IMAGE_REPO:$PARITY_BUILDER_IMAGE_TAG-$(git log -1 --format="%H") docker cp extract:/build/parity-ethereum/target/release/parity scripts/docker/centos/parity通过
docker create(不启动容器)+docker cp的方式,把编译好的parity二进制从构建镜像中拷贝到宿主机。 -
构建 runner 镜像:以 scripts/docker/centos/Dockerfile 为构建文件,将二进制
COPY进最终运行镜像。 -
清理临时产物:删除提取出的二进制目录、临时容器
extract以及 builder 镜像,避免残留。 -
验证:
docker run $PARITY_IMAGE_REPO:$PARITY_RUNNER_IMAGE_TAG --version确认镜像可运行且版本信息正确。
从脚本结构可以推断,
Dockerfile.build承担了完整的 Rust 编译工作,而Dockerfile只负责打包二进制,这正是镜像保持轻量的关键——运行镜像中不包含任何编译工具链。
3.4 运行镜像的细节设计
scripts/docker/centos/Dockerfile 非常精简,逐行拆解如下:
FROM centos:latest
RUN mkdir -p /opt/parity/data && \
chmod g+rwX /opt/parity/data && \
mkdir -p /opt/parity/release
COPY parity/parity /opt/parity/release
WORKDIR /opt/parity/data
EXPOSE 5001 8082 8083 8180 8545 8546 30303/tcp 30303/udp
# switch to non-root user
USER 1001
# if no base path provided, assume it's current workdir
CMD ["--base-path","."]
ENTRYPOINT ["/opt/parity/release/parity"]
几个关键设计点:
- 非 root 运行:
USER 1001将容器切换到 UID 1001 的用户,数据目录/opt/parity/data通过chmod g+rwX赋予了组读写权限,兼顾安全性与可写性; - 默认数据目录:
WORKDIR /opt/parity/data配合CMD ["--base-path","."],使容器在未指定--base-path时默认把链数据写到当前工作目录,与命令注释"if no base path provided, assume it's current workdir"一致; - 端口全部暴露:
EXPOSE一次性声明了全部默认服务端口(详见本文第五节),便于docker run -P自动映射。
四、多平台构建:Alpine 与 ARM 交叉编译
除 CentOS 外,仓库还提供了面向不同底层系统的构建方案,它们各自解决了不同场景的痛点。
4.1 Alpine:musl 静态构建
scripts/docker/alpine/Dockerfile 采用多阶段构建(multi-stage build):
-
builder 阶段:基于
alpine:edge,通过apk安装build-base、cargo、cmake、eudev-dev、linux-headers、perl、rust等编译依赖,随后在仓库根目录执行:cargo build --release --target x86_64-alpine-linux-musl --verbose strip target/x86_64-alpine-linux-musl/release/parity指定
x86_64-alpine-linux-musl目标可将产物静态链接到 musl libc,摆脱对 glibc 的运行时依赖;strip用于削减二进制体积。 -
runtime 阶段:仅安装
libstdc++、eudev-libs、libgcc三个运行库,创建 UID 1000 的非 root 用户parity,并显式预创建数据目录:RUN addgroup -g 1000 parity \ && adduser -u 1000 -G parity -s /bin/sh -D parity ... RUN mkdir -p /home/parity/.local/share/io.parity.ethereum/这里预创建的
~/.local/share/io.parity.ethereum/对应 Parity 默认的链数据与密钥目录布局,确保非 root 用户首次启动即可正常落盘。 -
运行镜像仅暴露
8080 8545 8180三个端口(UI、RPC 与 dapps 端口),比 CentOS 版更克制。
4.2 ARM:在 x86 宿主机上交叉编译
面向 ARM 设备的两个 Dockerfile 展示了完整的交叉编译套路:
- scripts/docker/ubuntu-aarch64/Dockerfile:基于
ubuntu:xenial,通过dpkg --add-architecture arm64启用多架构 apt 源,安装gcc-aarch64-linux-gnu、g++-aarch64-linux-gnu、libc6-dev-arm64-cross等交叉编译工具链,随后用rustup target add aarch64-unknown-linux-gnu添加 Rust 目标; - scripts/docker/ubuntu-arm/Dockerfile:基于
ubuntu:14.04,安装gcc-arm-linux-gnueabihf、g++-arm-linux-gnueabihf、libc6-dev-armhf-cross等工具链,对应armv7-unknown-linux-gnueabihf目标。
两者都在 .cargo/config 中写入链接器配置,例如:
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"
然后执行交叉编译、strip 并用 file 命令校验产物架构:
cargo build --target aarch64-unknown-linux-gnu --release --verbose
/usr/bin/aarch64-linux-gnu-strip /build/parity/target/aarch64-unknown-linux-gnu/release/parity
file /build/parity/target/aarch64-unknown-linux-gnu/release/parity
这类镜像适合在树莓派、ARM 云主机等设备上部署 Parity 节点,但注意最终运行镜像仍会暴露二进制(ENTRYPOINT 指向 /build/.../parity),属于开发验证型方案而非最小化产物。
五、镜像端口设计:一份来自 CLI 定义的对照表
README 用一张带箭头的注释图说明了 CentOS 镜像暴露的端口语义:
# secret
# ipfs store ui rpc ws listener discovery
# ↓ ↓ ↓ ↓ ↓ ↓ ↓
EXPOSE 5001 8082 8083 8180 8545 8546 30303/tcp 30303/udp
这些默认值均可在 parity/cli/mod.rs 中找到对应定义,可整理为下表:
| 端口 | 服务 | CLI 参数(默认值) | 源码位置 |
|---|---|---|---|
| 5001 | IPFS API | --ipfs-api-port=5001(默认 local 接口) |
parity/cli/mod.rs |
| 8082 | SecretStore HTTP | --secretstore-http-port=8082 |
parity/cli/mod.rs |
| 8083 | SecretStore 主端口 | --secretstore-port=8083 |
parity/cli/mod.rs |
| 8180 | Dapps/UI 相关端口 | dapps 配置中的端口默认 8180 |
parity/cli/mod.rs |
| 8545 | JSON-RPC over HTTP | --jsonrpc-port=8545 |
parity/cli/mod.rs |
| 8546 | JSON-RPC over WebSocket | --ws-port=8546 |
parity/cli/mod.rs |
| 30303/tcp + udp | P2P 监听与节点发现 | --port=30303 |
parity/cli/mod.rs |
由此可以得出几条实用结论:
-
只暴露、不默认监听外网:Dockerfile 的
EXPOSE只是声明元数据,不会改变 Parity 默认的监听行为。例如 JSON-RPC 默认仅绑定本机接口,若要容器对外提供服务,仍需显式传递--jsonrpc-interface=all、--jsonrpc-hosts=all等参数(--unsafe-expose可以一键开启所有接口的对外监听,源码注释明确警告"UNSAFE and should be used with great care"); -
端口整体平移:CLI 提供
--ports-shift=[SHIFT],可为网络端口及所有服务端口统一加上偏移量,在 Docker 场景下可用于规避宿主机端口冲突(见 parity/cli/mod.rs); -
运行示例:挂载数据卷并映射典型端口:
docker run -d --name parity \ -v /srv/parity/data:/opt/parity/data \ -p 8545:8545 -p 8546:8546 -p 30303:30303 \ -p 30303:30303/udp \ parity/parity:latest --jsonrpc-interface=all --jsonrpc-hosts=all注意
--base-path默认指向容器内工作目录/opt/parity/data,通过-v挂载即可将链数据持久化到宿主机。
六、Docker Hub 发布:镜像标签策略与健康检查
6.1 发布脚本的标签策略
scripts/docker/hub/publish-docker.sh 是官方 CI 发布流程的核心,从中可以看到 Docker Hub 镜像的命名与 tag 策略:
- 版本号与发布轨道分别来自
./tools/VERSION与./tools/TRACK; - 依据
SCHEDULE_TAG或CI_COMMIT_REF_NAME的值,在四种 tag 策略间切换:- 定时构建:
parity/parity:${SCHEDULE_TAG}; stable分支:同时打parity/parity:${VERSION}-stable、parity/parity:latest、parity/parity:stable三个 tag;- 形如
v2.7.0的版本 tag:parity/parity:${VERSION}-${TRACK}(如2.7.0-beta); - 其他分支:
parity/parity:${VERSION}-${CI_COMMIT_REF_NAME}。
- 定时构建:
- 构建时通过
--build-arg VCS_REF="${CI_COMMIT_SHA}"与--build-arg BUILD_DATE="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"注入元数据,写入 hub/Dockerfile 中的 OCI labels(io.parity.image.revision、io.parity.image.created等),便于追溯镜像来源; - 发布前脚本会校验 Docker Hub 凭据(
Docker_Hub_User_Parity/Docker_Hub_Pass_Parity),发布完成后docker logout。
6.2 镜像健康检查:同步完成判定
scripts/docker/hub/check_sync.sh 提供了容器内"是否完成区块同步"的判定逻辑,可配合 Docker HEALTHCHECK 或编排平台使用:
ETH_SYNCING=$(curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' http://localhost:8545 -H 'Content-Type: application/json')
RESULT=$(echo "$ETH_SYNCING" | jq -r .result)
脚本通过本地 JSON-RPC 调用 eth_syncing 方法:当结果为 false 时打印 "Parity is ready to start accepting traffic" 并退出 0,否则打印同步提示并退出 1。这也是 hub/Dockerfile 中安装 curl jq 的原因——它们被用作健康检查工具链。
6.3 hub 镜像的运行时构建
hub/Dockerfile 本身不编译源码,而是直接拷贝预构建产物与检查脚本:
COPY artifacts/x86_64-unknown-linux-gnu/parity /bin/parity
COPY tools/check_sync.sh /check_sync.sh
构建时通过 RUN parity --version 在构建期验证二进制可用,最后以 UID 1000 的非 root 用户 parity 运行,ENTRYPOINT ["/bin/parity"]。从源码结构看,该 Dockerfile 假设 artifacts/ 已由外部流水线填充,属于"二进制分发型"镜像。
七、构建与运行注意事项
综合以上内容,在实际使用中应留意以下几点:
- 构建耗时与资源:Parity 是大型 Rust 项目,直接
docker build或build.sh都会触发完整编译,建议在内存充足(一般 4GB 以上)的机器上执行,并可参考 hub/Dockerfile 中ENV RUST_BACKTRACE 1的做法,在构建期保留环境变量以便定位编译错误; - 版本追溯:使用
build.sh时 builder 镜像 tag 会附带 Git commit sha,可用于精确定位二进制对应的代码提交;发布镜像则通过 VCS_REF label 追溯; - 安全默认值:所有官方镜像均以非 root 用户运行,且默认端口仅暴露监听而不开放对外接口。若需对外提供 RPC/WS 服务,务必评估
--jsonrpc-interface=all、--unsafe-expose带来的安全风险; - 数据持久化:务必用
-v挂载数据目录(CentOS 镜像为/opt/parity/data,Alpine 镜像为/home/parity/.local/share/io.parity.ethereum/),否则容器重建后链数据会丢失; - 健康检查:可将 check_sync.sh 的
eth_syncing判定逻辑接入编排平台,在节点同步完成后再对外放量。
八、小结
Parity Ethereum 的 Docker 方案并非单一 Dockerfile,而是一套覆盖多平台、多发布场景的完整体系:CentOS 脚本提供可定制的两阶段自动化构建,Alpine 方案追求最小化运行镜像,ARM Dockerfile 演示交叉编译流程,Hub 目录则承载官方发布与健康检查。理解 scripts/docker/README.md 中暴露端口与默认值背后对应 parity/cli/mod.rs 的参数定义,能帮助你在容器化部署 Parity 节点时准确控制网络暴露面,快速完成从"构建镜像"到"安全运行"的落地。