# 版本升级操作指南
## 概述
本文档主要描述将已在运行的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:`配置项中。