011、数据库管理之Tiup

TiUP介绍

TiUP： 是TiDb 4.0版本引入的集群运维工具，通过TiUP可以进行TiDB的日常运维工作，包括部署、启动、关闭、销毁、弹性扩缩容和升级TiDB集群，以及管理TiDB集群参数。

TiUP 使用

tiup [flags] <ommand> [args ..]  	# 执行命令

tiup [flags] <component> [args...]  # 运行组件

示例

tiup list --installed  列出所有组件

tiup install tidb		列出tidb组件

帮助信息

tiup --help

TiUP is a command-line component management tool that can help to download and install
TiDB platform components to the local system. You can run a specific version of a component via
"tiup [:version]". If no version number is specified, the latest version installed
locally will be used. If the specified component does not have any version installed locally,
the latest stable version will be downloaded from the repository.

Usage:
  tiup [flags] <command> [args...]
  tiup [flags] <component> [args...]

Available Commands:
  install     Install a specific version of a component
  list        List the available TiDB components or versions
  uninstall   Uninstall components or versions of a component
  update      Update tiup components to the latest version
  status      List the status of instantiated components
  clean       Clean the data of instantiated components
  mirror      Manage a repository mirror for TiUP components
  help        Help about any command or component

Components Manifest:
  use "tiup list" to fetch the latest components manifest

Flags:
      --binary <component>[:version]   Print binary path of a specific version of a component <component>[:version]
                                       and the latest version installed will be selected if no version specified
      --binpath string                 Specify the binary path of component instance
  -h, --help                           help for tiup
  -T, --tag string                     Specify a tag for component instance
  -v, --version                        version for tiup

Component instances with the same "tag" will share a data directory ($TIUP_HOME/data/$tag):
  $ tiup --tag mycluster playground

Examples:
  $ tiup playground                    # Quick start
  $ tiup playground nightly            # Start a playground with the latest nightly version
  $ tiup install <component>[:version] # Install a component of specific version
  $ tiup update --all                  # Update all installed components to the latest version
  $ tiup update --nightly              # Update all installed components to the nightly version
  $ tiup update --self                 # Update the "tiup" to the latest version
  $ tiup list                          # Fetch the latest supported components list
  $ tiup status                        # Display all running/terminated instances
  $ tiup clean <name>                  # Clean the data of running/terminated instance (Kill process if it's running)
  $ tiup clean --all                   # Clean the data of all running/terminated instances

Use "tiup [command] --help" for more information about a command.

可以只关注两部分：

• 可用的命令

install：用于安装组件
list：查看可用组件列表
uninstall：卸载组件
update：更新组件版本
status：查看组件运行记录
clean：清除组件运行记录
mirror：从官方镜像克隆一个私有镜像
help：输出帮助信息

• 可用的组件

playground：在本机启动集群
client：连接本机的集群
cluster：部署用于生产环境的集群
bench：对数据库进行压力测试

• 命令和组件的区别
  命令和组件的区别在于，命令是 TiUP 自带的，用于进行包管理的操作。而组件是 TiUP 通过包管理操作安装的独立组件包。比如执行 tiup list 命令，TiUP 会直接运行自己内部的代码，而执行 tiup playground 命令则会先检查本地有没有叫做 playground 的组件包，若没有则先从镜像上下载过来，然后运行这个组件包。

TiUP 组件

TiUP 程序只包含少数几个命令，用来下载、更新、卸载组件。TiUP 通过各种组件来扩展其功能。组件是一个可以运行的程序或脚本，通过 tiup 运行组件时，TiUP 会添加一组环境变量，并为该程序创建好对应的数据目录，然后运行该程序。

通过运行 tiup 命令，可以运行支持的 TiUP 组件，其中运行的逻辑为：

• 如果用户通过 tiup [:version] 运行指定某个组件的特定版本：

  • 组件在本地未安装任何版本，则从镜像服务器下载最新稳定版本
  • 组件在本地安装有其他版本，但是没有用户指定的版本，则从镜像服务器下载用户指定版本
  • 如果本地已经安装指定版本，则设置环境变量来运行已经安装的版本

• 如果用户通过 tiup 运行某个组件，且未指定任何版本：

  • 组件在本地未安装任何版本，则从镜像服务器下载最新稳定版本
  • 如果本地已经安装部分版本，则设置环境变量来运行已经安装的版本中的最新版本

管理组件

通过以下一些命令来管理组件：

• list：查询组件列表，用于了解可以安装哪些组件，以及这些组件可选哪些版本
• install：安装某个组件的特定版本
• update：升级某个组件到最新的版本
• uninstall：卸载组件
• status：查看组件运行状态
• clean：清理组件实例
• help：打印帮助信息，后面跟其他 TiUP 命令则是打印该命令的使用方法

查询组件列表

使用 tiup list 命令来查询组件列表。该命令用法如下：

• tiup list：查看当前有哪些组件可以安装
• tiup list ${component}：查看某个组件有哪些版本可以安装

可以在命令中组合使用以下参数 (flag)：

--installed：查看本地已经安装了哪些组件，或者已经安装了某个组件的哪些版本
--all：显式隐藏的组件
--verbose：显式所有列（安装的版本、支持的平台）

示例一：查看当前已经安装的所有组件

tiup list --installed

示例二：从服务器获取 TiKV 所有可安装版本组件列表

tiup list tikv

安装组件

使用 tiup install 命令来安装组件。

tiup install <component>：安装指定组件的最新稳定版
tiup install <component>:[version]：安装指定组件的指定版本

示例一：使用 TiUP 安装最新稳定版的 TiDB

tiup install tidb

示例二：使用 TiUP 安装 nightly 版本的 TiDB

tiup install tidb:nightly

示例三：使用 TiUP 安装 v6.1.6 版本的 TiKV

tiup install tikv:v6.1.6

升级组件

可以使用 tiup update 命令来升级组件。除了以下几个参数，该命令的用法基本和 tiup install 相同：

--all：升级所有组件
--nightly：升级至 nightly 版本
--self：升级 TiUP 自己至最新版本
--force：强制升级至最新版本

示例一：升级所有组件至最新版本

tiup update --all

示例二：升级所有组件至 nightly 版本

tiup update --all --nightly

示例三：升级 TiUP 至最新版本

tiup update --self

运行组件

使用 tiup 命令来启动相应的组件：

tiup [flags] <component>[:version] [args...]

-T, --tag string  为组件实例指定 tag
该命令需要提供一个组件的名字以及可选的版本，若不提供版本，则使用该组件已安装的最新稳定版。

在组件启动之前，TiUP 会先为它创建一个目录，然后将组件放到该目录中运行。组件会将所有数据生成在该目录中，目录的名字就是该组件运行时指定的 tag 名称。如果不指定 tag，则会随机生成一个 tag 名称，并且在实例终止时自动删除工作目录。

