环境准备
先决条件
参考官网的TiDB 软件和硬件环境建议配置。
创建用户
创建普通用户、授权，并以普通用户身份登录测试机。
以 tidb 用户为例，后续安装 TiUP 及集群管理操作均通过该用户完成。
centos(7.3以上)：
useradd tidb &&passwd tidb
sudo chown tidb:tidb /home/tidb/
ubuntu（LTS 20.04以上）：
useradd -m tidb && passwd tidb
sudo chown tidb:tidb /home/tidb/
sudo chmod 750 /home/tidb/
sudo chmod 644 /home/tidb/.bashrc
修改/etc/passwd文件，将tidb用户sh改为bash。
离线部署TiUP组件
准备 TiUP 离线组件包
在官方下载页面选择对应版本的 TiDB server 离线镜像包（包含 TiUP 离线组件包）。
需要同时下载 TiDB-community-server 软件包和 TiDB-community-toolkit 软件包。
https://cn.pingcap.com/product-community/
我们选择社区版，最近的LTS版本，此处以v8.1.1为例：
部署离线环境 TiUP 组件
将离线包发送到测试机后，切换tidb用户，执行以下命令j解压并安装 TiUP 组件：
tar xzvf tidb-community-server-${version}-linux-amd64.tar.gz && \
sh tidb-community-server-${version}-linux-amd64/local_install.sh
复制打印的结果，生效环境变量。以ubuntu为例：
source /home/tidb/.bashrc
local_install.sh 脚本会自动执行如下命令将当前镜像地址设置为 tidb-community-server-${version}-linux-amd64。
tiup mirror set tidb-community-server-${version}-linux-amd64
合并离线包
如果是通过官方下载页面下载的离线软件包，需要将 TiDB-community-server 软件包和 TiDB-community-toolkit 软件包合并到离线镜像中。
执行以下命令合并离线组件到 server 目录下。
tar xf tidb-community-toolkit-${version}-linux-amd64.tar.gz
ls -ld tidb-community-server-${version}-linux-amd64 tidb-community-toolkit-${version}-linux-amd64
cd tidb-community-server-${version}-linux-amd64/
cp -rp keys ~/.tiup/
tiup mirror merge ../tidb-community-toolkit-${version}-linux-amd64
tiup mirror merge详见：
https://docs.pingcap.com/zh/tidb/stable/tiup-command-mirror-merge
若需将镜像切换到其他目录，可以通过手动执行 tiup mirror set
初始化集群拓扑文件
可执行如下命令，生成集群初始化配置文件：
tiup cluster template > topology.yaml
如果提示“A new version of cluster is available”可将打印的结果复制出来执行：
tiup update cluster
tiup update --all
然后再次生成集群初始化配置文件即可。
或者还可以使用模板自己创建此文件，基本配置文件的内容参考：
# # Global variables are applied to all deployments and used as the default value of
# # the deployments if a specific deployment value is missing.
global:
user: "tidb"
ssh_port: 22
deploy_dir: "/data/tidb/tidb-deploy"
data_dir: "/data/tidb/tidb-data"
# # Monitored variables are applied to all the machines.
monitored:
node_exporter_port: 9100
blackbox_exporter_port: 9115
server_configs:
tidb:
instance.tidb_slow_log_threshold: 300
tikv:
readpool.storage.use-unified-pool: false
readpool.coprocessor.use-unified-pool: true
pd:
replication.enable-placement-rules: true
replication.location-labels: ["host"]
tiflash:
logger.level: "info"
pd_servers:
- host: 10.0.8.86
tidb_servers:
- host: 10.0.8.86
tikv_servers:
- host: 10.0.8.86
port: 20160
status_port: 20180
config:
server.labels: { host: "logic-host-1" }
- host: 10.0.8.86
port: 20161
status_port: 20181
config:
server.labels: { host: "logic-host-2" }
- host: 10.0.8.86
port: 20162
status_port: 20182
config:
server.labels: { host: "logic-host-3" }
tiflash_servers:
- host: 10.0.8.86
monitoring_servers:
- host: 10.0.8.86
grafana_servers:
- host: 10.0.8.86
其他场景配置文件模板可从官网获取。
注意：
- 对于需要全局生效的参数，请在配置文件中
server_configs的对应组件下配置。 - 对于需要某个节点生效的参数，请在具体节点的
config中配置。 - 配置的层次结构使用
.表示。如：log.slow-threshold。更多格式参考 TiUP 配置参数模版。 - 如果需要指定在目标机创建的用户组名，可以参考这个例子。
更多参数说明，请参考：
- TiDB
config.toml.example - TiKV
config.toml.example - PD
config.toml.example - TiFlash
config.toml.example
执行部署命令
注意：
通过 TiUP 进行集群部署可以使用密钥或者交互密码方式来进行安全认证：
-
如果是密钥方式，可以通过 -i 或者 --identity_file 来指定密钥的路径。
-
如果是密码方式，可以通过 -p 进入密码交互窗口。
-
如果已经配置免密登录目标机，则不需填写认证。
一般情况下 TiUP 会在目标机器上创建 topology.yaml 中约定的用户和组，以下情况例外：
-
topology.yaml 中设置的用户名在目标机器上已存在。
-
在命令行上使用了参数 --skip-create-user 明确指定跳过创建用户的步骤。
执行部署命令前，先使用 check 及 check --apply 命令检查和自动修复集群存在的潜在风险：
1.检查集群存在的潜在风险
tiup cluster check ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa]
以测试环境举例
cd /home/tidb/.tiup/bin
tiup cluster check ./topology.yaml --user root -p
2.自动修复集群存在的潜在风险
tiup cluster check ./topology.yaml --apply --user root [-p] [-i /home/root/.ssh/gcp_rsa]
测试环境执行后仍有部分未修复，需要手动处理。
常见错误及解决方式汇总
- 解决numa的fail：
sudo apt-get install numactl
- 解决mount point / does not have ‘nodelalloc’ option set和mount point / does not have ‘noatime’ option set的fail，需要编辑/etc/fstab文件，增加nodelalloc和noatime的配置，配置如下：
# <file system> <mount point> <type> <options> <dump> <pass>
/dev/disk/by-uuid/f261169a-5d8e-445c-b9e6-8d6ebd961849 none swap sw 0 0
# / was on /dev/xvda4 during curtin installation
/dev/disk/by-uuid/b591a040-be76-4de3-88b9-ed105dd89c43 / ext4 defaults,nodelalloc,noatime 0 1
# /boot was on /dev/xvda3 during curtin installation
/dev/disk/by-uuid/56eb0efd-0066-4723-bf10-6b33f224b4f9 /boot ext4 defaults 0 1
/swap.img none swap sw 0 0
重启后生效。
也有说noatime对于虚拟机来说无所谓，后续进一步查看含义。
- will try to disable THP, please check again after reboot，重启后不会自动修复，需要手动关闭透明大页。
有两种方法，优选如下这种：
vim /etc/default/grub
向GRUB_CMDLINE_LINUX_DEFAULT选项追加transparent_hugepage=never，顺序无所谓：
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash transparent_hugepage=never"
然后执行：
update-grub
重启主机后生效。检查如下文件，是否中括号括在never上：
cat /sys/kernel/mm/transparent_hugepage/enabled
- multiple components tikv:/data/tidb/tidb-data/tikv-20160,tikv:/data/tidb/tidb-data/tikv-20161,tikv:/data/tidb/tidb-data/tikv-20162,tiflash:/data/tidb/tidb-data/tiflash-9000 are using the same partition x.x.x.x:/ as data dir, auto fixing not supported
此错误意思是不同tikv公用同一个目录，意味着磁盘要混用，这个对于读写效率影响相当严重，如果是测试环境的话无所谓，继续安装即可，如果是生产，强烈建议每个tikv对应不同的磁盘。
测试环境中将topology.yaml文件中tikv只保留第一个，剩下两个均注释掉；然后tiflash相关的也注释掉，重新检测后通过。
3.部署 TiDB 集群
命令示例：
tiup cluster deploy tidb-test-86 v8.1.1 ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa]
以上部署示例中：
- tidb-test-86 为部署的集群名称。
- v8.1.1 为部署的集群版本，可以通过执行 tiup list tidb 来查看 TiUP 支持的最新可用版本。
- 初始化配置文件为 topology.yaml。
- –user root 表示通过 root 用户登录到目标主机完成集群部署，该用户需要有 ssh 到目标机器的权限，并且在目标机器有 sudo 权限。也可以用其他有 ssh 和 sudo 权限的用户完成部署。
- [-i] 及 [-p] 为可选项，如果已经配置免密登录目标机，则不需填写。否则选择其一即可，[-i] 为可登录到目标机的 root 用户（或 --user 指定的其他用户）的私钥，也可使用 [-p] 交互式输入该用户的密码。
预期日志结尾输出如下内容，表示部署成功。
Deployed cluster `tidb-test-86` successfully, you can start it with command: `tiup cluster start tidb-test-86 --init`
查看 TiUP 管理的集群情况
执行如下命令：
tiup cluster list
TiUP 支持管理多个 TiDB 集群，该命令会输出当前通过 TiUP cluster 管理的所有集群信息，包括集群名称、部署用户、版本、密钥信息等。
当前测试环境输出结果为：
Name User Version Path PrivateKey
---- ---- ------- ---- ----------
tidb-test-86 tidb v8.1.1 /home/tidb/.tiup/storage/cluster/clusters/tidb-test-86 /home/tidb/.tiup/storage/cluster/clusters/tidb-test-86/ssh/id_rsa
检查部署的 TiDB 集群情况
例如，执行如下命令检查 tidb-test-86 集群情况：
tiup cluster display tidb-test-86
预期输出包括 tidb-test-86 集群中实例 ID、角色、主机、监听端口和状态（由于还未启动，所以状态为 Down/inactive）、目录信息。
此例中输入为：
Cluster type: tidb
Cluster name: tidb-test-86
Cluster version: v8.1.1
Deploy user: tidb
SSH type: builtin
Grafana URL: http://10.0.8.86:3000
ID Role Host Ports OS/Arch Status Data Dir Deploy Dir
-- ---- ---- ----- ------- ------ -------- ----------
10.0.8.86:3000 grafana 10.0.8.86 3000 linux/x86_64 Down - /data/tidb/tidb-deploy/grafana-3000
10.0.8.86:2379 pd 10.0.8.86 2379/2380 linux/x86_64 Down /data/tidb/tidb-data/pd-2379 /data/tidb/tidb-deploy/pd-2379
10.0.8.86:9090 prometheus 10.0.8.86 9090/12020 linux/x86_64 Down /data/tidb/tidb-data/prometheus-9090 /data/tidb/tidb-deploy/prometheus-9090
10.0.8.86:4000 tidb 10.0.8.86 4000/10080 linux/x86_64 Down - /data/tidb/tidb-deploy/tidb-4000
10.0.8.86:20160 tikv 10.0.8.86 20160/20180 linux/x86_64 N/A /data/tidb/tidb-data/tikv-20160 /data/tidb/tidb-deploy/tikv-20160
Total nodes: 5
启动集群
安全启动是 TiUP cluster 从 v1.9.0 起引入的一种新的启动方式，采用该方式启动数据库可以提高数据库安全性。推荐使用安全启动。
安全启动后，TiUP 会自动生成 TiDB root 用户的密码，并在命令行界面返回密码。
该自动生成的密码只会返回一次，如果没有记录或者忘记该密码，请参照忘记 root 密码修改密码。
安全启动
tiup cluster start tidb-test-86 --init
输出结果如下：
Starting cluster tidb-test-86...
+ [ Serial ] - SSHKeySet: privateKey=/home/tidb/.tiup/storage/cluster/clusters/tidb-test-86/ssh/id_rsa, publicKey=/home/tidb/.tiup/storage/cluster/clusters/tidb-test-86/ssh/id_rsa.pub
+ [Parallel] - UserSSH: user=tidb, host=10.0.8.86
+ [Parallel] - UserSSH: user=tidb, host=10.0.8.86
+ [Parallel] - UserSSH: user=tidb, host=10.0.8.86
+ [Parallel] - UserSSH: user=tidb, host=10.0.8.86
+ [Parallel] - UserSSH: user=tidb, host=10.0.8.86
+ [ Serial ] - StartCluster
Starting component pd
Starting instance 10.0.8.86:2379
Start instance 10.0.8.86:2379 success
Starting component tikv
Starting instance 10.0.8.86:20160
Start instance 10.0.8.86:20160 success
Starting component tidb
Starting instance 10.0.8.86:4000
Start instance 10.0.8.86:4000 success
Starting component prometheus
Starting instance 10.0.8.86:9090
Start instance 10.0.8.86:9090 success
Starting component grafana
Starting instance 10.0.8.86:3000
Start instance 10.0.8.86:3000 success
Starting component node_exporter
Starting instance 10.0.8.86
Start 10.0.8.86 success
Starting component blackbox_exporter
Starting instance 10.0.8.86
Start 10.0.8.86 success
+ [ Serial ] - UpdateTopology: cluster=tidb-test-86
Started cluster `tidb-test-86` successfully
The root password of TiDB database has been changed.
The new password is: '1X-W8_+Du754vat*9h'.
Copy and record it to somewhere safe, it is only displayed once, and will not be stored.
The generated password can NOT be get and shown again.
从中可以看到启动顺序，以及生成的root密码。看到Started cluster `tidb-test-86` successfully说明启动成功。
普通启动
用普通启动方式即去掉–init参数，用无密码的root登录。
验证集群运行状态
通过 TiUP 检查集群状态
执行如下命令：
tiup cluster display tidb-test-86
预期结果输出：各节点 Status 状态信息为 Up 说明集群状态正常。
此例中输出结果为：
Cluster type: tidb
Cluster name: tidb-test-86
Cluster version: v8.1.1
Deploy user: tidb
SSH type: builtin
Dashboard URL: http://10.0.8.86:2379/dashboard
Grafana URL: http://10.0.8.86:3000
ID Role Host Ports OS/Arch Status Data Dir Deploy Dir
-- ---- ---- ----- ------- ------ -------- ----------
10.0.8.86:3000 grafana 10.0.8.86 3000 linux/x86_64 Up - /data/tidb/tidb-deploy/grafana-3000
10.0.8.86:2379 pd 10.0.8.86 2379/2380 linux/x86_64 Up|L|UI /data/tidb/tidb-data/pd-2379 /data/tidb/tidb-deploy/pd-2379
10.0.8.86:9090 prometheus 10.0.8.86 9090/12020 linux/x86_64 Up /data/tidb/tidb-data/prometheus-9090 /data/tidb/tidb-deploy/prometheus-9090
10.0.8.86:4000 tidb 10.0.8.86 4000/10080 linux/x86_64 Up - /data/tidb/tidb-deploy/tidb-4000
10.0.8.86:20160 tikv 10.0.8.86 20160/20180 linux/x86_64 Up /data/tidb/tidb-data/tikv-20160 /data/tidb/tidb-deploy/tikv-20160
Total nodes: 5
使用mysql客户端连接
mysql -h 127.0.0.1 -P 4000 -u root -p
可以看到熟悉的命令行界面，版本信息为tidb相关信息：
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 3835691014
Server version: 8.0.11-TiDB-v8.1.1 TiDB Server (Apache License 2.0) Community Edition, MySQL 8.0 compatible
Copyright (c) 2000, 2024, Oracle and/or its affiliates.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
通过TiDB Dashboard检查集群状态
通过 {pd-ip}:{pd-port}/dashboard 登录 TiDB Dashboard，登录用户和口令为 TiDB 数据库 root 用户和口令。如果你修改过数据库的 root 密码，则以修改后的密码为准，默认密码为空。
此例中为：
http://10.0.8.86:2379/dashboard
主页面显示 TiDB 集群中节点信息
通过Grafana 检查集群状态
通过 {Grafana-ip}:3000 登录 Grafana 监控，默认用户名及密码为 admin/admin。
首次登录需要修改admin密码。
点击 Overview 监控页面检查 TiDB 端口和负载监控信息。
通过dbeaver连接
因为tidb兼容mysql协议，因此选择mysql即可，端口改为4000：
基本操作
绝大部分语法和mysql相同，如下是官网的例子。
检查 TiDB 版本
select tidb_version()\G
创建 PingCAP database
create database pingcap;
use pingcap;
创建 tab_tidb 表
CREATE TABLE `tab_tidb` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`name` varchar(20) NOT NULL DEFAULT '',
`age` int(11) NOT NULL DEFAULT 0,
`version` varchar(20) NOT NULL DEFAULT '',
PRIMARY KEY (`id`),
KEY `idx_age` (`age`));
插入数据
insert into `tab_tidb` values (1,'TiDB',5,'TiDB-v5.0.0');
查看 tab_tidb 数据
select * from tab_tidb;
查看 TiKV store 状态、store_id、存储情况以及启动时间
select STORE_ID,ADDRESS,STORE_STATE,STORE_STATE_NAME,CAPACITY,AVAILABLE,UPTIME from INFORMATION_SCHEMA.TIKV_STORE_STATUS;
创建管理员
create user 'wenjie.wang'@'%' identified by 'xxxxxxxxxx';
grant all privileges on *.* to 'wenjie.wang'@'%' with grant option;
退出
exit
关闭及销毁集群
关闭
关闭集群操作会按 Alertmanager -> Grafana -> Prometheus -> TiCDC -> Drainer -> TiFlash -> TiDB -> Pump -> TiKV -> PD 的顺序关闭整个 TiDB 集群所有组件（同时也会关闭监控组件）：
tiup cluster stop ${cluster-name}
和 start 命令类似，stop 命令也支持通过 -R 和 -N 参数来只停止部分组件。
例如，下列命令只停止 TiDB 组件：
tiup cluster stop ${cluster-name} -R tidb
下列命令只停止 1.2.3.4 和 1.2.3.5 这两台机器上的 TiDB 组件：
tiup cluster stop ${cluster-name} -N 1.2.3.4:4000,1.2.3.5:4000
销毁
销毁集群操作会关闭服务，清空数据目录和部署目录，并且无法恢复，需要谨慎操作。
tiup cluster destroy ${cluster-name}
