开发部署工具

重要

开发部署工具 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，-T开启log级别到DEBUG，p2p模块默认监听 0.0.0.0。

注解

为便于开发和体验，p2p模块默认监听IP是 0.0.0.0 ，出于安全考虑，请根据实际业务网络情况，修改为安全的监听地址，如内网IP或特定的外网IP

帮助

  1. Usage:
  2.     -l <IP list>                        [Required] "ip1:nodeNum1,ip2:nodeNum2" e.g:"192.168.0.1:2,192.168.0.2:3"
  3.     -f <IP list file>                   [Optional] split by line, every line should be "ip:nodeNum agencyName groupList p2p_port,channel_port,jsonrpc_port". eg "127.0.0.1:4 agency1 1,2 30300,20200,8545"
  4.     -e <FISCO-BCOS binary path>         Default download fisco-bcos from GitHub. If set -e, use the binary at the specified location
  5.     -o <Output Dir>                     Default ./nodes/
  6.     -p <Start Port>                     Default 30300,20200,8545 means p2p_port start from 30300, channel_port from 20200, jsonrpc_port from 8545
  7.     -i <Host ip>                        Default 127.0.0.1. If set -i, listen 0.0.0.0
  8.     -v <FISCO-BCOS binary version>      Default get version from https://github.com/FISCO-BCOS/FISCO-BCOS/releases. If set use specificd version binary
  9.     -s <DB type>                        Default rocksdb. Options can be rocksdb / mysql / scalable, rocksdb is recommended
  10.     -d <docker mode>                    Default off. If set -d, build with docker
  11.     -c <Consensus Algorithm>            Default PBFT. Options can be pbft / raft /rpbft, pbft is recommended
  12.     -C <Chain id>                       Default 1. Can set uint.
  13.     -g <Generate guomi nodes>           Default no
  14.     -z <Generate tar packet>            Default no
  15.     -t <Cert config file>               Default auto generate
  16.     -k <The path of ca root>            Default auto generate, the ca.crt and ca.key must in the path, if use intermediate the root.crt must in the path
  17.     -K <The path of sm crypto ca root>  Default auto generate, the gmca.crt and gmca.key must in the path, if use intermediate the gmroot.crt must in the path
  18.     -X <Certificate expiration time>    Default 36500 days
  19.     -T <Enable debug log>               Default off. If set -T, enable debug log
  20.     -S <Enable statistics>              Default off. If set -S, enable statistics
  21.     -F <Disable log auto flush>         Default on. If set -F, disable log auto flush
  22.     -E <Enable free_storage_evm>        Default off. If set -E, enable free_storage_evm
  23.     -h Help
  24. e.g
  25.     ./build_chain.sh -l "127.0.0.1:4"

选项介绍

l选项:

用于指定要生成的链的IP列表以及每个IP下的节点数，以逗号分隔。脚本根据输入的参数生成对应的节点配置文件，其中每个节点的端口号默认从30300开始递增，所有节点属于同一个机构和群组。

f选项

  1. + 用于根据配置文件生成节点，相比于`l`选项支持更多的定制。
  2. + 按行分割，每一行表示一个服务器，格式为`IP:NUM AgencyName GroupList`，每行内的项使用空格分割，**不可有空行**。
  3. + `IP:NUM`表示机器的IP地址以及该机器上的节点数。`AgencyName`表示机构名，用于指定使用的机构证书。`GroupList`表示该行生成的节点所属的组，以`,`分割。例如`192.168.0.1:2 agency1 1,2`表示`ip`为`192.168.0.1`的机器上有两个节点，这两个节点属于机构`agency1`，属于group1和group2。

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

  1. 192.168.0.1:1 agency1 1,2 30300,20200,8545
  2. 192.168.0.2:1 agency1 1,2 30300,20200,8545
  3. 192.168.0.3:2 agency1 1,3 30300,20200,8545
  4. 192.168.0.4:1 agency2 1   30300,20200,8545
  5. 192.168.0.5:1 agency3 2,3 30300,20200,8545
  6. 192.168.0.6:1 agency2 3   30300,20200,8545

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

  1. bash build_chain.sh -f ipconf -T

e选项[Optional]

