命令总览

TiUP TEM 组件提供以下命令，按完整部署流程排序：

template 生成配置模板准备阶段

deploy 部署集群部署阶段

tls-gen 生成 TLS 证书安全配置

start 启动集群启动阶段

display 显示集群信息监控阶段

list 列出所有集群监控阶段

show-config 显示集群配置配置管理

edit-config 编辑集群配置配置管理

reload 重新加载配置配置管理

restart 重启集群运维阶段

stop 停止集群运维阶段

scale-out 扩容集群扩缩容

scale-in 缩容集群扩缩容

upgrade 升级集群升级维护

patch 热更新组件升级维护

destroy 销毁集群销毁阶段

check 检查配置部署前阶段

全局选项

所有命令支持以下全局选项：

--ssh-timeout (int64，默认 5)

SSH 连接超时时间（秒）

--wait-timeout (int64，默认 120)

操作等待超时时间（秒）

-y --yes (bool，默认 false)

跳过所有确认提示，自动确认

--ssh-proxy-host (string)

SSH 代理服务器地址

--ssh-proxy-port (int，默认 22)

SSH 代理服务器端口

--ssh-proxy-user (string，默认当前用户)

SSH 代理登录用户名

--ssh-proxy-use-password (bool，默认 false)

SSH 代理使用密码认证

--ssh-proxy-identity (string，默认 ~/.ssh/id_rsa)

SSH 代理私钥路径

--format (string，默认 default)

输出格式（default/json）

--force (bool，默认 false)

强制模式，忽略确认

tiup tem template 生成配置模板

生成拓扑配置模板文件，支持生成三种模板：config.yaml（主配置）、metadb_topology.yaml（元数据库拓扑）、scale-out-demo.yaml（扩容示例）。

语法

tiup tem template [flags]

选项

--output (string，默认 -)

输出文件路径

--mode（string，默认 all）

模板模式：config/metadb/scale-out/all

--overwrite（bool，默认 false）

覆盖已存在的输出文件

配置模板选项

--name （string，默认 tem）

集群名称

-v, --version

tem 版本

-u, --user （string，默认 tidb）

运行 TEM 服务的用户

--ssh-port （uint，默认 22）

服务器 SSH 端口

--deploy-dir （string，默认 /tem-deploy）

TEM 部署目录

--data-dir （string，默认 /tem-data ）

TEM 数据目录

--init-tcm-port （uint，默认 8090）

初始 TCM 端口

--init-tisupervisor-port （uint，默认 8095）

初始 TiSupervisor 端口

--db-addresses（string，默认 127.0.0.1:4000）

TEM 元数据库用户

--db-user （string，默认 root）

TEM 元数据库密码

--db-password （string，默认 -）

TEM 元数据库名称

--db-name （string，默认 tem ）

TEM 日志最大大小（MB）

--log-max-size （uint，默认 300）

TEM 日志保留天数

--log-max-days （uint，默认 30 ）

TEM 服务器列表

--tem-servers （string，默认 127.0.0.1）

TEM 服务器端口列表

--tem-ports （uint，默认 8080 ）

MetaDB 模板选项

--metadb-deploy-dir （string，默认 /tidb-deploy）

MetaDB 部署目录

--metadb-data-dir （string，默认 /tidb-data）

MetaDB 数据目录

--pd-servers （string，默认 127.0.0.1）

PD 服务器列表

--pd-client-ports （uint，默认 2379）

PD 客户端端口列表

--pd-peer-ports （uint，默认 2380）

PD 对等端口列表

--tidb-servers （string，默认 127.0.0.1）

TiDB 服务器列表

--tidb-ports （uint，默认 4000）

TiDB 端口列表

--tidb-status-ports （uint，默认 10080）

TiDB 状态端口列表

--tikv-servers （string，默认 127.0.0.1）

TiKV 服务器列表

--tikv-ports （uint，默认 20160）

TiKV 端口列表

--tikv-status-ports（uint，默认 20180）

TiKV 状态端口列表

--node-exporter-port（uint，默认 9100）

Node Exporter 端口

--blackbox-exporter-port （uint，默认 9115）

Blackbox Exporter 端口

Scale-out 模板选项

--scale-out-servers （string，默认 172.17.0.3）

扩容 TEM 服务器列表

--scale-out-ports （uint，默认 8080）

扩容 TEM 端口列表

使用示例

# 生成所有模板到当前目录
tiup tem template

# 只生成 config.yaml
tiup tem template --mode config

# 只生成 metadb_topology.yaml
tiup tem template --mode metadb

# 只生成 scale-out 模板
tiup tem template --mode scale-out

# 输出到指定文件
tiup tem template --mode config -o my-config.yaml

