TiDB 完整部署\+分步扩容标准化实操文档

什么是TiDB

TiDB 是 PingCAP 开源研发的分布式 NewSQL 关系型数据库，兼容 MySQL 5.7 协议，既保留传统数据库 ACID 事务、标准 SQL 能力，又拥有 NoSQL 的无限水平扩容能力，同时支持在线业务（OLTP）+ 实时数据分析（OLAP）混合负载（HTAP）。

三大核心组件（存算分离架构）

1. TiDB Server（计算层）

无状态 SQL 入口，接收客户端 MySQL 连接、解析优化执行 SQL；可以运行时随意加节点提升并发读写性能，单台节点故障，请求自动转发其他节点，集群不会崩溃，仅并发上限小幅下降。

2. TiKV（存储层）

分布式 KV 存储，数据默认 3 副本、基于 Raft 算法强一致；数据自动分片均衡，新增存储节点会自动迁移数据实现扩容；某一台 TiKV 宕机，副本自动切换主节点，业务不停，只是集群整体存储算力下降、性能轻微衰减，完全不会整体瘫痪，正好匹配你之前的需求。

3. PD（调度集群，集群大脑）

管理元数据、分配全局时间戳、自动调度数据分片、均衡各节点负载，负责故障检测、副本迁移，保证集群稳定运行，一般部署 3 个节点做高可用。

TiDB 有免费可用版本，分为社区开源版、云免费试用版两大类，完全可以商用免费使用

（社区开源版，永久免费，推荐私有化部署）

授权协议 ：Apache 2.0 开源协议，个人、企业商用都永久免费，无功能阉割、无时间限制、无节点数限制。没有官方技术支持，问题需要靠官方文档、GitHub Issues、TiDB 社区论坛、开源社群解决

TiDB Cloud（云托管版，提供免费套餐）

免费试用集群（永久免费套餐）

配置：单节点开发集群，250MB 内存、10GB 存储，不限时长永久免费
适用：学习、个人项目、测试、小体量开发环境
限制：不支持高可用、仅单副本，不能用于生产业务，带宽、连接数有基础限制

付费集群免费试用额度

新用户注册 TiDB Cloud 可领取一定时长的高性能集群免费额度，可以体验企业级高可用分布式集群，额度用完自动计费。

文档说明

本文档适配本次实操三套流程： 1. 阶段一：主控机（172.16.204.129）全新部署（PD+TiDB+TiKV 全套服务） 2. 阶段二：从节点1（172.16.204.29）扩容 TiDB+TiKV 3. 阶段三：从节点2（172.16.204.54）仅扩容 TiKV 同时汇总全程所有报错坑点、原因、一键解决方案，为虚拟机测试环境专属优化。 目标效果：满足默认3副本高可用，任意一台TiKV节点关机下线，集群正常读写不中断

集群版本 ：v8.5.6 统一运维工具 ：TiUP 统一部署用户 ：tidb 统一目录规范：/home/TiDB/ 下部署、数据、日志目录

官网下载安装包：tidb-community-server-v8.5.6-linux-amd64.tar.gz和tidb-community-toolkit-v8.5.6-linux-amd64.tar.gz

下载地址 ：平凯数据库 - 新一代企业级分布式数据库专家

前置通用准备（所有服务器必须执行）

所有节点（主控+2台从节点）统一环境初始化，缺一不可

1. 创建运行用户并配置权限

复制代码

useradd -m tidb
passwd tidb
# 配置sudo免密（部署、启停、扩容必备）
echo 'tidb ALL=(ALL) NOPASSWD: ALL' >> /etc/sudoers

2. 系统环境标准化优化

复制代码

# 关闭防火墙
systemctl stop firewalld
systemctl disable firewalld

# 永久关闭SELinux
sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
setenforce 0

# 关闭Swap
swapoff -a
sed -i '/swap/d' /etc/fstab

# 关闭透明大页THP
echo never > /sys/kernel/mm/transparent_hugepage/enabled
echo never > /sys/kernel/mm/transparent_hugepage/defrag

# 安装依赖
dnf install -y numactl openssh-server

# 磁盘挂载 nodelalloc、noatime
# 编辑 fstab
vi /etc/fstab
#找到 / 对应的挂载行，在挂载参数位置添加：defaults,noatime,nodelalloc 示例：
UUID=xxxx  /  ext4  defaults,noatime,nodelalloc  0 1
# 重新挂载生效（不需要重启）
mount -o remount /

3. 中控机免密所有节点（核心前提）

在主控机 root 用户执行，分别对所有节点下发密钥

复制代码

ssh-keygen -t rsa -P ""
ssh-copy-id tidb@172.16.204.129 
ssh-copy-id tidb@172.16.204.29
ssh-copy-id tidb@172.16.204.54

校验免密：ssh tidb@节点IP，无需输密码直接登录即为正常

4. 安装必要的工具

无法联网场景，在同版本可联网机器下载 rpm 包

复制代码

yumdownloader --resolve tar numactl numactl-devel

然后在服务器上进行安装

复制代码

