长安链从零到一部署：证书、配置与节点启动全攻略-育师

简介：这是一份面向区块链开发与运维人员的长安链部署实战手册，定位于帮助读者从零开始完成长安链区块链系统的环境搭建与源码部署。内容围绕直播回顾“如何通过长安链快速部署区块链系统”展开，覆盖Git、Golang、Docker、GLIBC_2.18等环境依赖的安装配置，单机部署与多机部署的流程对照，以及智能合约的编译、部署与调用方法，并针对编译期、启动期和运行期常见报错给出具体排查思路。

资源为单份PDF文档，体积约691KB，内容结构清晰，从概念梳理（区块、区块链、智能合约、交易等术语说明）到操作命令再到问题解决均配有详细步骤，适合初次接触chainmaker的开发者按图索骥逐步操作，也适合已有基础的技术人员作为部署参考速查。

目前已有276人学习该资源，其沉淀的部署经验与排错要点对节省自建环境时的试错成本具有直接帮助。

1. 长安链从零到一部署：这条链路到底卡在哪

很多初次接触长安链的人，手里拿着部署文档，却在“证书生成”和“配置生成”这两步反复折腾。第一次搭长安链时，我在某个节点反复重启上困了两天：端口给了、证书也建了，节点就是起不来。后来才意识到，问题不在某个单一环节，而是整条链的启动是有顺序、有依赖的——证书是身份，配置是骨架，节点启动只是最后一步。把顺序理清楚，一条四节点的测试链才能在半小时内跑起来。

这篇笔记围绕“从零到一部署长安链”的最小可行链路展开：从环境准备、证书生成、配置生成、节点启动到链上验证，覆盖每一步的命令、参数和最容易踩的坑。适合要在自己服务器上搭一条可用联盟链的开发者，也适合给团队做部署培训前、想先自己完整跑通一遍的人。

这个方案需要什么：至少一台4核8G的Linux服务器，能访问软件源和官方下载服务器的网络环境，以及一个不排斥命令行的操作习惯。下面直接开始。

2. 部署前先想清楚：长安链的最小闭环是一台服务器上跑四节点

2.1 先理解“一条链”在长安链里由什么组成

长安链的部署包看起来工具很多，但拆开看，整条链的启动材料只有两块：身份证书和链配置。身份证书解决“谁在参与这条链”的问题，链配置解决“链怎么出块、节点怎么互相找”的问题。这两块材料由两个独立的小工具分别生成，再合并到节点启动目录里。

为什么强调顺序？因为配置生成时要读证书路径，证书还没生成就去跑配置命令，必然报错；反过来，证书生成不依赖配置。所以顺序一定是先证书、后配置、再启动。第一次部署时，我想把两个步骤合并到一条命令里省事，结果反复出错，后来规规矩矩拆开跑，再没出过问题。

部署的最小闭环，建议直接用官方 release 包里的示例组织结构。常见的最小集群配置是“三组织四节点”：组织 A 出一个节点、组织 B 出一个节点、组织 C 出两个节点，四个节点共同组成一个共识集群。为什么不是单节点？单节点跑不出“链”的行为验证，共识、同步、多节点日志这些关键效果都无法确认；在测试环境配五节点、七节点，又只是徒增部署成本，对验证流程没有额外收益。等这条四节点链跑通，再按同样的步骤往上加节点，心智负担会小很多。

用到具体目录时，我习惯把四个角色分开：tools 放证书和配置生成工具，chain-maker 放四节点程序，cmc 放命令行客户端，log 汇总节点日志。这个划分不是唯一的，但能避免后面“工具目录和节点目录混在一起、跑错命令”的低级问题。

2.2 部署前的服务器准备与目录规划

操作系统建议用 Ubuntu 20.04 或 CentOS 7.9，内存不低于 8G。如果只有 4G，四节点全开不是不能跑，但一旦开始部署合约，内存很容易被打满，OOM 的排查比部署本身还浪费时间。磁盘 30G 以上足够，节点日志默认全量保留，跑上几天后单节点日志到几 G 很正常。

先花两分钟检查环境，不要等跑到编译或脚本执行时才报缺工具：

# 确认系统、核数、内存、磁盘 cat /etc/os-release nproc && free -h && df -h /data # 确认 git/make/gcc/go 是否齐全 git --version && make --version | head -1 gcc --version | head -1 && go version

版本上没有太多讲究，通用发行版自带的版本都能跑通部署流程。如果机器上没有 /data 目录，就提前 mkdir 并确认写权限，后面所有目录都挂在 /data 下面，路径短，出错了也好查。

然后规划目录结构。我把四种产物分开，是沿用至今的目录习惯：

mkdir -p /data/chainmaker/{tools,chain-maker,cmc,log} tar -xzf chainmaker-*.tar.gz -C /data/chainmaker/tools