# 覆盖已存在的文件
tiup tem template --mode all --overwrite

# 自定义参数生成模板
tiup tem template --mode config --user deployer --deploy-dir /opt/tem --tem-servers 192.168.1.100,192.168.1.101 --tem-ports 8080,8080

tiup tem deploy 部署 TEM 集群

部署一个新的 TEM 集群，使用指定的拓扑文件。命令会通过 SSH 连接到目标主机，部署必要的文件，并创建运行服务的系统用户。

语法

tiup tem deploy <topology> [flags]

参数

topology.yaml` | string | 是 |

拓扑配置文件路径

选项

-u --user （string，默认当前用户）

SSH 登录用户名（需有 root 或 sudo 权限）

-i --identity_file （string，默认 ~/.ssh/id_rsa）

SSH 私钥文件路径

-p --password （bool，默认 false）

使用密码认证

--metadb-topology （string，默认 127.0.0.1）

MetaDB 拓扑文件路径

--start （bool，默认 true）

生成后是否启动服务

使用示例

# 基本部署（使用默认topology部署）
tiup tem deploy

#使用指定topology部署
tiup tem deploy topology.yaml

# 指定 MetaDB 拓扑文件
tiup tem deploy topology.yaml --metadb-topology metadb_topology.yaml

# 使用指定用户部署
tiup tem deploy topology.yaml -u tidb

# 使用密码认证部署
tiup tem deploy topology.yaml -p

注意事项

部署用户需要具有 root 或 sudo 权限
如果拓扑文件中启用了 TLS，部署会自动生成证书

tls-gen - 生成 TLS 证书

为集群生成 TLS 证书，包括内部通信和外部通信证书。支持生成 PEM 格式和 PKCS#12 格式的证书。

语法

tiup tem tls-gen [flags]

生成的证书文件

证书文件存储在 {storage-dir}/clusters/tem/tls 目录下：

内部证书（internal）

ca.crt - CA 根证书
ca.key - CA 私钥
tem-server.crt - TEM 服务器证书
tem-server.key - TEM 服务器私钥
tem-server.pfx - PKCS#12 格式证书

外部证书（external）

ca.crt - CA 根证书
ca.key - CA 私钥
tem-server.crt - TEM 服务器证书
tem-server.key - TEM 服务器私钥
tem-server.pfx - PKCS#12 格式证书

使用示例

# 为默认集群生成证书
tiup tem tls-gen

注意事项

如果证书已存在，命令会提示而不会覆盖
证书使用 RSA 加密和 RSASSA-PSS-SHA256 签名方案
生成的证书有效期由 CA 配置决定

start - 启动集群

启动已部署的 TEM 集群，服务将按照拓扑中定义的顺序启动。

语法

tiup tem start [flags]

使用示例

# 启动默认集群（tem）
tiup tem start

display - 显示集群信息

显示 TEM 集群的详细信息，包括拓扑结构和各节点的运行状态。

语法

tiup tem display [flags]

输出示例

TEM cluster: tem
TEM version: v1.0.0

Type: tem
ID                 Role        Host           Ports    OS/Arch       Status   Data Dir
--                 ----        ----           -----    -------       ------   --------
192.168.1.100:8080 tem         192.168.1.100  8080     linux/x86_64  Up       /opt/tem/data
192.168.1.101:8080 tem         192.168.1.101  8080     linux/x86_64  Up       /opt/tem/data
192.168.1.102:8080 tem         192.168.1.102  8080     linux/x86_64  Up       /opt/tem/data

使用示例

# 显示默认集群（tem）信息
tiup tem display

list - 列出集群

列出本地所有已部署的 TEM 集群。

语法

tiup tem list

输出示例

Name        User    Version    Path
----        ----    -------    ----
tem         tidb    v1.0.0     /root/.tiup/storage/tem/clusters/tem

使用示例

tiup tem list

show-config - 显示配置

显示集群的完整配置信息，包括拓扑和服务设置。

语法

tiup tem show-config [flags]

使用示例

# 显示配置
tiup tem show-config

edit-config - 编辑配置

使用默认编辑器编辑集群的配置文件。

语法

tiup tem edit-config [flags]

使用示例

# 编辑tem配置
tiup tem edit-config

注意事项

编辑完成后需要使用 reload 命令使配置生效
集群名称必须符合命名规范

reload - 重新加载配置

重新加载集群配置并重启必要的服务。

语法

tiup tem reload [flags]

选项

--skip-restart （bool，默认 false

跳过服务重启

使用示例

# 重新加载配置并重启服务
tiup tem reload
# 重新加载配置但不重启服务
tiup tem reload --skip-restart=true

restart - 重启集群

重启 TEM 集群，相当于先执行 stop 再执行 start。

语法

tiup tem restart [flags]

使用示例

# 重启集群
tiup tem restart

stop - 停止集群

停止运行中的 TEM 集群。

语法

tiup tem stop [flags]

选项

-R --role （string） | stringSlice

只停止指定角色 |

-N --node （string） stringSlice

只停止指定节点 |

使用示例

# 停止集群（tem）
tiup tem stop

# 停止指定节点
tiup tem stop -N 192.168.1.100:8080

# 停止指定角色
tiup tem stop -R tem

scale-out - 扩容集群

向现有集群添加新的 TEM 节点。支持两种模式：拓扑文件模式和主机/端口模式。

语法

# 拓扑文件模式
tiup tem scale-out --topology <topology.yaml> [flags]

# 主机/端口模式
tiup tem scale-out --host <host1,host2,...> --port <port1,port2,...> [flags]

选项

--topology （string）

扩容拓扑文件路径

--host（stringSlice）

要添加的主机列表

--port（sintSlice）

要添加的端口列表

-u --user （string，默认当前用户）

SSH 登录用户名

-i --identity_file （string，默认 ~/.ssh/id_rsa）

SSH 私钥文件路径

-p --password （string）

使用密码认证

使用示例

# 使用拓扑文件扩容集群
tiup tem scale-out --topology scale-out.yaml

# 使用主机/端口模式扩容单个节点
tiup tem scale-out --host 192.168.1.103 --port 8080

# 使用主机/端口模式扩容多个节点
tiup tem scale-out --host 192.168.1.103,192.168.1.104 --port 8080,8080

# 指定用户扩容
tiup tem scale-out --topology scale-out.yaml -u tidb

注意事项

主机数量和端口数量必须匹配
扩容后会自动生成 TLS 证书（如果启用）

scale-in - 缩容集群

功能描述

从集群中移除指定的 TEM 节点。

语法

tiup tem scale-in --node <node-id> [flags]

选项

-N --node （stringSlice）

要移除的节点 ID

--transfer-timeout （uint64，600）

迁移超时时间（秒）

--force` （bool，默认 false）

