# 版本升级操作指南 ## 概述 本文档主要描述将已在运行的chainmaker旧版本升级为新版本的步骤,正常情况下,伴随着新版发布,都会有相应的升级描述。本文档根据版本号倒序排版,即最新版本升级描述会在最前面,请读者注意。 ## v1.2.0 -> v1.2.3版本升级指南 v1.2.3兼容v1.2.0,升级时只需要替换相应二进制文件(无需修改配置文件),并重启所有节点。升级所有生态工具即可。 [升级步骤参考](#upgradeStep) ## v1.1.1 -> v1.2.0版本升级指南 v1.2.0兼容v1.1.1,升级时只需要替换相应二进制文件(无需修改配置文件),并重启所有节点。升级所有生态工具即可。 [升级步骤参考](#upgradeStep) ## v1.1.0 -> v1.2.3版本升级指南 ### 链配置变更说明 从v1.1.1版本开始,各个存储模块可以独立配置。更加方便对存储数据库根据不同场景选用不同配置。同时也对存储结构做了些调整。升级时需要更新所有数据文件。 从v1.1.1版本开始,支持串行sql合约的执行。开启sql合约需要修改创世块配置文件bcN.yml:contract.enable_sql_support=true。故不支持从以前版本直接升级为可运行sql合约的链。只能部署新版本。 ### 升级操作步骤 #### 步骤 ***写在最前面:建议所有操作都备份** - **1.停止交易:** 停止所有向节点发交易请求,即不要再让链出新块。 - **2.确认同步:** 确认现有全部节点状态已同步到一致,即块高度一致。 - **3.停止节点:** 停止所有节点服务。 - **4.编译chainmaker:** 编译v1.2.3版本的可执行文件,并替换原v1.1.0版本的可执行文件。 - **5.修改配置:** 按照相应的版本[修改所有节点的`chainmaker.yml`](#upgradeNodeConf),`bc*.yml`不要修改!!! `bc*.yml`不要修改!!! `bc*.yml`不要修改!!! - **6.修改数据:**[复制结果集数据,并清洗数据结构。](#cleanData) - **6.启动:** 启动所有节点,观察日志有无错误信息。若使用`cluster_quick_start.sh `命令启动则需要[移除release](../tutorial/快速入门.html#restartNode)下的*tar.gz文件 - **7.链升级成功:** 正常情况下,至此版本升级成功。 - **8.编译wasm文件:** 使用和chainmaker-go相同版本的合约SDK编译新的wasm文件。 - **9.升级合约:** 使用新的合约升级以前版本的合约。 - **10.升级配套工具:** 如果有使用`sdk`或者`cmc`工具,请将`sdk`或`cmc`版本升级为v1.2.3,否则可能会导致交易失败。 #### 修改节点配置 修改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存储配置如下:** ```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` ```yml 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)/ ``` #### 修改数据 **1、复制结果集数据** 复制**每个节点**中的历史数据库为结果集数据库,相应参数如下: chainmakerProject:部署的项目根目录 store_path:为chainmaker.yml文件中的storage.store_path属性的值 chain_id:为chainmaker.yml文件中的blockchain.chainId的值(若有多条链,则需要多次执行该升级步骤) ```sh # 进入数据目录 cd ${chainmakerProject}/${store_path}/${chain_id}/ # 复制结果集数据库 cp -r store_history store_result ``` **2、清洗数据** linux x86 如下操作,其他系统请[下载项目](https://git.chainmaker.org.cn/chainmaker/chainmaker-tools)编译后使用,执行upgrade命令。 - 下载upgradeTool二进制文件(需登录):https://git.chainmaker.org.cn/chainmaker/chainmaker-tools/uploads/2cd5246f9e30ab409592ad435c9e2597/upgradeTool - 执行upgradeTool命令,如下 ```sh # 其中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 ``` ### 新添加节点 若已有正在运行中的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的配置保持一致,[见上](#upgradeNodeConf) - 5、复制数据并使用upgradeTool清理org5的data数据,[见上](#cleanData) - 6、启动org5并等待同步,至此添加新节点完成。(日志搜索:put block即可查看当前区块落库情况) ## v1.1.0 -> v1.1.1版本升级指南 暂不支持升级,请选用最新版本。 ## v1.0.0 -> v1.1.0版本升级指南 从v1.1.0版本开始,共识节点的节点网络地址不再上链,改为只将共识节点的节点ID(NodeID)上链。目的是让节点IP发生变更时,减少运维的操作复杂度,运维人员只需修改本地`chainmaker.yml`文件中的网络配置即可,无需发起链配置变更交易。 ### 链配置变更说明 链配置项中共识节点配置变更说明如下: v1.0.0版本`bc*.yml`中共识配置及权限配置: ```yaml #共识配置 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`中共识配置变更为: ```yaml #共识配置 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`中网络配置: ```yaml 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`中网络配置变更为: ```yaml 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`中合约事件配置: ```yaml 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 ``` ### 升级操作步骤 ***写在最前面:建议所有操作都备份** - **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](../tutorial/快速入门.html#restartNode)下的*tar.gz文件 - **7.链升级成功:** 正常情况下,至此版本升级成功。 - **8.编译wasm文件:** 使用和chainmaker-go相同版本的合约SDK编译新的wasm文件。 - **9.升级合约:** 使用新的合约升级以前版本的合约。 - **10.升级配套工具:** 如果有使用`sdk`或者`cmc`工具,请将`sdk`或`cmc`版本升级为v1.1.0,否则可能会导致交易失败。 ### 新添加节点注意事项 1.新节点的`bc*.yml`文件必须与v1.0.0版本时期保持一致,无需修改为v1.1.0版本。v1.1.0版本程序已对其做了兼容,如果修改`bc*.yml`会导致创世块不一致,无法完成同步。 2.新节点的`chainmaker.yml`文件需要与v1.1.0版本保持一致,即需要将共识节点地址添加至`net:seeds:`配置项中。