3. 版本升级操作指南

3.1. 概述

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

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

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

升级步骤参考

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

3.3. v1.2.x -> v2.x版本升级指南

若有升级需求请联系长安链官方团队。
1.2.x和2.x都是长期支持的版本。2.x的版本相对1.2.x来说底层数据结构、记录共识状态等都有了很大变动。不支持滚动升级。

3.4. v1.2.0 -> v1.2.3版本升级指南

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

升级步骤参考

3.5. v1.1.1 -> v1.2.0版本升级指南

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

升级步骤参考

3.6. v1.1.0 -> v1.2.3版本升级指南

3.6.1. 链配置变更说明

从v1.1.1版本开始,各个存储模块可以独立配置。更加方便对存储数据库根据不同场景选用不同配置。同时也对存储结构做了些调整。升级时需要更新所有数据文件。

从v1.1.1版本开始,支持串行sql合约的执行。开启sql合约需要修改创世块配置文件bcN.yml:contract.enable_sql_support=true。故不支持从以前版本直接升级为可运行sql合约的链。只能部署新版本。

3.6.2. 升级操作步骤

3.6.2.1. 步骤

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

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

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

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

  • 4.编译chainmaker: 编译v1.2.3版本的可执行文件,并替换原v1.1.0版本的可执行文件。

  • 5.修改配置: 按照相应的版本修改所有节点的chainmaker.ymlbc*.yml不要修改!!! bc*.yml不要修改!!! bc*.yml不要修改!!!

  • 6.修改数据:复制结果集数据,并清洗数据结构。

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

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

  • 8.编译wasm文件: 使用和chainmaker-go相同版本的合约SDK编译新的wasm文件。

  • 9.升级合约: 使用新的合约升级以前版本的合约。

  • 10.升级配套工具: 如果有使用sdk或者cmc工具,请将sdkcmc版本升级为v1.2.3,否则可能会导致交易失败。

3.6.2.2. 修改节点配置

修改v1.1.0版本的chainmaker.yml文件,按照v1.2.3版本配置添加各个子存储模块,

包括:

  • 默认存储配置:store_path

  • 区块数据存储配置:blockdb_config

  • 状态数据存储配置:statedb_config

  • 历史变更存储配置:historydb_config

  • 结果集存储配置:resultdb_config

  • 事件存储配置:contract_eventdb_config,disable_contract_eventdb= true默认不开启

v1.1.0 chainmaker.yml存储配置如下:

storage:
  provider: LevelDB
  store_path: ../data/ledgerData
  enable_contract_eventdb: false #是否开启合约事件存储功能, 默认为false,如果设置为true,需要配置mysql
  mysql:    #MySQL相关配置,只有provider选择MySQL或者enable_contract_eventdb为true时才需要配置
    dsn: root:password@tcp(127.0.0.1:3306)/    #mysql的连接信息,包括用户名、密码、ip、port等,示例:root:admin@tcp(127.0.0.1:3306)
    max_idle_conns: 10    #连接池中维持的最大的空闲连接数,默认为10
    max_open_conns: 10    #最大的可用连接数,默认为10
    conn_max_lifetime: 60    #连接维持的最长时间,单位秒,默认为60

v1.2.3 chainmaker.yml存储配置如下:

请按照下面示例更新v1.1.0版本配置文件,添加存储模块配置。

注意:storage.store_path的值在v1.2.3版本需与v1.1.0版本一致。且下列leveldb路径配置也须与之保持一致

storage. blockdb_config.   leveldb_config. store_path

storage. statedb_config.   leveldb_config. store_path

storage. historydb_config. leveldb_config. store_path

storage. resultdb_config.  leveldb_config. store_path

storage:
  store_path: ../data/ledgerData
  blockdb_config:
    provider: leveldb
    leveldb_config:
      store_path: ../data/ledgerData
  statedb_config:
    provider: leveldb
    leveldb_config:
      store_path: ../data/ledgerData
  historydb_config:
    provider: leveldb
    leveldb_config:
      store_path: ../data/ledgerData
  resultdb_config:
    provider: leveldb
    leveldb_config:
      store_path: ../data/ledgerData
  disable_contract_eventdb: true 
  contract_eventdb_config:
    provider: sql                 
    sqldb_config:
      sqldb_type: mysql           
      dsn: root:password@tcp(127.0.0.1:3306)/  

3.6.2.3. 修改数据

1、复制结果集数据

复制每个节点中的历史数据库为结果集数据库,相应参数如下:

chainmakerProject:部署的项目根目录

store_path:为chainmaker.yml文件中的storage.store_path属性的值

chain_id:为chainmaker.yml文件中的blockchain.chainId的值(若有多条链,则需要多次执行该升级步骤)

# 进入数据目录
cd ${chainmakerProject}/${store_path}/${chain_id}/
# 复制结果集数据库
cp -r store_history store_result