如果想要多次启动同一个组件并复用之前的工作目录，就可以在启动时用 --tag 指定相同的名字。指定 tag 后，在实例终止时就不会自动删除工作目录，方便下次启动时复用。

示例一：运行 v6.1.6 版本的 TiDB

tiup tidb:v6.1.6

示例二：指定 tag 运行 TiKV

tiup --tag=experiment tikv

查询组件运行状态

使用 tiup status 命令来查看组件的运行状态：

tiup status

运行该命令会得到一个实例列表，每行一个实例。列表中包含这些列：

Name：实例的 tag 名称
Component：实例的组件名称
PID：实例运行的进程 ID
Status：实例状态，RUNNING 表示正在运行，TERM 表示已经终止
Created Time：实例的启动时间
Directory：实例的工作目录，可以通过 --tag 指定
Binary：实例的可执行程序，可以通过 --binpath 指定
Args：实例的运行参数

清理组件实例

使用 tiup clean 命令来清理组件实例，并删除工作目录。如果在清理之前实例还在运行，会先 kill 相关进程。

tiup clean [tag] [flags]

参数：

--all：清除所有的实例信息
其中 tag 表示要清理的实例 tag，如果使用了 --all 则不传递 tag。

示例一：清理 tag 名称为 experiment 的组件实例

tiup clean experiment

示例二：清理所有组件实例

tiup clean --all

卸载组件

TiUP 安装的组件会占用本地磁盘空间，如果不想保留过多老版本的组件，可以先查看当前安装了哪些版本的组件，然后再卸载某个组件。

使用 tiup uninstall 命令来卸载某个组件的所有版本或者特定版本，也支持卸载所有组件。该命令用法如下：

tiup uninstall [component][:version] [flags]

支持的参数：

--all：卸载所有的组件或版本
--self：卸载 TiUP 自身
component 为要卸载的组件名称，version 为要卸载的版本，这两个都可以省略，省略任何一个都需要加上 --all 参数：若省略版本，加 --all 表示卸载该组件所有版本
若版本和组件都省略，则加 --all 表示卸载所有组件及其所有版本

示例一：卸载 v6.1.6 版本的 TiDB

tiup uninstall tidb:v6.1.6

示例二：卸载所有版本的 TiKV

tiup uninstall tikv --all

示例三：卸载所有已经安装的组件

tiup uninstall --all

命令

清单列表

命令清单
TiUP 包含众多的命令，这些命令又包含了许多子命令：

• install：安装组件
• list：查看组件列表
• uninstall：卸载组件
• update：升级已安装的组件
• status：查看组件运行状态
• clean：清理组件数据目录
• mirror：镜像管理
• telemetry：遥测开关
• completion：TiUP 命令补全
• env：查看 TiUP 相关环境变量
• help：查看特定命令或组件的帮助文档

组件清单

• cluster：生产环境 TiDB 集群管理
• dm：生产环境 DM 集群管理

tiup clean

命令 tiup clean 用于清除组件运行过程中产生的数据。

• 语法

tiup clean [name] [flags]
[name] 取值为 status 命令输出的 Name 字段。若省略 [name]，则必须配合 --all 使用。

• 选项

--all
清除所有运行记录。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

Clean instance of `%s`, directory: %s

tiup completion

TiUP 提供了 tiup completion 命令用于生成命令行自动补全的配置文件。目前支持 bash 和 zsh 两种 shell 的命令补全。

• 安装

如果是 bash，需要提前安装好 bash-completion：
在 Linux 上的安装方式为：使用包管理器安装 bash-completion 包，例如执行 yum install bash-completion 或者 apt install bash-completion。

• 语法

tiup completion <shell>
<shell> 为 shell 类型，目前支持 bash 和 zsh。

• 使用方式

bash，将自动补全代码写入一个文件，并且在 .bash_profile 中对其执行 source 命令：

tiup completion bash > ~/.tiup.completion.bash

printf "
# tiup shell completion
source '$HOME/.tiup.completion.bash'
" >> $HOME/.bash_profile

source $HOME/.bash_profile

zsh
tiup completion zsh > "${fpath[1]}/_tiup"

tiup help

TiUP 命令行界面为用户提供了丰富的帮助信息，用户可以通过 help 命令或者 --help 参数查看。tiup help 命令等价于 tiup --help。

• 语法

tiup help [command]
[command] 用于指定要查看哪个命令的帮助信息，若不指定，则查看 TiUP 自身的帮助信息。

• 输出

[command] 或 TiUP 的帮助信息。

tiup install

命令 tiup install 用于组件安装，它会从镜像仓库中下载指定版本的组件包，并在本地的 TiUP 数据目录中解压，以便后续使用。另外，当 TiUP 需要运行一个镜像仓库中不存在的组件时，会尝试先下载该组件，再自动运行，若仓库中不存在会报错。

• 语法

tiup install <component1>[:version] [component2...N] [flags]
<component1> 和 <component2> 代表组件名字，[version] 代表一个可选的版本号，若不加 version，则安装指定组件的最新稳定版本。[component2...N] 表示可同时指定多个组件或同一个组件的多个版本。

• 输出
  正常情况下输出组件的下载信息

若组件不存在则报错 The component "%s" not found
若版本不存在则报错 version %s not supported by component %s

tiup list

命令 tiup list 用于查询镜像中可用的组件列表。

• 语法

tiup list [component] [flags]
[component] 是可选的组件名称。若指定，则列出该组件的所有版本；若不指定，则列出所有组件列表。

• 选项

--all
显示所有组件。默认只显示非隐藏组件。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
--installed
只显示已经安装的组件或版本。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
--verbose
在组件列表中显示已安装的版本列表。默认组件列表不显示当前已安装的版本。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  若未指定 [component]

  • 若指定 --verbose：输出 组件名 (Name)、已安装版本 (Installed)、组件管理员 (Owner)、组件描述 (Description) 构成的组件信息列表
  • 若不指定 --verbose：输出 组件名 (Name)、组件管理员 (Owner)、组件描述 (Description) 构成的组件信息列表

  若指定 [component]

  • 若 [component] 存在：输出 版本 (Version)、是否已安装 (Installed)、发布时间 (Release)、支持的平台 (Platforms) 构成的版本信息列表
  • 若 [component] 不存在：报错 failed to fetch component: unknown component

tiup status

使用命令 tiup status 可查看组件的运行信息：

通过 tiup [flags] <component> [args...] 
运行组件之后，可以通过该命令查看组件的运行信息。

• 注意
  只能查询到以下两种组件的信息：

尚在运行的组件
通过 tiup -T/--tag 指定 tag 运行的组件

• 语法

tiup status [flags]

• 输出
  由以下字段构成的表格：

Name: 通过 -T/--tag 指定的 Tag 名字，若未指定，则为随机字符串
Component: 运行的组件
PID: 对应的进程 ID
Status: 组件运行状态
Created Time: 启动时间
Directory: 数据目录
Binary: 二进制文件路径
Args: 启动参数