用于指定fisco-bcos二进制所在的完整路径，脚本会将fisco-bcos拷贝以IP为名的目录下。不指定时，默认从GitHub下载master分支最新的二进制程序。

  1. # 从GitHub下载下载最新release二进制，生成本机4节点
  2. $ bash build_chain.sh -l "127.0.0.1:4"
  3. # 使用 bin/fisco-bcos 二进制，生成本机4节点
  4. $ bash build_chain.sh -l "127.0.0.1:4" -e bin/fisco-bcos

o选项[Optional]

指定生成的配置所在的目录。

p选项[Optional]

指定节点的起始端口，每个节点占用三个端口，分别是p2p,channel,jsonrpc使用,分割端口，必须指定三个端口。同一个IP下的不同节点所使用端口从起始端口递增。

  1. # 两个节点分别占用`30300,20200,8545`和`30301,20201,8546`。
  2. $ bash build_chain.sh -l 127.0.0.1:2 -p 30300,20200,8545

v选项[Optional]

用于指定搭建FISCO BCOS时使用的二进制版本。build_chain默认下载Release页面最新版本，设置该选项时下载参数指定version版本并设置config.ini配置文件中的[compatibility].supported_version=${version}。如果同时使用-e选项，则配置[compatibility].supported_version=${version}为Release页面最新版本号。

d选项[Optional]

使用docker模式搭建FISCO BCOS，使用该选项时不再拉取二进制，但要求用户启动节点机器安装docker且账户有docker权限，即用户加入docker群组。 在节点目录下执行如下命令启动节点

  1. $ ./start.sh

该模式下 start.sh 脚本启动节点的命令如下

  1. $ docker run -d --rm --name ${nodePath} -v ${nodePath}:/data --network=host -w=/data fiscoorg/fiscobcos:latest -c config.ini

s选项[Optional]

有参数选项，参数为db名，目前支持rocksdb、mysql、external、scalable。默认使用RocksDB。

  • RocksDB模式，使用RocksDB作为后端数据库。
  • MySQL模式，使用MySQL作为后端数据库，节点直连MySQL，需要在群组ini文件中配置数据库相关信息。
  • External模式，使用MySQL作为后端数据库，节点使用amdb-proxy连接数据库，代理和节点通过amop协议通信，需要在群组ini文件中配置topic信息。
  • scalable模式，区块数据和状态数据存储在不同的数据库中，区块数据根据配置存储在以块高命名的RocksDB实例中。如需使用裁剪数据的功能，必须使用scalable模式。

c选项[Optional]

有参数选项，参数为共识算法类型，目前支持PBFT、Raft、rPBFT。默认共识算法是PBFT。

  • PBFT：设置节点共识算法为PBFT。
  • Raft：设置节点共识算法为Raft。
  • rPBFT：设置节点共识算法为rPBFT。

C选项[Optional]

用于指定搭建FISCO BCOS时的链标识。设置该选项时将使用参数设置config.ini配置文件中的[chain].id，参数范围为正整数，默认设置为1。

  1. # 该链标识为2。
  2. $ bash build_chain.sh -l 127.0.0.1:2 -C 2

g选项[Optional]

无参数选项，设置该选项时，搭建国密版本的FISCO BCOS。使用g选项时要求二进制fisco-bcos为国密版本。

z选项[Optional]

无参数选项，设置该选项时，生成节点的tar包。

t选项[Optional]

该选项用于指定生成证书时的证书配置文件。

T选项[Optional]

无参数选项，设置该选项时，设置节点的log级别为DEBUG。log相关配置参考这里。

k选项[Optional]

使用用户指定的链证书和私钥签发机构和节点的证书，参数指定路径，路径下必须包括ca.crt/ca.key，如果所指定的私钥和证书是中间ca，那么此文件夹下还需要包括root.crt，用于存放上级证书链。

K选项[Optional]

国密模式使用用户指定的链证书和私钥签发机构和节点的证书，参数指定路径，路径下必须包括gmca.crt/gmca.key，如果所指定的私钥和证书是中间ca，那么此文件夹下还需要包括gmroot.crt，用于存放上级证书链。

D选项[Optional]

无参数选项，设置该选项时，生成节点的目录名为IP_P2P端口，默认为节点从0开始的编号。

