經(jīng)常有朋友問我Polkadot SDK也就是以前的Substrate到底怎么上手尤其是想把一條平行鏈跑起來卻不知道從哪一步開始。網(wǎng)上教程一堆但要么太老要么是照著文檔念一遍真正自己動手的時候全是坑。這篇文章就是我反復(fù)搭環(huán)境、編譯、跑通測試網(wǎng)之后整理出來的一份可以照著抄的完整流程希望能幫你少走點(diǎn)彎路。先說清楚這篇文章要解決什么問題。Polkadot SDK本身是一個區(qū)塊鏈開發(fā)框架平行鏈模板則是官方準(zhǔn)備的一個“差不多能用的鏈”它已經(jīng)接好了共識、P2P網(wǎng)絡(luò)、賬戶系統(tǒng)、余額模塊、權(quán)限治理模塊等一堆基礎(chǔ)功能。你要做的不是從零寫一條鏈而是把這個模板拿過來編譯成一條真正能跑的平行鏈節(jié)點(diǎn)然后和Rococo測試網(wǎng)或者本地中繼鏈連接上。整個過程涉及工具鏈配置、代碼編譯、鏈配置、節(jié)點(diǎn)啟動、平行鏈注冊等環(huán)節(jié)每個環(huán)節(jié)都有不少容易踩的坑。這篇文章適合兩類人一類是完全沒碰過Rust和Substrate但想用Polkadot SDK做開發(fā)的人另一類是已經(jīng)跑過獨(dú)立Substrate節(jié)點(diǎn)但對“平行鏈”這層概念還比較模糊想把連接中繼鏈這步徹底搞明白的人。我會盡量把每一步背后的原因也講清楚而不只是告訴你“敲這個命令”。1. 項(xiàng)目設(shè)計與核心思路拆解1.1 為什么用模板而不是從零寫鏈剛接觸Polkadot生態(tài)時我也有過“從零手寫一條鏈”的想法試過之后才發(fā)現(xiàn)完全沒必要。平行鏈本質(zhì)上是一條“插進(jìn)中繼鏈”的區(qū)塊鏈它的區(qū)塊頭要提交給中繼鏈驗(yàn)證所以除了普通區(qū)塊鏈的共識、存儲、交易池之外還得實(shí)現(xiàn)平行鏈特定的接口比如驗(yàn)證人怎么校驗(yàn)?zāi)愕膮^(qū)塊、出塊人怎么從中繼鏈拿到可用性數(shù)據(jù)。這些東西如果自己寫光是把接口定義理解清楚就得花不少時間。官方提供的平行鏈模板polkadot-sdk倉庫里的substrate-parachain-template現(xiàn)在叫parachain-template已經(jīng)把這些問題都處理好了。它默認(rèn)實(shí)現(xiàn)了CollatorSelection收集人選擇和Session會話管理兩個關(guān)鍵pallet也就是說你拿到的模板已經(jīng)具備“跑起來然后注冊成平行鏈”的基礎(chǔ)條件。直接基于它改能夠把所有精力放在業(yè)務(wù)邏輯上。這里也順帶提一個重要的選擇用polkadot-sdk而不是老版本的substrate。Polkadot SDK是2024年以后的統(tǒng)一版本號發(fā)布方式以前分的substrate、polkadot、cumulus三個倉庫合并成了一個倉庫。查資料時如果看到2023年之前的文檔很多路徑和依賴名稱都對不上這點(diǎn)必須有心理準(zhǔn)備。1.2 模板整體架構(gòu)速覽拿到的模板代碼大致分為三層最底層是runtime封裝了鏈上的業(yè)務(wù)邏輯比如余額怎么轉(zhuǎn)賬、質(zhì)押怎么結(jié)算、Staking怎么驗(yàn)證全部以pallet的形式掛載在runtime里。中間層是node節(jié)點(diǎn)負(fù)責(zé)把runtime跑起來處理網(wǎng)絡(luò)、同步、交易池之類的底層工作最終生成一個可執(zhí)行文件。最上層是pallets自定義業(yè)務(wù)模塊默認(rèn)會有一個template示例pallet方便你往里面添加自己的邏輯。這個概念怎么理解呢你可以把runtime想象成一臺手表的機(jī)芯決定“時間怎么計算”而節(jié)點(diǎn)是表殼和指針負(fù)責(zé)把機(jī)芯展示出來。平時你開發(fā)業(yè)務(wù)就是在機(jī)芯里面加零件節(jié)點(diǎn)層基本不用動。2. 環(huán)境準(zhǔn)備與工具鏈安裝2.1 Rust工具鏈的具體配置方法Polkadot SDK是Rust寫的所以你首先得裝Rust。我建議用rustup來管理版本選擇上別用最新的stable而是用官方推薦的nightly-2024-XX-XX某個固定版本。理由很實(shí)在Polkadot SDK的編譯依賴許多只有nightly才有的特性但最新nightly又經(jīng)常引入不兼容的改動所以官方模板里會鎖定一個測試過的nightly版本。打開模板目錄或下載好代碼后里面有個文件叫rust-toolchain.toml內(nèi)容大概是這樣[toolchain] channel nightly-2024-03-01 components [rustfmt, clippy] targets [wasm32-unknown-unknown] profile minimal這個文件告訴rustup進(jìn)入當(dāng)前目錄時自動切換到你鎖定的nightly版本。所以推薦的做法是先把官方模板克隆下來再執(zhí)行rustup安裝不要自己手動選版本。如果已經(jīng)裝了其他版本也沒關(guān)系rustup會按需下載。執(zhí)行安裝curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup show執(zhí)行rustup show會按照rust-toolchain.toml自動下載對應(yīng)工具鏈。這一步可能需要幾分鐘取決于網(wǎng)絡(luò)狀況。另外提醒一句編譯wasm需要wasm32-unknown-unknown目標(biāo)這個目標(biāo)不能少否則后面編譯runtime會直接報錯找不到目標(biāo)。2.2 系統(tǒng)依賴與資源預(yù)估編譯Polkadot SDK內(nèi)存吃得很兇代碼編譯期的峰值內(nèi)存可以達(dá)到8GB到16GB。建議虛擬機(jī)或云服務(wù)器至少4核8GB起步16GB會更穩(wěn)。磁盤方面一個release編譯目標(biāo)目錄大概會占10到15GB預(yù)留30GB以上比較穩(wěn)妥。系統(tǒng)依賴是另一個容易卡住的點(diǎn)。Ubuntu/Debian上執(zhí)行apt update apt install -y git clang curl libssl-dev protobuf-compiler build-essentialmacOS上需要保證Xcode Command Line Tools已經(jīng)安裝同時用Homebrew安裝protobuf和clangxcode-select --install brew install protobuf clang這里重點(diǎn)說一下protobuf-compiler。Polkadot SDK在編譯過程中會用到Prost生成Rust的protobuf代碼如果系統(tǒng)里沒有protoc編譯到某個依賴時就會莫名其妙地報protoc: not found或者failed to execute protoc。這個錯誤很常見但排錯方向卻很少被人提及先把protobuf裝好能免掉一個大麻煩。2.3 源碼獲取與依賴加速獲取模板代碼最直接的方式是直接克隆官方倉庫git clone https://github.com/paritytech/polkadot-sdk.git但polkadot-sdk整個倉庫體積非常大如果沒有特殊需求建議只拉取模板子目錄。官方也提供了模板的獨(dú)立模板倉庫substrate-parachain-template的歷史版本但要注意版本匹配。我更推薦的做法是克隆polkadot-sdk然后切到模板目錄下工作因?yàn)檫@樣能保證使用的依賴代碼版本和自己倉庫的同步更新一致后續(xù)升級依賴時也不容易出錯。依賴下載靠cargo從crates.io拉在國內(nèi)網(wǎng)絡(luò)下慢得讓人絕望。強(qiáng)烈建議配置~/.cargo/config.toml使用國內(nèi)鏡像源比如字節(jié)跳動的鏡像[source.crates-io] replace-with rsproxy-sparse [source.rsproxy-sparse] registry sparsehttps://rsproxy.cn/index/另外polkadot-sdk里有一些依賴是GitHub依賴不走crates.io所以如果拉取時卡住還得結(jié)合代理或者多試幾次。這里提醒一下不要在公網(wǎng)上討論代理工具但本地開發(fā)時自己做好網(wǎng)絡(luò)加速是完全合理的工程實(shí)踐。3. 模板結(jié)構(gòu)解析與核心文件說明3.1 頂層目錄分布我把負(fù)責(zé)人目錄列出來這樣進(jìn)入倉庫之后你能快速找到方向。parachain-template/ ├── node/ │ ├── src/ │ │ ├── command.rs # CLI入口和參數(shù)解析 │ │ ├── rpc.rs # RPC接口 │ │ ├── chain_spec.rs # 鏈配置初始賬戶、初始token、初始收集人 │ │ ├── service.rs # 節(jié)點(diǎn)服務(wù)組裝最重要文件之一 │ │ └── main.rs ├── pallets/ │ └── template/ ├── runtime/ │ └── src/ │ ├── lib.rs # runtime組裝文件所有pallet都要在這掛載 │ ├── config.rs # 各pallet的Config實(shí)現(xiàn) │ ├── genesis_config.rs # 創(chuàng)世配置 │ └── weights.rs # 權(quán)重計算 ├── specs/ # 鏈的規(guī)格文件 ├── rust-toolchain.toml └── Cargo.toml一眼看過去最需要關(guān)心的是runtime/src/lib.rs、runtime/src/config.rs、node/src/chain_spec.rs這三個文件。模板自帶的所有能力、初始配置基本都在這幾個文件里。3.2 關(guān)鍵文件的作用很多人剛拿到代碼時會問為什么平行鏈需要這么多配置文件普通的一條鏈不是編譯完就直接跑嗎這里說一下根本原因。平行鏈需要向中繼鏈注冊自己的“身份”中繼鏈要驗(yàn)證它、要給它分配平行鏈編號、要讓它接入共享安全。所以在啟動和連接的整個過程中需要一份描述自己是誰、初始狀態(tài)是什么的ChainSpec文件。同時因?yàn)槠叫墟湹某鰤K邏輯依賴中繼鏈的驗(yàn)證人集合所以節(jié)點(diǎn)的服務(wù)邏輯service.rs會比普通節(jié)點(diǎn)復(fù)雜得多。chain_spec.rs里需要重點(diǎn)關(guān)注這幾個部分parachain_id你的平行鏈在中繼鏈上的編號比如2000。collator賬號負(fù)責(zé)出塊的收集人至少要有幾個初始賬號。sudo賬號擁有超級權(quán)限用來執(zhí)行注冊、升級、轉(zhuǎn)賬等治理操作。endowed_accounts初始擁有token的賬戶列表。這些值不只是一堆配置它們會直接影響你能不能成功出塊、能不能進(jìn)行后續(xù)的升級操作。后面實(shí)操部分我會具體演示怎么改。3.3 為什么默認(rèn)是“收集人”而不是“驗(yàn)證人”這是初學(xué)平行鏈時最常混淆的概念。普通鏈有驗(yàn)證人負(fù)責(zé)打包和驗(yàn)證區(qū)塊但平行鏈自己不維護(hù)一條“完整驗(yàn)證人鏈”它的出塊節(jié)點(diǎn)叫“收集人”Collator。收集人的職責(zé)是從交易池拿交易聚合出區(qū)塊再把區(qū)塊頭和有效性證明提交給中繼鏈的驗(yàn)證人。中繼鏈上的驗(yàn)證人負(fù)責(zé)做最終校驗(yàn)。所以模板的service.rs里運(yùn)行的是收集人節(jié)點(diǎn)而不是驗(yàn)證人節(jié)點(diǎn)。啟動命令也是polkadot-parachain這樣的節(jié)點(diǎn)其實(shí)模板的二進(jìn)制就叫parachain-template-node它與中繼鏈節(jié)點(diǎn)連接時是通過“平行鏈-中繼鏈”專用的共識協(xié)議的。這一點(diǎn)如果沒理解透很可能在配置節(jié)點(diǎn)時下意識去找“驗(yàn)證人密鑰”但找半天也找不到正確配置。4. 編譯全流程與常見報錯處理4.1 第一次編譯前的編譯選項(xiàng)在項(xiàng)目根目錄執(zhí)行cargo build --release第一次編譯WebAssembly和native代碼大概需要40分鐘到1小時時間長短主要取決于CPU性能也有一部分磁盤IO影響。官方文檔建議使用--release這會讓二進(jìn)制小很多、運(yùn)行效率高很多。如果只是想快速檢查代碼是否編譯通過可以用cargo check --release只需驗(yàn)證類型和依賴不產(chǎn)生最終二進(jìn)制會快很多。我在第一次編譯時遇到最多的是“內(nèi)存不足”。如果當(dāng)前機(jī)器只有8GB內(nèi)存建議臨時增加swap交換分區(qū)否則編譯到一半會被Linux的OOM Killer殺掉。增加swap的方法fallocate -l 8G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile注意這只是開發(fā)環(huán)境下的臨時方案生產(chǎn)環(huán)境還是得保證足夠內(nèi)存。編譯過程中還有一點(diǎn)容易被忽視就是CPU核心數(shù)過高反而可能出問題。Cargo默認(rèn)會占用所有可用核心但在一些云服務(wù)器上多核心編譯反而因?yàn)閮?nèi)存不夠而頻繁觸發(fā)交換。這里可以用一個參數(shù)限制并發(fā)cargo build --release -j 8這樣能限制同時編譯的任務(wù)數(shù)量減少內(nèi)存峰值。我自己實(shí)測下來16GB內(nèi)存的機(jī)器用默認(rèn)并行度沒問題8GB內(nèi)存建議限制到-j4或-j8。4.2 被頻繁踩坑的編譯報錯及定位方法我整理了一份高頻報錯表幫你在卡住時快速定位報錯信息出現(xiàn)原因解決辦法failed to run custom build command for ... libp2p缺少protocapt install protobuf-compiler或brew install protobuffailed to select a version for ...依賴版本沖突檢查Cargo.toml依賴版本和Cargo.lock是否匹配刪除Cargo.lock后重新生成thewasm32-unknown-unknowntarget is not installed缺wasm目標(biāo)rustup target add wasm32-unknown-unknowntoolchain nightly-... is not installedrust-toolchain沒生效執(zhí)行rustup show確認(rèn)自動安裝手動rustup toolchain install nightly-xxxxcannot find attribute macroconstruct_runtimein this scoperuntime版本不匹配或宏導(dǎo)入錯誤檢查Cargo.toml中substrate-wasm-builder和frame的版本清理后重編recursion limit reached while expanding the macro依賴宏遞歸過深在對應(yīng)lib.rs或主入口加#![recursion_limit 256]報錯信息只是個線索真正排錯時要多看日志前幾百行上下文。比如failed to run custom build command之后往往有一大堆上一級依賴信息排查時從最底層的第一個error開始解決不要從最上面的warning開始。4.3 二進(jìn)制產(chǎn)物的驗(yàn)證編譯完成后在target/release下會有一個parachain-template-node可執(zhí)行文件或者polkadot-parachain取決于模板名稱。執(zhí)行./target/release/parachain-template-node --version如果輸出版本號比如parachain-template-node 0.1.0說明本地代碼和工具鏈基本正常接下來可以生成鏈規(guī)格和啟動節(jié)點(diǎn)。5. 平行鏈的啟動與連接中繼鏈5.1 生成鏈規(guī)格ChainSpec平行鏈啟動前要生成一份描述創(chuàng)世狀態(tài)的JSON文件它包含初始賬戶、初始余額、初始收集人列表等信息。生成命令是./target/release/parachain-template-node build-spec --disable-default-bootnode plain-parachain.json--disable-default-bootnode非常重要如果不加生成的規(guī)格里會包含一堆模板自帶的默認(rèn)節(jié)點(diǎn)官方測試節(jié)點(diǎn)這些節(jié)點(diǎn)在國內(nèi)網(wǎng)絡(luò)環(huán)境下根本連不通會拖慢啟動過程。生成完之后可以打開JSON看一眼搜索parachainId確認(rèn)編號是否符合預(yù)期。默認(rèn)可能不是2000可以根據(jù)后續(xù)中繼鏈要求改。建議在生成時直接指定鏈名或編號比如./target/release/parachain-template-node build-spec --disable-default-bootnode --chain mychain mychain-spec.json但這一步只能改部分配置要在創(chuàng)世就注入自己的賬戶最可靠的方式還是直接改chain_spec.rs源碼后重新編譯或者用build-spec生成后手動修改JSON里genesis下的字段。5.2 本地中繼鏈還是公共測試網(wǎng)連接中繼鏈有兩條路一條是連官方公共測試網(wǎng)Rococo另一條是本地起一條中繼鏈用polkadot二進(jìn)制配合rococo-custom或dev鏈。對初學(xué)者我更推薦先本地起一條中繼鏈來練兵。本地中繼鏈的好處太多了出塊速度可控一般設(shè)為2秒或6秒一個塊出問題好排查。擁有sudo權(quán)限可以自己執(zhí)行平行鏈注冊、轉(zhuǎn)交中繼鏈token等操作。不會因?yàn)楣矞y試網(wǎng)上的排隊(duì)、資源不足影響你的研發(fā)節(jié)奏。本地方案的步驟如下構(gòu)建或下載一個polkadot的release二進(jìn)制中繼鏈節(jié)點(diǎn)。生成中繼鏈規(guī)格指定一個或兩個驗(yàn)證人。啟動中繼鏈節(jié)點(diǎn)。構(gòu)建平行鏈節(jié)點(diǎn)并啟動它。在中繼鏈上注冊平行鏈通過sudo調(diào)用registrar.registerParachain。這里中繼鏈的二進(jìn)制可以直接從官方Release頁面下載預(yù)編譯版本也可以自己用cargo build --release -p polkadot編譯但耗時比平行鏈本身還長所以首次就別自己折騰了。5.3 啟動平行鏈節(jié)點(diǎn)并連接本地中繼鏈先啟動中繼鏈。用預(yù)生成的rococo-custom-2.json兩個驗(yàn)證人或dev模式。如果只用單驗(yàn)證人可以執(zhí)行polkadot --chain rococo-custom-2.json --alice --tmp --port 30333 --rpc-port 9944這里的--alice會為Alice預(yù)置驗(yàn)證人密鑰--tmp指定臨時數(shù)據(jù)目錄每次重啟會清空狀態(tài)。重新開一個終端啟動平行鏈節(jié)點(diǎn)./target/release/parachain-template-node \ --alice \ --collator \ --force-authoring \ --tmp \ --port 40333 \ --rpc-port 8844 \ --ws-port 9945 \ -- --execution wasm \ --chain /path/to/relay-chain-spec.json \ --port 30344 \ --rpc-port 9946 \ --tmp注意這條命令中有個非常容易忽略的細(xì)節(jié)在--后面指定的是中繼鏈相關(guān)參數(shù)--前面的參數(shù)是平行鏈自身參數(shù)。平行鏈節(jié)點(diǎn)實(shí)際上是一個“二元節(jié)點(diǎn)”既要跑自己的平行鏈邏輯又要作為全節(jié)點(diǎn)連接中繼鏈所以有兩組參數(shù)。很多新手在日志里看到大量中繼鏈同步信息卻看不到自己的區(qū)塊生產(chǎn)多半就是這兩組參數(shù)混在一起導(dǎo)致的。啟動之后如果一切正常日志里會出現(xiàn) Idle空閑中等待交易或Prepared block for proposing說明平行鏈運(yùn)行起來了但還沒有真正開始出塊因?yàn)橹欣^鏈上還沒注冊它。5.4 通過Polkadot JS注冊平行鏈并轉(zhuǎn)交充值注冊這一步核心操作是通過中繼鏈的registrar模塊的registerParachain調(diào)用完成。操作時要持有中繼鏈上的sudo賬號通常是Alice。流程是打開Polkadot JS Apps連接到中繼鏈RPC本地ws://127.0.0.1:9944。在Developer-Extrinsics中找到registrar的registerParachain。填入平行鏈ID與前面ChainSpec里的ID一致比如2000。填入平行鏈的創(chuàng)世狀態(tài)genesis state和驗(yàn)證人代碼validation code也就是runtime編譯出來的wasm。這兩個數(shù)據(jù)怎么拿需要用到平行鏈節(jié)點(diǎn)提供的RPC對應(yīng)兩個調(diào)用# 獲取創(chuàng)世狀態(tài) curl http://127.0.0.1:8844 -H Content-Type: application/json -d {jsonrpc:2.0,method:chain_getBlock,params:[],id:1}不過更直接的方法是平行鏈節(jié)點(diǎn)自己提供了一種便捷命令來導(dǎo)出創(chuàng)世狀態(tài)和wasm# 導(dǎo)出創(chuàng)世狀態(tài) ./target/release/parachain-template-node export-genesis-state genesis-state # 導(dǎo)出wasm驗(yàn)證代碼 ./target/release/parachain-template-node export-genesis-wasm genesis-wasm把兩個文件內(nèi)容填到Polkadot JS的對應(yīng)字段里就完成了注冊。這里有個細(xì)節(jié)如果文件內(nèi)容是二進(jìn)制格式Polkadot JS有時不接受需要轉(zhuǎn)成hex格式?？梢杂脁xd -p genesis-wasm | tr -d \n轉(zhuǎn)換。完成注冊后等待幾個區(qū)塊平行鏈就會開始出塊。再回到平行鏈節(jié)點(diǎn)的日志可以看到開頭的出塊日志說明平行鏈已經(jīng)從“準(zhǔn)備中”變成了“運(yùn)行中”。6. 自定義平行鏈模板加一個屬于自己的pallet6.1 為什么必須先跑通模板再加業(yè)務(wù)很多朋友一上來就想在模板里加自己的業(yè)務(wù)邏輯結(jié)果連基礎(chǔ)鏈都沒跑通出了問題根本分不清是模板問題還是自己代碼問題。我個人強(qiáng)烈建議的路徑是先原封不動編譯、跑通、注冊再去添加業(yè)務(wù)。等到模板跑通之后業(yè)務(wù)添加就相對自由了。最簡單的方式是在pallets/template里改這個目錄已經(jīng)寫好了Extrinsic的示例你可以順著它的寫法定義自己的Call、Storage、Event。6.2 修改chain_spec設(shè)置初始賬戶如果想讓某個賬戶在創(chuàng)世時就有余額需要修改node/src/chain_spec.rs里的endowed_accounts列表。找到這行類似vec![ get_account_id_from_seed::sr25519::Public(Alice), get_account_id_from_seed::sr25519::Public(Bob), ]添加你自己的地址只需要在列表里加一個SS58格式地址vec![ get_account_id_from_seed::sr25519::Public(Alice), YOUR_SS58_ADDRESS.into(), ]這里要注意地址格式。Polkadot生態(tài)的SS58地址在不同鏈上前綴不一樣平行鏈的默認(rèn)前綴是42所以添加自己的地址時保持和模板里Alice、Bob的地址前綴一樣即可5開頭的通用地址。如果你用了其他工具導(dǎo)入了地址注意檢查SS58前綴。改完重新編譯cargo build --release再用build-spec重新生成鏈規(guī)格后面注冊的創(chuàng)世狀態(tài)就會帶上這些初始余額。6.3 在runtime中掛載自定義pallet的流程如果你想完全新建一個pallet而不是改示例步驟如下第一步在pallets/下創(chuàng)建新目錄比如pallets/my_pallet仿照pallets/template寫好Cargo.toml、src/lib.rs。第二步在自己的pallet的Cargo.toml里保持依賴版本和workspace一致。這一步最容易出錯因?yàn)閜olkadot-sdk統(tǒng)一使用workspace true的方式引用依賴新建的pallet也會自動繼承workspace。如果版本不一致比如frame-support使用了default-features false卻沒同時開啟std編譯時就會遇到一堆trait未實(shí)現(xiàn)錯誤。第三步在runtime/Cargo.toml加上對應(yīng)的依賴格式參照現(xiàn)有的pallet-template。第四步在runtime/src/lib.rs里用construct_runtime!宏注冊。格式construct_runtime!( pub enum Runtime { ... MyPallet: pallet_my_pallet, } );最后在runtime/src/config.rs如果你的模板版本是在單獨(dú)的config.rs文件里實(shí)現(xiàn)Config中實(shí)現(xiàn)pallet_my_pallet::Config通常寫一個空實(shí)現(xiàn)就夠了比如impl pallet_my_pallet::Config for Runtime { type RuntimeEvent RuntimeEvent; }重新編譯檢查是否通過。如果通過說明你的pallet已經(jīng)成功掛載可以開始在里面寫業(yè)務(wù)了。7. 常見問題排查與調(diào)試技巧7.1 區(qū)塊高度不增長這是最常見的現(xiàn)象。平行鏈注冊完成日志卻一直是Idle不出塊。排查思路按順序來先確認(rèn)中繼鏈?zhǔn)欠裾３鰤K。如果中繼鏈卡住了平行鏈也不可能出塊。然后看平行鏈的區(qū)塊頭是否已提交給中繼鏈。打開Polkadot JS進(jìn)入Parachains-Overview如果顯示你的平行鏈“是”出塊狀態(tài)說明正常如果顯示“準(zhǔn)備中”說明注冊還沒生效或驗(yàn)證人沒被分配到。再看平行鏈節(jié)點(diǎn)日志中是否有Could not create proposal如果有多半是交易池有無效交易或構(gòu)建區(qū)塊時補(bǔ)了無效的Runtime調(diào)用。檢查錢包余額。平行鏈需要在中繼鏈上有一定的余額來支付注冊和出塊手續(xù)費(fèi)如果你的平行鏈賬戶被清空了它可能無法繼續(xù)提交區(qū)塊頭。大部分情況下問題出在中繼鏈驗(yàn)證人的抵押數(shù)量不夠或者平行鏈賬戶沒有足夠的token來支付“抵押存款”。解決方法是在中繼鏈上給平行鏈賬戶轉(zhuǎn)賬或者以sudo身份修改平行鏈相關(guān)的存款參數(shù)。7.2 驗(yàn)證人收不到平行鏈狀態(tài)有時中繼鏈節(jié)點(diǎn)日志顯示一切正常但平行鏈就是不被認(rèn)可。這時可以先看RPCcurl http://127.0.0.1:9944 -H Content-Type: application/json -d {jsonrpc:2.0,method:chain_getHeader,params:[],id:1}如果中繼鏈返回正常的head信息但平行鏈節(jié)點(diǎn)返回的head始終停留在一個高度那說明平行鏈出塊后沒有把區(qū)塊頭廣播給中繼鏈。重點(diǎn)檢查平行鏈啟動命令中--后面的中繼鏈規(guī)格文件是否使用了--chain指定了正確的中繼鏈。如果平行鏈并不知道自己連接的是哪條中繼鏈它無法正確上傳塊頭。另外如果用了多個--tmp參數(shù)容易造成平行鏈和中繼鏈的數(shù)據(jù)目錄混亂出現(xiàn)奇怪的連接問題。建議每個節(jié)點(diǎn)都顯式指定數(shù)據(jù)目錄--base-path /tmp/parachain-alice中繼鏈節(jié)點(diǎn)同樣指定--base-path /tmp/relay-alice避免多個進(jìn)程共用一個臨時目錄報沖突。7.3 同步卡住或者大量“Import failed”同步卡住通常表現(xiàn)為區(qū)塊高度停滯或日志刷屏。優(yōu)先看是否遇到“bad justification”或“dispute”。這往往是因?yàn)槠叫墟満椭欣^鏈的runtime版本不匹配。舉個具體的例子中繼鏈升級了新版本而平行鏈的驗(yàn)證人代碼wasm還是老版本導(dǎo)致驗(yàn)證人校驗(yàn)不一致。解決方法是重新生成平行鏈的wasm并更新到中繼鏈注冊時直接使用新的wasm而不是沿用舊文件。注意平行鏈的wasm文件大小是否合理如果生成出來很小幾百字節(jié)很可能沒有正確導(dǎo)出wasm需要重新查編譯路徑。7.4 日志級別調(diào)整排查問題時默認(rèn)日志不夠詳細(xì)可以把日志級別調(diào)高RUST_LOGparachain_templatedebug,pallet_collator_selectiondebug,auradebug,consensusdebug ./target/release/parachain-template-node ...但這些模塊名在不同版本里有細(xì)微差異建議先執(zhí)行一次RUST_LOGdebug看輸出再針對性縮小范圍。日志調(diào)優(yōu)能省下大量猜測時間這條經(jīng)驗(yàn)真的重要。8. 模板的二開經(jīng)驗(yàn)分享走到這里你已經(jīng)擁有了一條能出塊的平行鏈無論是連本地中繼鏈還是Rococo都能跑通。下面是我在二開過程中的一點(diǎn)體會。模板默認(rèn)帶的業(yè)務(wù)非常少只有余額、權(quán)限、資產(chǎn)、示例pallet這些基礎(chǔ)功能。真正做應(yīng)用時你會想往里加更多模塊比如NFT、DeFi、游戲道具等。這時候建議維護(hù)兩個分支一個upstream分支只跟蹤官方SDK的更新另一個develop分支存放自己的業(yè)務(wù)代碼。每次官方更新了bug修復(fù)或新版本把upstream合并到develop解決完沖突再繼續(xù)開發(fā)。別在模板主分支直接寫業(yè)務(wù)否則后續(xù)升級依賴時會很痛苦。依賴升級的時間點(diǎn)也值得講究。不要一看到有新版本就立刻升而是要認(rèn)真看changelog。如果只是修復(fù)了某個pallet的bug或優(yōu)化了性能可以先不升如果涉及安全補(bǔ)丁或新的共識機(jī)制比如異步支持、新的彈性擴(kuò)容那就值得花時間升。實(shí)測中最穩(wěn)妥的方式是每三四個月統(tǒng)一升一次每次留出1到2天的兼容性調(diào)試時間。最后再分享一個小技巧。如果你打算長期做Polkadot SDK開發(fā)本地建議預(yù)先構(gòu)建一份編譯緩存就是第一次完整編譯后不要輕易清掉target目錄也不要頻繁切換nightly版本。Rust的增量編譯在這里效果雖然一般但依賴緩存總比重頭拉取強(qiáng)太多。每次切版本或清target少則半小時多則一整天這筆時間成本實(shí)在不劃算。整個過程走完差不多就能理解平行鏈在Polkadot生態(tài)里的定位了。它和中繼鏈的關(guān)系就像一臺臺業(yè)務(wù)服務(wù)器接入了一個統(tǒng)一的共享共識網(wǎng)絡(luò)。模板給了你骨架剩下的血肉需要你自己去長。編譯、連接、注冊、二開每一步都有坑但每跨過一個坑你對這套系統(tǒng)的理解就深一層。遇到問題時多留心排查路徑的先后順序大多數(shù)問題其實(shí)都能靠日志定位到根因。