2. 版本升级说明
2.1. 概述
本文档主要描述将旧版本chainmaker升级为新版本的步骤，正常情况下，伴随着新版发布，都会有相应的升级描述。本文档根据版本号倒序排版，即最新版本升级描述会在最前面，请读者注意。
2.2. 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.2.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相关的配置项如下：
只运行旧版本合约，请参考《支持旧版本Docker VM》。
只运行新版本合约，请参考《支持新版本Docker VM》。
同时运行新旧版本合约，或存在旧版本合约升级到新版本合约的操作，需要同时进行上述两种配置。
4. 合约升级（推荐）
在通用升级步骤参考第7步启动链成功之后，推荐更新合约SDK并重新编译合约。
合约SDK主要变更如下：
package import 路径变更
添加key、field校验，仅支持数字、字母以及._-
新增
Contract合约接口方法UpgradeContract，合约升级时由调用InitContract改为调用UpgradeContract更新
Contract合约接口方法InvokeContract，由之前的传递CMStubInterface来获取method，改为入参传递method，无需再传递stub手动获取methodSDK使用方式变更，由之前每个函数入参传递一个
CMStubInterface实例来使用SDK接口方法改为通过sdk.Instance全局变量来使用SDK提供的接口方法。
v2.3.0版本合约编写请参考：《使用Golang进行智能合约开发》。
2.3. 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.3.1. 升级 Docker Go VM虚拟机
如果启用了Docker VM虚拟机，除通用升级步骤参考中的操作外，需要额外做以下操作：
替换启停脚本
在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的链》。
更新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
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.4. v2.1.0 -> v2.2.0版本升级指南
由于版本v2.2.0使用了新版本的wasm引擎，请注意在执行 通用升级步骤参考 的第4步时，需要同时将 ./main/libwasmer_runtime_c_api.so 文件复制为生产环境的 /usr/lib64/libwasmer.so 文件。
2.4.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.4.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.5. v2.0.0 -> v2.1.0版本升级指南
v2.1.0兼容v2.0.0，升级时只需要替换相应二进制文件（无需修改配置文件），并重启所有节点。升级所有生态工具即可。
从历史版本升级为 v2.1.0版本，新功能只支持自研网络（需将所有节点停止，并修改chainmaker.yml文件的net.provider为liquid后，再启动）。若想体验其他新功能如java国密、公钥身份、透明加密等，请重新安装新版本ChainMaker。
2.6. 通用升级操作步骤
写在最前面：建议所有操作都备份
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工具，请将sdk或cmc版本升级为和链一致的版本,否则可能会导致交易失败。
2.6.1. 新添加节点注意事项
1.新节点的bc*.yml文件必须与旧版本时期保持一致（路径参数则需要路径对应的内容保持一致），无需修改为新的版本。新的版本程序已对其做了兼容，如果修改bc*.yml会导致创世块不一致，无法完成同步。
2.新节点的chainmaker.yml文件需要与新的版本格式保持一致。