• 组件运行状态 (Status)
  组件可能处于如下任一运行状态：

在线 (Up)：组件正常运行。
离线 (Down) 或无法访问 (Unreachable)：组件未启动或对应主机存在网络问题。
已缩容下线 (Tombstone)：组件上的数据已被完整迁出并缩容完毕。仅 TiKV 或 TiFlash 组件存在该状态。
下线中 (Pending Offline)：组件上的数据正在被迁出并缩容。仅 TiKV 或 TiFlash 组件存在该状态。
未知 (Unknown)：未知的组件运行状态。

tiup uninstall

命令 tiup uninstall 用于卸载已安装的组件。

• 语法

tiup uninstall <component1>:<version> [component2...N] [flags]

<component1> 表示要卸载的组件名字
<version> 表示要卸载的版本，如果省略，则表示卸载该组件的全部已安装版本，因为安全原因，省略 <version> 时必须加上选项 --all 明确表示需要卸载该组件的所有版本
[component2...N] 表示可指定卸载多个组件或版本

• 选项

--all
卸载指定组件的全部已安装版本，省略 <version> 时使用。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--self
卸载 TiUP 自身：删除所有从镜像上下载过来的数据，但会保留 TiUP 及其组件产生的数据，数据存放在 TIUP_HOME 环境变量指定的目录中，若未设置过 TIUP_HOME，则默认值为 ~/.tiup/。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

正常退出：Uninstalled component "%s" successfully!
若未指定 <version> 也未指定 --all：报错 Use "tiup uninstall tidbx --all" if you want to remove all versions.

tiup update

命令 tiup update 用于升级已安装的组件或者自身。升级操作不会删除旧的版本，仍然可以在执行时指定旧版本使用。

• 语法

tiup update [component1][:version] [component2..N] [flags]

[component1] 表示要升级的组件名字
[version] 表示要升级的版本，如果省略，则表示升级到该组件的最新稳定版本
[component2...N] 表示可指定升级多个组件或版本。如果一个组件也不指定：即 [component1][:version] [component2..N] 为空，则需要配合使用 --all 选项或 --self 选项。

• 选项

--all
若未指定任何组件，则必须指定该选项。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--force
若指定的组件版本已经安装，则默认跳过升级操作，指定该参数可强制升级已安装版本。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--nightly
将指定组件升级到 nightly 版本。使用该参数的命令等价于 tiup update <component>:nightly。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--self
升级 TiUP 自身。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

升级成功：Updated successfully!
目标版本不存在：Error: version %s not supported by component %s

TiUP Cluster

通过 TiUP Cluster 组件就可以进行日常的运维工作，包括部署、启动、关闭、销毁、弹性扩缩容、升级 TiDB 集群、管理 TiDB 集群参数。

• 语法

tiup cluster [command] [flags]
[command] 代表命令名字，支持的命令列表请参考下方命令清单。

• 选项

--ssh (string，默认 builtin)
指定 SSH 客户端连接远端（部署 TiDB 服务的机器）执行命令，支持以下值：

builtin：使用 tiup-cluster 内置的 easyssh 客户端
system：使用当前操作系统默认的 SSH 客户端
none：不使用 ssh 客户端，这种方式只支持部署到当前机器
--ssh-timeout（uint，默认 5）
设置 SSH 连接超时时间，单位为秒。

--wait-timeout（uint，默认 120）
运维过程中涉及到很多操作：指定 systemctl 启动/停止服务，等待端口上线/下线等，每个操作可能会消耗数秒。--wait-timeout 用于设置每个步骤的最长等待时间（单位为秒），超时后报错退出。

-y, --yes
跳过所有风险操作的二次确认，除非是使用脚本调用 TiUP，否则不推荐使用。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
-v, --version
输出 TiUP Cluster 当前版本信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
-h, --help
输出相关命令的帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

命令清单

import：导入 ansible 部署的集群
template：输出拓扑模版
check：部署前后的集群检查
deploy：根据指定拓扑部署集群
list：查询已部署的集群列表
display：展示指定集群状态
start：启动指定集群
stop：停止指定集群
restart：重启指定集群
scale-in：缩容指定集群
scale-out：扩容指定集群
upgrade：升级指定集群
prune：销毁指定集群中状态为 Tombstone 的实例
edit-config：修改指定集群配置
reload：重载指定集群配置
patch：替换已部署集群的某个服务
rename：重命名集群
clean：删除指定集群数据
destroy：销毁指定集群
audit：查询集群操作审计日志
replay：重试指定命令
enable：开启指定集群或服务开机自启动
disable：关闭指定集群或服务开机自启动
meta backup：备份指定集群运维操作所需的 TiUP meta 文件
meta restore：恢复指定集群的 TiUP meta 文件
help：输出帮助信息

tiup cluster audit

命令 tiup cluster audit 可以用于查看历史上对所有集群执行了什么命令，以及每个命令的执行日志。

• 语法

tiup cluster audit [audit-id] [flags]

若不填写 [audit-id] 则按时间倒序输出操作记录的表格，第一列为 audit-id。
若填写 [audit-id] 则查看指定的 audit-id 的执行日志

• 选项

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

若指定 [audit-id]，则输出对应的执行日志
若不指定 [audit-id] 则输出含有以下字段的表格：
	ID：该条记录对应的 audit-id
	Time：该条记录对应的命令执行时间
	Command：该条记录对应的命令

tiup cluster audit cleanup

命令 tiup cluster audit cleanup 可以用于清理 tiup cluster 产生的执行日志。

• 语法

tiup cluster audit cleanup [flags]

• 选项

--retain-days
执行日志保留天数
数据类型：INT
默认值：60，单位为“天”
默认保留 60 天的执行日志，即删除 60 天之前的执行日志。
-h, --help
输出帮助信息
数据类型：BOOLEAN
默认值：false
在命令中添加该选项，并传入 true 或不传值，均可开启此功能。

• 输出

clean audit log successfully

tiup cluster check

在正式上线之前需要进行一系列检查，来确保集群拥有最好的表现。为了简化人工检查的步骤，TiUP Cluster 提供了 check 子命令，用于检查指定集群的机器硬件和软件环境是否满足正常运行条件。

检查项列表

• 操作系统版本
  检查部署机操作系统发行版和版本：目前仅支持部署在 CentOS 7 的操作系统上，之后随兼容性改进可能支持更多系统版本。

• CPU EPOLLEXCLUSIVE
  检查部署机 CPU 是否支持 EPOLLEXCLUSIVE。

• numactl
  检查部署机是否安装 numactl，若用户配置绑核，则必须安装 numactl。

• 系统时间
  检查部署机系统时间是否同步：将部署机系统时间与中控机对比，偏差超出某一阈值（500ms）后报错。

