本文档介绍如何将 gaiad 全节点升级到新版本。

​
Cosmovisor

Cosmos SDK 提供了一个便捷的进程管理器，它封装在 gaiad 二进制之上，并且可以在治理升级提案成功通过后自动切换到新的二进制文件。Cosmovisor 完全是可选的，但推荐使用。更多信息请参阅 cosmos.network 文档 和 cosmos-sdk/cosmovisor/readme。

​
设置

要开始使用 Cosmovisor，先下载它 
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor
设置环境变量 
echo "# Setup Cosmovisor" >> ~/.profile
echo "export DAEMON_NAME=gaiad" >> ~/.profile
echo "export DAEMON_HOME=$HOME/.gaia" >> ~/.profile
source ~/.profile
创建相应目录 
mkdir -p ~/.gaia/cosmovisor/upgrades
mkdir -p ~/.gaia/cosmovisor/genesis/bin/
cp $(which gaiad) ~/.gaia/cosmovisor/genesis/bin/

# 验证设置。
# 它应返回与 gaiad 相同的版本
cosmovisor version
现在可以通过运行以下命令启动 gaiad 
cosmovisor start

​
为升级做准备

Cosmovisor 会持续轮询 $DAEMON_HOME/data/upgrade-info.json 以获取新的升级指令。当升级准备就绪时，节点运营者可以下载新的二进制文件，并将其放到 $DAEMON_HOME/cosmovisor/upgrades/<name>/bin 目录下，其中 <name> 是升级模块计划中指定的、经过 URI 编码的升级名称。 也可以让 Cosmovisor 自动下载新的二进制文件。为此请设置以下环境变量。 
export DAEMON_ALLOW_DOWNLOAD_BINARIES=true

​
手动软件升级

先停止你的 gaiad 实例。然后升级软件： 
cd gaia
git fetch --all && git checkout <new_version>
make install
注意：如果你在这一步遇到问题，请检查是否已安装最新稳定版的 Go。
有关每个公共测试网需要哪个版本的详细信息，请参阅 测试网仓库；有关各个版本发布的详细信息，请参阅 Gaia 发布页面。 你的全节点现已完成无缝升级！如果没有破坏性变更，你只需运行以下命令重新启动节点： 
gaiad start

​
升级 genesis 文件

如果你要升级到的新版本包含破坏性变更，你将不得不重新启动你的链。如果不包含破坏性变更，你可以跳转到 重启
要升级 genesis 文件，你可以从可信来源获取它，或在本地导出它。

​
从可信来源获取

如果你要加入主网，请从 主网仓库 获取 genesis。如果你要加入公共测试网，请从 测试网仓库 中对应的测试网获取 genesis。否则，请从你信任的来源获取。 将新的 genesis 保存为 new_genesis.json。然后用 new_genesis.json 替换旧的 genesis.json 
cd $HOME/.gaia/config
cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json
然后，前往重置数据部分。

​
在本地将状态导出为新的 genesis

如果你此前在该网络的旧版本上运行节点，并且希望基于该旧网络的状态在本地构建新的 genesis，请使用以下命令： 
cd $HOME/.gaia/config
gaiad export --for-zero-height --height=<export-height> > new_genesis.json
上述命令会获取某个高度 <export-height> 的状态，并将其转换为一个新的 genesis 文件，用于启动新网络。 然后，用 new_genesis.json 替换旧的 genesis.json。 
cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json
此时，你可能需要运行一个脚本，把导出的 genesis 更新为与你的新版本兼容的 genesis。例如，Account 类型的属性发生了变化，那么脚本应从账户存储中查询已编码的账户数据，对其进行反序列化，更新其类型，然后重新序列化并写回存储。你可以在这里找到此类脚本的示例。

​
重置数据

如果你要升级到的版本 new_version 与前一个版本相比不包含破坏性变更，则不应重置数据。如果不包含破坏性变更，你可以跳转到 重启
如果你在主网上运行的是验证者节点，执行 gaiad unsafe-reset-all 时务必始终小心。如果你不是在切换 chain-id，绝不应使用此命令。
::: danger 重要 确保每个节点都有唯一的 priv_validator.json。不要把旧节点的 priv_validator.json 复制到多个新节点。运行两个使用相同 priv_validator.json 的节点会导致你因双签而被罚没！ 首先，删除过期文件并重置数据。如果你运行的是验证者节点，请务必先确认你完全理解重置操作的影响再执行。 
gaiad unsafe-reset-all
你的节点现在已回到干净状态，同时会保留原始的 priv_validator.json 和 config.toml。如果你之前配置了任何哨兵节点或全节点，你的节点仍会尝试连接它们，但如果它们也尚未完成升级，连接可能会失败。 :::