注意 release 包解压后通常会多一层目录，我这里给出的命令是把包直接解到 tools 下，解完先看一眼 tools 目录树的实际层级，确认 bin 目录的位置。别用绝对路径去追目录，后面每条命令都会因为目录层级不对而多绕一圈。

端口规划同样要在部署前定好。长安链每个节点至少要两个端口：一个 P2P 端口供节点间共识通信，一个 RPC 端口供 cmc 和管理台访问。示例配置里四个节点的起始端口分别是 11301 和 12301，后面的节点依次递增。下面是这次部署实际使用的端口规划表：

用途	端口（节点1-4）	说明
P2P TCP	11301、11302、11303、11304	节点间通信与共识，必须互通
RPC	12301、12302、12303、12304	客户端/管理台访问节点
监控指标	14321（可选）	不做监控可不开

P2P 端口不通是最隐蔽的问题：节点进程都活着，但互相找不到对方，区块高度永远不动。先在防火墙层面把上面的端口按节点放行，等跑到第 5 章排查避坑时，你会感谢这一步省下的时间。

3. 用 cryptogen 和 config 生成证书与配置：最小命令和参数含义

3.1 证书生成：一份 crypto_config.yml 决定整条链的身份

长安链的证书生成工具是 chainmaker-cryptogen，你给它一份描述组织、节点、用户角色的 YAML，它按模板生成一整棵证书树。配置文件的核心是 organizations 字段：每个组织的 id、名称、节点数量、用户数量、证书签名算法。算法上开发测试用 ECDSA 足够，如果后面要适配国密环境，就把签名算法换成 SM2，注意后续 config 生成和节点编译都要对应换成国密版本，这个前后不一致会直接导致节点握手失败。

生成证书的命令是：

cd /data/chainmaker/tools ./bin/chainmaker-cryptogen generate \ --config ./config/crypto_config.yml \ --output ./build/crypto-config

逻辑说明：generate 按配置文件的描述，在 output 路径下创建组织目录、节点证书和用户证书。执行成功后，日志里每一行 “Create ... ok” 对应一套证书，看到这些输出基本可以确认这一步没跑偏。

参数说明：--config 指定组织与节点的描述文件；--output 指定证书输出目录。我一般固定把 output 指向 tools 下的 build 目录，因为后续 config 工具默认会从同一个 build 目录里读证书，这样能少配置一层相对路径，也降低“路径写错”的概率。

这里有个值得注意的细节：如果 output 目录已存在同名内容，工具不会自动清空。重复生成前先手动清理，否则两套证书可能混在同一个目录里，后续配置生成时取到旧文件，启动阶段会报证书不匹配。

注意：第一次做部署验证时，直接用 release 包自带的示例 crypto_config.yml 就能跑通，不用急着改成自己的组织和域名。先让链路转起来，再回来改组织名、链 ID，这是最快的一条路。

3.2 配置生成：把证书路径焊接到链配置里

证书准备好之后，用 chainmaker-config 工具把证书、共识节点、链参数合并成节点实际启动时读取的配置目录。这个阶段有一个核心配置文件：config_tpl.yml，它相当于整条链的“总体设计图”。

配置生成命令：

cd /data/chainmaker/tools ./bin/chainmaker-config config generate \ --config ./config/config_tpl.yml

逻辑说明：config generate 读取模板文件，再用 build/crypto-config 里的证书路径做替换，最终在 build 目录下生成每个节点各自的配置子目录。执行完后，build 目录里会按节点 ID 出现多套配置，每套里都有 chain.yml、bc.yml 以及对应的证书副本。

参数说明：--config 指向模板文件，这个模板里需要重点确认三处——chain_id 是这条链的唯一标识，后面 cmc 连接时要用同一个 ID；consensus 字段里的节点列表必须和证书生成时的组织节点对应上；每个组织名的证书路径要指向 build/crypto-config 下实际存在的目录。

我一般会在跑完 config generate 后立刻做一次检查，确认链 ID 和共识配置写进去了：

# 检查两处必改字段：chain_id 和 consensus 类型 grep -n "chain_id\|consensus" ./build/config/*/chain.yml | head -20

如果输出里的 chain_id 和你预期一致，再进入启动环节；不一致就先回去改 config_tpl.yml，重新 generate。这里不要手动去改 build 目录下生成的 chain.yml，因为格式是工具按模板生成的，手工改很容易在下一次 generate 时被覆盖，还可能引入语法错误。

3.3 生成后的目录结构：先看清再启动

配置生成完，build 目录的结构直接决定后面 start.sh 能不能找到节点程序。先花十几秒看一下目录树：

tree -L 2 /data/chainmaker/tools/build