• 系统时区
  检查部署机系统时区是否同步：将部署机系统的时区配置进行对比，如果时区不一致则报错。

• 时间同步服务
  检查部署机是否配置了时间同步服务：即 ntpd 是否在运行

• Swap 分区
  检查部署机是否启用 Swap 分区：建议禁用 Swap 分区

• 内核参数
  检查各项内核参数的值：

net.ipv4.tcp_tw_recycle: 0
net.ipv4.tcp_syncookies: 0
net.core.somaxconn: 32768
vm.swappiness: 0
vm.overcommit_memory: 0 或 1
fs.file-max: 1000000

• THP（透明大页）
  检查部署机是否启用透明大页：建议禁用透明大页。

• 系统限制
  检查 /etc/security/limits.conf 中各项 limit 值：
  其中 为部署、运行 TiDB 集群的用户，最后一列的数值为要求达到的最小值。

<deploy-user>    soft   nofile    1000000
<deploy-user>    hard   nofile    1000000
<deploy-user>    soft   stack     10240

• SELinux
  检查 SELinux 是否启用：建议用户禁用 SELinux。

• 防火墙
  检查 FirewallD 服务是否启用：建议用户禁用 FirewallD 或为 TiDB 集群各服务添加允许规则。

• irqbalance
  检查 irqbalance 服务是否启用：建议用户启用 irqbalance 服务。

• 磁盘挂载参数
  检查 ext4 分区的挂载参数：确保挂载参数包含 nodelalloc,noatime 选项。

• 端口占用
  检查部署机上是否已有进程占用了端口：检查拓扑中定义的端口（包括自动补全的默认端口）在部署机上是否已被占用。

• CPU 核心数
  检查部署机 CPU 信息：建议生产集群 CPU 逻辑核心数 >= 16,默认不检查 CPU 核心数，需要通过选项 --enable-cpu 启用。

• 内存大小
  检查部署机的内存大小：建议生产集群总内存容量 >= 32Gb。默认不检查内存大小，需要通过选项 --enable-mem 启用。

• fio 磁盘性能测试
  使用 fio 测试 data_dir 所在磁盘的性能，注意默认不进行 fio 磁盘性能测试，需要通过选项 --enable-disk 启用。包括三个测试项目：

fio_randread_write_latency
fio_randread_write
fio_randread

语法

tiup cluster check <topology.yml | cluster-name> [flags]

若集群尚未部署，需要传递将用于部署集群的 topology.yml 文件，tiup-cluster 会根据该文件的内容连接到对应机器去检查。若集群已经部署，则可以使用集群的名字 作为检查对象。
注意
若传递的是集群名字，则需要配合 --cluster 选项使用。

选项

--apply
尝试自动修复失败的检查项，目前仅会尝试修复以下项目：

SELinux
防火墙
irqbalance
内核参数
系统 Limits
THP（透明大页）
数据类型：BOOLEAN

该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--cluster
tiup-cluster 支持对未部署的集群进行检查，也支持对已部署的集群进行检查，命令格式：

tiup cluster check <topology.yml | cluster-name> [flags]
若选择的格式为 tiup cluster check <cluster-name> 则必须加上该选项：tiup cluster check <cluster-name> --cluster。

该选项的数据类型为 BOOLEAN。该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

-N, --node
指定要检查的节点。该选项的值为以逗号分割的节点 ID 列表，节点 ID 为 tiup-component-cluster-display 命令返回的集群状态表格的第一列。
数据类型：STRINGS
如果不指定该选项，默认检查所有节点，即 []。
注意
若同时指定了 -R, --role，那么将检查它们的交集中的服务。

-R, --role
指定要检查的角色。该选项的值为以逗号分割的节点角色列表，角色为 tiup-component-cluster-display 命令返回的集群状态表格的第二列。
数据类型：STRINGS
如果不指定该选项，默认检查所有角色。
注意
若同时指定了 -N, --node，那么将检查它们的交集中的服务。

--enable-cpu
默认情况下 tiup-cluster 不检查 CPU 核心数，该选项用于启用 CPU 核心数检查。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--enable-disk
默认情况下 tiup-cluster 不进行 fio 磁盘性能测试，该选项用于启用 fio 磁盘性能测试。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--enable-mem
默认情况下 tiup-cluster 不检查内存大小，该选项用于启用内存大小检查。

-u, --user（string，默认为当前执行命令的用户）
指定连接目标机器的用户名，该用户在目标机器上需要有免密 sudo root 的权限。

注意
仅当 --cluster 选项为 false 时该选项有效，否则该值固定为部署集群时拓扑文件中指定的用户名。

-i, --identity_file（string，默认 ~/.ssh/id_rsa）
指定连接目标机器的密钥文件。

注意
仅当 --cluster 选项为 false 时该选项有效，否则该值固定为 ${TIUP_HOME}/storage/cluster/clusters/<cluster-name>/ssh/id_rsa

-p, --password
在连接目标机器时使用密码登录：

对于指定了 --cluster 的集群，密码为部署集群时拓扑文件中指定的用户的密码
对于未指定 --cluster 的集群，密码为 -u/--user 参数指定的用户的密码
数据类型：BOOLEAN

该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

输出
输出含有以下字段的表格：

Node：目标节点
Check：检查项
Result：检查结果（Pass/Warn/Fail）
Message：结果描述

tiup cluster clean

测试环境中，有时候需要将集群重置回刚部署的状态，即删除所有数据，命令 tiup cluster clean 可以很方便的做到这一点：它会停止集群，然后删除集群上的数据。手工重启集群之后，就能得到一个全新的集群了。该命令一定会先停止集群（即使选择只清理日志也是），生产环境请勿使用。

• 语法

tiup cluster clean <cluster-name> [flags]
<cluster-name> 为要清理的集群。

• 选项

--all
同时清理数据和日志，等价于同时指定 --data 和 --log，若不指定该选项，则必须至少指定以下选项之一：

--data：清理数据
--log：清理日志
数据类型：BOOLEAN

该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--data
该选项开启数据清理，若不指定该选项，也不指定 --all，则不清理数据。

--log
该选项开启日志清理，若不指定该选项，也不指定 --all，则不清理日志。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
--ignore-node（StringArray，默认为空）
指定不需要清理的节点，如需指定多个，重复使用多次该选项：--ignore-node <node-A> --ignore-node <node-B>。

--ignore-role（StringArray，默认为空）
指定不需要清理的角色，如需指定多个，重复使用多次该选项：--ignore-role <role-A> --ignore-role <role-B>。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

tiup-cluster 的执行日志。

tiup cluster deploy

命令 tiup cluster deploy 用于部署一个全新的集群。

• 语法

tiup cluster deploy <cluster-name> <version> <topology.yaml> [flags]

<cluster-name> 表示新集群的名字，不能和现有集群同名
<version> 为要部署的 TiDB 集群版本号，如 v6.1.6
<topology.yaml> 为事先编写好的拓扑文件