E选项[Optional]

无参数选项，设置该选项时，启用Free Storage Gas模式，默认关闭Free Storage Gas模式

节点文件组织结构

  • cert文件夹下存放链的根证书和机构证书。
  • 以IP命名的文件夹下存储该服务器所有节点相关配置、fisco-bcos可执行程序、SDK所需的证书文件。
  • 每个IP文件夹下的node*文件夹下存储节点所需的配置文件。其中config.ini为节点的主配置，conf目录下存储证书文件和群组相关配置。配置文件详情，请参考这里。每个节点中还提供start.sh和stop.sh脚本，用于启动和停止节点。
  • 每个IP文件夹下的提供start_all.sh和stop_all.sh两个脚本用于启动和停止所有节点。
  1. nodes/
  2. ├── 127.0.0.1
  3. │   ├── fisco-bcos # 二进制程序
  4. │   ├── node0 # 节点0文件夹
  5. │   │   ├── conf # 配置文件夹
  6. │   │   │   ├── ca.crt # 链根证书
  7. │   │   │   ├── group.1.genesis # 群组1初始化配置，该文件不可更改
  8. │   │   │   ├── group.1.ini # 群组1配置文件
  9. │   │   │   ├── node.crt # 节点证书
  10. │   │   │   ├── node.key # 节点私钥
  11. │   │   │   ├── node.nodeid # 节点id，公钥的16进制表示
  12. │   │   ├── config.ini # 节点主配置文件，配置监听IP、端口等
  13. │   │   ├── start.sh # 启动脚本，用于启动节点
  14. │   │   └── stop.sh # 停止脚本，用于停止节点
  15. │   ├── node1 # 节点1文件夹
  16. │   │.....
  17. │   ├── node2 # 节点2文件夹
  18. │   │.....
  19. │   ├── node3 # 节点3文件夹
  20. │   │.....
  21. │   ├── sdk # SDK需要用到的
  22. │   │   ├── ca.crt # 链根证书
  23. │   │   ├── sdk.crt # SKD所需的证书文件，建立连接时使用
  24. │   │   └── sdk.key # SDK所需的私钥文件，建立连接时使用
  25. ├── cert # 证书文件夹
  26. │   ├── agency # 机构证书文件夹
  27. │   │   ├── agency.crt # 机构证书
  28. │   │   ├── agency.key # 机构私钥
  29. │   │   ├── agency.srl
  30. │   │   ├── ca-agency.crt
  31. │   │   ├── ca.crt
  32. │   │   └── cert.cnf
  33. │   ├── ca.crt # 链证书
  34. │   ├── ca.key # 链私钥
  35. │   ├── ca.srl
  36. │   └── cert.cnf

使用举例

无外网条件的单群组

最简单的操作方式是在有外网的Linux机器上使用build_chain建好链，借助-z选项打包，然后拷贝到无外网的机器上运行。

  1. 针对某下场景下无外网条件下建链，请从发布页面下载最新的目标操作系统的二进制，例如对于Linux系统下载fisco-bcos.tar.gz。
  2. 请从发布页面下载最新版本的build_chain脚本。
  3. 上传fisco-bcos.tar.gz和build_chain.sh到目标服务器，需要注意目标服务器要求64位，要求安装有openssl 1.0.2以上版本。
  4. 解压fisco-bcos.tar.gz得到fisco-bcos可执行文件，作为-e选项的参数。
  5. 构建本机上4节点的FISCO BCOS联盟链，使用默认起始端口30300,20200,8545（4个节点会占用30300-30303,20200-20203,8545-8548）。
  6. 执行下面的指令，假设最新版本是2.2.0，则将2.2.0作为-v选项参数。
  1. # 构建FISCO BCOS联盟链
  2. $ bash build_chain.sh -l "127.0.0.1:4" -p 30300,20200,8545 -e ./fisco-bcos -v 2.2.0
  3. # 生成成功后，输出`All completed`提示
  4. Generating CA key...
  5. ==============================================================
  6. Generating keys ...
  7. Processing IP:127.0.0.1 Total:4 Agency:agency Groups:1
  8. ==============================================================
  9. Generating configurations...
  10. Processing IP:127.0.0.1 Total:4 Agency:agency Groups:1
  11. ==============================================================
  12. [INFO] FISCO-BCOS Path   : bin/fisco-bcos
  13. [INFO] Start Port        : 30300 20200 8545
  14. [INFO] Server IP         : 127.0.0.1:4
  15. [INFO] State Type        : storage
  16. [INFO] RPC listen IP     : 127.0.0.1
  17. [INFO] Output Dir        : /Users/fisco/WorkSpace/FISCO-BCOS/tools/nodes
  18. [INFO] CA Key Path       : /Users/fisco/WorkSpace/FISCO-BCOS/tools/nodes/cert/ca.key
  19. ==============================================================
  20. [INFO] All completed. Files in /Users/fisco/WorkSpace/FISCO-BCOS/tools/nodes

