2. 版本升级说明

2.1. 概述

本文档主要描述将旧版本chainmaker升级为新版本的步骤,正常情况下,伴随着新版发布,都会有相应的升级描述。本文档根据版本号倒序排版,即最新版本升级描述会在最前面,请读者注意。

2.2. v2.3.0 -> v2.3.1版本升级指南

2.2.1. 平滑升级

在之前的版本中,要进行版本升级需要将所有节点停止,然后进行二进制替换和配置修改,会造成业务服务的中断,从v2.3.1版开始,将支持了区块链网络的平滑升级,逐个将区块链网络中的节点升级为新版本,而在升级过程中区块链网络始终保持正常的接收交易和打包区块。平滑升级具体操作步骤如下:

1.更新链配置,确保链版本为v2.3.0

使用cmc的链配置查看命令,查看当前链配置的版本(此时二进制文件还没有替换

./cmc client chainconfig query \
--sdk-conf-path=./testdata/sdk_config.yml

其中返回的”version”字段如果是”v2.3.0”则直接进入下一步,如果不是,则需要执行以下命令修改链配置中的版本:

./cmc client contract user invoke \
--contract-name=CHAIN_CONFIG \
--method=UPDATE_VERSION \
--params="{\"block_version\":\"2301\"}" \
--sdk-conf-path=./testdata/sdk_config.yml \
--sync-result=true \
--admin-key-file-paths=./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.key,./testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.key,./testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.key \
--admin-crt-file-paths=./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.crt,./testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.crt,./testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.crt

执行成功后可以再次查询链配置中的version字段,确保version值为 “v2.3.0“或者是”2301”都可。

2.停止并替换二进制

如果您需要保持区块链网络的持续运行,可以修改客户端连接,将交易发送到另一个节点,然后使用stop.sh停止一个节点(需要停止虚拟机),然后替换二进制。如果是基于Docker或者K8s则停用容器或Pod,然后更新Docker镜像为v2.3.1版本。

3.升级 Docker Go 虚拟机

如果您使用vm-engine镜像,请更新chainmakerofficial/chainmaker-vm-engine,命令如下:

docker pull chainmakerofficial/chainmaker-vm-engine:v2.3.1

如果您使用vm-docker-go镜像,请更新chainmakerofficial/chainmaker-vm-docker-go,命令如下:

docker pull chainmakerofficial/chainmaker-vm-docker-go:v2.3.1

4.启动节点和Docker Go虚拟机

如果您使用了Docker Go虚拟机:

  • 如果Docker Go是本机部署,需要同时替换下bin目录下的start.sh脚本,脚本会处理新合约虚拟机的拉起和停止。脚本由build_release.sh生成,可以参考《编译和安装包制作》

  • 如果Docker Go是独立部署(比如部署在其他host),可以参考《独立部署DockerVM》

重新执行start.sh脚本启动节点(需要启动虚拟机)。

5.逐个替换所有节点的二进制和DockerGo虚拟机

针对链中的每一个共识节点和同步节点,逐个执行步骤2、3、4的操作,也就是行:停止->替换->启动 操作,确保所有节点都已经升级为最新版本。

4.更新链配置,设置链版本为2030100

当所有共识节点都升级完二进制后,使用cmc更新链配置version到最新的2030100

./cmc client contract user invoke \
--contract-name=CHAIN_CONFIG \
--method=UPDATE_VERSION \
--params="{\"block_version\":\"2030100\"}" \
--sdk-conf-path=./testdata/sdk_config.yml \
--sync-result=true \
--admin-key-file-paths=./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.key,./testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.key,./testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.key \
--admin-crt-file-paths=./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.crt,./testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.crt,./testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.crt

5.检查升级是否成功

更新链配置后,正常发起业务交易,系统会打包新区块,通过cmc查询最新区块,关注header中的block_version字段,如果该值为2030100,则说明平滑升级成功。

./cmc query block-by-height  --sdk-conf-path=./testdata/sdk_config.yml

2.2.2. 新系统合约的启用

在本次v2.3.1的版本升级中,启用了中继跨链使用的系统合约,如果您考虑使用中继跨链功能,在完成了上述的平滑升级后,可以通过以下命令初始化之前版本中没有初始化的系统合约:

./cmc client contract user invoke \
--contract-name=CONTRACT_MANAGE \
--method=INIT_NEW_NATIVE_CONTRACT \
--sdk-conf-path=./testdata/sdk_config.yml \
--sync-result=true \
--result-to-string=true

本命令返回的message是OK,则说明新系统合约初始化成功。

2.2.3. 账本文件临时存储的启用

长安链默认使用文件来存储区块和交易的账本数据,使用数据库存储区块和交易的索引信息,由于账本文件占存储空间的大部分,出于成本和扩展性的考虑,一般会将账本文件存储在NFS之类的网络文件系统中。但是NFS的临时卡顿会影响整个链的出块,为此可以启用账本文件的临时存储功能。具体操作步骤如下:

1.修改配置文件

修改节点的chainmaekr.yml配置,storage选项下,增加block_store_tmp_path选项,值为本地高速磁盘

storage:
  store_path: /nfs/ledgerData  #账本的持久化文件存储路径
  block_store_tmp_path: /ssd/ledgerData_tmp #启用临时的账本文件存储,建议本地高速磁盘
  ......

2.停止节点,移动.END文件,启动节点

停止节点,将store_path下的.END文件移动到block_store_tmp_path下,这里的移动为了安全起见,建议先拷贝再删除原有的.END文件。移动完成后启动节点即可。

3.若节点为多链结构

若节点为多链结构,则chainID有多个,如: chain1,chain2,chain3…, 此时:

originfile1: /data/wx-org1.chainmaker.org/ledgerData1/chain1/bfdb —-移动.END文件到—> tmpfile1: /ssd/ledgerData_TMP/chain1/bfdb

originfile2: /data/wx-org1.chainmaker.org/ledgerData1/chain2/bfdb —-移动.END文件到—> tmpfile1: /ssd/ledgerData_TMP/chain2/bfdb

originfile3: /data/wx-org1.chainmaker.org/ledgerData1/chain3/bfdb —-移动.END文件到—> tmpfile1: /ssd/ledgerData_TMP/chain3/bfdb

2.3. v2.2.1 -> v2.3.1版本升级指南

由于v2.3.1中启用了全新的平滑升级特性,该特性通过读取链配置中的version来决定所产区块的版本,所以必须通过先升级v2.3.0的方式,然后再按前面提到的v2.3.0升级v2.3.1的操作流程升级到v2.3.1。

长安链不支持v2.2.1及之前版本直接升v2.3.1

长安链不支持v2.2.1及之前版本直接升v2.3.1

长安链不支持v2.2.1及之前版本直接升v2.3.1

2.4. v2.2.1 -> v2.3.0版本升级指南

若未选用docker-vm虚拟机引擎,则直接参考:通用升级步骤参考

版本v2.3.0进行了Docker Go合约引擎重构升级,相比之前的版本具有一定的性能和稳定性提升,支持多语言跨合约调用,推荐升级到v2.3.0版本。v2.3.0之前的Docker Go合约文件需要参考v2.3.0合约升级指南进行修改并升级。

2.4.1. 升级 Docker Go 虚拟机

1. 更新镜像

更新镜像chainmakerofficial/chainmaker-vm-engine,命令如下:

docker pull chainmakerofficial/chainmaker-vm-engine:v2.3.0.1

2. 替换启停脚本

如果Docker VM是本机部署,在编译替换chainmaker的时候,需要同时替换下bin目录下的start.sh, stop.sh, restart.sh三个脚本,脚本会处理合约虚拟机的拉起和停止。脚本由build_release.sh生成,可以参考《编译和安装包制作》

如果Docker VM是独立部署(比如部署在其他host),可以参考《独立部署DockerVM》

3. 更新配置文件

v2.3.0版本中chainmaker.yml中vm相关的配置项如下:

  1. 只运行旧版本合约,请参考《支持旧版本Docker VM》

  2. 只运行新版本合约,请参考《支持新版本Docker VM》

  3. 同时运行新旧版本合约,或存在旧版本合约升级到新版本合约的操作,需要同时进行上述两种配置。

4. 合约升级(推荐)

通用升级步骤参考第7步启动链成功之后,推荐更新合约SDK并重新编译合约。

合约SDK主要变更如下:

  1. package import 路径变更

  2. 添加key、field校验,仅支持数字、字母以及._-

  3. 新增Contract合约接口方法UpgradeContract,合约升级时由调用InitContract改为调用UpgradeContract

  4. 更新Contract合约接口方法InvokeContract,由之前的传递CMStubInterface来获取method,改为入参传递method,无需再传递stub手动获取method

  5. SDK使用方式变更,由之前每个函数入参传递一个CMStubInterface实例来使用SDK接口方法改为通过sdk.Instance全局变量来使用SDK提供的接口方法。

v2.3.0版本合约编写请参考:《使用Golang进行智能合约开发》

2.5. v2.1.0, v2.2.0 -> v2.2.1版本升级指南

由于版本v2.2.0使用了新版本的wasm引擎,请注意在执行 通用升级步骤参考 的第4步时,需要同时将 ./main/libwasmer_runtime_c_api.so 文件复制为生产环境的 /usr/lib64/libwasmer.so 文件。

2.5.1. 升级 Docker Go VM虚拟机

如果启用了Docker VM虚拟机,除通用升级步骤参考中的操作外,需要额外做以下操作:

  1. 替换启停脚本

    在v2.2.1 版本中Docker VM虚拟机不再由Chainmaker节点程序拉起,

    如果Docker VM是本机部署,在第4步编译替换chainmaker的时候,需要同时替换下bin目录下的start.sh, stop.sh, restart.sh三个脚本,脚本会处理合约虚拟机的拉起和停止。脚本由build_release.sh生成,可以参考《通过命令行体验链》

    如果Docker VM是独立部署(比如部署在其他host),可以参考《启动支持Docker_VM的链》

  2. 更新vm-docker-go虚拟机镜像

    在第4步替换二进制之后,也需要更新vm-docker-go虚拟机镜像(chainmakerofficial/chainmaker-vm-docker-go)至v2.2.1版本,命令如下:

    docker pull chainmakerofficial/chainmaker-vm-docker-go:v2.2.1
    
  3. contract-sdk-docker-go 合约升级(强烈建议)

    在第7步启动链成功之后,强烈建议更新合约SDK。

    更新合约SDK镜像(chainmakerofficial/chainmaker-docker-go-contract)至v2.2.1版本,命令如下:

    docker pull chainmakerofficial/chainmaker-docker-go-contract:v2.2.1
    

    如果是v2.2.0之前的合约文件还需要对合约源码进行一些修改,参考v2.1.0 -> v2.2.0版本升级指南升级合约文件。

2.6. v2.1.0 -> v2.2.0版本升级指南

由于版本v2.2.0使用了新版本的wasm引擎,请注意在执行 通用升级步骤参考 的第4步时,需要同时将 ./main/libwasmer_runtime_c_api.so 文件复制为生产环境的 /usr/lib64/libwasmer.so 文件。

2.6.1. vm-docker-go 虚拟机引擎升级

如果启用了vm-docker-go虚拟机(必须), 通用升级步骤参考中需要额外做以下操作:

其中,在第3步停止节点之后,需要更新vm-docker-go虚拟机镜像(chainmakerofficial/chainmaker-vm-docker-go)至v2.2.0.1版本,命令如下:

docker pull chainmakerofficial/chainmaker-vm-docker-go:v2.2.0.1

2.6.2. contract-sdk-docker-go 合约升级(强烈建议)

在第7步启动链成功之后,强烈建议更新合约SDK。

更新合约SDK镜像(chainmakerofficial/chainmaker-docker-go-contract)至v2.2.0.1版本,命令如下:

docker pull chainmakerofficial/chainmaker-docker-go-contract:v2.2.0.1

在第8步编译合约文件之前,还需要对合约源码进行一些修改,修改内容如下,【合约编译步骤参考】

v2.1.0版本合约源码示例如下:

package main

import (
  "encoding/json"
  "log"
  "strconv"

  "chainmaker.org/chainmaker-contract-sdk-docker-go/pb/protogo"
  "chainmaker.org/chainmaker-contract-sdk-docker-go/shim"
)
   // ---snip---

v2.2.0.1版本合约源码需要修改至如下格式(合约SDK import路径需要更新):

package main

import (
    "encoding/json"
    "log"
    "strconv"

    "chainmaker.org/chainmaker/chainmaker-contract-sdk-docker-go/pb/protogo"
    "chainmaker.org/chainmaker/chainmaker-contract-sdk-docker-go/shim"
)
// ---snip---

2.7. v2.0.0 -> v2.1.0版本升级指南

v2.1.0兼容v2.0.0,升级时只需要替换相应二进制文件(无需修改配置文件),并重启所有节点。升级所有生态工具即可。

通用升级步骤参考

从历史版本升级为 v2.1.0版本,新功能只支持自研网络(需将所有节点停止,并修改chainmaker.yml文件的net.provider为liquid后,再启动)。若想体验其他新功能如java国密、公钥身份、透明加密等,请重新安装新版本ChainMaker。

2.8. 通用升级操作步骤

写在最前面:建议所有操作都备份

  • 1.停止交易: 停止所有向节点发交易请求,即不要再让链出新块。

  • 2.确认同步: 确认现有全部节点状态已同步到一致,即块高度一致。

  • 3.停止节点: 停止所有节点服务。

  • 4.编译chainmaker: 编译新版本的可执行文件,并替换原版本的可执行文件(一般在目录bin中)。

  • 5.修改配置: 若不使用新版本特性,则可跳过;若需使用,可修改所有节点的chainmaker.yml对应部分。

  • 6.启动: 启动所有节点,观察日志有无错误信息。若使用cluster_quick_start.sh 命令启动则需要移除release下的*tar.gz文件。

  • 7.链升级成功: 正常情况下,至此版本升级成功。

  • 8.(强烈建议)编译合约文件: 使用和chainmaker-go最近版本的合约SDK编译新的合约文件。

  • 9.(强烈建议)升级合约: 使用新的合约升级以前版本的合约。

  • 10.(强烈建议)升级配套工具: 如果有使用sdk或者cmc工具,请将sdkcmc版本升级为和链一致的版本,否则可能会导致交易失败。

2.8.1. 新添加节点注意事项

1.新节点的bc*.yml文件必须与旧版本时期保持一致(路径参数则需要路径对应的内容保持一致),无需修改为新的版本。新的版本程序已对其做了兼容,如果修改bc*.yml会导致创世块不一致,无法完成同步。

2.新节点的chainmaker.yml文件需要与新的版本格式保持一致。