Cosmovisor

• 设计
• 贡献
• 设置
  • 安装
  • 命令行参数和环境变量
  • 目录布局
• 使用
  • 初始化
  • 检测升级
  • 添加升级二进制文件
  • 自动下载
  • 为升级做准备
• 示例：SimApp 升级
  • 链设置
    • 准备 Cosmovisor 并启动链
  • 更新应用

​

设计

• 它会将参数传递给关联的应用（由 DAEMON_NAME 环境变量配置）。 运行 cosmovisor run arg1 arg2 .... 将会执行 app arg1 arg2 ...；
• 它会在需要时通过重启和升级来管理应用；
• 它使用环境变量进行配置，而不是位置参数。

​

贡献

​

设置

​

安装

go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

go install cosmossdk.io/tools/cosmovisor/cmd/[email protected]

​

命令行参数和环境变量

• help、--help 或 -h - 输出 cosmovisor 帮助信息，并检查你的 cosmovisor 配置。
• run - 使用其余提供的参数运行已配置的二进制文件。
• version - 输出 cosmovisor 版本，同时使用 version 参数运行该二进制文件。
• config - 显示当前 cosmovisor 配置，即显示 cosmovisor 正在使用的环境变量值。
• add-upgrade - 手动向 cosmovisor 添加一个升级。此命令允许你轻松将某次升级对应的二进制文件添加到 cosmovisor 中。
• add-batch-upgrade - 一次性添加多个升级。
• show-upgrade-info - 显示来自 upgrade-info.json 文件的当前升级信息。

• DAEMON_HOME 是保存 cosmovisor/ 目录的位置，该目录包含创世二进制文件、升级二进制文件，以及与每个二进制文件关联的其他辅助文件（例如 $HOME/.gaiad、$HOME/.regend、$HOME/.simd 等）。
• DAEMON_NAME 是二进制文件本身的名称（例如 gaiad、regend、simd 等）。
• DAEMON_ALLOW_DOWNLOAD_BINARIES（可选），如果设置为 true，将启用新二进制文件的自动下载（出于安全原因，这主要面向全节点而非验证者）。默认情况下，cosmovisor 不会自动下载新二进制文件。
• DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM（可选，默认 = false），如果为 true，cosmovisor 将要求升级计划中为待下载的二进制文件提供校验和。如果为 false，cosmovisor 不会强制要求提供校验和，但如果提供了仍会进行校验。
• DAEMON_RESTART_AFTER_UPGRADE（可选，默认 = true），如果为 true，升级成功后会使用相同的命令行参数和标志重新启动子进程（但使用新的二进制文件）。否则（false），cosmovisor 会在升级后停止运行，并要求系统管理员手动重启。注意，这里的重启只发生在升级之后，不会在子进程出错后自动重启。
• DAEMON_RESTART_DELAY（可选，默认无），允许节点运营者定义节点停机（用于升级）与在指定时间后重新启动之间的延迟。该值必须是一个时长（例如 1s）。
• DAEMON_SHUTDOWN_GRACE（可选，默认无），如果设置了该值，会先向二进制文件发送中断信号，并等待指定时间，以便在发送 kill 信号前完成清理或将缓存刷新到磁盘。该值必须是一个时长（例如 1s）。
• DAEMON_POLL_INTERVAL（可选，默认 300 毫秒），是轮询升级计划文件的时间间隔。该值必须是一个时长（例如 1s）。
• DAEMON_DATA_BACKUP_DIR 用于设置自定义备份目录。如果未设置，则使用 DAEMON_HOME。
• UNSAFE_SKIP_BACKUP（默认 false），如果设置为 true，则直接升级而不执行备份。否则（false，默认），会在尝试升级前备份数据。默认值 false 在发生故障以及需要通过备份回滚时非常有用，也更推荐使用。我们建议使用默认备份选项 UNSAFE_SKIP_BACKUP=false。
• DAEMON_PREUPGRADE_MAX_RETRIES（默认 0）。在收到退出状态 31 后，对 pre-upgrade 进行重试的最大次数。默认值 0 表示单次返回退出状态 31 就会立即导致升级失败。在重试次数耗尽后，Cosmovisor 会将该次升级标记为失败。
• DAEMON_GRPC_ADDRESS（可选，默认 localhost:9090）。节点的 gRPC 地址，由 prepare-upgrade 命令和批量升级监视器使用。
• COSMOVISOR_DISABLE_LOGS（默认 false）。如果设置为 true，将完全禁用 Cosmovisor 的日志（但不会禁用底层进程的日志）。例如，当你执行的某个 Cosmovisor 子命令返回有效 JSON，而你随后需要解析它时，这会很有用，因为 Cosmovisor 追加的日志会使输出不再是有效 JSON。
• COSMOVISOR_COLOR_LOGS（默认 true）。如果设置为 true，将为 Cosmovisor 日志添加颜色（但不会影响底层进程）。
• COSMOVISOR_TIMEFORMAT_LOGS（默认 kitchen）。如果设置为某个值（layout|ansic|unixdate|rubydate|rfc822|rfc822z|rfc850|rfc1123|rfc1123z|rfc3339|rfc3339nano|kitchen），将为 Cosmovisor 日志添加时间戳前缀（但不会影响底层进程）。
• COSMOVISOR_CUSTOM_PREUPGRADE（默认 \`）。如果设置了该值，则会在升级之前，使用参数 [ upgrade.Name, upgrade.Height ]运行$DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE`。这会执行一个自定义脚本（独立于链守护进程的 pre-upgrade 命令，且在其之前执行）。
• COSMOVISOR_DISABLE_RECASE（默认 false）。如果设置为 true，则升级目录必须与升级计划名称完全匹配，不做任何大小写转换。