常见的目录结构是 build/{节点ID}/{组织名}/ 下面挂证书和配置文件，再往上是各节点的 start.sh 要遍历的粒度。如果你的 build 目录层级和官方示例不一致，后面启动脚本大概率会报路径不存在。

这一步还要确认一件事：build 目录里是否已经包含每个组织的管理员证书。cmc 部署合约时需要用到管理员身份，很多人在第 4 章验证时才发现 build 下没有 admin 相关证书，只能回头重新去看 crypto_config.yml 里是不是漏配了 user 角色。

到这里，证书和配置两大块就绪，下一步就可以真正把节点拉起来了。

4. 启动四节点集群：start.sh 拉起进程与首次区块验证

4.1 把 build 拷贝到运行目录，并用 start.sh 拉起四节点

工具生成的 build 目录在 tools 下，而节点运行目录是独立的 chain-maker。这一步是“部署”里最容易出现路径断层的环节：有人直接拿着 build 目录里的配置去启动，却找不到节点二进制，或者反过来。

常见的做法是把 build 整体拷贝到运行目录，再执行启动脚本：

cp -r /data/chainmaker/tools/build /data/chainmaker/chain-maker/ cd /data/chainmaker/chain-maker ./start.sh sleep 5 ps -ef | grep chainmaker | grep -v grep

逻辑说明：start.sh 会遍历 build 下的各节点目录，逐节点调用链程序启动后台进程，并把日志写到对应节点目录下的 log/chainmaker.log。执行后先看进程数，理想情况是 grep 出 4 个 chainmaker 进程。

参数说明：这里没有额外参数，但注意两点。第一次启动时如果之前已经手动跑过节点，先执行 ./stop.sh 清掉旧进程，否则会出现双份进程抢端口。sleep 5 是为了等节点完成初始化，太早 ps 可能只看到部分进程。

启动后如果进程数不对，先别急着重启，去对应节点目录的 log 里看一眼末尾的错误。常见错误我在第 5 章会展开，这里提一个通用原则：日志比人靠谱，多看几行日志再动手。

4.2 用 cmc 验证静态信息：链 ID、节点数与区块高度

节点全部拉起后，用 cmc 做验证。验证分两层：静态信息查得到，说明 RPC 通、链 ID 对；动态行为正常，说明共识和合约调用没问题。

先做静态查询：

cd /data/chainmaker/tools/cmc export LD_LIBRARY_PATH=./lib:/data/chainmaker/tools/lib ./cmc query chain-info \ --sdk-config ./sdk_config.yml

逻辑说明：cmc 通过 sdk_config.yml 里配置的 RPC 地址连接任意一个节点，查询链基础信息。输出里最关键的是 chain_id 和当前区块高度。刚启动时区块高度低是正常的，四节点需要先完成共识握手，等高度开始稳定增长，基本说明链在正常出块。

参数说明：--sdk-config 指向 cmc 使用的 SDK 配置文件。这个文件里要确认三个字段：节点地址、RPC 端口、chain_id，三者必须和 build 下 chain.yml 里的实际配置一致。

如果这里 TIMEOUT，大概率不是链路问题，而是 sdk_config.yml 里的端口或 chain_id 写错了。第 5 章会专门讲这个翻车现场。

4.3 部署存证合约做动态验证：从 create 到 invoke

静态信息正常只能说明节点进程在跑，真正判断“链可用”要动态走一遍合约部署和调用。存证合约是长安链官方示例里最常用的入门合约，逻辑简单，非常适合做链上读写验证。

部署合约的命令：

cd /data/chainmaker/tools/cmc # 部署存证合约 ./cmc client contract user create \ --contract-name=fact \ --byte-code-path=./fact.eca \ --admin-key=./admin_key \ --admin-crt=./admin_crt \ --sdk-config=./sdk_config.yml \ --sync=true

逻辑说明：user create 把合约字节码提交到链上，sync=true 表示等待交易上链后再返回。返回结果里有交易 ID 且没有报错，说明这个合约已经在链上生成，可以被调用。

参数说明：--byte-code-path 指向合约编译产物；--admin-key 和 --admin-crt 分别指管理员私钥和证书，这两个文件在 build 目录里，不要拿节点证书当管理员证书用，权限模型上两者角色不同。

部署完成后，再调用一次写接口：

# 调用存证接口 ./cmc client contract user invoke \ --contract-name=fact \ --method=save \ --params="{\"file_hash\":\"abc123\",\"file_name\":\"test.txt\"}" \ --sdk-config=./sdk_config.yml

逻辑说明：invoke 调用合约的 save 方法，写入 file_hash 和 file_name 两个字段。如果返回结果里交易 ID 存在、gas 没有报错，说明读写链路全部打通了。

到这里，一条四节点的长安链已经从零到一跑通了。接下来要做的不是收工，而是把最常见的坑整理清楚，因为真实环境里几乎没有人一次就能跑通。

