6. 版本升级操作指南

6.1. 概述

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

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

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

6.3. v1.2.0、v1.2.3、v1.2.4 -> v1.2.5版本升级指南

v1.2.5兼容v1.2.n各版本，升级时只需要替换相应二进制文件（无需修改配置文件），并重启所有节点。升级对应生态工具即可。

升级步骤参考#upgradeStep)

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

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

升级步骤参考

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

6.5.1. 链配置变更说明

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

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

6.5.2. 升级操作步骤

6.5.2.1. 步骤

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

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

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

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

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

  • 5.修改配置： 按照相应的版本修改所有节点的chainmaker.yml，bc*.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工具，请将sdk或cmc版本升级为v1.2.3,否则可能会导致交易失败。

6.5.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)/

6.5.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

6.5.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即可查看当前区块落库情况）

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

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

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

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

6.7.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_ADD、NODE_ADDR_UPDATE、NODE_ADDR_DELETE全部改为NODE_ID_ADD、NODE_ID_UPDATE、NODE_ID_DELETE，原NODE_ADDR_ADD、NODE_ADDR_UPDATE、NODE_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、rocksdb、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

6.7.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工具，请将sdk或cmc版本升级为v1.1.0,否则可能会导致交易失败。

6.7.3. 新添加节点注意事项

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

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