# tidb 依赖的解压工具
rpm -ivh tar-1.35-3.oe2403.x86_64.rpm

# 安装 numactl
rpm -ivh numactl-2.0.16-10.oe2403.x86_64.rpm
# 需要开发库（编译 MySQL、Redis、Java 依赖常用）必须带上 numactl-devel。
rpm -ivh numactl-devel-2.0.16-10.oe2403.x86_64.rpm

阶段一：主控机全新部署（PD+TiDB+TiKV）

1. 主控机前置准备

部署离线环境tiup组件

复制代码

cd /home/TiDB
#解压安装包
tar zxvf tidb-community-server-v8.5.6-linux-amd64.tar.gz
tar zxvf tidb-community-toolkit-v8.5.6-linux-amd64.tar.gz

#部署离线环境 TiUP 组件
cd tidb-community-server-v8.5.6-linux-amd64/
sh local_install.sh

#根据提示执行
source /home/TiDB/.bash_profile

合并离线包

复制代码

cp -rp keys ~/.tiup/
tiup mirror merge ../tidb-community-toolkit-v8.5.6-linux-amd64

初始化拓扑文件

执行命令，生成集群初始化配置文件：

复制代码

cd /home/TiDB
tiup cluster template > topology.yaml

2. 编写初始部署拓扑 topology.yaml

复制代码

# 主控机单机初始部署拓扑
global:
  user: "tidb"
  ssh_port: 22
  listen_host: 0.0.0.0
  arch: "arm64"
  
pd_servers:
  - host: 172.16.204.129
    client_port: 2379
    peer_port: 2380
    deploy_dir: /home/TiDB/pd-deploy
    data_dir: /home/TiDB/pd-data
    log_dir: /home/TiDB/pd-deploy/log

tidb_servers:
  - host: 172.16.204.129
    port: 4000
    status_port: 10080
    deploy_dir: /home/TiDB/tidb-deploy
    log_dir: /home/TiDB/tidb-deploy/log

tikv_servers:
  - host: 172.16.204.129
    port: 20160
    status_port: 20180
    deploy_dir: /home/TiDB/tikv-deploy
    data_dir: /home/TiDB/tikv-data
    log_dir: /home/TiDB/tikv-deploy/log

3. 环境预检 & 自动修复

复制代码

tiup cluster check tidb-test topology.yaml --cluster --user tidb --apply

4. 正式部署集群

复制代码

tiup cluster deploy tidb-test v8.5.6 topology.yaml --user tidb

5.初始化安全启动集群

安全启动后，TiUP 会自动生成 TiDB root 用户的密码，并在命令行界面返回密码。

使用安全启动方式后，不能通过无密码的 root 用户登录数据库，你需要记录命令行返回的密码进行后续操作。

复制代码

tiup cluster start tidb-test --init

6. 启动集群 + 开启开机自启

部署集群成功后，先启动集群，后配置开机自启

复制代码

# 启动集群
tiup cluster start tidb-test

# 配置开机自启
tiup cluster enable tidb-test

7.验证集群状态

复制代码

# 验证集群状态
tiup cluster display tidb-test

8. 本地连接TiDB

复制代码

mysql -h127.0.0.1 -uroot -p -P4000

阶段一易错点

错误现象 ：初始部署默认 PD 监听 127.0.0.1，后续扩容节点无法连接 PD（Connection refused）根因：127.0.0.1 仅本机可访问，跨节点无法连通 修复方案（必做）：

复制代码

# 1. 编辑集群配置
tiup cluster edit-config tidb-test
# 2. 将 pd_servers 的 host 从 127.0.0.1 改为 主控机真实内网IP
# 3. 滚动重启PD生效
tiup cluster reload tidb-test -R pd

校验方式：ss -tulpn | grep 2379，监听内网IP/0.0.0.0 即为正常

上述修复不起作用，则需要直接销毁现有集群，重新全新部署

重新全新部署

需要重新编辑 topology.yaml 将 127.0.0.1 改为主控机真实内网IP 后

查看集群列表

复制代码

tiup cluster list

如果能看到 tidb-test，直接执行集群销毁：

复制代码

tiup cluster destroy tidb-test

输入 y 确认，TiUP 会自动：

停止所有节点 PD/TiDB/TiKV/ 监控服务
删除所有节点的 deploy_dir、data_dir 部署与数据目录
清空 TiUP 本地集群元数据

销毁完成后，所有节点干净，可以重新部署。

阶段二：扩容节点1（172.16.204.29）新增 TiDB+TiKV

场景：新增整机计算+存储节点，同时扩容SQL接入和存储能力

1. 网络连通校验

在新机器(172.16.204.29)测试连通 PD 内网 2379 端口：

复制代码

# 验证命令
curl http://主控机内网IP:2379/pd/api/v1/leader

# 文档中以172.16.204.129为主控机
curl http://172.16.204.129:2379/pd/api/v1/leader

2. 在主控机中编写扩容拓扑 scale-out-29.yaml

复制代码