强制移除，跳过优雅停止

使用示例

# 移除默认集群的单个节点
tiup tem scale-in -N 192.168.1.103:8080

# 移除指定集群的单个节点
tiup tem scale-in -N 192.168.1.103:8080

# 移除多个节点
tiup tem scale-in -N 192.168.1.103:8080,192.168.1.104:8080

# 强制移除
tiup tem scale-in -N 192.168.1.103:8080 --force

注意事项

节点 ID 格式为 host:port
缩容操作会先停止节点服务，然后清理相关文件

15. upgrade - 升级集群

功能描述

将 TEM 集群升级到指定的目标版本。

语法

tiup tem upgrade <version> [flags]

参数说明

version （string)

目标版本号

使用示例

# 升级默认集群到 v1.1.0
tiup tem upgrade v1.1.0

patch - 热更新组件

使用指定的包替换远程服务包并重启服务，支持在不停止整个集群的情况下更新 TEM 二进制文件。

语法

tiup tem patch <package-path> [flags]

参数说明

package-path（string)

新包文件路径

选项

-u --user

SSH 登录用户名

-i --identity_file （string，默认 ~/.ssh/id_rsa)

SSH 私钥文件路径

-p --password （bool，默认 false)

使用密码认证

-o --overwrite （bool，默认 faltruese)

在后续扩容中使用此包

-r --restart （bool，默认 true)

打补丁后重启服务

-N --node （stringSlice)

指定要打补丁的节点

-R --role （stringSlice)

指定要打补丁的角色

--offline（bool，默认 false)

对已停止的集群打补丁

使用示例

# 对集群打补丁
tiup tem patch /path/to/new-tem.tar.gz -N tem-192.168.1.100:8080 -R tem

# 打补丁但不重启
tiup tem patch /path/to/new-tem.tar.gz -N tem-192.168.1.100:8080 -R tem --restart=false

# 对离线集群打补丁
tiup tem patch /path/to/new-tem.tar.gz -N tem-192.168.1.100:8080 -R tem --offline

注意事项

必须指定 -N（节点）或 -R（角色）中的至少一个
有效角色包括：tem

destroy - 销毁集群

销毁指定的 TEM 集群，停止所有服务并移除所有数据。此操作不可逆。

语法

tiup tem destroy [flags]

选项

--retain-node-data （stringArray)

保留指定节点的数据

--retain-role-data （stringArray)

保留指定角色的数据

--force （bool，默认 false)

强制销毁，忽略远程错误

使用示例

# 销毁默认集群（tem-server）
tiup tem destroy

