Substrate 这个词我第一次看到时第一反应是生物化学课本里的“底物”——酶催化反应时抓住的那个分子。后来转到区块链开发才发现同样的词被 Parity 拿来命名了一套框架定位一模一样一块承载应用的底层。Substrate 不是一条公链而是一个拿来建链的框架。你可以基于它一条命令跑起自己的链也可以从零开始写业务模块把状态转换、共识、P2P 网络和链上治理都搭起来。这篇文章我会从“为什么选择 Substrate”讲起拆解它的分层架构带你实操起链、写 Pallet、做 Runtime 升级最后聊聊那些文档不写但实际会上头的坑。1. Substrate 到底是什么它解决的是哪种痛1.1 名字的隐喻酶要底物链要 Substrate如果你读过生化应该记得 substrate 是酶的底物。酶自身不会随便反应必须抓住一个底物才能催化特定的转化底物不同反应产物完全不同。Parity 用这个命名区块链框架核心想表达的就是“底层和载体”你的业务逻辑像酶一样需要一块经过验证的基础环境来承载Substrate 就是那层环境。Substrate 自己不是一条链也不是一个智能合约平台。它是一个模块化的区块链开发框架替你把区块链里面最难啃的基础设施全部做成了可插拔组件——共识、网络同步、状态存储、最终性、RPC。你写的业务逻辑被称为 Runtime也就是状态转换函数给定当前链上状态和下一个区块Runtime 输出新的状态。一句话总结Substrate 是让区块链生长出来的土壤而不是那一棵具体的树。1.2 没有 Substrate 之前自己造链有多痛苦在 Substrate 流行之前想从零造一条链你需要同时搞定太多层面的问题。共识算法里是选工作量证明还是权益证明出块间隔怎么设分叉回滚规则怎么写网络层面节点之间怎么发现彼此区块和交易怎么广播孤儿块怎么缓存存储层面状态按 Merkle 树组织要能快速验证还要支持轻客户端更头疼的是升级一旦链上逻辑有 Bug传统方案基本只能硬分叉逼着所有节点运营商手动升级社区也可能因此撕裂。这些问题里任何一件单独拿出来都够一个团队折腾半年。而且底层基础设施一旦出错往往不是功能性问题而是安全问题。Substrate 把这些通用能力全部收敛到外部节点里让业务开发者不用碰网络和共识的细节。你只需要实现 Runtime 需要的那组接口剩下的事情交给框架。所以很多项目从“想法”到“能跑的链”周期可以从两三年压缩到几周。1.3 谁在用它独立链、平行链和联盟链目前 Substrate 生态里最有代表性的项目是 Polkadot 和 Kusama这两条链本身都用 Substrate 构建大量平行链也通过 Substrate 的共享安全模型接入。但这不意味着你只有做平行链才能用得上它。实际环境里很多团队用 Substrate 跑独立应用链、内部联盟链甚至拿它做概念验证原型。为什么这么普适因为 Substrate 把“跑一条链”的门槛从工程问题变成了配置问题。你想做存证、结算、治理、游戏资产都可以先用现成 Pallet 拼出核心逻辑再慢慢替换掉不合适的组件。如果你想要的是一个去中心化系统而不是一个简单的智能合约Substrate 是很值得认真考虑的技术底座。2. 架构拆解Client、Runtime、FRAME 各管哪一段2.1 Client跑腿的“外部节点”Client 在 Substrate 里叫 external node也就是常见的节点程序。它干的是“跑腿”的活和其他节点建立 P2P 连接、同步区块、广播交易、管理本地数据库、暴露 RPC 接口。用户提交交易后Client 负责把交易放进交易池在共识引擎指挥下打包或验证区块。这里有个容易被忽略的重点Client 完全不关心你的业务里有几种积分、存了什么凭证它只关心区块头怎么连成合法链、所有节点怎么最终达成一致。业务逻辑变化不会影响网络同步的逻辑这是 Substrate 分层设计的价值所在。以前我刚开始看代码时总在 client 目录里找业务逻辑结果发现找错了地方业务逻辑根本不在这一层。2.2 Runtime真正定义业务的状态转换函数Runtime 是 Substrate 真正的灵魂。它是一段编译成 WebAssembly 的代码定义了每一步状态转换逻辑。每笔交易、每次调用链上状态怎么变都由 Runtime 说了算。同时Runtime 也会以原生代码形式嵌入节点用来加速执行但最终验证的时候节点还是会用链上存储的 Wasm 做确定性执行。因为链上存的是 Wasm而不是某台机器的原生指令所以任何节点只要支持 Wasm 执行就能跑这条链。更重要的是更新链上那段 Wasm就相当于更新整条链的业务规则。这正是 Substrate 无分叉升级最底层的依据客户端只是一个通用执行器升级不再依赖所有节点的软件同步。2.3 FRAME 与 Pallet像乐高一样组装模块写 Runtime 时通常你不会从零手写所有逻辑而是用 FRAME。FRAME 是 Parity 提供的一套宏和库核心概念是 Pallet一个功能专一的模块。System Pallet 管理账户和区块基本信息Balances Pallet 管理转账Multisig Pallet 做多签Sudo Pallet 提供超级管理员权限。一个 Runtime 就是多个 Pallet 的组合通过construct_runtime!宏拼装起来。搭链很像搭乐高需要什么功能就从货架上拿对应的 Pallet货架没有就自己写一个。这种模块化设计带来的好处不只是开发快更在于长期维护清晰每个 Pallet 是独立的 crate有自己的存储、事件、错误和调用接口团队可以并行开发不同模块互不阻塞。3. 五分钟跑通一条链环境准备与实操全流程3.1 装好 Rust 和 wasm targetSubstrate 是 Rust 项目所以第一步是装 Rust。Linux 或 macOS 最省心Windows 建议用 WSL2。安装命令很简单curl https://sh.rustup.rs -sSf | sh source ~/.cargo/env接下来要准备 nightly 工具链和 wasm 编译目标rustup update nightly rustup target add wasm32-unknown-unknown --toolchain nightly为什么要编译到 wasm32-unknown-unknown我在前面提过Runtime 需要编译成 Wasm 存到链上这是无分叉升级的前提。这一步不做后面cargo build --release就会在构建 Runtime 时报错。另外Substrate 模板目录里通常自带rust-toolchain.toml进目录后会自动使用指定版本不要手贱去切 Rust 版本不然很容易遇到一堆莫名其妙的编译错误。3.2 用模板创建项目最省事的方式是用官方模板 pluscargo-generate初始化。先装cargo-generatecargo install cargo-generate然后执行cargo generate --git https://github.com/paritytech/substrate-node-template.git --name my-chain如果你网络不太好也可以直接下载模板 zip 再解压。项目名叫my-chain里面有两个最值得关注的 cratenode是外部客户端pallets/template是模板 Palletruntime目录里则拼装着所有 Pallet。这个结构看起来很复杂但你真正需要频繁改动的就是runtime/src/lib.rs和pallets/template这两个地方。3.3 编译、启动、连上前端进入项目目录开始编译cd my-chain cargo build --release第一次编译会很慢二十分钟到四十分钟都很正常取决于机器配置。编译完成之后启动开发节点./target/release/node-template --dev --tmp--dev表示使用开发链配置--tmp表示数据存在临时目录退出即清空。如果不想每次重新开始就把--tmp去掉并明确指定一个数据目录。启动后日志里会看到 libp2p 网络信息、Aura 出块信息区块号会持续增长。这时可以打开两个图形界面验证链真的在工作。官方有 substrate-front-end-template是个 React 应用跑起来后能查看账户余额、提交交易。也可以直接用 Polkadot.js Apps把连接端点设置成ws://127.0.0.1:9944。节点默认的 HTTP RPC 端口是 9933WebSocket 端口是 9944很多连接问题都是因为连到了 HTTP 端口才失败。4. 手写一个 Pallet给链加一个自定义业务模块4.1 先设计存储、事件、调用怎么定模板里的 Pallet 叫 pallet-template功能非常简单允许一个签名账户把一个值存到链上。我开始改业务时不会直接上复杂逻辑而是先把这个最简单链路跑通用户签名调用一个函数链上保存一个数字同时触发一个事件。这三点分别对应 FRAME 的 Storage、Call 和 Event。存储组件用StorageValue适合保存单个值事件SomethingStored需要包含存的数字和操作者账户调用方法do_something里用ensure_signed拿到签名者防止无身份调用。这个设计看起来朴素但已经涵盖了 Pallet 最核心的骨架后续加复杂业务无非是把单值变成 Map把单事件变成多事件把单调用变成多调用。4.2 用 FRAME 新式宏写一个“存个数”模块以 Substrate 0.9.x 系列常用的#[frame_support::pallet]新式宏为例代码大概长这样#[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; #[pallet::config] pub trait Config: frame_system::Config { type RuntimeEvent: FromEventSelf IsTypeSelf as frame_system::Config::RuntimeEvent; } #[pallet::pallet] pub struct PalletT(_); #[pallet::storage] #[pallet::getter(fn something)] pub type SomethingT: Config StorageValue_, u32, ValueQuery; #[pallet::event] #[pallet::generate_deposit(pub(super) fn deposit_event)] pub enum EventT: Config { SomethingStored(u32, T::AccountId), } #[pallet::call] implT: Config PalletT { #[pallet::weight(10_000)] pub fn do_something(origin: OriginForT, something: u32) - DispatchResult { let who ensure_signed(origin)?; Something::T::put(something); Self::deposit_event(Event::T::SomethingStored(something, who)); Ok(()) } } }有几点需要解释一下。Configtrait 定义了这个 Pallet 需要 Runtime 提供哪些类型比如RuntimeEvent这样事件才能统一汇入 Runtime 的事件枚举。#[pallet::pallet]生成 Pallet 结构体它是一种零大小类型作为模块调用的入口。ValueQuery表示存储值默认是u32的零值如果你需要区分“不存在”和“值为 0”就改成OptionQuery。ensure_signed(origin)这行很关键它把调用者的签名解析出来随后才能记录who。如果调用来自非签名来源比如根权限调用这个调用会直接返回错误。这个设计不是为了为难用户而是符合大多数业务对“谁操作了状态”的强烈需求。4.3 注册进 Runtime让它真正生效光在 Pallet 里写代码还不够必须把 Pallet 注册到 Runtime 的construct_runtime!宏里。打开runtime/src/lib.rs在construct_runtime!的列表中加入TemplateModule: pallet_template,同时确保 runtime 里已经对pallet_template做了模块声明和公开导出。然后重新编译cargo build --release编译通过后再启动节点打开 Polkadot.js Apps在 Extrinsics 页面选择templateModule.doSomething提交一个数字如果链上状态被修改且出现了templateModule.SomethingStored事件说明这个自定义 Pallet 已经真正生效。很多新手在这里会卡住明明代码没问题但前端看不到调用十有八九是construct_runtime!里的模块名写错了。宏要求第一个词是生成的 Runtime 结构体名字比如TemplateModule第二个词是模块的 crate 入口比如pallet_template两者不是同一个东西不能混写。4.4 Pallet 开发里那些没人提醒你的细节我的经验是写 Pallet 时顺序决定效率。先定 Storage再定 Event然后写 Call因为 Call 一定会引用存储和事件类型。Event 类型必须在Configtrait 里声明RuntimeEvent并且 Runtime 的RuntimeEvent枚举要包含对应变体如果漏了编译会直接报 trait bound 错误。#[pallet::weight]这个值在示例里随手填了10_000但生产环境绝不能这么写。Weight 衡量的是执行这笔交易消耗的计算资源填少了会导致区块执行超限填多了白白浪费用户手续费。正确做法是用 FRAME Benchmarking 工具对每个 Call 做实际测量再自动生成权重。演示阶段用固定值没问题但心里要明白这是临时方案。还有一个小坑StorageValue如果用ValueQuery读取永远不会返回None它会返回类型的默认值。如果你依赖Option判断是否存在就会踩坑。所以业务上需要表达“没有存储过”时要用OptionQuery或者额外维护一个布尔标记。5. Runtime 升级无分叉升级的甜与苦5.1 为什么这是 Substrate 的杀手锏传统区块链如果要改业务逻辑硬分叉是常见的办法所有节点运营商都要手动升级客户端社区还要经历一场争论。Substrate 把 Runtime 编译成 Wasm 存进链里整条链的规则就不在客户端代码里而在链上数据里。当某个区块执行了“更新 Runtime”的调用后续区块会自动加载新的 Wasm状态完全保留节点不需要停机。这件事怎么强调都不过分。它意味着你可以像给传统后端发版本一样给区块链发业务更新。但甜头背后是苦头如果你改坏了没有立刻回滚的按钮必须在链上再部署一个修复版本如果新 Runtime 需要读取旧存储却忘了迁移轻则读取错误重则模块 panic甚至导致链停止出块。5.2 实操替换链上的 Wasm Runtime实际操作分三步。第一步编译出新的 Runtime Wasmcargo build --release生成的 wasm 文件通常在target/release/wbuild/node-template-runtime/node_template_runtime.compact.wasm。第二步准备一个拥有 sudo 权限的账户开发模式下//Alice默认是 sudo。第三步打开 Polkadot.js Apps选择 Developer - Extrinsics提交sudo.sudoUncheckedWeight调用内部嵌套system.setCode上传刚才的 Wasm 文件。这里有一个很常见的失败点新 Runtime 的spec_version必须比当前链上的版本大。如果版本号一样或者更小setCode会被拒绝。每次升级前记得去runtime/src/lib.rs里把spec_version递增。提交成功后下一个区块开始节点会加载新 Runtime你可以通过链上 Runtime 版本信息确认是否切换成功。5.3 存储迁移升级不等于换个二进制无分叉升级最脆弱的地方不在 Wasm 替换而在存储迁移。新 Runtime 如果改变了某个 StorageMap 的 key 编码或者把一个存储项从StorageValue改成了StorageMap旧数据读出来就会对不上。Substrate 提供了on_runtime_upgrade钩子在运行时升级完成、交易执行前执行一段迁移函数。迁移策略大体有三种一次性迁移在升级那个区块把全量数据改完适合数据量小的情况惰性迁移在用户每次读取时检查版本号按需迁移适合大数据量场景分轮迁移把迁移分段每轮处理一部分。无论哪种迁移代码都应当是不可逆的要先用本地链、测试网络充分验证。我在实际项目里被存储迁移坑过很多次最稳妥的做法是写一个升级测试创世起链写入一批旧数据然后执行新的 Runtime Wasm跑一遍关键交易最后验证核心账户余额和关键存储项没有丢失。Substrate 提供了try-runtime工具可以在真实链数据快照上预演迁移能把绝大多数隐患提前暴露出来。6. 常见坑与排查心得6.1 第一个坑永远是编译Substrate 是个庞大的 Rust 工程首次编译接近半小时很正常。如果你在编译过程中看到进程被 killed多半是内存不够尤其是链接阶段。解决办法是加 swap或者在.cargo/config.toml里切换链接器为rust-lld可以明显降低内存压力。还有一个特别容易踩的坑不要手动升级 Rust 版本。模板自带rust-toolchain.toml进入目录后 rustup 会自动切换。如果你在全局强行rustup update可能导致 nightly 版本与 Substrate 某个历史版本不兼容然后你会看到成片成片的 trait bound 错误而这些错误本质上跟业务逻辑毫无关系。另外别一改几行代码就cargo build --release先用cargo check做类型检查速度会快很多实在需要缓存可以上 sccache。6.2 节点不出块、连不上 RPC 时的排查思路节点日志停在“Waiting for new blocks”或者 Aura 不出块第一反应不是看代码而是看系统时间。Aura 共识对时间偏差敏感本地时间如果有几分钟偏差可能一直轮不到你出块。开发模式下可以把系统时间同步一下再重启节点。连不上 RPC 时先确认端口真的在监听ss -tlnp | grep 9944如果端口没起来节点大概率还没启动完成如果端口起来了但前端连不上检查是不是用了 HTTP 端口 9933 而不是 WebSocket 端口 9944。同步卡住的时候尝试--pruningarchive或更换同步模式。退出节点后如果立即重启报了数据库锁错误看看是不是旧进程还占着数据目录直接 kill 旧进程再启动比反复重启有效得多。6.3 Runtime 升级后报错的排查顺序升级后调用某个 Pallet 报错先别急着改业务逻辑按这个顺序排查。第一查spec_version链上当前 Runtime 版本是否真的比旧版本高如果没变说明setCode可能没有生效。第二查存储迁移新版本是否改了存储结构、删除或重命名了 Storage 项尤其要检查on_runtime_upgrade里有没有 Panic。第三查权限ensure_signed和ensure_root是否误用导致合法调用被拒。常见报错里BadOrigin基本是因为调用方不符合权限要求ModuleError则需要看具体错误枚举比如InsufficientBalance或NoPermission。日志里可能不会直接显示完整错误名需要再额外 debug 一层或调用返回的错误码去 RPC 里查对应枚举。这套流程走下来大部分问题都能定位到具体模块。我自己刚接触 Substrate 时最大的教训是贪新。网上教程、官方文档、社群答疑经常因为版本不同而对不上今天常见的宏写法半年前可能已经完全不是这个风格。后来我强迫自己只用官方 node-template锁死一个 release 版本遇到问题先看对应版本的文档才慢慢把链跑顺。如果你也想上手我的建议是顺序别乱先跑通模板再改一个 Pallet然后体验一次 Runtime 升级最后再碰存储迁移。过程中遇到任何编译错误先怀疑版本错位十次里有七八次是环境的问题。这就是 Substrate 最需要跨过的一道坎跨过去之后你会觉得搭链不过是组装乐高。
Substrate实战：模块化区块链框架从入门到无分叉升级
Substrate 这个词我第一次看到时第一反应是生物化学课本里的“底物”——酶催化反应时抓住的那个分子。后来转到区块链开发才发现同样的词被 Parity 拿来命名了一套框架定位一模一样一块承载应用的底层。Substrate 不是一条公链而是一个拿来建链的框架。你可以基于它一条命令跑起自己的链也可以从零开始写业务模块把状态转换、共识、P2P 网络和链上治理都搭起来。这篇文章我会从“为什么选择 Substrate”讲起拆解它的分层架构带你实操起链、写 Pallet、做 Runtime 升级最后聊聊那些文档不写但实际会上头的坑。1. Substrate 到底是什么它解决的是哪种痛1.1 名字的隐喻酶要底物链要 Substrate如果你读过生化应该记得 substrate 是酶的底物。酶自身不会随便反应必须抓住一个底物才能催化特定的转化底物不同反应产物完全不同。Parity 用这个命名区块链框架核心想表达的就是“底层和载体”你的业务逻辑像酶一样需要一块经过验证的基础环境来承载Substrate 就是那层环境。Substrate 自己不是一条链也不是一个智能合约平台。它是一个模块化的区块链开发框架替你把区块链里面最难啃的基础设施全部做成了可插拔组件——共识、网络同步、状态存储、最终性、RPC。你写的业务逻辑被称为 Runtime也就是状态转换函数给定当前链上状态和下一个区块Runtime 输出新的状态。一句话总结Substrate 是让区块链生长出来的土壤而不是那一棵具体的树。1.2 没有 Substrate 之前自己造链有多痛苦在 Substrate 流行之前想从零造一条链你需要同时搞定太多层面的问题。共识算法里是选工作量证明还是权益证明出块间隔怎么设分叉回滚规则怎么写网络层面节点之间怎么发现彼此区块和交易怎么广播孤儿块怎么缓存存储层面状态按 Merkle 树组织要能快速验证还要支持轻客户端更头疼的是升级一旦链上逻辑有 Bug传统方案基本只能硬分叉逼着所有节点运营商手动升级社区也可能因此撕裂。这些问题里任何一件单独拿出来都够一个团队折腾半年。而且底层基础设施一旦出错往往不是功能性问题而是安全问题。Substrate 把这些通用能力全部收敛到外部节点里让业务开发者不用碰网络和共识的细节。你只需要实现 Runtime 需要的那组接口剩下的事情交给框架。所以很多项目从“想法”到“能跑的链”周期可以从两三年压缩到几周。1.3 谁在用它独立链、平行链和联盟链目前 Substrate 生态里最有代表性的项目是 Polkadot 和 Kusama这两条链本身都用 Substrate 构建大量平行链也通过 Substrate 的共享安全模型接入。但这不意味着你只有做平行链才能用得上它。实际环境里很多团队用 Substrate 跑独立应用链、内部联盟链甚至拿它做概念验证原型。为什么这么普适因为 Substrate 把“跑一条链”的门槛从工程问题变成了配置问题。你想做存证、结算、治理、游戏资产都可以先用现成 Pallet 拼出核心逻辑再慢慢替换掉不合适的组件。如果你想要的是一个去中心化系统而不是一个简单的智能合约Substrate 是很值得认真考虑的技术底座。2. 架构拆解Client、Runtime、FRAME 各管哪一段2.1 Client跑腿的“外部节点”Client 在 Substrate 里叫 external node也就是常见的节点程序。它干的是“跑腿”的活和其他节点建立 P2P 连接、同步区块、广播交易、管理本地数据库、暴露 RPC 接口。用户提交交易后Client 负责把交易放进交易池在共识引擎指挥下打包或验证区块。这里有个容易被忽略的重点Client 完全不关心你的业务里有几种积分、存了什么凭证它只关心区块头怎么连成合法链、所有节点怎么最终达成一致。业务逻辑变化不会影响网络同步的逻辑这是 Substrate 分层设计的价值所在。以前我刚开始看代码时总在 client 目录里找业务逻辑结果发现找错了地方业务逻辑根本不在这一层。2.2 Runtime真正定义业务的状态转换函数Runtime 是 Substrate 真正的灵魂。它是一段编译成 WebAssembly 的代码定义了每一步状态转换逻辑。每笔交易、每次调用链上状态怎么变都由 Runtime 说了算。同时Runtime 也会以原生代码形式嵌入节点用来加速执行但最终验证的时候节点还是会用链上存储的 Wasm 做确定性执行。因为链上存的是 Wasm而不是某台机器的原生指令所以任何节点只要支持 Wasm 执行就能跑这条链。更重要的是更新链上那段 Wasm就相当于更新整条链的业务规则。这正是 Substrate 无分叉升级最底层的依据客户端只是一个通用执行器升级不再依赖所有节点的软件同步。2.3 FRAME 与 Pallet像乐高一样组装模块写 Runtime 时通常你不会从零手写所有逻辑而是用 FRAME。FRAME 是 Parity 提供的一套宏和库核心概念是 Pallet一个功能专一的模块。System Pallet 管理账户和区块基本信息Balances Pallet 管理转账Multisig Pallet 做多签Sudo Pallet 提供超级管理员权限。一个 Runtime 就是多个 Pallet 的组合通过construct_runtime!宏拼装起来。搭链很像搭乐高需要什么功能就从货架上拿对应的 Pallet货架没有就自己写一个。这种模块化设计带来的好处不只是开发快更在于长期维护清晰每个 Pallet 是独立的 crate有自己的存储、事件、错误和调用接口团队可以并行开发不同模块互不阻塞。3. 五分钟跑通一条链环境准备与实操全流程3.1 装好 Rust 和 wasm targetSubstrate 是 Rust 项目所以第一步是装 Rust。Linux 或 macOS 最省心Windows 建议用 WSL2。安装命令很简单curl https://sh.rustup.rs -sSf | sh source ~/.cargo/env接下来要准备 nightly 工具链和 wasm 编译目标rustup update nightly rustup target add wasm32-unknown-unknown --toolchain nightly为什么要编译到 wasm32-unknown-unknown我在前面提过Runtime 需要编译成 Wasm 存到链上这是无分叉升级的前提。这一步不做后面cargo build --release就会在构建 Runtime 时报错。另外Substrate 模板目录里通常自带rust-toolchain.toml进目录后会自动使用指定版本不要手贱去切 Rust 版本不然很容易遇到一堆莫名其妙的编译错误。3.2 用模板创建项目最省事的方式是用官方模板 pluscargo-generate初始化。先装cargo-generatecargo install cargo-generate然后执行cargo generate --git https://github.com/paritytech/substrate-node-template.git --name my-chain如果你网络不太好也可以直接下载模板 zip 再解压。项目名叫my-chain里面有两个最值得关注的 cratenode是外部客户端pallets/template是模板 Palletruntime目录里则拼装着所有 Pallet。这个结构看起来很复杂但你真正需要频繁改动的就是runtime/src/lib.rs和pallets/template这两个地方。3.3 编译、启动、连上前端进入项目目录开始编译cd my-chain cargo build --release第一次编译会很慢二十分钟到四十分钟都很正常取决于机器配置。编译完成之后启动开发节点./target/release/node-template --dev --tmp--dev表示使用开发链配置--tmp表示数据存在临时目录退出即清空。如果不想每次重新开始就把--tmp去掉并明确指定一个数据目录。启动后日志里会看到 libp2p 网络信息、Aura 出块信息区块号会持续增长。这时可以打开两个图形界面验证链真的在工作。官方有 substrate-front-end-template是个 React 应用跑起来后能查看账户余额、提交交易。也可以直接用 Polkadot.js Apps把连接端点设置成ws://127.0.0.1:9944。节点默认的 HTTP RPC 端口是 9933WebSocket 端口是 9944很多连接问题都是因为连到了 HTTP 端口才失败。4. 手写一个 Pallet给链加一个自定义业务模块4.1 先设计存储、事件、调用怎么定模板里的 Pallet 叫 pallet-template功能非常简单允许一个签名账户把一个值存到链上。我开始改业务时不会直接上复杂逻辑而是先把这个最简单链路跑通用户签名调用一个函数链上保存一个数字同时触发一个事件。这三点分别对应 FRAME 的 Storage、Call 和 Event。存储组件用StorageValue适合保存单个值事件SomethingStored需要包含存的数字和操作者账户调用方法do_something里用ensure_signed拿到签名者防止无身份调用。这个设计看起来朴素但已经涵盖了 Pallet 最核心的骨架后续加复杂业务无非是把单值变成 Map把单事件变成多事件把单调用变成多调用。4.2 用 FRAME 新式宏写一个“存个数”模块以 Substrate 0.9.x 系列常用的#[frame_support::pallet]新式宏为例代码大概长这样#[frame_support::pallet] pub mod pallet { use frame_support::pallet_prelude::*; use frame_system::pallet_prelude::*; #[pallet::config] pub trait Config: frame_system::Config { type RuntimeEvent: FromEventSelf IsTypeSelf as frame_system::Config::RuntimeEvent; } #[pallet::pallet] pub struct PalletT(_); #[pallet::storage] #[pallet::getter(fn something)] pub type SomethingT: Config StorageValue_, u32, ValueQuery; #[pallet::event] #[pallet::generate_deposit(pub(super) fn deposit_event)] pub enum EventT: Config { SomethingStored(u32, T::AccountId), } #[pallet::call] implT: Config PalletT { #[pallet::weight(10_000)] pub fn do_something(origin: OriginForT, something: u32) - DispatchResult { let who ensure_signed(origin)?; Something::T::put(something); Self::deposit_event(Event::T::SomethingStored(something, who)); Ok(()) } } }有几点需要解释一下。Configtrait 定义了这个 Pallet 需要 Runtime 提供哪些类型比如RuntimeEvent这样事件才能统一汇入 Runtime 的事件枚举。#[pallet::pallet]生成 Pallet 结构体它是一种零大小类型作为模块调用的入口。ValueQuery表示存储值默认是u32的零值如果你需要区分“不存在”和“值为 0”就改成OptionQuery。ensure_signed(origin)这行很关键它把调用者的签名解析出来随后才能记录who。如果调用来自非签名来源比如根权限调用这个调用会直接返回错误。这个设计不是为了为难用户而是符合大多数业务对“谁操作了状态”的强烈需求。4.3 注册进 Runtime让它真正生效光在 Pallet 里写代码还不够必须把 Pallet 注册到 Runtime 的construct_runtime!宏里。打开runtime/src/lib.rs在construct_runtime!的列表中加入TemplateModule: pallet_template,同时确保 runtime 里已经对pallet_template做了模块声明和公开导出。然后重新编译cargo build --release编译通过后再启动节点打开 Polkadot.js Apps在 Extrinsics 页面选择templateModule.doSomething提交一个数字如果链上状态被修改且出现了templateModule.SomethingStored事件说明这个自定义 Pallet 已经真正生效。很多新手在这里会卡住明明代码没问题但前端看不到调用十有八九是construct_runtime!里的模块名写错了。宏要求第一个词是生成的 Runtime 结构体名字比如TemplateModule第二个词是模块的 crate 入口比如pallet_template两者不是同一个东西不能混写。4.4 Pallet 开发里那些没人提醒你的细节我的经验是写 Pallet 时顺序决定效率。先定 Storage再定 Event然后写 Call因为 Call 一定会引用存储和事件类型。Event 类型必须在Configtrait 里声明RuntimeEvent并且 Runtime 的RuntimeEvent枚举要包含对应变体如果漏了编译会直接报 trait bound 错误。#[pallet::weight]这个值在示例里随手填了10_000但生产环境绝不能这么写。Weight 衡量的是执行这笔交易消耗的计算资源填少了会导致区块执行超限填多了白白浪费用户手续费。正确做法是用 FRAME Benchmarking 工具对每个 Call 做实际测量再自动生成权重。演示阶段用固定值没问题但心里要明白这是临时方案。还有一个小坑StorageValue如果用ValueQuery读取永远不会返回None它会返回类型的默认值。如果你依赖Option判断是否存在就会踩坑。所以业务上需要表达“没有存储过”时要用OptionQuery或者额外维护一个布尔标记。5. Runtime 升级无分叉升级的甜与苦5.1 为什么这是 Substrate 的杀手锏传统区块链如果要改业务逻辑硬分叉是常见的办法所有节点运营商都要手动升级客户端社区还要经历一场争论。Substrate 把 Runtime 编译成 Wasm 存进链里整条链的规则就不在客户端代码里而在链上数据里。当某个区块执行了“更新 Runtime”的调用后续区块会自动加载新的 Wasm状态完全保留节点不需要停机。这件事怎么强调都不过分。它意味着你可以像给传统后端发版本一样给区块链发业务更新。但甜头背后是苦头如果你改坏了没有立刻回滚的按钮必须在链上再部署一个修复版本如果新 Runtime 需要读取旧存储却忘了迁移轻则读取错误重则模块 panic甚至导致链停止出块。5.2 实操替换链上的 Wasm Runtime实际操作分三步。第一步编译出新的 Runtime Wasmcargo build --release生成的 wasm 文件通常在target/release/wbuild/node-template-runtime/node_template_runtime.compact.wasm。第二步准备一个拥有 sudo 权限的账户开发模式下//Alice默认是 sudo。第三步打开 Polkadot.js Apps选择 Developer - Extrinsics提交sudo.sudoUncheckedWeight调用内部嵌套system.setCode上传刚才的 Wasm 文件。这里有一个很常见的失败点新 Runtime 的spec_version必须比当前链上的版本大。如果版本号一样或者更小setCode会被拒绝。每次升级前记得去runtime/src/lib.rs里把spec_version递增。提交成功后下一个区块开始节点会加载新 Runtime你可以通过链上 Runtime 版本信息确认是否切换成功。5.3 存储迁移升级不等于换个二进制无分叉升级最脆弱的地方不在 Wasm 替换而在存储迁移。新 Runtime 如果改变了某个 StorageMap 的 key 编码或者把一个存储项从StorageValue改成了StorageMap旧数据读出来就会对不上。Substrate 提供了on_runtime_upgrade钩子在运行时升级完成、交易执行前执行一段迁移函数。迁移策略大体有三种一次性迁移在升级那个区块把全量数据改完适合数据量小的情况惰性迁移在用户每次读取时检查版本号按需迁移适合大数据量场景分轮迁移把迁移分段每轮处理一部分。无论哪种迁移代码都应当是不可逆的要先用本地链、测试网络充分验证。我在实际项目里被存储迁移坑过很多次最稳妥的做法是写一个升级测试创世起链写入一批旧数据然后执行新的 Runtime Wasm跑一遍关键交易最后验证核心账户余额和关键存储项没有丢失。Substrate 提供了try-runtime工具可以在真实链数据快照上预演迁移能把绝大多数隐患提前暴露出来。6. 常见坑与排查心得6.1 第一个坑永远是编译Substrate 是个庞大的 Rust 工程首次编译接近半小时很正常。如果你在编译过程中看到进程被 killed多半是内存不够尤其是链接阶段。解决办法是加 swap或者在.cargo/config.toml里切换链接器为rust-lld可以明显降低内存压力。还有一个特别容易踩的坑不要手动升级 Rust 版本。模板自带rust-toolchain.toml进入目录后 rustup 会自动切换。如果你在全局强行rustup update可能导致 nightly 版本与 Substrate 某个历史版本不兼容然后你会看到成片成片的 trait bound 错误而这些错误本质上跟业务逻辑毫无关系。另外别一改几行代码就cargo build --release先用cargo check做类型检查速度会快很多实在需要缓存可以上 sccache。6.2 节点不出块、连不上 RPC 时的排查思路节点日志停在“Waiting for new blocks”或者 Aura 不出块第一反应不是看代码而是看系统时间。Aura 共识对时间偏差敏感本地时间如果有几分钟偏差可能一直轮不到你出块。开发模式下可以把系统时间同步一下再重启节点。连不上 RPC 时先确认端口真的在监听ss -tlnp | grep 9944如果端口没起来节点大概率还没启动完成如果端口起来了但前端连不上检查是不是用了 HTTP 端口 9933 而不是 WebSocket 端口 9944。同步卡住的时候尝试--pruningarchive或更换同步模式。退出节点后如果立即重启报了数据库锁错误看看是不是旧进程还占着数据目录直接 kill 旧进程再启动比反复重启有效得多。6.3 Runtime 升级后报错的排查顺序升级后调用某个 Pallet 报错先别急着改业务逻辑按这个顺序排查。第一查spec_version链上当前 Runtime 版本是否真的比旧版本高如果没变说明setCode可能没有生效。第二查存储迁移新版本是否改了存储结构、删除或重命名了 Storage 项尤其要检查on_runtime_upgrade里有没有 Panic。第三查权限ensure_signed和ensure_root是否误用导致合法调用被拒。常见报错里BadOrigin基本是因为调用方不符合权限要求ModuleError则需要看具体错误枚举比如InsufficientBalance或NoPermission。日志里可能不会直接显示完整错误名需要再额外 debug 一层或调用返回的错误码去 RPC 里查对应枚举。这套流程走下来大部分问题都能定位到具体模块。我自己刚接触 Substrate 时最大的教训是贪新。网上教程、官方文档、社群答疑经常因为版本不同而对不上今天常见的宏写法半年前可能已经完全不是这个风格。后来我强迫自己只用官方 node-template锁死一个 release 版本遇到问题先看对应版本的文档才慢慢把链跑顺。如果你也想上手我的建议是顺序别乱先跑通模板再改一个 Pallet然后体验一次 Runtime 升级最后再碰存储迁移。过程中遇到任何编译错误先怀疑版本错位十次里有七八次是环境的问题。这就是 Substrate 最需要跨过的一道坎跨过去之后你会觉得搭链不过是组装乐高。