2、清洗数据

linux x86 如下操作,其他系统请下载项目编译后使用,执行upgrade命令。

# 其中path参数为chainmaker.yml文件中storage.store_path值的目录的绝对路径,或相对当前路径。
# 如: chainmaker.yml在此目录/data/build/release/wx-org1/config/wx-org1.chainmaker.org/chainmaker.yml且storage.store_path = ../data/ledgerData
# 则写如下路径:
chmod +x upgradeTool
upgradeTool -p /data/build/release/wx-org1/data/ledgerData

3.6.3. 新添加节点

若已有正在运行中的org1-org4节点且已成功升级为v1.2.3,此时若需添加org5同步节点,操作步骤如下:

  • 1、启动org5用v1.1.0的版本:配置文件(bc1.yml、chainmaker.yml)用v1.1.0版本的、chainmaker二进制文件也用v1.1.0版本的

    • bc1.yml:和其他节点内容保持一致,路径修改自己当前项目路径;

    • chainmaker.yml:使用v1.1.0版本,其中seed需要指向org1-org4;

    • chainmaker:二进制文件使用v1.1.0;

  • 2、启动成功后:等待org5同步区块至未升级前的区块高度(日志类似:fail to verify the block whose height is 5,说明第5个区块可能是v1.2.3版本打包的区块。同步到第5个区块出错,此时需要升级到v1.2.3,按如下步骤)

  • 3、停止org5

  • 4、替换org5的chainmaker二进制文件版本为v1.2.3,和chainmaker.yml与v1.2.3的配置保持一致,见上

  • 5、复制数据并使用upgradeTool清理org5的data数据,见上

  • 6、启动org5并等待同步,至此添加新节点完成。(日志搜索:put block即可查看当前区块落库情况)

3.7. v1.1.0 -> v1.1.1版本升级指南

暂不支持升级,请选用最新版本。

3.8. v1.0.0 -> v1.1.0版本升级指南

从v1.1.0版本开始,共识节点的节点网络地址不再上链,改为只将共识节点的节点ID(NodeID)上链。目的是让节点IP发生变更时,减少运维的操作复杂度,运维人员只需修改本地chainmaker.yml文件中的网络配置即可,无需发起链配置变更交易。

3.8.1. 链配置变更说明

链配置项中共识节点配置变更说明如下:

v1.0.0版本bc*.yml中共识配置及权限配置:

#共识配置
consensus:
  # 共识类型(0-SOLO,1-TBFT,3-HOTSTUFF,4-RAFT,10-POW)
  type: 1
  # 共识节点列表,组织必须出现在trust_roots的org_id中,每个组织可配置多个共识节点,节点地址采用libp2p格式
  nodes:
    - org_id: "wx-org1.chainmaker.org"
      address:
        - "/ip4/127.0.0.1/tcp/11301/p2p/QmcQHCuAXaFkbcsPUj7e37hXXfZ9DdN7bozseo5oX4qiC4"
    - org_id: "wx-org2.chainmaker.org"
      address:
        - "/ip4/127.0.0.1/tcp/11302/p2p/QmeyNRs2DwWjcHTpcVHoUSaDAAif4VQZ2wQDQAUNDP33gH"
    - org_id: "wx-org3.chainmaker.org"
      address:
        - "/ip4/127.0.0.1/tcp/11303/p2p/QmXf6mnQDBR9aHauRmViKzSuZgpumkn7x6rNxw1oqqRr45"
    - org_id: "wx-org4.chainmaker.org"
      address:
        - "/ip4/127.0.0.1/tcp/11304/p2p/QmRRWXJpAVdhFsFtd9ah5F4LDQWFFBDVKpECAF8hssqj6H"
# 权限配置(只能整体添加、修改、删除)
resource_policies:
  - resource_name: NODE_ADDR_UPDATE
    policy:
      rule: SELF # 规则(ANY,MAJORITY...,全部大写,自动转大写)
      org_list: # 组织名称(组织名称,区分大小写)
      role_list: # 角色名称(role,全部小写,自动转小写)
        - admin

v1.1.0版本bc*.yml中共识配置变更为:

#共识配置
consensus:
  # 共识类型(0-SOLO,1-TBFT,3-HOTSTUFF,4-RAFT,10-POW)
  type: 1
  # 共识节点列表,组织必须出现在trust_roots的org_id中,每个组织可配置多个共识节点
  nodes:
    - org_id: "wx-org1.chainmaker.org"
      node_id:
        - "QmcQHCuAXaFkbcsPUj7e37hXXfZ9DdN7bozseo5oX4qiC4"
    - org_id: "wx-org2.chainmaker.org"
      node_id:
        - "QmeyNRs2DwWjcHTpcVHoUSaDAAif4VQZ2wQDQAUNDP33gH"
    - org_id: "wx-org3.chainmaker.org"
      node_id:
        - "QmXf6mnQDBR9aHauRmViKzSuZgpumkn7x6rNxw1oqqRr45"
    - org_id: "wx-org4.chainmaker.org"
      node_id:
        - "QmRRWXJpAVdhFsFtd9ah5F4LDQWFFBDVKpECAF8hssqj6H"