• 选项

-u, --user（string，默认为当前执行命令的用户）
指定连接目标机器的用户名，该用户在目标机器上需要有免密 sudo root 的权限。

-i, --identity_file（string，默认 ~/.ssh/id_rsa）
指定连接目标机器的密钥文件。

-p, --password
在连接目标机器时使用密码登录，不可和 -i/--identity_file 同时使用。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--ignore-config-check
在组件二进制文件部署之后，TiUP 会对 TiDB，TiKV 和 PD 组件执行配置检查，检查方式为 <binary> --config-check <config-file>，其中 <binary> 为部署的二进制文件的路径，<config-file> 为根据用户配置生成的配置文件。如果想要跳过该项检查，可以使用该选项。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--no-labels
当两个或多个 TiKV 部署到同一台机器时，会存在一个风险：由于 PD 无法感知集群的拓扑结构，可能将一个 Region 的多个副本调度到一台物理机上的不同 TiKV，这样这台物理机就成为了单点。为了避免这种情况，用户可以通过 label 来告诉 PD 不要将相同的 Region 调度到同一台机器上（配置方式参考通过拓扑 label 进行副本调度）。
但是对于测试环境，可能并不在意是否将一个 Region 的副本调度到了同一台机器上，这个时候可以使用 --no-labels 来绕过检查。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--skip-create-user
在部署集群时，tiup-cluster 会先检查拓扑文件中指定的用户名是否存在，如果不存在就会创建一个。指定 --skip-create-user 选项后不再检查用户是否存在，直接跳过创建步骤。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  部署日志。

tiup cluster destroy

当业务下线之后，如果想将集群占有的机器释放出来让给其他业务使用，需要清理掉集群上的数据以及部署的二进制文件。tiup cluster destroy 命令会执行以下操作销毁集群：

停止集群
对于每个服务，删除其日志目录，部署目录，数据目录
如果各个服务的数据目录/部署目录的父目录是由 tiup-cluster 创建的，也一并删除

• 语法

tiup cluster destroy <cluster-name> [flags]

为要销毁的集群名字。

• 选项

--force
在某些情况下，有可能集群中的某些节点已经宕机，导致无法通过 SSH 连接到节点进行操作，这个时候可以通过 --force 选项忽略这些错误。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--retain-node-data（StringArray，默认为空）
指定需要保留数据的节点，如需指定多个，重复使用多次该选项：--retain-node-data <node-A> --retain-node-data <node-B>。

--retain-role-data（StringArray，默认为空）
指定需要保留数据的角色，如需指定多个，重复使用多次该选项：--retain-role-data <role-A> --retain-role-data <role-B>。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  tiup-cluster 的执行日志。

tiup cluster disable

命令 tiup cluster disable 用于关闭集群服务所在机器重启之后的自启动，该命令会到指定的节点上去执行 systemctl disable 来关闭服务的自启动。

• 语法
  为要关闭自启的集群。

tiup cluster disable <cluster-name> [flags]

• 选项

-N, --node
指定要关闭自启的节点，该选项的值为以逗号分割的节点 ID 列表，节点 ID 为 tiup-component-cluster-display 命令返回的集群状态表格的第一列。
数据类型：STRINGS
如果不指定该选项，默认关闭所有节点的自启。
注意
若同时指定了 -R, --role，那么将关闭它们的交集中的服务自启。

-R, --role
指定要关闭自启的角色，该选项的值为以逗号分割的节点角色列表，角色为 tiup-component-cluster-display 命令返回的集群状态表格的第二列。
数据类型：STRINGS
如果不指定该选项，默认关闭所有角色的自启。
注意: 若同时指定了 -N, --node，那么将关闭它们的交集中的服务自启。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  tiup-cluster 的执行日志。

tiup cluster display

查看集群中每个组件的运行状态，逐一登录到各个机器上查看显然很低效。因此，tiup-cluster 提供了 tiup cluster display 命令来高效完成这件工作。

• 语法
  为要操作的集群名字，如果忘记集群名字可通过集群列表查看。

tiup cluster display <cluster-name> [flags]

• 选项

--dashboard
默认情况会展示整个集群的所有节点信息，加上该选项后仅展示 dashboard 的信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

-N, --node（strings，默认为 []，表示所有节点）
指定要查询的节点，不指定则表示所有节点。该选项的值为以逗号分割的节点 ID 列表，如果不确定要查询节点的 ID，不指定此选项，输出会显示所有节点的 ID 和状态信息。

注意
若同时指定了 -R, --role，那么将查询它们的交集中的服务状态。

-R, --role（strings，默认为 []，表示所有角色）
指定要查询的角色，不指定则表示所有角色。该选项的值为以逗号分割的节点角色列表，如果不确定要查询节点的角色，不指定此选项，输出会显示所有节点的角色和状态信息。

注意
若同时指定了 -N, --node，那么将查询它们的交集中的服务状态。

--process
加上该选项后会增加展示节点的 CPU 和内存的使用信息，默认情况下不展示。
数据类型：BOOLEAN
默认值：false
在命令中添加该选项，并传入 true 或不传值，均可开启此功能。

--uptime
加上该选项后会增加展示节点的 uptime 信息，默认情况下不展示。
数据类型：BOOLEAN
默认值：false
在命令中添加该选项，并传入 true 或不传值，均可开启此功能。

--status-timeout
获取节点状态信息的超时时间。
数据类型：INT
默认值：10，单位为 s。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  • 集群名称
  • 集群版本
  • SSH 客户端类型
  • Dashboard 地址
  • 含有以下字段的表格：
    • ID：节点 ID，由 IP:PORT 构成
    • Role：该节点部署的服务角色（如 TiDB、 TiKV 等）
    • Host：该节点对应的机器 IP
    • Ports：服务占用的端口号
    • OS/Arch：该节点的操作系统和机器架构
    • Status：该节点服务当前的状态
    • Data Dir：服务的数据目录，- 表示没有数据目录
    • Deploy Dir：服务的部署目录
• 节点服务的状态 (Status)

在线 (Up)：节点服务正常运行。
离线 (Down) 或无法访问 (Unreachable)：节点服务未启动或对应主机存在网络问题。
已缩容下线 (Tombstone)：节点服务上的数据已被完整迁出并缩容完毕。仅 TiKV 或 TiFlash 存在该状态。
下线中 (Pending Offline)：节点服务上的数据正在被迁出并缩容。仅 TiKV 或 TiFlash 存在该状态。
未知 (Unknown)：未知的节点服务运行状态。

tiup cluster edit-config

在部署集群之后，如果需要再调整集群服务的配置，可以使用命令 tiup cluster edit-config，它会启动一个编辑器修改指定集群的拓扑文件。