​
重启

如果没有破坏性变更，你只需运行以下命令重新启动节点： 
gaiad start
This document describes the upgrade procedure of a gaiad full-node to a new version.

​
Cosmovisor

The Cosmos SDK provides a convenient process manager that wraps around the gaiad binary and can automatically swap in new binaries upon a successful governance upgrade proposal. Cosmovisor is entirely optional but recommended. More information can be found in cosmos.network docs and cosmos-sdk/cosmovisor/readme.

​
Setup

To get started with Cosmovisor first download it 
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor
Set up the environment variables 
echo "# Setup Cosmovisor" >> ~/.profile
echo "export DAEMON_NAME=gaiad" >> ~/.profile
echo "export DAEMON_HOME=$HOME/.gaia" >> ~/.profile
source ~/.profile
Create the appropriate directories 
mkdir -p ~/.gaia/cosmovisor/upgrades
mkdir -p ~/.gaia/cosmovisor/genesis/bin/
cp $(which gaiad) ~/.gaia/cosmovisor/genesis/bin/

# verify the setup. 
# It should return the same version as gaiad
cosmovisor version
Now gaiad can start by running 
cosmovisor start

​
Preparing an Upgrade

Cosmovisor will continually poll the $DAEMON_HOME/data/upgrade-info.json for new upgrade instructions. When an upgrade is ready, node operators can download the new binary and place it under $DAEMON_HOME/cosmovisor/upgrades/<name>/bin where <name> is the URI-encoded name of the upgrade as specified in the upgrade module plan. It is possible to have Cosmovisor automatically download the new binary. To do this set the following environment variable. 
export DAEMON_ALLOW_DOWNLOAD_BINARIES=true

​
Manual Software Upgrade

First, stop your instance of gaiad. Next, upgrade the software: 
cd gaia
git fetch --all && git checkout <new_version>
make install
NOTE: If you have issues at this step, please check that you have the latest stable version of GO installed.
See the testnet repo for details on which version is needed for which public testnet, and the Gaia release page for details on each release. Your full node has been cleanly upgraded! If there are no breaking changes then you can simply restart the node by running: 
gaiad start

​
Upgrade Genesis File

If the new version you are upgrading to has breaking changes, you will have to restart your chain. If it is not breaking, you can skip to Restart
To upgrade the genesis file, you can either fetch it from a trusted source or export it locally.

​
Fetching from a Trusted Source

If you are joining the mainnet, fetch the genesis from the mainnet repo. If you are joining a public testnet, fetch the genesis from the appropriate testnet in the testnet repo. Otherwise, fetch it from your trusted source. Save the new genesis as new_genesis.json. Then replace the old genesis.json with new_genesis.json 
cd $HOME/.gaia/config
cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json
Then, go to the reset data section.

​
Exporting State to a New Genesis Locally

If you were running a node in the previous version of the network and want to build your new genesis locally from a state of this previous network, use the following command: 
cd $HOME/.gaia/config
gaiad export --for-zero-height --height=<export-height> > new_genesis.json
The command above take a state at a certain height <export-height> and turns it into a new genesis file that can be used to start a new network. Then, replace the old genesis.json with new_genesis.json. 
cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json
At this point, you might want to run a script to update the exported genesis into a genesis that is compatible with your new version. For example, the attributes of the Account type changed, a script should query encoded account from the account store, unmarshal them, update their type, re-marshal and re-store them. You can find an example of such script here.

​
Reset Data

If the version new_version you are upgrading to is not breaking from the previous one, you should not reset the data. If it is not breaking, you can skip to Restart
If you are running a validator node on the mainnet, always be careful when doing gaiad unsafe-reset-all. You should never use this command if you are not switching chain-id.
::: danger IMPORTANT Make sure that every node has a unique priv_validator.json. Do not copy the priv_validator.json from an old node to multiple new nodes. Running two nodes with the same priv_validator.json will cause you to get slashed due to double signing! First, remove the outdated files and reset the data. If you are running a validator node, make sure you understand what you are doing before resetting. 
gaiad unsafe-reset-all
Your node is now in a pristine state while keeping the original priv_validator.json and config.toml. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven’t also been upgraded.

​
Restart

If there are no breaking changes then you can simply restart the node by running: 
gaiad start