建链脚本

重要

build_chain脚本目标是让用户最快的使用FISCO BCOS,对于企业级应用部署FISCO BCOS请参考 企业级部署工具

FISCO BCOS提供了build_chain.sh脚本帮助用户快读搭建FISCO BCOS联盟链,该脚本默认从GitHub下载master分支最新版本预编译可执行程序进行相关环境的搭建。

脚本功能简介

  • build_chain.sh脚本用于快速生成一条链中节点的配置文件,脚本依赖于openssl请根据自己的操作系统安装openssl 1.0.2以上版本。脚本的源码位于FISCO-BCOS/tools/build_chain.sh
  • 快速体验可以使用-l选项指定节点IP和数目。-f选项通过使用一个指定格式的配置文件,支持创建各种复杂业务场景FISCO BCOS链。-l-f选项必须指定一个且不可共存
  • 建议测试时使用-T-i选项,-T开启log级别到DEBUG,-i设置RPC和channel监听0.0.0.0,p2p模块默认监听0.0.0.0

帮助

Usage:
    -l <IP list>                        [Required] "ip1:nodeNum1,ip2:nodeNum2" e.g:"192.168.0.1:2,192.168.0.2:3"
    -f <IP list file>                   [Optional] split by line, every line should be "ip:nodeNum agencyName groupList". eg "127.0.0.1:4 agency1 1,2"
    -e <FISCO-BCOS binary path>         Default download fisco-bcos from GitHub. If set -e, use the binary at the specified location
    -o <Output Dir>                     Default ./nodes/
    -p <Start Port>                     Default 30300,20200,8545 means p2p_port start from 30300, channel_port from 20200, jsonrpc_port from 8545
    -i <Host ip>                        Default 127.0.0.1. If set -i, listen 0.0.0.0
    -v <FISCO-BCOS binary version>      Default get version from FISCO-BCOS/blob/master/release_note.txt. eg. 2.0.0
    -d <docker mode>                    Default off. If set -d, build with docker
    -s <State type>                     Default storage. if set -s, use mpt 
    -S <Storage type>                   Default leveldb. if set -S, use external
    -c <Consensus Algorithm>            Default PBFT. If set -c, use Raft
    -C <Chain id>                       Default 1. Can set uint.
    -g <Generate guomi nodes>           Default no
    -z <Generate tar packet>            Default no
    -t <Cert config file>               Default auto generate
    -T <Enable debug log>               Default off. If set -T, enable debug log
    -F <Disable log auto flush>         Default on. If set -F, disable log auto flush
    -h Help
e.g
    ./tools/build_chain.sh -l "127.0.0.1:4"

选项介绍

  • l选项: 用于指定要生成的链的IP列表以及每个IP下的节点数,以逗号分隔。脚本根据输入的参数生成对应的节点配置文件,其中每个节点的端口号默认从30300开始递增,所有节点属于同一个机构和群组。
  • f选项
    • 用于根据配置文件生成节点,相比于l选项支持更多的定制。
    • 按行分割,每一行表示一个服务器,格式为IP:NUM AgencyName GroupList,每行内的项使用空格分割,不可有空行
    • IP:NUM表示机器的IP地址以及该机器上的节点数。AgencyName表示机构名,用于指定使用的机构证书。GroupList表示该行生成的节点所属的组,以,分割。例如192.168.0.1:2 agency1 1,2表示ip192.168.0.1的机器上有两个节点,这两个节点属于机构agency1,属于group1和group2。

下面是一个配置文件的例子,每个配置项以空格分隔。

192.168.0.1:2 agency1 1,2
192.168.0.1:2 agency1 1,3
192.168.0.2:3 agency2 1
192.168.0.3:5 agency3 2,3
192.168.0.4:2 agency2 3

假设上述文件名为ipconf,则使用下列命令建链,表示使用配置文件,设置日志级别为DEBUG,监听0.0.0.0

$ bash build_chain.sh -f ipconf -T -i
  • e选项[Optional] 用于指定fisco-bcos二进制所在的完整路径,脚本会将fisco-bcos拷贝以IP为名的目录下。不指定时,默认从GitHub下载master分支最新的二进制程序。
# 从GitHub下载下载最新release二进制,生成本机4节点
$ bash build_chain.sh -l "127.0.0.1:4"
# 使用 bin/fisco-bcos 二进制,生成本机4节点
$ bash build_chain.sh -l "127.0.0.1:4" -e bin/fisco-bcos 
  • o选项[Optional] 指定生成的配置所在的目录。
  • p选项[Optional] 指定节点的起始端口,每个节点占用三个端口,分别是p2p,channel,jsonrpc使用,分割端口,必须指定三个端口。同一个IP下的不同节点所使用端口从起始端口递增。
# 两个节点分别占用`30300,20200,8545`和`30301,20201,8546`。
$ bash build_chain.sh -l 127.0.0.1:2 -p 30300,20200,8545
  • i选项[Optional] 无参数选项,设置该选项时,设置节点的RPC和channel监听0.0.0.0
  • v选项[Optional] 用于指定搭建FISCO BCOS时使用的二进制版本。build_chain默认下载Release页面最新版本,设置该选项时下载参数指定version版本并设置config.ini配置文件中的[compatibility].supported_version=${version}。如果同时使用-e选项指定二进制,那么通过./fisco-bcos --version获取指定二进制版本,并将[compatibility].supported_version设置为获取的二进制版本。
  • d选项[Optional] 使用docker模式搭建FISCO BCOS,使用该选项时不再拉取二进制,但要求用户启动节点机器安装docker且账户有docker权限。该模式下脚本启动节点的命令如下
