简介长安链从零到一部署教程以PDF形式整理面向区块链开发与运维人员系统解决长安链源码部署全流程中的环境搭建、单机/多机组网、智能合约开发与排错问题。内容源自直播回顾从环境依赖git、golang、docker、GLIBC_2.18讲起依次覆盖证书生成、单机部署启动、合约编译与部署调用并单独梳理常见编译与运行报错及多机部署对照表适合需要快速上手长安链的初学者按步骤跟做。教程详述了区块、区块链、智能合约、交易哈希等核心概念帮助读者建立基础认知后再动手实践部署环节配有sudo权限配置、修改软件源、编译证书管理工具等操作细节遇到missing go.sum entry、GLIBC_2.18缺失、权限不足等问题也可直接对应排查。资源为单个PDF文件压缩包大小约691KB篇幅紧凑、目录清晰便于随时查阅。已有276人学习下载实用性获得一定认可。对于希望低成本掌握国产联盟链部署细节的用户这份手册能有效节约踩坑时间直接对照操作即可完成基础链搭建与合约上链。1. 长安链从零到一部署先看懂这张 PDF 真正解决什么问题刚接触联盟链的人第一次部署长安链时最容易把大量时间浪费在环境依赖上真正跑起来之后才发现合约上链又是另一个坎。这份“长安链从零到一部署”材料正好把这两件事串成了完整步骤先装好 git、golang、docker 与 GLIBC_2.18然后编译证书管理工具生成四组织证书再用 prepare.sh 一次性产出配置编译链后启动最后通过 docker 镜像编译 tinygo 合约并用 cmc 命令行把合约部署上链。适合想在一台机器上快速拉起一条本地链的开发者也适合已经部署过其他联盟链、想对比工具链差异的人。它最值得看的地方其实是最后几章启动后到底看什么日志才能确认出块成功哪些错误能直接通过命令和参数解决。2. 环境与概念四项依赖为什么缺一不可端口和 RuntimeType 怎么选长安链部署前要过的第一道关是环境。材料开头虽然只给了一个很小的依赖表但每一项都有具体用途git 负责拉源码docker 负责提供合约编译镜像golang 负责编译链程序和各类命令行工具GLIBC_2.18 是 wasmer 虚拟机运行合约时的底层库。由于我长期和底层环境打交道这里有个明显的感受越早把依赖版本和来源弄清楚后面翻车的概率越低。环境安装顺序也不只是“凑齐工具”它直接决定 prepare.sh、build_release.sh 和合约编译三步能不能顺利走过去。2.1 依赖清单背后的设计版本检查要走在安装前面依赖安装的常见做法是分软件逐项装装完统一做版本检查。以 CentOS 为例sudo 权限确认后先验证系统本身可用# 查看系统版本与当前用户 cat /etc/redhat-release whoami # 如果用户没有 sudo 权限则用 root 执行把 your_user 替换成实际账号 sudo usermod -G admin -a your_user这里的逻辑是先把增量权限拿到手后续所有安装命令才不需要反复切换用户。接着改 yum 源建议在操作之前备份原始源文件这是可回滚的后悔药。安装 git 后立刻检查版本git 版本过低会影响后续仓库 submodule 的拉取行为。cd /etc/yum.repos.d/ sudo mv CentOS-Base.repo CentOS-Base.repo.bak sudo curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo sudo yum clean all sudo yum makecache sudo yum install git -y git --version注意这里做的只是更换系统软件源涉及网络下载的地址建议确认当前网络可访问。go 的安装版本材料中使用了 1.16.3实际部署时建议不低于 1.15否则部分模块在编译时会出现函数签名不匹配的问题。安装完 go 后配置环境变量sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.16.3.linux-amd64.tar.gz sudo vim /etc/profile # 在文件末尾追加下面三行 export PATH$PATH:/usr/local/go/bin export GOROOT/usr/local/go export GOPATH/home/your_user/go source /etc/profile go version这里有个常见误操作只 export PATH 却忘了 GOROOT导致 go 命令能执行但编译链时找不到标准库。注册 GOROOT 的作用是让 go 工具链精确定位安装目录而 GOPATH 决定第三方依赖源码的存放位置。为了让依赖下载更顺畅后面 go mod download 步骤可能会依赖模块镜像源这一步属于环境加速配置不等于任何网络通道工具。docker 的安装则相对独立主要服务是提供合约编译环境要注意部署链本身不依赖 docker依赖 docker 的只是智能合约编译镜像。2.2 端口“双份消费”net 端口和 rpc 端口各管什么第一次跑 prepare.sh 时很容易被 11300 和 12300 两组端口搞混。长安链节点监听两类端口一类是节点间的 libp2p 通信端口配置在 net 段的 listen_addr另一类是给 SDK、cmc 等客户端用的 gRPC 端口对应 rpc 段。单机部署时 4 个节点各占两个端口prepare.sh 传参的起始端口会按节点编号递增。比如 11300 为起始值时4 个节点实际使用 11301 到 1130412300 为起始值时4 个节点实际使用 12301 到 12304。为什么要分两套因为节点间共识、交易广播走内网或专线而客户端访问需要暴露到业务侧。多机部署时rpc 端口通常要对业务方开放net 端口保持节点间可达即可。初次部署时如果发现某个节点状态一直异常先用netstat -lptn | grep 1130\|1230看端口是否都被监听再确认防火墙是否只放行了 rpc 端口而阻断了 net 端口。2.3 合约 RuntimeType同一个 wasm 文件还要声明“国籍”合约开发容易忽略 runtimeType 参数。长安链的智能合约编译成 wasm 后节点需要知道它是由哪种语言编译的才能用对应的虚拟机引擎执行。材料里给了一张清晰的对照表我按实际使用频率重新整理如下RuntimeType数值适用语言编译命令GASM4tinygotinygo build -no-debug -opts -o main.wasm -target wasmWASMER2rustwasm-pack buildWXVM3cemmake makeEVM5solidity通过 solc 编译表格反映了一个关键点runtimeType 是节点选择执行引擎的依据不是合约本身的自描述信息。创建合约时如果填错比如用 tinygo 编译却填了 2rust交易发送后节点会报 “runtime type error, expect rust:[2], but got 4”。后面章节会专门讲这个排错过程这里先记住结论先确认合约源码语言再决定 runtimeType 数值而不是看到 wasm 就默认填 4。3. 单机部署从拉源码到启动四步命令链的完整拆解单机部署是熟悉长安链工具链最快的方式。材料给出的路径是固定的拉源码、编译证书工具、生成证书配置、编译链、启动。这几步看似是连续命令实际每步都有前置条件。比如证书工具编译失败问题大概率出在 go 依赖下载prepare.sh 生成目录后突然报错则要回头检查 clone 时有没有拉 submodule。理解了这一步后面多机部署只是把启动方式从 cluster_quick_start 换成 restart.sh。3.1 获取源码--recursive 是第一条后悔药cd ~/workspace git clone --recursive https://git.chainmaker.org.cn/chainmaker/chainmaker-go.git git clone --recursive https://git.chainmaker.org.cn/chainmaker/chainmaker-cryptogen.git长安链仓库用 submodule 管理了多个公共模块比如 common、utils 等。加 --recursive 的作用是克隆时同时拉取所有子模块不加则子模块目录是空的。如果已经用不带参数的方式克隆完了补救做法是git submodule init git submodule update我习惯在拉完代码后立刻检查一下子模块是否完整ls -la chainmaker-go/common/go.mod ls -la chainmaker-go/tools/cmc/go.mod这两个文件存在才说明子模块拉对了。后面如果编译时报 “go.mod no such file or directory”排查方向直接就是这里。3.2 编译证书管理工具make 之外还有一个软链接长安链的证书体系由 chainmaker-cryptogen 生成它属于组织管理工具编译目标是得到可执行文件。常见做法是先进 cryptogen 目录执行 make再把生成的可执行文件通过软链接放到 chainmaker-go/tools 下cd chainmaker-cryptogen make cd ../chainmaker-go/tools ln -s ../../chainmaker-cryptogen/ . cd ../scripts这里解释下为什么用软链接而不是拷贝prepare.sh 在生成配置时是通过 tools 目录定位 cryptogen 的软链接可以保证 cryptogen 后续更新后无需重新拷贝。如果 make 执行后长时间没有反应优先检查 go 环境变量和网络状态。make 过程会下载部分 Go 依赖下载源不可用就会卡住。材料里那句“make 或 go build 没有反应可以检查下网络”指的就是这种情况。3.3 prepare.sh 参数里的秘密组织数、共识类型、起始端口./prepare.sh 4 1 11300 12300这是单机部署的核心命令四个参数的顺序分别是组织数、共识类型、net 端口起始值、rpc 端口起始值。以 4 1 11300 12300 为例它生成 4 个组织每个组织 1 个共识节点共识引擎为 TBFT节点间通信从 11300 递增分配端口对外 gRPC 服务从 12300 递增分配端口。生成完成后证书、创世区块、节点配置都会落在 build 目录下。tree -L 2 ../build/ tree -L 3 ../build/这个命令会产生不少输出重点看 release 目录是否出现 4 个组织的文件夹名称类似 wx-org1.chainmaker.org。如果只看到部分组织说明 prepare.sh 中途中断过。共识类型直接决定网络能否出块这里补一张参数速查表参数值共识类型适用场景0SOLO单节点开发调试只有一个出块节点1TBFT多节点生产测试默认推荐4RAFT对确定性要求高的小规模网络材料里 prepare.sh 默认是 TBFT这个选择很合理单机部署跑 4 节点 TBFT 可以顺便观察 leader 切换和广播机制。SOLO 只适合验证单节点流程不适合做后续多机扩展。3.4 编译、封包与启动四行命令连起来的时间线./build_release.sh tree ../build/release/ ./cluster_quick_start.sh normalbuild_release.sh 做的事情是把链源码编译成可执行文件并连同配置、证书打成安装包。脚本执行时间取决于机器 CPU 和 Go 依赖缓存首次执行通常在十几分钟量级。编译完成后release 目录下每个组织都有一份完整的安装包其中 bin 目录里有 chainmaker 可执行文件log 目录用于存放运行日志config 目录保存节点配置。启动命令 cluster_quick_start.sh normal 会逐节点解压安装包并调用 restart.sh。这里有个注意点如果第一次启动后修改了配置文件再执行启动脚本配置会被安装包重新覆盖。合理的做法是第一次启动成功后把 build 下解压出来的运行目录备份到独立位置后续改配置基于备份目录操作。启动结果检查是部署是否成功的第一反馈ps -ef | grep chainmaker | grep -v grep netstat -lptn | grep 1230\|1130看到多个 chainmaker 进程同时存在且 11301 到 11304、12301 到 12304 都在监听说明进程层面已经就绪。此时还不能急着认为组网成功下一步要看日志里的出块标记这个细节放在第 6 章专门讲。4. 合约开发与上链从 wasm 编译到 cmc 调用的完整闭环链跑起来只是开始业务要跑在合约上。长安链合约开发流程分为三步拉取编译环境、编译出 wasm 文件、通过 cmc 或 SDK 把合约创建到链上。材料里用的是 tinygo 模板部署命令则统一走 cmc 命令行客户端。本章是对这三步的展开重点说明每一步的产物和验证方式。4.1 编译合约的 docker 镜像挂载目录后容器内出产物合约编译环境用 docker 隔离是最省事的方式不会把 Go、Rust、C 工具链都装在宿主机上。材料给的做法是拉取一个专用编译镜像并运行docker pull huzhenyuan/chainmaker-go-contract:1.0.0 docker run -d \ --name chainmaker-go-contract \ -v /home/your_user/workspace/chainmaker-go-contract/:/home \ huzhenyuan/chainmaker-go-contract:1.0.0 \ bash -c while true; do echo hello chainmaker; sleep 5; done参数里 -v 的作用是把宿主机的合约工程目录挂载到容器 /home容器内编译生成的主.wasm 会直接写到宿主机目录。后面那段 bash -c 的目的是让容器保持运行状态而不是执行完就退出这样随时可以 docker exec 进入容器操作。如果觉得长期挂一个容器占资源也可以改用 docker run --rm 一次性执行编译命令但频繁进入容器调试时保持运行更方便。进入容器后的编译步骤docker exec -it chainmaker-go-contract bash cd /home tar xvf /data/contract_go_template.tar.gz cd contract_tinygo sh build.sh编译产物是 /home/contract_go/main.wasm这个文件就是最终要部署到链上的字节码。build.sh 内部对 tinygo 开了 -no-debug 和 -opts 参数前者去掉调试符号减小体积后者做体积优化。合约字节码越小编译和上链传输越快这是长安链常规推荐。4.2 编译 cmc 命令行客户端复制配置的坑合约部署需要 cmc 工具它是长安链 SDK 的命令行封装。材料建议用源码编译方式获得因为官方 release 里不一定包含所有测试配置cd ~/workspace git clone --recurse-submodules https://git.chainmaker.org.cn/chainmaker/chainmaker-go.git cd chainmaker-go/tools/cmc go mod download go build编译完成后当前目录会多出 cmc 二进制。使用前要准备 sdk 配置文件与证书文件常见做法是从 SDK 目录复制 testdata 到 cmc 运行目录cp -r ../sdk/testdata ./ cd testdata mv crypto-config crypto-config-bak cp -r ../../../build/crypto-config/ ./这一步的逻辑是sdk 自带的 testdata 里只有默认生成的测试证书必须替换成本次部署链的正式证书否则 cmc 连接节点时 TLS 认证会失败。mv 操作相当于留了后悔药避免替换后想回退还得重新拉 SDK。这里特别容易犯的错是直接改 sdk_config.yml 里的节点地址却忘了连证书一起换。4.3 创建合约与调用合约方法参数怎么改cmc 创建合约的命令很长但结构很固定基本就是管理证书、客户端证书、合约字节码和运行参数四组内容。完整命令如下./cmc client contract user create \ --admin-key-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.tls.key \ --admin-crt-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.tls.crt \ --client-crt-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.crt \ --client-key-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.key \ --org-idwx-org1.chainmaker.org \ --byte-code-path/home/your_user/workspace/chainmaker-go-contract/contract_tinygo/main.wasm \ --contract-namefact_001 \ --runtime-typeGASM \ --sdk-conf-path./testdata/sdk_config.yml \ --version1.0 \ --sync-resulttrue \ --params{}参数说明分三块看第一块是身份证书--admin-* 是管理员证书--client-* 是客户端证书它们都属于 wx-org1.chainmaker.org 组织第二块是合约本体--runtime-typeGASM 与 tinygo 对应--byte-code-path 指向第 4.1 节生成的 main.wasm第三块是交互方式--sync-resulttrue 会等待交易执行完成并返回结果而不只是收到交易。如果部署环境有多个组织创建合约需要用对应组织的管理员证书。合约部署成功后调用合约方法用的是 invoke./cmc client contract user invoke \ --contract-namefact_001 \ --methodsave \ --org-idwx-org1.chainmaker.org \ --client-crt-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.crt \ --client-key-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.key \ --sdk-conf-path./testdata/sdk_config.yml \ --sync-resulttrue \ --params{\time\:\123\,\file_hash\:\2352B3523FB3F2B2FB2E254AA5B6\,\file_name\:\name.png\}这段命令里 --methodsave 是合约定义的公开方法--params 是一段 JSON 字符串注意内部双引号要加转义。查询合约则简单得多./cmc client contract user get \ --contract-namefact_001 \ --methodsave \ --sdk-conf-path./testdata/sdk_config.yml \ --org-idwx-org1.chainmaker.org \ --client-crt-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.crt \ --client-key-file-paths./testdata/crypto-config/wx-org1.chainmaker.org/user/client1/client1.tls.key \ --params{\time\:\123\,\file_hash\:\2352B3523FB3F2B2FB2E254AA5B6\,\file_name\:\name.png\}get 类型交易是查询类操作天然同步返回结果不需要等共识。4.4 同步返回与异步执行为什么 SDK 说 ok 不代表成功这是新手最常误解的点。长安链的交易执行是异步的SDK 返回消息 ok 只代表节点接收了交易并进入交易池并不代表合约已经执行成功。材料专门把“返回成功但实际执行失败”列为运行时错误的典型案例。如果执行合约时 runtimeType 选错或合约内部 panic交易最终会落块但执行结果是失败。要拿到真实执行结果在 cmc 里就是 --sync-resulttrueSDK 层面则选择同步发送模式。同步发送会自动等待交易上链并解析执行结果。查询类交易天然走同步路径也是排查异步问题的好工具。如果已经用异步方式发出去了可以用返回的 txId 到链上查询交易详情材料建议通过节点日志和交易哈希确认最终状态。5. 避坑指南五个导致部署翻车的细节及解决顺序长安链部署失败集中在编译期、启动期和运行期三个阶段。材料把常见问题整理得很实用但问题之间是有先后顺序的环境没干净之前后面启动大概率连环报错。以下五条是实际部署中最高频的翻车点每条按现象、原因、解决的顺序写方便直接对照。5.1 启动报错 GLIBC_2.18 not found现象执行 chainmaker 可执行文件时报/lib64/libc.so.6: version GLIBC_2.18 not found该错误由 wasmer 运行库触发。原因节点使用的 wasmer 虚拟机需要 GLIBC 2.18 及以上版本而 CentOS 7 默认自带的 GLIBC 版本低于 2.18。这颗依赖是系统级的不是普通应用库。材料里提醒得很明确GLIBC 是 Linux 系统最底层 API安装失败可能导致系统不可用需要谨慎操作。解决进入 chainmaker-go/scripts/3rd 目录执行sh install.sh该脚本会在当前系统上安装或升级 GLIBC 到 2.18。执行前先确认为 CentOS 7.6 相近版本并用strings /lib64/libc.so.6 | grep ^GLIBC_查看当前版本留底。升级过程不要中断也不要同时操作其他系统级包否则可能连基础命令都无法运行。另一个思路是更换操作系统版本在测试环境直接使用自带 GLIBC 2.18 以上的系统省去这步风险操作。5.2 编译时报 missing go.sum entry现象执行 ./build_release.sh 时提示missing go.sum entry; to add it并且会指出具体缺失的模块。原因go mod download 没有完整拉取依赖常见于网络中断、依赖源不稳定或源码变更后 go.sum 未同步。解决分别进入 chainmaker-go/main、chainmaker-go/common、chainmaker-go/tools/cmc 三个目录执行go mod download补齐对应模块的校验记录后再重新编译。执行时可以观察目录下 go.sum 文件的更新时间确认新增记录已写入。如果下载反复失败检查 Go 模块镜像源配置是否生效并确认磁盘空间充足。5.3 configure 阶段报 no acceptable C compiler found现象安装 GLIBC_2.18 或编译含 CGO 组件时报configure: error: no acceptable C compiler found in $PATH。原因系统没有安装 gcc或 gcc 不在当前用户的 PATH 下。很多入门环境是精简安装默认不包含编译工具链。解决sudo yum install -y gcc gcc --version装完 gcc 后Common 目录里依赖 cgo 的组件才能往下一步走。这个错误本身不难修但要放在其他编译问题之前处理因为后续所有涉及 CGO 的编译都会先经过这里。5.4 restart.sh 权限不足现象执行 cluster_quick_start.sh 启动时报./restart.sh: Permission denied但脚本本身存在。原因Git 仓库中部分脚本默认没有可执行位解压安装包后也没有补上执行权限携带到目标机器后无法直接以 ./ 方式运行。解决对两个位置分别补权限。一是源码 scripts 目录二是 release 安装包内各节点的 bin 目录cd chainmaker-go/scripts/bin chmod x *.sh cd chainmaker-go/build/release/chainmaker-V1.0.0-wx-org1.chainmaker.org/bin chmod x *.sh如果是多机部署每个节点服务器的安装包里都要重复这一步。补完权限后重新启动即可。5.5 runtime type errorexpect rust[2] but got 4现象合约创建命令发送成功但交易执行后链上返回失败日志里有contract invoke failed, runtime type error, expect rust:[2], but got 4。原因创建合约时填写了运行时类型实际确认为其他语言。日志中 expect rust:[2] 表示节点期望的是 rust 对应数值 2实际收到 tinygo 对应的 4说明 cmc 命令里 runtime-type 参数与合约源码语言不一致。解决确认合约是由哪些语言编译的。若使用 tinygo则创建命令填--runtime-typeGASM使用 rust 填 WASMER使用 c 填 WXVM。数值与语言的对应关系是固定的建议在组装创建合约命令前先列一个语言与 runtime 数值的对应表别凭记忆填。5.6 SDK 返回 ok 但交易实际执行失败现象SDK 提交安装或调用合约后返回 message 为 ok但根据 txId 查询到交易执行失败。原因SDK 返回的 ok 仅表示交易被链节点接收交易是否执行成功取决于后续共识与虚拟机执行结果。查询类交易是同步的写类型交易默认是异步确认所以要先同步等待执行结果。解决在 cmc 命令中设置 --sync-resulttrue在 SDK 中启用同步发送模式阻塞等待交易执行结果返回。若交易已发出要根据 txId 查询交易内容确认失败原因后再处理。这个排查路径也是我个人的固定习惯每次提交写类型交易后强制走一遍同步发送或主动查询避免被 ok 误导。6. 通过日志验证出块标记与组网成功怎么看很多人在节点进程都活着、端口都在监听时认为部署已经成功。进程存在只能说明节点没崩溃但链是否出块、节点间是否完成组网必须看日志才能确定。长安链日志里有两条关键标记一条是出块标记“put block”另一条是组网成功标记“all necessary peers connected”。6.1 出块标记长什么样cd chainmaker-go/build/release/chainmaker-V1.0.0-wx-org1.chainmaker.org/log cat system.log | grep ERROR\|put block正常日志形如[INFO] [Storage] chain1 store/blockstore_impl.go:241 chain[chain1]: put block[12] (txs:1 bytes:8078), time used (mashal:0, log:2, commit:5, total:7)这个标记中 block[12] 是高度txs:1 表示该区块包含一笔交易bytes:8078 是区块大小后面的时间字段是序列化、日志落盘、状态提交的耗时。只要高度在稳定递增就说明共识和存储链路是通的。调试时清零重启也常见重点看高度是否持续增长而不是追求从 0 开始。6.2 组网成功的关键标记SOLO 共识下看到start blockchain[chain1] success即可认为基本链路可用。TBFT 等多共识类型网络则要等所有节点互相发现cat system.log | grep init blockchain\|all necessary peers connected出现all necessary peers connected说明当前节点与配置中其他组织的共识节点都建立了长连接交易可以广播到全网。节点修复或重启后要以当前时间的日志为准不要只搜历史匹配。每个节点都要确认一次不能只查一个节点的日志就认为全网组网成功。6.3 验证清单固化成一个习惯单机部署或多机部署完成后我还有一组固定检查动作看进程数、看端口监听、看出块高度、看组网连接。这四条命令执行顺序固定经验证通过后才允许进入合约开发或业务测试阶段。从那以后只要是部署长安链我都会强制走完这四步再继续后续操作少一个标记就当没部署成功希望帮到你。本文还有配套的精品资源点击获取