群组新增节点

本节以为上一小节生成的群组1新增一个共识节点为例操作。

为新节点生成私钥证书

接下来的操作，都在上一节生成的nodes/127.0.0.1目录下进行

  1. 获取证书生成脚本
  1. curl -LO https://raw.githubusercontent.com/FISCO-BCOS/FISCO-BCOS/master/tools/gen_node_cert.sh

注解

  1. 生成新节点私钥证书
  1. # -c指定机构证书及私钥所在路径
  2. # -o输出到指定文件夹，其中newNode/conf中会存在机构agency新签发的证书和私钥
  3. bash gen_node_cert.sh -c ../cert/agency -o newNode

国密版本请执行下面的指令生成证书。

  1. bash gen_node_cert.sh -c ../cert/agency -o newNodeGm -g ../gmcert/agency/

准备配置文件

  1. 拷贝群组1中节点node0配置文件与工具脚本

    1. cp node0/config.ini newNode/config.ini
    2. cp node0/conf/group.1.genesis newNode/conf/group.1.genesis
    3. cp node0/conf/group.1.ini newNode/conf/group.1.ini
    4. cp node0/*.sh newNode/
    5. cp -r node0/scripts newNode/

  2. 更新newNode/config.ini中监听的IP和端口，对于[rpc]模块，修改listen_ip、channel_listen_port和jsonrpc_listen_port；对于[p2p]模块，修改listen_port

  3. 将新节点的P2P配置中的IP和Port加入原有节点的config.ini中的[p2p]字段。假设新节点IP:Port为127.0.0.1:30304则，修改后的[P2P]配置为

注解

为便于开发和体验，p2p模块默认监听IP是 0.0.0.0 ，出于安全考虑，请根据实际业务网络情况，修改为安全的监听地址，如：内网IP或特定的外网IP

  1. ```bash
  2. [p2p]
  3.     listen_ip=0.0.0.0
  4.     listen_port=30300
  5.     ;enable_compress=true
  6.     ; nodes to connect
  7.     node.0=127.0.0.1:30300
  8.     node.1=127.0.0.1:30301
  9.     node.2=127.0.0.1:30302
  10.     node.3=127.0.0.1:30303
  11.     node.4=127.0.0.1:30304
  12. ```
  1. 启动新节点，执行newNode/start.sh
  2. 通过console将新节点加入群组1，请参考这里和这里，nodeID可以通过命令cat newNode/conf/node.nodeid来获取
  3. 检查连接和共识

生成新机构证书

  1. 获取机构证书生成脚本
  1. curl -LO https://raw.githubusercontent.com/FISCO-BCOS/FISCO-BCOS/master/tools/gen_agency_cert.sh
  1. 生成新机构私钥和证书
  1. # -c 指定链证书及私钥所在路径，目录下必须有ca.crt 和 ca.key， 如果ca.crt是二级CA，则还需要root.crt(根证书) 
  2. # -g 指定国密链证书及私钥所在路径，目录下必须有gmca.crt 和 gmca.key，如果gmca.crt是二级CA，则还需要gmroot.crt(根证书) 
  3. # -a 新机构的机构名
  4. bash gen_agency_cert.sh -c nodes/cert/ -a newAgencyName

国密版本请执行下面的指令。

  1. bash gen_agency_cert.sh -c nodes/cert/ -a newAgencyName -g nodes/gmcert/

多服务器多群组

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