$ docker run -d --rm --name ${nodePath} -v ${nodePath}:/data --network=host -w=/data fiscoorg/fiscobcos:latest -c config.ini
  • s选项[Optional] 无参数选项,设置该选项时,节点使用mptstate存储合约局部变量,默认使用storagestate存储合约局部变量。
  • S选项[Optional] 无参数选项,设置该选项时,节点使用外部数据库存储数据,目前支持MySQL。
  • c选项[Optional] 无参数选项,设置该选项时,设置节点的共识算法为Raft,默认设置为PBFT
  • C选项[Optional] 用于指定搭建FISCO BCOS时的链标识。设置该选项时将使用参数设置config.ini配置文件中的[chain].id,参数范围为正整数,默认设置为1。
# 该链标识为2。
$ bash build_chain.sh -l 127.0.0.1:2 -C 2
  • g选项[Optional] 无参数选项,设置该选项时,搭建国密版本的FISCO BCOS。使用g选项时要求二进制fisoc-bcos为国密版本
  • z选项[Optional] 无参数选项,设置该选项时,生成节点的tar包。
  • t选项[Optional] 该选项用于指定生成证书时的证书配置文件。
  • T选项[Optional] 无参数选项,设置该选项时,设置节点的log级别为DEBUG。log相关配置参考这里

节点文件组织结构

  • cert文件夹下存放链的根证书和机构证书。
  • 以IP命名的文件夹下存储该服务器所有节点相关配置、fisco-bcos可执行程序、SDK所需的证书文件。
  • 每个IP文件夹下的node*文件夹下存储节点所需的配置文件。其中config.ini为节点的主配置,conf目录下存储证书文件和群组相关配置。配置文件详情,请参考这里。每个节点中还提供start.shstop.sh脚本,用于启动和停止节点。
  • 每个IP文件夹下的提供start_all.shstop_all.sh两个脚本用于启动和停止所有节点。
nodes/
├── 127.0.0.1
│   ├── fisco-bcos # 二进制程序
│   ├── node0 # 节点0文件夹
│   │   ├── conf # 配置文件夹
│   │   │   ├── ca.crt # 链根证书
│   │   │   ├── group.1.genesis # 群组1初始化配置,该文件不可更改
│   │   │   ├── group.1.ini # 群组1配置文件
│   │   │   ├── node.crt # 节点证书
│   │   │   ├── node.key # 节点私钥
│   │   │   ├── node.nodeid # 节点id,公钥的16进制表示
│   │   ├── config.ini # 节点主配置文件,配置监听IP、端口等
│   │   ├── start.sh # 启动脚本,用于启动节点
│   │   └── stop.sh # 停止脚本,用于停止节点
│   ├── node1 # 节点1文件夹
│   │.....
│   ├── node2 # 节点2文件夹
│   │.....
│   ├── node3 # 节点3文件夹
│   │.....
│   ├── sdk # SDK需要用到的
│   │   ├── ca.crt # 链根证书
│   │   ├── node.crt # SKD所需的证书文件,建立连接时使用
│   │   └── node.key # SDK所需的私钥文件,建立连接时使用
├── cert # 证书文件夹
│   ├── agency # 机构证书文件夹
│   │   ├── agency.crt # 机构证书
│   │   ├── agency.key # 机构私钥
│   │   ├── agency.srl
│   │   ├── ca-agency.crt
│   │   ├── ca.crt
│   │   └── cert.cnf
│   ├── ca.crt # 链证书
│   ├── ca.key # 链私钥
│   ├── ca.srl
│   └── cert.cnf

使用举例

单服务器单群组

构建本机上4节点的FISCO BCOS联盟链,使用默认起始端口30300,20200,8545(4个节点会占用30300-30303,20200-20203,8545-8548),监听外网Channeljsonrpc端口,允许外网通过SDK或API与节点交互。

# 构建FISCO BCOS联盟链
$ bash build_chain.sh -l "127.0.0.1:4" -i
# 生成成功后,输出`All completed`提示
Generating CA key...
==============================================================
Generating keys ...
Processing IP:127.0.0.1 Total:4 Agency:agency Groups:1
==============================================================
Generating configurations...
Processing IP:127.0.0.1 Total:4 Agency:agency Groups:1
==============================================================
[INFO] FISCO-BCOS Path   : bin/fisco-bcos
[INFO] Start Port        : 30300 20200 8545
[INFO] Server IP         : 127.0.0.1:4
[INFO] State Type        : storage
[INFO] RPC listen IP     : 0.0.0.0
[INFO] Output Dir        : /Users/fisco/WorkSpace/FISCO-BCOS/tools/nodes
[INFO] CA Key Path       : /Users/fisco/WorkSpace/FISCO-BCOS/tools/nodes/cert/ca.key
==============================================================
[INFO] All completed. Files in /Users/fisco/WorkSpace/FISCO-BCOS/tools/nodes

多服务器多群组

使用build_chain脚本构建多服务器多群组的FISCO BCOS联盟链需要借助脚本配置文件,详细使用方式可以参考这里