• 注意
  • 修改配置时不能增删机器，增删机器属于集群扩容和集群缩容的功能。
  • 执行完该命令后配置只是在中控机上修改了，要应用配置需要执行 tiup cluster reload 命令来重新加载。
• 语法
  代表要操作的集群名。

tiup cluster edit-config <cluster-name> [flags]

• 选项

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

正常情况无输出
若修改了不能修改的字段，则保存文件时报错并提示用户重新编辑，不能修改的字段参考拓扑文件中的相关描述

tiup cluster enable

用于设置集群服务在机器重启后的自启动，该命令会到指定的节点上去执行 systemctl enable 来开启服务的自启。

• 语法
  为要启用自启的集群。

tiup cluster enable <cluster-name> [flags]

• 选项

-N, --node
指定要开启自启的节点，该选项的值为以逗号分割的节点 ID 列表，节点 ID 为 tiup-component-cluster-display 命令返回的集群状态表格的第一列。
数据类型：STRINGS
如果不指定该选项，默认开启所有节点的自启。
注意
若同时指定了 -R, --role，那么将开启它们的交集中的服务自启。

-R, --role
指定要开启自启的角色，该选项的值为以逗号分割的节点角色列表，角色为 tiup-component-cluster-display 命令返回的集群状态表格的第二列。
数据类型：STRINGS
如果不指定该选项，默认开启所有角色的自启。
注意
若同时指定了 -N, --node，那么将开启它们的交集中的服务自启。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  tiup-cluster 的执行日志

tiup cluster help

tiup cluster help <command> 基本等价于 
tiup cluster <command> --help。

• 语法
  [command] 用于指定要查看哪个命令的帮助信息，若不指定，则查看 tiup-cluster 自身的帮助信息。

tiup cluster help [command] [flags]

• 选项

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

[command] 或 tiup-cluster 的帮助信息。

tiup cluster list

tiup-cluster 支持使用同一个中控机部署多套集群，而命令 tiup cluster list 可以查看当前登录的用户使用该中控机部署了哪些集群。

• 注意

部署的集群数据默认放在 ~/.tiup/storage/cluster/clusters/ 目录下，因此在同一台中控机上，当前登录用户无法查看其他用户部署的集群。

• 语法

tiup cluster list [flags]

• 选项

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  输出含有以下字段的表格：
  • Name：集群名字
  • User：部署用户
  • Version：集群版本
  • Path：集群部署数据在中控机上的路径
  • PrivateKey：连接集群的私钥所在路径

tiup cluster meta backup

如果运维所需的 TiUP meta 文件丢失，会导致无法继续使用 TiUP 管理集群。可以通过 tiup cluster meta backup 命令定期备份 TiUP meta 文件。

• 语法
  为要操作的集群名字，如果忘记集群名字可通过集群列表查看。

tiup cluster meta backup <cluster-name> [flags]

• 选项

--file（string，默认为当前目录）
指定 TiUP meta 备份文件存储的目标目录。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  tiup-cluster 的执行日志。

tiup cluster meta restore

当需要恢复 TiUP meta 文件时，可以通过 tiup cluster meta restore 命令从备份文件中恢复。

• 语法

tiup cluster meta restore <cluster-name> <backup-file> [flags]
<cluster-name> 代表需要执行操作的集群名。
<backup-file> 代表 TiUP meta 备份文件所在的文件路径。
注意
恢复操作会覆盖当前的 meta 文件，建议仅在 meta 文件丢失的情况下进行恢复。

• 输出
  tiup-cluster 的执行日志。

tiup cluster patch

在集群运行过程中，如果需要动态替换某个服务的二进制文件（即替换过程中保持集群可用），那么可以使用 tiup cluster patch 命令，它会完成以下几件事情：

1. 将用于替换的二进制包上传到目标机器
2. 如果目标服务是 TiKV、TiFlash 或者 TiDB Binlog 之类的存储服务，则先通过 API 下线节点
3. 停止目标服务
4. 解压二进制包，替换服务
5. 启动目标服务

• 语法

tiup cluster patch <cluster-name> <package-path> [flags]
<cluster-name> 代表要操作的集群名
<package-path> 为用于替换的二进制包路径

• 准备二进制包
  在运行 tiup cluster patch 命令之前，你需要打包所需的二进制文件。请按照以下步骤操作：

1、确定以下变量的值：

${component}：需要替换的组件名（例如 tidb、tikv、pd）。
${version}：组件的版本（例如 v7.0.0、v6.5.1）。
${os}：操作系统 (linux)。
${arch}：组件运行的平台 (amd64、arm64)。

2、下载当前的组件包：

wget https://tiup-mirrors.pingcap.com/${component}-${version}-${os}-${arch}.tar.gz -O /tmp/${component}-${version}-${os}-${arch}.tar.gz

3、创建临时打包目录：

mkdir -p /tmp/package && cd /tmp/package

4、解压原来的二进制包：

tar xf /tmp/${component}-${version}-${os}-${arch}.tar.gz

5、查看临时打包目录中的文件结构：

find .

6、将要替换的二进制文件或配置文件复制到临时目录的对应位置。

7、将临时目录中的所有文件打包：

tar czf /tmp/${component}-hotfix-${os}-${arch}.tar.gz *

完成上述步骤后，你可以在 tiup cluster patch 命令中使用 /tmp/${component}-hotfix-${os}-${arch}.tar.gz 作为 <package-path>。

• 选项

--overwrite
对某个组件（比如 TiDB，TiKV）进行 patch 后，如果要在该集群扩容该组件，tiup-cluster 会默认使用 patch 前的版本。如果希望后续扩容的时候也使用 patch 之后的版本，需要指定 --overwrite 选项。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--transfer-timeout（uint，默认 300）
在重启 PD 或 TiKV 时，会先将被重启节点的 leader 迁移到其他节点，迁移过程会需要一定时间，可以通过设置 --transfer-timeout 设置最长等待时间（单位为秒），超时之后会跳过等待直接重启服务。

注意
若出现跳过等待直接重启的情况，服务性能可能会出现抖动。

-N, --node（strings，默认为 []，未选中任何节点）
指定要替换的节点，该选项的值为以逗号分割的节点 ID 列表，节点 ID 为集群状态表格的第一列。

注意
若同时指定了 -R, --role，那么将替换它们的交集中的服务。

-R, --role（strings，默认为 []，未选中任何角色）
指定要替换的角色，该选项的值为以逗号分割的节点角色列表，角色为集群状态表格的第二列。

注意
若同时指定了 -N, --node，那么将替换它们的交集中的服务。

--offline
声明当前集群处于停止状态。指定该选项时，TiUP Cluster 仅原地替换集群组件的二进制文件，不执行迁移 Leader 以及重启服务等操作。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  tiup-cluster 的执行日志。

tiup cluster prune

在缩容集群时，对于某些组件，并不会立即停止服务并删除数据，而是需要等数据调度完成之后，用户手动执行 tiup cluster prune 命令清理。