​

目录布局

.
├── current -> genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── $DAEMON_NAME
└── upgrades
│   └── <name>
│       ├── bin
│       │   └── $DAEMON_NAME
│       └── upgrade-info.json
└── preupgrade.sh (optional)

.simapp
├── config
├── data
└── cosmovisor

​

使用

• 安装 cosmovisor 二进制文件
• 配置主机的 init 系统（例如 systemd、launchd 等）
• 正确设置环境变量
• 创建 <DAEMON_HOME>/cosmovisor 目录
• 创建 <DAEMON_HOME>/cosmovisor/genesis/bin 目录
• 创建 <DAEMON_HOME>/cosmovisor/upgrades/<name>/bin 目录
• 将不同版本的 <DAEMON_NAME> 可执行文件放入对应的 bin 目录中。

​

初始化

• 如果 <DAEMON_HOME>/cosmovisor 文件夹尚不存在，则创建它
• 如果 <DAEMON_HOME>/cosmovisor/genesis/bin 文件夹尚不存在，则创建它
• 将提供的可执行文件复制到 <DAEMON_HOME>/cosmovisor/genesis/bin/<DAEMON_NAME>
• 创建指向 genesis 文件夹的 current 链接

​

检测升级

• 启动时，cosmovisor 对当前正在运行的升级了解不多，除了当前二进制文件位于 current/bin/。它会尝试读取 current/upgrade-info.json 文件，以获取当前升级名称的信息。
• 如果 cosmovisor/current/upgrade-info.json 和 data/upgrade-info.json 都不存在，那么 cosmovisor 会等待 data/upgrade-info.json 文件出现来触发升级。
• 如果 cosmovisor/current/upgrade-info.json 不存在，但 data/upgrade-info.json 存在，那么 cosmovisor 会假定 data/upgrade-info.json 中的内容是一个有效的升级请求。在这种情况下，cosmovisor 会立即尝试根据 data/upgrade-info.json 中的 name 属性执行升级。
• 否则，cosmovisor 会等待 upgrade-info.json 发生变化。一旦文件中记录了新的升级名称，cosmovisor 就会触发升级机制。

1. 如果启用了 DAEMON_ALLOW_DOWNLOAD_BINARIES，首先自动将新的二进制文件下载到 cosmovisor/<name>/bin（其中 <name> 是 upgrade-info.json:name 属性）；
2. 更新 current 符号链接，使其指向新目录，并将 data/upgrade-info.json 保存到 cosmovisor/current/upgrade-info.json。