# 销毁集群但保留某些节点的数据
tiup tem destroy --retain-node-data 192.168.1.100:8080

# 强制销毁
tiup tem destroy  --force

check - 检查配置

部署前检查配置是否有效。

语法

tiup check <topology> [flags]

参数说明

topology.yaml （string)

拓扑配置文件路径

选项

--metadb-topology （string)

metadb 拓扑文件路径

--scale-out（string)

scale-out 拓扑文件路径

使用示例

 # 检测tem拓扑配置
tiup check topology.yaml

# 检测metadb拓扑配置
tiup check --metadb-topology metadb_topology.yaml

# 检测scale-out拓扑配置
tiup check --scale-out scale-out_topology.yaml

命令总览

template 生成配置模板 准备阶段

deploy 部署集群 部署阶段

tls-gen 生成 TLS 证书 安全配置

start 启动集群 启动阶段

display 显示集群信息 监控阶段

list 列出所有集群 监控阶段

show-config 显示集群配置 配置管理

edit-config 编辑集群配置 配置管理

reload 重新加载配置 配置管理

restart 重启集群 运维阶段

stop 停止集群 运维阶段

scale-out 扩容集群 扩缩容

scale-in 缩容集群 扩缩容

upgrade 升级集群 升级维护

patch 热更新组件 升级维护

destroy 销毁集群 销毁阶段

check 检查配置 部署前阶段

全局选项

--ssh-timeout (int64，默认 5)

--wait-timeout (int64，默认 120)

-y --yes (bool，默认 false)

--ssh-proxy-host (string)

--ssh-proxy-port (int，默认 22)

--ssh-proxy-user (string，默认 当前用户)

--ssh-proxy-use-password (bool，默认 false)

--ssh-proxy-identity (string，默认 ~/.ssh/id_rsa)

--format (string，默认 default)

--force (bool，默认 false)

tiup tem template 生成配置模板

语法

选项

--output (string，默认 -)

--mode（string，默认 all）

--overwrite（bool，默认 false）

配置模板选项

--name （string，默认 tem）

-v, --version

-u, --user （string，默认 tidb）

--ssh-port （uint，默认 22）

--deploy-dir （string，默认 /tem-deploy）

--data-dir （string，默认 /tem-data ）

--init-tcm-port （uint，默认 8090）

--init-tisupervisor-port （uint，默认 8095）

--db-addresses（string，默认 127.0.0.1:4000）

--db-user （string，默认 root）

--db-password （string，默认 -）

--db-name （string，默认 tem ）

--log-max-size （uint，默认 300）

--log-max-days （uint，默认 30 ）

--tem-servers （string，默认 127.0.0.1）

--tem-ports （uint，默认 8080 ）

MetaDB 模板选项

--metadb-deploy-dir （string，默认 /tidb-deploy）

--metadb-data-dir （string，默认 /tidb-data）

--pd-servers （string，默认 127.0.0.1）

--pd-client-ports （uint，默认 2379）

--pd-peer-ports （uint，默认 2380）

--tidb-servers （string，默认 127.0.0.1）

--tidb-ports （uint，默认 4000）

--tidb-status-ports （uint，默认 10080）

--tikv-servers （string，默认 127.0.0.1）

--tikv-ports （uint，默认 20160）

--tikv-status-ports（uint，默认 20180）

--node-exporter-port（uint，默认 9100）

--blackbox-exporter-port （uint，默认 9115）

Scale-out 模板选项

--scale-out-servers （string，默认 172.17.0.3）

--scale-out-ports （uint，默认 8080）

使用示例

tiup tem deploy 部署 TEM 集群

语法

参数

topology.yaml` | string | 是 |

选项

-u --user （string，默认 当前用户）

-i --identity_file （string，默认 ~/.ssh/id_rsa）

-p --password （bool，默认 false）

--metadb-topology （string，默认 127.0.0.1）

--start （bool，默认 true）

template 生成配置模板准备阶段

deploy 部署集群部署阶段

tls-gen 生成 TLS 证书安全配置

start 启动集群启动阶段

display 显示集群信息监控阶段

list 列出所有集群监控阶段

show-config 显示集群配置配置管理

edit-config 编辑集群配置配置管理

reload 重新加载配置配置管理

restart 重启集群运维阶段

stop 停止集群运维阶段

scale-out 扩容集群扩缩容

scale-in 缩容集群扩缩容

upgrade 升级集群升级维护

patch 热更新组件升级维护

destroy 销毁集群销毁阶段

check 检查配置部署前阶段

--ssh-proxy-user (string，默认当前用户)

-u --user （string，默认当前用户）

-u --user （string，默认当前用户）