• 语法

tiup cluster prune <cluster-name> [flags]

• 选项

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  清理过程的日志。

tiup cluster reload

在修改集群配置之后，需要通过 tiup cluster reload 命令让集群重新加载配置才会生效。

• 语法
  代表要操作的集群名

tiup cluster reload <cluster-name> [flags]

• 选项

--force
忽略重新加载过程中的错误，强制 reload。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--transfer-timeout（uint，默认 300）
在重启 PD 或 TiKV 时，会先将被重启节点的 leader 迁移到其他节点，迁移过程会需要一定时间，可以通过设置 --transfer-timeout 设置最长等待时间（单位为秒），超时之后会跳过等待直接重启服务。

--ignore-config-check
在组件二进制文件部署之后，TiUP 会对 TiDB，TiKV 和 PD 组件执行配置检查，检查方式为 <binary> --config-check <config-file>，其中 <binary> 为部署的二进制文件的路径，<config-file> 为根据用户配置生成的配置文件。如果想要跳过该项检查，可以使用该选项。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

-N, --node（strings，默认为 []，表示所有节点）
指定要重启的节点，不指定则表示所有节点。该选项的值为以逗号分割的节点 ID 列表，节点 ID 为集群状态表格的第一列。

注意
若同时指定了 -R, --role，那么将重启它们的交集中的服务
若指定了选项 --skip-restart，则该选项无效

-R, --role（strings，默认为 []，表示所有角色）
指定要重启的角色，不指定则表示所有角色。该选项的值为以逗号分割的节点角色列表，角色为集群状态表格的第二列。

注意
若同时指定了 -N, --node，那么将重启它们的交集中的服务
若指定了选项 --skip-restart，则该选项无效

--skip-restart
命令 tiup cluster reload 会执行两个操作：

刷新所有节点配置
重启指定节点
该选项指定后仅刷新配置，不重启任何节点，这样刷新的配置也不会应用，需要等对应服务下次重启才会生效。

数据类型：BOOLEAN

该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出

tiup-cluster 的执行日志。

tiup cluster rename

集群名字是部署集群时指定的，在集群部署之后，如果想更改集群名字，可以通过 tiup cluster rename 命令来实现。

• 注意

如果配置了 grafana_servers 的 dashboard_dir 字段，在执行 tiup cluster rename 命令进行集群重命名后，需要额外做以下操作：

对于本地的 dashboards 目录中的 *.json 文件，将 datasource 字段的值更新为新的集群名（这是因为 datasource 是以集群名命名的）
执行 tiup cluster reload -R grafana 命令

• 语法

tiup cluster rename <old-cluster-name> <new-cluster-name> [flags]
<old-cluster-name> 老的集群名
<new-cluster-name> 新的集群名

• 选项

-h, --help
输出帮助信息。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  tiup-cluster 的执行日志。

tiup cluster replay

对集群进行升级或重启等操作时，操作有可能因为环境的原因而偶然失败。这时如果重新进行操作，需要从头开始执行所有步骤。如果集群规模较大，会耗费较长时间。此时可以使用 tiup cluster replay 命令重试刚才失败的命令，并且跳过已经成功的步骤。

• 语法

tiup cluster replay <audit-id> [flags]
<audit-id> 代表要重试的命令对应的 audit-id。使用 tiup cluster audit 可查看历史命令及其 audit-id。

• 输出
  对应的命令的输出。

tiup cluster restart

命令 tiup cluster restart 用于重启指定集群的所有或部分服务。

• 语法
  tiup cluster restart [flags]
  为要操作的集群名字，如果忘记集群名字可通过集群列表查看。

• 选项

-N, --node（strings，默认为 []，表示所有节点）
指定要重启的节点，不指定则表示所有节点。该选项的值为以逗号分割的节点 ID 列表，节点 ID 为集群状态表格的第一列。

注意
若同时指定了 -R, --role，那么将重启它们的交集中的服务。

-R, --role（strings，默认为 []，表示所有角色）
指定要重启的角色，不指定则表示所有角色。该选项的值为以逗号分割的节点角色列表，角色为集群状态表格的第二列。

注意
若同时指定了 -N, --node，那么将重启它们的交集中的服务。

• 输出
  重启服务的日志。

tiup cluster scale-in

tiup cluster scale-in 命令用于集群缩容，缩容即下线服务，最终会将指定的节点从集群中移除，并删除遗留的相关文件。

• 下线特殊处理
  由于 TiKV，TiFlash 和 TiDB Binlog 组件的下线是异步的（需要先通过 API 执行移除操作）并且下线过程耗时较长（需要持续观察节点是否已经下线成功），所以对 TiKV，TiFlash 和 TiDB Binlog 组件做了特殊处理：

  • 对 TiKV，TiFlash 及 TiDB Binlog 组件的操作:
    • tiup-cluster 通过 API 将其下线后直接退出而不等待下线完成
    • 执行 tiup cluster display 查看下线节点的状态，等待其状态变为 Tombstone
    • 执行 tiup cluster prune 命令清理 Tombstone 节点，该命令会执行以下操作：
      • 停止已经下线掉的节点的服务
      • 清理已经下线掉的节点的相关数据文件
      • 更新集群的拓扑，移除已经下线掉的节点
  • 对其他组件的操作
    • 下线 PD 组件时，会通过 API 将指定节点从集群中删除掉（这个过程很快），然后停掉指定 PD 的服务并且清除该节点的相关数据文件
    • 下线其他组件时，直接停止并且清除节点的相关数据文件

• 语法
  为要操作的集群名字，如果忘记集群名字可通过集群列表查看。

tiup cluster scale-in <cluster-name> [flags]

• 选项

-N, --node（strings，无默认值，必须非空）
选择要缩容的节点，若缩容多个节点，以逗号分割。

--force
在某些情况下，有可能被缩容的节点宿主机已经宕机，导致无法通过 SSH 连接到节点进行操作，这个时候可以通过 --force 选项强制将其从集群中移除。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
警告
使用该选项强制移除正在服务和下线中的 TiKV / TiFlash 节点时，这些节点会被直接删除，不等待数据调度完成，因此这个场景下，数据丢失风险非常大。不建议对未宕机的节点使用该选项。如果元数据所在的 Region 发生数据丢失，整个集群将不可用且无法恢复。

--transfer-timeout（uint，默认 300）
在缩容 PD 或 TiKV 时，会先将被缩容节点的 leader 迁移到其他节点，迁移过程会需要一定时间，可以通过设置 --transfer-timeout 设置最长等待时间（单位为秒），超时之后会跳过等待直接缩容服务。

注意
若出现跳过等待直接缩容的情况，服务性能可能会出现抖动。

• 输出
  缩容日志

tiup cluster scale-out

