# 版本升级操作指南

## 概述

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

## v2.1.0, v2.2.0 -> v2.2.1版本升级指南

升级流程请参看 [通用升级步骤参考](#upgradeStep)

### 升级 Docker Go VM虚拟机

如果启用了Docker VM虚拟机，除[通用升级步骤参考](#upgradeStep)中的操作外，需要额外做以下操作：

1. **替换启停脚本**
   
   在v2.2.1 版本中Docker VM虚拟机不再由Chainmaker节点程序拉起，
   
   如果Docker VM是本机部署，在第4步编译替换chainmaker的时候，需要同时替换下bin目录下的`start.sh, stop.sh, restart.sh`三个脚本，脚本会处理合约虚拟机的拉起和停止。脚本由`build_release.sh`生成，可以参考[《通过命令行工具启动链》](../tutorial/通过命令行工具启动链.md)。
   
   如果Docker VM是独立部署（比如部署在其他host），可以参考[《Docker VM的部署和启动》](../operation/智能合约.html#dockerVmStandalone)以TCP方式部署启动。

2. **更新vm-docker-go虚拟机镜像**
   
   在第4步替换二进制之后，也需要更新vm-docker-go虚拟机镜像（chainmakerofficial/chainmaker-vm-docker-go）至v2.2.1版本，命令如下：
   
   ```shell
   docker pull chainmakerofficial/chainmaker-vm-docker-go:v2.2.1
   ```

3. **contract-sdk-docker-go 合约升级（强烈建议）**
   
    在第7步启动链成功之后，**强烈建议**更新合约SDK。
   
    更新合约SDK镜像（chainmakerofficial/chainmaker-docker-go-contract）至v2.2.1版本，命令如下：
   
   ```shell
     docker pull chainmakerofficial/chainmaker-docker-go-contract:v2.2.1
   ```
   如果是v2.2.0之前的合约文件还需要对合约源码进行一些修改，参考[v2.1.0 -> v2.2.0版本升级指南](#upgradeTo220)升级合约文件。

<span id="upgradeTo220"></span>

## v2.1.0 -> v2.2.0版本升级指南

由于版本v2.2.0使用了新版本的wasm引擎，请注意在执行 [通用升级步骤参考](#upgradeStep) 的第4步时，需要同时将 ./main/libwasmer_runtime_c_api.so 文件复制为生产环境的 /usr/lib64/libwasmer.so 文件。

### vm-docker-go 虚拟机引擎升级

如果启用了vm-docker-go虚拟机（必须）， [通用升级步骤参考](#upgradeStep)中需要额外做以下操作：

其中，在第3步停止节点之后，需要更新vm-docker-go虚拟机镜像（chainmakerofficial/chainmaker-vm-docker-go）至v2.2.0.1版本，命令如下：

```shell
docker pull chainmakerofficial/chainmaker-vm-docker-go:v2.2.0.1
```

### contract-sdk-docker-go 合约升级（强烈建议）

在第7步启动链成功之后，**强烈建议**更新合约SDK。

更新合约SDK镜像（chainmakerofficial/chainmaker-docker-go-contract）至v2.2.0.1版本，命令如下：

```shell
docker pull chainmakerofficial/chainmaker-docker-go-contract:v2.2.0.1
```

在第8步编译合约文件之前，还需要对合约源码进行一些修改，修改内容如下，[【合约编译步骤参考】](../operation/智能合约.md)：

v2.1.0版本合约源码示例如下：

```go
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路径需要更新）：

```go
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---
```



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

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

[通用升级步骤参考](#upgradeStep)

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

<span id="upgradeStep"></span>

## 通用升级操作步骤

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

- **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`版本升级为和链一致的版本,否则可能会导致交易失败。

### 新添加节点注意事项

1.新节点的`bc*.yml`文件必须与旧版本时期保持一致（路径参数则需要路径对应的内容保持一致），无需修改为新的版本。新的版本程序已对其做了兼容，如果修改`bc*.yml`会导致创世块不一致，无法完成同步。

2.新节点的`chainmaker.yml`文件需要与新的版本格式保持一致。



<br><br>