Docker部署Parachain节点：Cumulus容器化部署与镜像构建完整指南
【免费下载链接】cumulusWrite Parachains on Substrate项目地址: https://gitcode.com/gh_mirrors/cum/cumulus
Cumulus 是 Parity 开源的 Substrate Parachain 开发框架，而 Docker 容器化部署 Parachain 节点 是快速搭建测试链、验证 Collator（出块节点）行为的最快方式。本指南带你用容器完成 Cumulus 镜像构建与节点部署，全程无需在本地安装 Rust 工具链，几分钟即可跑通一个完整的 Parachain 测试网络。
为什么选择容器化部署 Cumulus？
Parachain 节点的构建依赖庞大的 Rust 工具链，本地编译往往耗时数十分钟甚至数小时。使用 Docker（或 Podman）部署 Cumulus 节点有三大好处：
- 📦环境隔离：构建和运行互不污染，本机零依赖
- 🚀可复现：镜像化交付，团队协作与 CI 流水线开箱即用
- 🧹最小足迹：不占本机磁盘和内存资源，
docker-compose一条命令拉起整条测试链
官方文档对容器用法的说明位于docs/container.md，其中明确指出Podman 与 Docker 命令可互换（可通过alias docker=podman直接兼容）。
四种容器镜像构建方式：按需选择
Cumulus 提供了从"开箱即用"到"完全自编译"的 4 种镜像方案，难度递增：
| 方式 | 适用场景 | 难度 | 关键文件 |
|---|---|---|---|
| 官方镜像 | 直接拉取现成镜像运行节点 | ⭐ | parity/polkadot-parachain镜像 |
| Parity CI 镜像 | 用容器代替本地编译出 Linux 二进制 | ⭐⭐ | docker/scripts/build_polkadot.sh |
| 二进制注入镜像 | 已有编译好的二进制，快速打包 | ⭐⭐ | docker/injected.Dockerfile |
| 容器内全量构建 | 零本地环境，一行命令出镜像 | ⭐⭐⭐ | docker/polkadot-parachain_builder.Containerfile |
方式一：拉取 Parity 官方镜像
官方维护的容器镜像可直接用于运行节点，是最快验证 Cumulus 的方式。
方式二：用 CI 镜像编译 Linux 二进制
借助 Parity 内部通用的 CI 基础镜像，不需要安装 Rust 即可编译出 Linux 二进制，编译产物位于target/目录，为后续注入镜像做准备。
方式三：二进制注入（Injected Image）
这是最快得到一个可用镜像的办法：把编译好的polkadot-parachain二进制注入到 Parity 基础镜像parity/base-bin中。注入逻辑由docker/injected.Dockerfile完成，它会自动拷贝parachains/chain-specs/下的所有链规格到镜像的/specs目录，并暴露 30333、9933、9944、9615 四个端口。
方式四：Containerfile 容器内全量构建
完全不想碰编译环境？直接执行容器内构建，由docker/polkadot-parachain_builder.Containerfile负责在 CI 基础镜像里完成整个 Cargo Release 编译。耗时较长，但对新手最友好——无需本地 Rust 工具链，构建完成后即可用--collator --tmp参数快速启动测试节点。
一键部署：Docker Compose 拉起完整测试网络
Cumulus 内置了一套开箱即用的测试编排文件docker/docker-compose.yml，一次docker-compose up就能同时启动6 个容器：
| 服务 | 作用 | 镜像/构建来源 |
|---|---|---|
node_alice/node_bob | 两个 Relay Chain 全节点，固定 IP 172.28.1.1 / 172.28.1.2 | polkadot:${BRANCH}镜像 |
genesis_state | 导出 Parachain 创世状态到共享卷 | docker/test-parachain-collator.dockerfile |
collator | 测试 Parachain 的出块节点（Collator） | 同上，collator构建阶段 |
runtime | 输出编译好的 Parachain Runtime WASM 到共享卷 | 同上，runtime构建阶段 |
registrar | 等待就绪后自动调用registrar.registerPara注册 Parachain 100 | docker/parachain-registrar.dockerfile |
整套流程自动完成：编译 Runtime → 导出创世状态 → 等待 Relay Chain 节点就绪 → 发送注册交易 → 启动 Collator。其中注册脚本docker/scripts/register_para.sh会等待 Runtime WASM 与创世状态文件写入共享卷，再通过polkadot-js-api以//Alice账户发起注册交易；Collator 启动脚本docker/scripts/inject_bootnodes.sh则会自动从 Alice/Bob 节点的 RPC 接口获取 Peer ID 并注入 bootnodes，彻底省去手工配置。
最快启动方式
在仓库根目录执行以下两个脚本即可完成"构建 + 后台启动"：
- 启动测试链与 Collator：
docker/scripts/run_collator.sh（内部执行docker build+docker-compose up -d） - 停止 Collator：
docker/scripts/stop_collator.sh
如果你只想手动构建某个镜像，可执行docker/scripts/build_docker.sh并指定目标 dockerfile，脚本会自动以文件名作为镜像名打标签。
端口速查表
宿主机映射的常用端口如下，便于用 Polkadot.js Apps 等工具接入：
| 节点 | P2P | RPC (9933 系) | WS (9944 系) |
|---|---|---|---|
| Alice | 30333 | 9933 | 9944 |
| Bob | 30344 | 9935 | 9945 |
健康检查：如何确认 Parachain 节点部署成功？
docker/test-parachain-collator.dockerfile中为 Collator 配置了 HEALTHCHECK，执行docker/scripts/healthcheck.sh：该脚本两次查询 Parachain 100 的parachains.heads（间隔 60 秒），只要 Head 发生变化，即说明Collator 已在持续为 Parachain 生产区块，部署成功。检查间隔设为 300 秒，避免频繁 RPC 请求。
常见问题与排错清单
- ⏳首次构建很慢：Containerfile 全量构建需编译整个 Cargo 工作区，请耐心等待；构建阶段结果会被缓存，二次启动可复用。
- 🐳Podman 用户：全部命令中把
docker换成podman，或建立 alias 即可。 - 🔌WS 连不上：确认 Collator 已注入正确的 bootnodes（查看容器日志中
--bootnodes参数），并确认 Relay Chain 节点 RPC 已就绪。 - 🧪本地二进制开发：若你已用 CI 镜像编译出
polkadot-parachain，可用注入镜像（方式三）省去容器内编译环节。
延伸阅读
- 容器使用完整说明：
docs/container.md - 测试网络编排与卷定义：
docker/docker-compose.yml - 多阶段构建（builder / collator / runtime 三个目标）：
docker/test-parachain-collator.dockerfile - 集成测试网络拓扑：
zombienet/examples/small_network.toml
掌握了以上 4 种镜像构建方式和 Compose 一键部署流程，你就已经具备用 Docker 容器化运行 Cumulus Parachain 节点的全部能力——从本地开发测试到 CI 流水线交付，一条命令即可完成。
【免费下载链接】cumulusWrite Parachains on Substrate项目地址: https://gitcode.com/gh_mirrors/cum/cumulus
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