tiup cluster scale-out 命令用于集群扩容，扩容的内部逻辑与部署类似，tiup-cluster 组件会先建立新节点的 SSH 连接，在目标节点上创建必要的目录，然后执行部署并且启动服务。其中 PD 节点的扩容会通过 join 方式加入到集群中，并且会更新与 PD 有关联的服务的配置；其他服务直接启动加入到集群中。

• 语法

tiup cluster scale-out <cluster-name> <topology.yaml> [flags]

<cluster-name> 为要操作的集群名字，如果忘记集群名字可通过集群列表查看
<topology.yaml> 为事先编写好的扩容拓扑文件，该文件应当仅包含扩容部分的拓扑

选项

-u, --user（string，默认为当前执行命令的用户）
指定连接目标机器的用户名，该用户在目标机器上需要有免密 sudo root 的权限。

-i, --identity_file（string，默认 ~/.ssh/id_rsa）
指定连接目标机器的密钥文件。

-p, --password
在连接目标机器时使用密码登录，不可和 -i/--identity_file 同时使用。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--no-labels
当两个或多个 TiKV 部署到同一台机器时，会存在一个风险：由于 PD 无法感知集群的拓扑结构，可能将一个 Region 的多个副本调度到一台物理机上的不同 TiKV，这样这台物理机就成为了单点。为了避免这种情况，用户可以通过 label 来指定 PD 不要将相同的 Region 调度到同一台机器上（配置方式参考通过拓扑 label 进行副本调度）。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
但是对于测试环境，可能并不在意是否将一个 Region 的副本调度到了同一台机器上，这个时候可以使用 --no-labels 来绕过检查。

--skip-create-user
在扩容集群时，tiup-cluster 会先检查拓扑文件中指定的用户名是否存在，如果不存在就会创建一个。指定 --skip-create-user 选项后不再检查用户是否存在，直接跳过创建步骤。

• 输出
  扩容日志

tiup cluster start

命令 tiup cluster start 用于启动指定集群的所有或部分服务。

• 语法

tiup cluster start <cluster-name> [flags]

<cluster-name> 为要操作的集群名字，如果忘记集群名字可通过集群列表查看。

• 选项

--init
以安全方式启动集群。推荐在集群第一次启动时使用，该方式会在启动时自动生成 TiDB root 用户的密码，并在命令行界面返回密码。

注意
使用安全启动方式后，不能通过无密码的 root 用户登录数据库，你需要记录命令行返回的密码进行后续操作。
该自动生成的密码只会返回一次，如果没有记录或者忘记该密码，请参照忘记 root 密码修改密码。

-N, --node（strings，默认为 []，表示所有节点）
指定要启动的节点，不指定则表示所有节点。该选项的值为以逗号分割的节点 ID 列表，节点 ID 为集群状态表格的第一列。

注意
若同时指定了 -R, --role，那么将启动它们的交集中的服务。

-R, --role（strings，默认为 []，表示所有角色）
指定要启动的角色，不指定则表示所有角色。该选项的值为以逗号分割的节点角色列表，角色为集群状态表格的第二列。

注意
若同时指定了 -N, --node，那么将启动它们的交集中的服务。

• 输出
  启动日志。

tiup cluster stop

命令 tiup cluster stop 用于停止指定集群的所有服务或部分服务。

• 语法

tiup cluster stop <cluster-name> [flags]

<cluster-name> 为要操作的集群名字，如果忘记集群名字可通过集群列表查看。

• 选项

-N, --node（strings，默认为 []，表示所有节点）
指定要停止的节点，不指定则表示所有节点。该选项的值为以逗号分割的节点 ID 列表，节点 ID 为集群状态表格的第一列。

注意
若同时指定了 -R, --role，那么将停止它们的交集中的服务。

-R, --role（strings，默认为 []，表示所有角色）
指定要停止的角色，不指定则表示所有角色。该选项的值为以逗号分割的节点角色列表，角色为集群状态表格的第二列。

注意
若同时指定了 -N, --node，那么将停止它们的交集中的服务。

• 输出
  停止服务的日志。

tiup cluster template

部署集群之前，需要准备一份集群的拓扑文件。TiUP 内置了拓扑文件的模版，用户可以通过修改该模版来生成最终的拓扑文件。使用 tiup cluster template 命令可以输出 TiUP 内置的模版内容。

• 语法

tiup cluster template [flags]
如果不指定该选项，输出的默认模版包含以下实例：

3 个 PD 实例
3 个 TiKV 实例
1 个 TiDB 实例
1 个 Prometheus 实例
1 个 Grafana 实例
1 个 Alertmanager 实例

• 选项

--full
输出详细的拓扑模版，该模版会以注释的形式带上可配置的参数。在命令中添加该选项，可开启该选项。
如果不指定该选项，默认输出最简单的拓扑模版。

--multi-dc
输出多数据中心的拓扑模版。在命令中添加该选项，可开启该选项。
如果不指定该选项，默认输出单地单机房的拓扑模版。

• 输出
  根据指定选项输出拓扑模版，可重定向到拓扑文件中用于部署。

tiup cluster upgrade

命令 tiup cluster upgrade 用于将指定集群升级到特定版本。

• 语法

tiup cluster upgrade <cluster-name> <version> [flags]
<cluster-name> 为要操作的集群名字，如果忘记集群名字可通过集群列表查看。
<version> 为要升级到的目标版本，目前仅允许升级到比当前集群更高的版本，不允许升级到比当前集群更低的版本，即不允许降级。同时也不允许升级成 nightly 版本

• 选项

--force
升级集群需要保证集群目前是启动的，在某些情况下，可能希望在集群未启动的状态下升级，这时候可以使用 --force 忽略升级过程的错误，强制替换二进制文件并启动集群。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。
注意
对正在提供服务的集群强制升级可能导致集群服务不可用。对于未启动的集群，升级成功后会自动启动集群。

--transfer-timeout（uint，默认 300）
在升级 PD 或 TiKV 时，会先将被升级节点的 leader 迁移到其他节点，迁移过程会需要一定时间，可以通过设置 --transfer-timeout 设置最长等待时间（单位为秒），超时之后会跳过等待直接升级服务。

注意
若出现跳过等待直接升级的情况，服务性能可能会出现抖动。

--ignore-config-check
在二进制文件更新之后，TiUP 会对 TiDB，TiKV 和 PD 组件执行配置检查，检查方式为 <binary> --config-check <config-file>，其中 <binary> 为新部署的二进制文件的路径，<config-file> 为根据用户配置生成的配置文件。如果想要跳过该项检查，可以使用该选项。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

--offline
声明当前集群处于停止状态。指定该选项时，TiUP Cluster 仅原地替换集群组件的二进制文件，不执行迁移 Leader 以及重启服务等操作。
数据类型：BOOLEAN
该选项默认关闭，默认值为 false。在命令中添加该选项，并传入 true 值或不传值，均可开启此功能。

• 输出
  升级服务的日志。