​

添加升级二进制文件

​

自动下载

1. 在升级计划的 info 字段中，以 JSON 格式在 `

​

更新应用

make build

cosmovisor add-upgrade v047-to-v050 ./build/simd

./build/simd tx upgrade software-upgrade v047-to-v050 --title upgrade --summary upgrade --upgrade-height 200 --upgrade-info "{}" --no-validate --from validator --yes
./build/simd tx gov deposit 1 10000000stake --from validator --yes
./build/simd tx gov vote 1 yes --from validator --yes

​

升级前处理

func preUpgradeCommand() *cobra.Command {
    return &cobra.Command{
        Use:   "pre-upgrade",
        Short: "Pre-upgrade command",
        Run: func(cmd *cobra.Command, args []string) {
            if err := HandlePreUpgrade(); err != nil {
                os.Exit(30)
            }
            os.Exit(0)
        },
    }
}

rootCmd.AddCommand(
    // ..
    preUpgradeCommand(),
)

• Design
• Contributing
• Setup
  • Installation
  • Command Line Arguments And Environment Variables
  • Folder Layout
• Usage
  • Initialization
  • Detecting Upgrades
  • Adding Upgrade Binary
  • Auto-Download
  • Preparing for an Upgrade
• Example: SimApp Upgrade
  • Chain Setup
    • Prepare Cosmovisor and Start the Chain
  • Update App

​

Design

• it will pass arguments to the associated app (configured by DAEMON_NAME env variable). Running cosmovisor run arg1 arg2 .... will run app arg1 arg2 ...;
• it will manage an app by restarting and upgrading if needed;
• it is configured using environment variables, not positional arguments.

​

Contributing

​

Setup

​

Installation

go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

go install cosmossdk.io/tools/cosmovisor/cmd/[email protected]

​

Command Line Arguments And Environment Variables

• help, --help, or -h - Output cosmovisor help information and check your cosmovisor configuration.
• run - Run the configured binary using the rest of the provided arguments.
• version - Output the cosmovisor version and also run the binary with the version argument.
• config - Display the current cosmovisor configuration, that means displaying the environment variables value that cosmovisor is using.
• add-upgrade - Add an upgrade manually to cosmovisor. This command allow you to easily add the binary corresponding to an upgrade in cosmovisor.
• add-batch-upgrade - Add multiple upgrades at once.
• show-upgrade-info - Show the current upgrade info from the upgrade-info.json file.

• DAEMON_HOME is the location where the cosmovisor/ directory is kept that contains the genesis binary, the upgrade binaries, and any additional auxiliary files associated with each binary (e.g. $HOME/.gaiad, $HOME/.regend, $HOME/.simd, etc.).
• DAEMON_NAME is the name of the binary itself (e.g. gaiad, regend, simd, etc.).
• DAEMON_ALLOW_DOWNLOAD_BINARIES (optional), if set to true, will enable auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators). By default, cosmovisor will not auto-download new binaries.
• DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM (optional, default = false), if true cosmovisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If false, cosmovisor will not require a checksum to be provided, but still check the checksum if one is provided.
• DAEMON_RESTART_AFTER_UPGRADE (optional, default = true), if true, restarts the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (false), cosmovisor stops running after an upgrade and requires the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs.
• DAEMON_RESTART_DELAY (optional, default none), allow a node operator to define a delay between the node halt (for upgrade) and backup by the specified time. The value must be a duration (e.g. 1s).
• DAEMON_SHUTDOWN_GRACE (optional, default none), if set, send interrupt to binary and wait the specified time to allow for cleanup/cache flush to disk before sending the kill signal. The value must be a duration (e.g. 1s).
• DAEMON_POLL_INTERVAL (optional, default 300 milliseconds), is the interval length for polling the upgrade plan file. The value must be a duration (e.g. 1s).
• DAEMON_DATA_BACKUP_DIR option to set a custom backup directory. If not set, DAEMON_HOME is used.
• UNSAFE_SKIP_BACKUP (defaults to false), if set to true, upgrades directly without performing a backup. Otherwise (false, default) backs up the data before trying the upgrade. The default value of false is useful and recommended in case of failures and when a backup needed to rollback. We recommend using the default backup option UNSAFE_SKIP_BACKUP=false.
• DAEMON_PREUPGRADE_MAX_RETRIES (defaults to 0). The maximum number of times to retry pre-upgrade after exit status of 31. With the default of 0, a single exit-31 result immediately fails the upgrade. After retries are exhausted, Cosmovisor fails the upgrade.
• DAEMON_GRPC_ADDRESS (optional, default localhost:9090). The gRPC address of the node, used by the prepare-upgrade command and the batch upgrade watcher.
• COSMOVISOR_DISABLE_LOGS (defaults to false). If set to true, this will disable Cosmovisor logs (but not the underlying process) completely. This may be useful, for example, when a Cosmovisor subcommand you are executing returns a valid JSON you are then parsing, as logs added by Cosmovisor make this output not a valid JSON.
• COSMOVISOR_COLOR_LOGS (defaults to true). If set to true, this will colorize Cosmovisor logs (but not the underlying process).
• COSMOVISOR_TIMEFORMAT_LOGS (defaults to kitchen). If set to a value (layout|ansic|unixdate|rubydate|rfc822|rfc822z|rfc850|rfc1123|rfc1123z|rfc3339|rfc3339nano|kitchen), this will add timestamp prefix to Cosmovisor logs (but not the underlying process).
• COSMOVISOR_CUSTOM_PREUPGRADE (defaults to “). If set, this will run $DAEMON\_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE prior to upgrade with the arguments [ upgrade.Name, upgrade.Height ]. Executes a custom script (separate and prior to the chain daemon pre-upgrade command)
• COSMOVISOR_DISABLE_RECASE (defaults to false). If set to true, the upgrade directory will expected to match the upgrade plan name without any case changes

​

Folder Layout

.
├── current -> genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── $DAEMON_NAME
└── upgrades
│   └── <name>
│       ├── bin
│       │   └── $DAEMON_NAME
│       └── upgrade-info.json
└── preupgrade.sh (optional)

.simapp
├── config
├── data
└── cosmovisor

​

Usage

• installing the cosmovisor binary
• configuring the host’s init system (e.g. systemd, launchd, etc.)
• appropriately setting the environmental variables
• creating the <DAEMON_HOME>/cosmovisor directory
• creating the <DAEMON_HOME>/cosmovisor/genesis/bin folder
• creating the <DAEMON_HOME>/cosmovisor/upgrades/<name>/bin folders
• placing the different versions of the <DAEMON_NAME> executable in the appropriate bin folders.

​

Initialization

• creates the <DAEMON_HOME>/cosmovisor folder if it doesn’t yet exist
• creates the <DAEMON_HOME>/cosmovisor/genesis/bin folder if it doesn’t yet exist
• copies the provided executable file to <DAEMON_HOME>/cosmovisor/genesis/bin/<DAEMON_NAME>
• creates the current link, pointing to the genesis folder

​

Detecting Upgrades

• When starting, cosmovisor doesn’t know much about currently running upgrade, except the binary which is current/bin/. It tries to read the current/upgrade-info.json file to get information about the current upgrade name.
• If neither cosmovisor/current/upgrade-info.json nor data/upgrade-info.json exist, then cosmovisor will wait for data/upgrade-info.json file to trigger an upgrade.
• If cosmovisor/current/upgrade-info.json doesn’t exist but data/upgrade-info.json exists, then cosmovisor assumes that whatever is in data/upgrade-info.json is a valid upgrade request. In this case cosmovisor tries immediately to make an upgrade according to the name attribute in data/upgrade-info.json.
• Otherwise, cosmovisor waits for changes in upgrade-info.json. As soon as a new upgrade name is recorded in the file, cosmovisor will trigger an upgrade mechanism.

1. if DAEMON_ALLOW_DOWNLOAD_BINARIES is enabled, start by auto-downloading a new binary into cosmovisor/<name>/bin (where <name> is the upgrade-info.json:name attribute);
2. update the current symbolic link to point to the new directory and save data/upgrade-info.json to cosmovisor/current/upgrade-info.json.

​

Adding Upgrade Binary

​

Auto-Download

1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the "binaries" key. For example:
   {
     "binaries": {
       "linux/amd64": "https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
     }
   }
   
   You can include multiple binaries at once to ensure more than one environment will receive the correct binaries:
   {
     "binaries": {
       "linux/amd64": "https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f",
       "linux/arm64": "https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f",
       "darwin/amd64": "https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
     }
   }
   
   When submitting this as a proposal ensure there are no spaces. An example command using gaiad could look like:
   > gaiad tx upgrade software-upgrade Vega \
   --title Vega \
   --deposit 100uatom \
   --upgrade-height 7368420 \
   --upgrade-info '{"binaries":{"linux/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-amd64","linux/arm64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-arm64","darwin/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-darwin-amd64"}}' \
   --summary "upgrade to Vega" \
   --gas 400000 \
   --from user \
   --chain-id test \
   --home test/val2 \
   --node tcp://localhost:36657 \
   --yes
   

   See all 12 lines
2. Store a link to a file that contains all information in the above format (e.g. if you want to specify lots of binaries, changelog info, etc. without filling up the blockchain). For example:
   https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e
   

sha256sum ./testdata/repo/zip_directory/autod.zip

​

Preparing for an Upgrade

cosmovisor prepare-upgrade

1. Retrieves upgrade information directly from the blockchain about the next scheduled upgrade.
2. Downloads the new binary specified in the upgrade plan.
3. Verifies the binary’s checksum (if required by configuration).
4. Places the new binary in the appropriate directory for Cosmovisor to use during the upgrade.

• The name and height of the upcoming upgrade
• The URL from which the new binary is being downloaded
• Confirmation of successful completion

INFO Preparing for upgrade name=v1.0.0 height=1000000
INFO Downloading upgrade binary url=https://example.com/binary/v1.0.0?checksum=sha256:339911508de5e20b573ce902c500ee670589073485216bee8b045e853f24bce8
INFO Upgrade preparation complete name=v1.0.0 height=1000000

​

Example: SimApp Upgrade

​

Chain Setup

git checkout v0.47.4
make build

./build/simd tendermint unsafe-reset-all

./build/simd config chain-id test
./build/simd config keyring-backend test
./build/simd config broadcast-mode sync

./build/simd init test --chain-id test --overwrite

cat <<< $(jq '.app_state.gov.params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json

./build/simd keys add validator
./build/simd genesis add-genesis-account validator 1000000000stake --keyring-backend test
./build/simd genesis gentx validator 1000000stake --chain-id test
./build/simd genesis collect-gentxs

​

Prepare Cosmovisor and Start the Chain

export DAEMON_NAME=simd
export DAEMON_HOME=$HOME/.simapp

export DAEMON_RESTART_AFTER_UPGRADE=true

cosmovisor init ./build/simd

cosmovisor run start

​

Update App

make build

cosmovisor add-upgrade v047-to-v050 ./build/simd

./build/simd tx upgrade software-upgrade v047-to-v050 --title upgrade --summary upgrade --upgrade-height 200 --upgrade-info "{}" --no-validate --from validator --yes
./build/simd tx gov deposit 1 10000000stake --from validator --yes
./build/simd tx gov vote 1 yes --from validator --yes

​

Pre-Upgrade Handling

func preUpgradeCommand() *cobra.Command {
    return &cobra.Command{
        Use:   "pre-upgrade",
        Short: "Pre-upgrade command",
        Run: func(cmd *cobra.Command, args []string) {
            if err := HandlePreUpgrade(); err != nil {
                os.Exit(30)
            }
            os.Exit(0)
        },
    }
}

rootCmd.AddCommand(
    // ..
    preUpgradeCommand(),
)