tikv_servers:
  - host: 172.16.204.29
    ssh_port: 22
    port: 20161
    status_port: 20181
    deploy_dir: /home/TiDB/tidb-deploy-20161
    data_dir: /home/TiDB/tidb-data-20161
    log_dir: /home/TiDB/tidb-deploy-20161/log

tidb_servers:
  - host: 172.16.204.29
    ssh_port: 22
    port: 4001
    status_port: 10081
    deploy_dir: /home/TiDB/tidb-deploy-4001
    log_dir: /home/TiDB/tidb-deploy-4001/log

2. 预检修复 + 在线扩容

复制代码

tiup cluster check tidb-test scale-out-29.yaml --cluster --user tidb --apply
# 延长超时时间，规避虚拟机TiKV启动超时
tiup cluster scale-out tidb-test scale-out-29.yaml --user tidb --wait-timeout 360

3. 扩容后验证

复制代码

# 查看集群状态 
tiup cluster display tidb-test

阶段二高频易错点+解决方案

报错1：端口冲突 port conflict 根因：扩容失败残留集群元数据、本地目录/Systemd服务未清理解决方案：强制下线残留节点 + 清空本地残留

复制代码

# 强制下线残留节点 在主控机执行
tiup cluster scale-in tidb-test --node 172.16.204.29:20161 --force

复制代码

# 清空本地残留 在扩容服务器执行
rm -rf /home/TiDB/tidb-deploy-20161 /home/TiDB/tidb-data-20161
rm -rf /home/TiDB/tidb-deploy-4001

报错2：TiKV启动超时 2m超时 根因：虚拟机内存小、TiKV被OOM杀死、初始化磁盘慢解决方案：扩容命令加 --wait-timeout 360，低配机器优先单扩TiKV
报错3：连接PD 127.0.0.1:2379 refused 根因：未修改PD内网监听地址，跨节点回环地址不通解决方案：执行阶段一PD地址修正操作

阶段三：扩容节点2（172.16.204.54）仅新增TiKV（纯存储扩容）

场景：仅扩容存储、均衡数据、补齐3副本高可用，无需部署TiDB

1. 网络连通校验

在新机器(172.16.204.29)测试连通 PD 内网 2379 端口：

复制代码

# 验证命令
curl http://主控机内网IP:2379/pd/api/v1/leader

# 文档中以172.16.204.129为主控机
curl http://172.16.204.129:2379/pd/api/v1/leader

2. 编写扩容拓扑 scale-out-54.yaml

复制代码

# 仅新增TiKV，无TiDB，规避资源不足报错
tikv_servers:
  - host: 172.16.204.54
    ssh_port: 22
    port: 20162
    status_port: 20182
    deploy_dir: /home/TiDB/tidb-deploy-20162
    data_dir: /home/TiDB/tidb-data-20162
    log_dir: /home/TiDB/tidb-deploy-20162/log

3. 预检修复 + 在线扩容

复制代码

# 集群环境预检 + 自动修复（必执行）
tiup cluster check tidb-test scale-out-54.yaml --cluster --user tidb --apply

# 执行在线扩容
tiup cluster scale-out tidb-test scale-out-54.yaml --user tidb

4. 最终集群校验

复制代码

tiup cluster display tidb-test

阶段三易错点

禁止重复配置同节点端口，新节点直接用默认20162无冲突
无需部署TiDB，纯存储扩容更稳定，减少OOM概率
扩容后自动补齐3副本，集群实现高可用，单TiKV节点宕机不影响业务

全局高频报错汇总+一键解决方案（全流程通用）

1. SSH握手失败、密码/密钥认证失败

根因：中控机未免密、SSH关闭密码登录、tidb无sudo权限解决：重新下发免密密钥、校验sudoers配置、关闭防火墙

2. TiKV OOM被杀、启动超时

根因：虚拟机内存不足，TiKV默认占用50%内存解决：扩容命令加长超时，低配机器只扩TiKV、不扩TiDB

3. 所有端口冲突报错

统一处理流程：强制缩容清理元数据 → 清空本地部署目录 → 重载系统服务 → 重新预检扩容

复制代码

tiup cluster scale-in tidb-test --node IP:端口 --force
rm -rf 对应部署/数据目录
systemctl daemon-reload

4. 误删中控机tidb-deploy/tidb-data

根因：丢失TiUP集群元数据，无法运维集群解决：无需销毁集群，tiup cluster import 恢复拓扑，业务数据无损

最终集群架构 & 高可用说明

主控机：PD + TiDB + TiKV（核心调度+计算+存储） 2. 172.16.204.29：TiDB + TiKV（扩容计算+存储） 3. 172.16.204.54：纯TiKV（补齐3副本存储） 最终效果：满足默认3副本高可用，任意一台TiKV节点(除了主控机)关机下线，集群正常读写不中断

常用运维命令

复制代码

# 查看集群状态
tiup cluster display tidb-test
# 启停集群
tiup cluster start/stop tidb-test
# 开机自启
tiup cluster enable tidb-test
# 查看PD调度进度
tiup ctl:v8.5.6 pd -u http://主控IP:2379 store