5. 长安链部署避坑清单：5个翻车现场和对应的解

5.1 现象：四个节点都显示已启动，但区块高度一直是0

这是最让人头疼的问题：进程在，日志也在写，但链不出块。原因绝大多数出在 P2P 通信上——节点间没连上，共识组永远凑不齐。最常见的有两个：chain.yml 里的 seed 地址填成了 127.0.0.1；或者防火墙没放行 P2P 端口。

解决：先看各节点日志里有没有 “connection refused”，谁连不上谁就是地址或端口的问题。然后核对 chain.yml 里 seed 节点的地址，把所有节点之间的 IP 都改成内网实际 IP，而不是本机回环地址。改完配置后要重启全部节点，单点重启不会触发重新组网。最后用ss -lntp | grep 11301确认端口在监听。

5.2 现象：start.sh 显示 OK，ps 却找不到进程

脚本没报错，但进程就是没了。这种“秒退”基本都是资源或权限问题。最典型的有两个：机器内存不够，节点被内核 OOM Kill 掉；或者日志目录没有写权限，节点启动时写日志失败直接退出。

解决：先dmesg | tail -20看有没有 Out of memory 记录，如果有就加内存或减节点数。再检查运行目录属主，chown -R 当前用户 /data/chainmaker把权限归到部署账号。最后用ulimit -n 65535调高文件描述符上限，这个值太低会在网络连接数上来后引发更多怪问题。

5.3 现象：重新生成证书后，config generate 报“证书不存在”

改了组织名重新生成证书，回头跑 config generate 却提示找不到证书。这个翻车现场几乎都是大小写和目录路径不一致引起的。crypto_config.yml 里的组织 ID 写的 OrgA，但证书目录生成的是 orgA，或者 config_tpl.yml 里的路径还指向旧的 build 目录。

解决：先把两个配置里的组织 ID 逐项比对，统一用全小写。再确认 config_tpl.yml 里的证书根路径确实指向新生成的 build/crypto-config。如果之前清过 build 目录，config_tpl.yml 里写的相对路径基准不对也会报这个错。把路径改成绝对路径是最省事的。

5.4 现象：cmc 一直 TIMEOUT，查询不到任何链上信息

cmc 查询超时是最容易误导人的问题——很多人第一反应是链挂了，实际链上一切正常。真正原因通常是 sdk_config.yml 里的 RPC 地址或端口写错，或者 chain_id 和 chain.yml 里不一致。

解决：打开 sdk_config.yml，逐项核对节点地址、RPC 端口和 chain_id。记住一个原则：RPC 端口是 12301 那一组，不是 P2P 的 11301 组。用curl telnet://节点IP:12301或者在节点本机用ss -lntp | grep 12301确认 RPC 端口真的在监听，再回头看 cmc 配置。

5.5 现象：部署合约反复报 CONTRACT_FAIL

部署合约时返回 CONTRACT_FAIL，很多人第一反应是合约写得有问题，其实在测试环境里，这个报错多半是 gas 不足，或者合约字节码与链上虚拟机版本不匹配。

解决：先调大交易 gas 参数，给足资源再试。以 cmc 为例，部署和调用时都加上--gas-limit 100000000，测试链本来就是用来试错的，不用在 gas 上省。如果调大后仍然报错，去确认合约编译时用的 SDK 版本和链上版本一致，老合约字节码发到新链上报错很常见，重新编译一份再部署通常能解决。

6. 进阶：给跑起来的链动态加节点，以及多链怎么编排

6.1 扩容节点：让新节点加入现有共识网络

四节点跑通后，下一个自然需求是扩容。给一条已运行的链加节点，核心不是启动新节点，而是让新节点能通过 P2P 找到现有节点，并且现有节点认可新节点的身份。

常见做法是：先在新机器上按原来的 crypto_config.yml 生成新节点证书，把新节点配置目录整好，再把新节点目录同步到目标机器。这里的关键是 seed 配置指向现有节点：

# 把新节点运行目录同步到目标机器 rsync -av /data/chainmaker/chain-maker/node5/ user@目标机器IP:/data/chainmaker/chain-maker/node5/

参数说明：rsync 会把整个节点目录带权限同步过去，避免重新手工搭目录。注意目标机器的目录层级必须和现有节点保持一致，否则启动脚本找不到配置。

同步完成后，修改新节点 chain.yml 里的 seed 节点列表，填一个现有节点的 P2P 地址；同时按共识要求把新节点的证书登记进现有节点的信任配置里。在测试环境，许多人直接重启全部节点让配置重新加载，验证新节点同步到最新区块高度后，就算扩容成功。生产环境要按官方变更流程做灰度替换，千万别直接在跑着的链上删配置。