# 权限配置(只能整体添加、修改、删除)
resource_policies:
  - resource_name: NODE_ID_UPDATE
    policy:
      rule: SELF # 规则(ANY,MAJORITY...,全部大写,自动转大写)
      org_list: # 组织名称(组织名称,区分大小写)
      role_list: # 角色名称(role,全部小写,自动转小写)
        - admin

v1.1.0版本将权限配置中NODE_ADDR_ADDNODE_ADDR_UPDATENODE_ADDR_DELETE全部改为NODE_ID_ADDNODE_ID_UPDATENODE_ID_DELETE,原NODE_ADDR_ADDNODE_ADDR_UPDATENODE_ADDR_DELETE已全部弃用。

v1.0.0版本chainmaker.yml中网络配置:

net:
  provider: LibP2P
  listen_addr: /ip4/0.0.0.0/tcp/11301
  tls:
    enabled: true
    priv_key_file: ../config/wx-org1/certs/node/consensus1/consensus1.tls.key
    cert_file:     ../config/wx-org1/certs/node/consensus1/consensus1.tls.crt

v1.1.0版本chainmaker.yml中网络配置变更为:

net:
  provider: LibP2P
  listen_addr: /ip4/0.0.0.0/tcp/11301
  # 所有共识节点的完整网络地址需要配在seeds中
  seeds:
    - "/ip4/127.0.0.1/tcp/11301/p2p/QmcQHCuAXaFkbcsPUj7e37hXXfZ9DdN7bozseo5oX4qiC4"
    - "/ip4/127.0.0.1/tcp/11302/p2p/QmeyNRs2DwWjcHTpcVHoUSaDAAif4VQZ2wQDQAUNDP33gH"
    - "/ip4/127.0.0.1/tcp/11303/p2p/QmXf6mnQDBR9aHauRmViKzSuZgpumkn7x6rNxw1oqqRr45"
    - "/ip4/127.0.0.1/tcp/11304/p2p/QmRRWXJpAVdhFsFtd9ah5F4LDQWFFBDVKpECAF8hssqj6H"
  tls:
    enabled: true
    priv_key_file: ../config/wx-org1/certs/node/consensus1/consensus1.tls.key
    cert_file:     ../config/wx-org1/certs/node/consensus1/consensus1.tls.crt

v1.1.0版本chainmaker.yml中合约事件配置:

storage:
    provider: leveldb        #合约事件功能适配支持levedb、badgerdb、mysql provider
    store_path: ../data/ledgerData
    enable_contract_eventdb: false #是否开启合约事件存储功能, 默认为false,如果设置为true,需要配置mysql
    mysql:    #MySQL相关配置,provider选择MySQL或者enable_contract_eventdb为true时需要配置
      dsn: root:password@tcp(127.0.0.1:3306)/    #mysql的连接信息,包括用户名、密码、ip、port等,示例:root:admin@tcp(127.0.0.1:3306)
      max_idle_conns: 10    #连接池中维持的最大的空闲连接数,默认为10
      max_open_conns: 10    #最大的可用连接数,默认为10
      conn_max_lifetime: 60    #连接维持的最长时间,单位秒,默认为60

3.8.2. 升级操作步骤

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

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

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

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

  • 4.编译chainmaker: 编译v1.1.0版本的可执行文件,并替换原v1.0.0版本的可执行文件。

  • 5.修改配置: 按照相应的版本修改所有节点的chainmaker.yml,将bc*.yml中的共识节点地址添加至net:seeds:中。 bc*.yml不要修改!!! bc*.yml不要修改!!! bc*.yml不要修改!!!

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

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

  • 8.编译wasm文件: 使用和chainmaker-go相同版本的合约SDK编译新的wasm文件。

  • 9.升级合约: 使用新的合约升级以前版本的合约。

  • 10.升级配套工具: 如果有使用sdk或者cmc工具,请将sdkcmc版本升级为v1.1.0,否则可能会导致交易失败。

3.8.3. 新添加节点注意事项

1.新节点的bc*.yml文件必须与v1.0.0版本时期保持一致,无需修改为v1.1.0版本。v1.1.0版本程序已对其做了兼容,如果修改bc*.yml会导致创世块不一致,无法完成同步。

2.新节点的chainmaker.yml文件需要与v1.1.0版本保持一致,即需要将共识节点地址添加至net:seeds:配置项中。