企业官网建设流程全解析

不管你是从 MySQL 单机被慢查询逼到墙角，还是因为业务涨到需要水平扩展才来看 TiDB，部署这一步总是绕不开的第一道坎。网上讲 Tidb 部署的文章不算少，但多数停留在“照着敲命令”的层面，真正从规划到验证一路踩完坑的详细记录并不多。这篇文章把我实际部署 TiDB 集群的经验整理出来，包括拓扑怎么定、TiUP 怎么用、环境检查看哪几项、启动之后怎么确认集群是健康的，以及后来扩容升级时总结出的一些细节。无论你是在捣鼓一套三节点测试集群，还是为生产环境盘硬件选型，都能从中找到可以照着做的依据。

我先说一个可能反直觉的结论：TiDB 部署的难点从来不在执行那几条命令，而在动手之前。你如果不先想清楚数据量、节点角色、磁盘类型和网络环境，后面 TiUP 跑得再顺，上线后也会被各种莫名其妙的性能问题折磨。所以这篇文章大部分篇幅都在讲“怎么判断该这么配”和“出了问题怎么查”，命令只是载体。

1. 部署前先算账：从数据量和访问模式反推机器配置

1.1 TiDB 集群的三个核心角色，各管什么事

刚接触 TiDB 的人容易把它当成一个“能水平扩展的 MySQL”，然后上来就按 MySQL 主从的思路去规划机器，这是最常见的误区。TiDB 部署时最少会涉及三类节点，职责完全不同：

• TiDB Server（SQL 层）：负责接收客户端请求、解析 SQL、生成执行计划、把查询下推到 TiKV。它是一个无状态的计算层，可以随便扩容，节点之间不需要同步数据。
• PD（Placement Driver，调度中心）：负责维护整个集群的元数据、分配全局事务时间戳（TSO）、管理 Region 的调度和复制。PD 通常部署奇数个节点，生产环境至少 3 个，因为它的选主依赖 Raft。
• TiKV（存储层）：真正的数据存储节点，数据按 Region 切分后分布在各个 TiKV 上。TiKV 也用 Raft 做多副本复制，生产环境一般至少 3 台，才能容忍单节点故障。

另外还有一个可选的 TiFlash，专门跑列式存储，供实时分析类查询用。如果业务里 OLTP 和 OLAP 混跑，建议从一开始就把 TiFlash 的物理资源单独留出来，后面再加也不是不行，但数据同步和节点调度会给你找点事做。

1.2 先按数据量和并发算，再决定买什么机器

我见过不少人问“部署 TiDB 最低要几台机器”，这个问题本身没有标准答案，取决于你的数据落盘量、QPS、查询复杂度和可用性要求。给你一个我常用的估算思路：

• 原始数据量在 200GB 以内、QPS 在几千以内，只想先跑通功能或者做 PoC，3 台 8C16G 的机器就够了，PD 和 TiDB 可以混布在任意节点上，TiKV 独立占一台物理机。
• 数据量到了 1TB 上下，QPS 上到一两万，每台 TiKV 建议至少 16C32G，磁盘必须换成 NVMe SSD。
• 数据量超过 5TB，或者对容灾有刚性要求，建议 TiKV 单独部署在 3 台以上的物理机上，PD 和 TiDB 各自独立节点，避免资源争抢。

这里还有一个很容易被忽视的点：TiKV 的磁盘性能直接决定集群的写入延迟和 Raft 日志落盘速度。官方推荐生产环境使用 SSD 甚至 NVMe，这真的不是官方在“劝你花钱”。TiKV 每个写请求都要先写 Raft 日志，再写 RocksDB，机械盘在这种双写模式下延迟会抖到你怀疑集群是不是挂了。

我习惯在规划阶段做一个简单表格，把每个节点的角色和资源需求列清楚，避免部署的时候搞混：

表格里的内存数值不用太纠结，实际可以按你的业务峰值去压。重点是：TiKV 的内存不是越大越好，但太小一定会出问题。RocksDB 的 block cache 默认会用掉机器内存的一部分，如果机器内存只有 8G，你还部署了多个 TiKV 实例，内存挤兑会直接导致 OOM。

1.3 拓扑是混布还是独立节点，取决于你能不能接受故障半径

环境规划里最容易被忽略的是“故障半径”这个概念。混布的意思是同一台物理机上既跑 PD 又跑 TiDB 甚至 TiKV，好处是省机器，坏处是一台机器宕机可能导致多个角色同时不可用。

我的建议是：

• 测试环境随便混布，怎么方便怎么来。
• 生产环境至少保证 TiKV 不要和 PD 混布在同一台物理机。PD 是大脑，TiKV 是身体，大脑和身体同时挂掉，整个集群就直接瘫痪了。
• TiDB Server 相对无状态，和 PD 混布影响不大，但如果并发很高，CPU 争抢会让 PD 的 Raft 心跳延迟变大，进而引发调度抖动。

另外还要考虑网络。TiDB 内部组件之间大量走 RPC，PD 和 TiKV 之间的心跳、TiKV 和 TiKV 之间的 Raft 复制，都要求低延迟。跨地域部署不是不行，但你要想清楚机房之间的 RTT。同一个城市内两个机房 5ms 以内的延迟勉强可以接受，如果是异地 100ms，Raft 多数派写入的延迟会直接飙升，这类场景需要专门配置label和isolation-level，而不是简单地把节点分散开。

2. 用 TiUP 部署一个标准三节点集群：从拓扑文件到启动验证

2.1 离线环境怎么搞定安装源

很多公司的生产网是隔离的，不能直接访问外网镜像。这一步你如果没处理好，后面所有命令都会卡在下载依赖上。TiUP 支持离线部署，操作逻辑是先在一台能联网的机器上把完整镜像拉下来，拷到内网机器上，再切到本地镜像。

如果你是在有外网的环境，直接装 TiUP 就行：

curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh source ~/.bashrc tiup --version

离线环境要走下面这套流程：

# 在一台能联网的机器上，下载对应版本的离线镜像包 # 比如 TiDB v8.1.0 的 linux-amd64 离线包 tar -xzf tidb-community-server-v8.1.0-linux-amd64.tar.gz cd tidb-community-server-v8.1.0-linux-amd64 sh local_install.sh source ~/.bashrc # 之后把整个目录拷到内网跳板机，并切换到本地镜像 tiup mirror set /path/to/tidb-community-server-v8.1.0-linux-amd64 tiup cluster --version

这里有个坑：离线包的local_install.sh执行完，默认的 mirror 还是外网地址，你必须手动tiup mirror set切到离线目录，否则部署时 TiUP 检测到某些组件不在本地就会去外网拉取，然后超时失败。我第一次做离线部署就栽在这，集群拓扑检查全过了，deploy 阶段卡在下载上下不来。

2.2 手写一份 topology.yaml：每个字段都别糊弄

TiUP 部署的核心是拓扑文件，它决定了集群有哪些节点、每个节点跑什么角色、数据目录和端口怎么安排。下面是一份我在三节点生产环境用的简化拓扑，你可以根据实际 IP 改成自己的：

global: user: "tidb" ssh_port: 22 deploy_dir: "/tidb-deploy" data_dir: "/tidb-data" pd_servers: - host: 10.0.1.11 - host: 10.0.1.12 - host: 10.0.1.13 tidb_servers: - host: 10.0.1.11 - host: 10.0.1.12 - host: 10.0.1.13 tikv_servers: - host: 10.0.1.21 config: server.grpc-concurrency: 8 - host: 10.0.1.22 config: server.grpc-concurrency: 8 - host: 10.0.1.23 config: server.grpc-concurrency: 8 monitoring_servers: - host: 10.0.1.11 grafana_servers: - host: 10.0.1.11 alertmanager_servers: - host: 10.0.1.11

这份文件的关键点全在细节里：

• user必须是有 sudo 权限的账号。TiUP 要创建用户、创建目录、调内核参数，没有 sudo 会到处报错。我不建议直接用 root 跑，但部署用户一定要能 sudo。
• deploy_dir 和 data_dir 分开。程序二进制放一块盘，数据放另一块盘，这是生产环境的基本素养。如果只有一块盘，至少目录要分开，未来扩盘时方便迁移。
• PD 和 TiDB 在 10.0.1.11~13 混布，这个拓扑是在测试环境验证过的混布方案。
• TiKV 单独落在 10.0.1.21~23，三台物理机，保证单一机器故障时 TiKV 不会同时少两个副本。

还有节点数的问题：PD 和 TiKV 的副本数建议是奇数，TiDB 节点数无所谓。三节点 PD 挂一个不会影响选主，五节点能容忍两个故障，但通常三节点已经满足绝大多数场景。

2.3 环境检查、部署、启动三步走

拓扑文件写完之后，不要直接部署，先跑环境检查：

tiup cluster check ./topology.yaml --user tidb

它会检查当前机器是否满足 TiDB 的最低要求，比如 CPU 核数、内存、磁盘挂载、SELinux 状态、透明大页是否关闭、时钟是否同步。检查结果里如果有Warn，建议逐项看一下。很多Warn不影响部署所以 TiUP 不会拦你，但会影响性能，比如透明大页没关、swappiness 太高。后面我会专门讲这些项为什么重要。

检查通过之后，执行部署：

tiup cluster deploy tidb-prod v8.1.0 ./topology.yaml --yes

tidb-prod是集群名，你可以随便起，但注意后续所有tiup cluster命令都要带上这个名字。部署完成后启动：

tiup cluster start tidb-prod tiup cluster display tidb-prod

display输出的表格里能看到每个节点的状态。正常情况所有角色都应该是Up。如果某个节点是Down，先用tiup cluster log tidb-prod -R pd -p 30之类的方式拉对应组件日志，别急着重启，先看原因。

2.4 部署完之后，访问入口和数据目录长什么样

集群起来后，访问入口和 MySQL 一样，默认端口是 4000。TiDB 兼容 MySQL 协议，所以你可以直接用 mysql 客户端连：

mysql -h 10.0.1.11 -P 4000 -u root

初次连接时 root 默认没有密码，所以第一步要立刻设置密码，这个习惯一定要养成：

ALTER USER 'root'@'%' IDENTIFIED BY 'your-strong-password';

数据目录上，TiKV 和 PD 的数据会落在 topology.yaml 里指定的/tidb-data下，TiKV 的数据目录结构是data_dir/raft和data_dir/db，分别对应 Raft 日志和 RocksDB 数据。看到这两个目录说明 TiKV 的存储已经初始化了。不要手动去改这些文件，TiKV 在运行时会自己管理。

3. 环境层面的坑，才是部署 TiDB 真正费时间的地方

3.1 时钟不同步，PD 的 TSO 会乱

TiDB 的事务模型依赖 PD 下发全局单调递增的时间戳（TSO）。如果各节点系统时间不一致，PD 和 TiKV 之间会判断不了消息先后顺序，轻则日志报错、事务延迟变高，重则 PD 选主出问题，集群完全不可用。这个问题在测试环境尤其容易被忽略，因为大家习惯了虚拟机能上网就以为时间一定是对的。

我的标准操作是在部署前就把三台机器都配好 NTP，然后执行：

timedatectl set-ntp yes timedatectl status

再看一下各节点时钟偏移：

date && ssh 10.0.1.12 date && ssh 10.0.1.13 date

如果主机之间的时间差超过几百毫秒，基本上 TiDB 跑起来后你会在日志里看到类似clock offset的告警。这里面最讨厌的是 PD 和 TiKV 的时钟偏差过大，导致max_timestamp和min_timestamp逻辑异常，读到的数据可能不是最新版本。真出现这种情况，优先校准 NTP，不要直接调应用。

3.2 swap 和透明大页，两个性能隐形杀手

TiDB 节点上，操作系统的内存和存储设置直接影响 RocksDB 的表现。第一个要看的是 swap。TiKV 进程如果被换到 swap 区，延迟会瞬间飙到几十毫秒甚至更高，而且表现是间歇性的——你压测时一会儿好一会儿坏，查了半天发现 swap 在作怪。

建议在/etc/sysctl.conf里把 swappiness 降到最低：

echo 'vm.swappiness=0' >> /etc/sysctl.conf sysctl -p

注意，vm.swappiness=0是让系统在内存不足时尽量不 swap，但进程 OOM 时还是可能直接被杀。所以还得配合内存监控，不能以为关了 swap 就万事大吉。

第二个要看的是透明大页（THP）。RocksDB 对内存分配很敏感，THP 开启时内存分配延迟不稳定，TiKV 官方建议直接关掉：

echo never > /sys/kernel/mm/transparent_hugepage/enabled echo never > /sys/kernel/mm/transparent_hugepage/defrag

这两个目录里的值重启后会恢复，所以建议写进开机启动脚本里。TiUP 的check命令会检测 THP 状态，但它只给 Warn 不拦你，很多人看到 Warn 就跳过，这就埋下了性能隐患。

3.3 磁盘 IO 调度器和文件描述符

SSD 场景下，磁盘 IO 调度器最好改成none或者noop。老内核默认可能是cfq，这种调度器面向机械盘设计，对 NVMe 是纯负担。修改方式：

echo none > /sys/block/nvme0n1/queue/scheduler

要确定哪一块盘是数据盘，不要全系统一把梭。还有文件描述符上限，TiKV 在高并发下会同时打开大量文件，默认的 1024 肯定不够，设置成 1M 是常见做法。你可以在/etc/security/limits.conf里加上：

tidb soft nofile 1000000 tidb hard nofile 1000000

这里有一个隐藏细节：TiUP 启动服务时用的是拓扑文件里user指定的账号，所以 limits 要加在那个账号上面。如果你用 root 部署，这些 limits 可能不会生效，这也是我不推荐 root 的原因之一。

3.4 防火墙、SELinux 和端口占用

内网机器上最常见的部署失败原因其实是端口被占或者防火墙挡了内部通信。TiDB 集群内部的端口比较多，PD 的 2379、2380，TiKV 的 20160，TiDB 的 4000，Prometheus 的 9090，Grafana 的 3000。不同机器之间必须有这些端口的互通权限。

我处理防火墙的办法是：测试环境直接放行，生产环境按端口列表精确放行，不要图省事关闭整个 firewalld，因为你不知道同一个物理机上还有没有其他业务。

firewall-cmd --permanent --add-port=2379/tcp firewall-cmd --permanent --add-port=2380/tcp firewall-cmd --permanent --add-port=20160/tcp firewall-cmd --permanent --add-port=4000/tcp firewall-cmd --permanent --add-port=9090/tcp firewall-cmd --permanent --add-port=3000/tcp firewall-cmd --reload

SELinux 如果处于 enforcing 状态，经常会导致 TiUP 的 ssh 执行和目录访问权限出问题。生产环境如果安全要求高，可以逐个组件手工加策略，但大多数团队选择临时置为 permissive。我自己的习惯是至少在部署阶段先setenforce 0，部署完成、确认无异常后再评估是否恢复。

3.5 一个问题排查的完整链路：集群起来了，但写数据很慢

下面分享一个我实际遇到的案例，完整还原排查过程，比直接告诉你“要开多个 TiKV 实例”更有参考价值。

现象是：三节点集群部署完成后，写入一条简单 insert 要几百毫秒，压测时 QPS 上不去。第一反应我去看tiup cluster display，节点全部 Up，日志没有明显报错，这就排除了进程级故障。

第二步看监控。TiDB Dashboard 里的 QPS 曲线是平的，延迟曲线却一直是锯齿状。点进 TiKV 实例的写延迟面板，发现 Raft store 的 fsync 延迟平均在 80ms 以上，这个数值明显不正常——NVMe 盘的 fsync 正常应该在微秒级。

第三步登录 TiKV 所在机器，用iostat -x 1看磁盘利用率，发现%util接近 100%，但读写速率并不高。这种情况通常不是 IO 吞吐打满，而是 IO 等待太长。再查调度器，发现系统盘和数据盘共用一台机器，数据盘用的是/dev/vdb，调度器是cfq，而且这块盘其实是一块虚拟化的共享存储，物理机的邻居业务正在大量写盘。

到这里原因基本清楚了：数据盘本身的硬件性能就不是 NVMe，加上 IO 调度器不对，多个写入请求排队，延迟当然高。

解决过程分两步：

• 把数据盘调度器改成none，消除一层排队。
• 确认这是共享存储而不是本地 NVMe 后，调整业务预期，并做了跨节点检查，发现另外两台 TiKV 的数据盘同样是虚拟磁盘。测试没问题，生产直接换物理机。

这个案例给我的教训是：TiKV 的数据盘一定不要用共享存储、不要用机械盘、不要用普通云盘（除非云盘本身承诺足够的 IOPS），这三个限制写在拓扑规划阶段，后面能省掉大量定位时间。

4. 集群起来了，怎么判定它是真的健康

4.1 从命令行到 Dashboard：逐层确认集群状态

很多人启动完集群，看到节点 Up 就觉得部署成功了，这远远不够。节点 Up 只能说明进程活着，不代表数据面是健康的。我第一次部署完成后想当然地建了表开始跑业务，直到某个 Region 一直没有 Leader，才意识到集群虽然起来了，但调度和副本状态有问题。

我的标准验证流程是四步走：

# 第一步：看集群拓扑和节点状态 tiup cluster display tidb-prod # 第二步：用 MySQL 协议连进去 mysql -h 10.0.1.11 -P 4000 -u root -p # 第三步：在 SQL 层查集群组件信息 SELECT * FROM information_schema.cluster_info;

如果cluster_info能列出所有 tidb、pd、tikv 实例的地址、状态、版本号，说明组件间的注册信息是通的。接下来查存储节点状态和 Region 情况：

SELECT store_id, node_state, address, version, capacity, available FROM information_schema.tidb_store_status;

重点看node_state是否全是Online，available是否正常。如果是刚部署的集群，Region 数量可能很少，这没关系，关键是每个 TiKV 上的 Region 数要相对均衡。如果某个 TiKV 的 Region 数是 0，说明数据没有分布过去，需要查 PD 的调度日志。

最后打开 TiDB Dashboard，登录后接上 PD 地址，看“集群诊断”页面有没有异常告警。只要时间同步、region 均衡、节点全部 Online，基本上这个集群就是健康的。

4.2 建一张表跑一下读和写，验证 SQL 层到存储层链路

集群健康不等于业务链路健康，我每次部署完都会手动做一次最小功能验证：

CREATE DATABASE deploy_test; USE deploy_test; CREATE TABLE t (id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(64)); BEGIN; INSERT INTO t (name) VALUES ('hello'); COMMIT; SELECT * FROM t WHERE id = 1;

这里有个容易误判的点：单条 SQL 跑通只说明基本链路是通的，不能说明 TiKV 真的在干活。你可以用EXPLAIN看一眼执行计划：

EXPLAIN SELECT * FROM t WHERE id = 1;

如果执行计划里的访问对象是table:t而不是cop下推到 TiKV，先不用慌，小表可能走了点查。真正要确认数据落到 TiKV，可以查一下 Region 的数量：

SELECT COUNT(*) FROM information_schema.tikv_region_status;

查出的 Region 数不为 0，说明数据确实在存储层切分落盘了。

4.3 压测、容错和备份恢复，上线前必做的三件事

如果说上面这些是“能跑”，那上线前还要验证“扛得住”和“坏了能恢复”。我见过不少团队部署完直接上生产，结果第一次故障演练就发现副本同步有问题，那时候再改配置代价就大了。

第一件是压测。用 sysbench 或者 tpcc 跑一轮读写混合，确认 QPS、延迟和资源使用率在合理范围。压测时不要只看 QPS，重点看延迟曲线是否平稳。曲线如果出现周期性尖刺，优先怀疑监控采集程序、定时任务和磁盘 IO。

第二件是容错演练。生产环境三副本的情况下，停掉一台 TiKV 进程，观察集群是否仍然可以正常读写。TiDB 在副本数足够时会自动选出新的 Leader，正常情况下业务几乎感知不到。演练之后记得恢复节点，并确认 Region 重新达到均衡。

第三件是备份恢复。TiDB 的官方备份工具是 br（Backup & Restore），部署完就应该测试一轮无缝备份和恢复：

tiup install br tiup br backup full --pd "10.0.1.11:2379" --storage "local:///backup/tidb" --filter "deploy_test.*"

我要强调一下：备份这件事一定不要在部署完就抛到脑后。TiDB 的运维模型跟 MySQL 不一样，SQL 层的逻辑备份工具只能兜底，真正的物理备份得靠 br，而且恢复时要起一个临时实例来测试恢复结果。这个流程你不在刚部署完的时候跑通，等真出事故的时候一定会手忙脚乱。

5. 部署完成之后别急着走：扩容、升级和运维里容易忽略的细节

5.1 用 scale-out 加节点，比想象中简单，但调度要耐心等

集群上线后业务增长，需要加 TiKV 节点。TiUP 的扩容流程和部署差不多，只需要写一个包含新节点的新拓扑文件，然后执行：

tiup cluster scale-out tidb-prod ./scaleout.yaml --yes

scaleout.yaml里只需要写新增的节点，比如：

tikv_servers: - host: 10.0.1.24 config: server.grpc-concurrency: 8

扩容命令执行完成后，新节点会以Online状态加入集群，但数据不会瞬间搬过去。PD 会根据 Region 调度一点点把数据从旧节点迁移到新节点，这个过程可能持续几小时甚至更久，取决于数据量。有些人扩容完发现新 TiKV 的 Region 数还是 0，就误以为扩容失败，其实只是调度还没开始或比较慢。可以用 PD 的调度参数来控制速度：

# 调节 region 调度的并发度，默认同时调度的 region 数较小 tiup ctl:v8.1.0 pd -u http://10.0.1.11:2379 config set schedule.max-merge-region-keys 200000

不过在生产环境，我不建议一上来就把调度并发调太高，调度本身就是资源消耗，太快会挤占业务流量。

5.2 版本升级，先想清楚要不要就地升还是新集群迁数据

TiDB 的版本升级有好几条路，最常用的是tiup cluster upgrade。如果你有离线镜像，先切到离线镜像，再执行升级：

tiup mirror set /path/to/new-version-offline-package tiup cluster upgrade tidb-prod v8.5.0 --offline

升级前务必做两件事。第一是看官方文档的兼容性说明，比如 v7.1 升 v8.1 时有哪些参数废弃或默认值变化。第二是把拓扑文件、配置文件和当前集群参数备份下来，升级失败时能回滚。

还有一种情况是你想做大版本的安全升级，又担心原地升级风险，那可以在新机器上部署一个新版本集群，再用备份恢复把数据迁过去。这个方案的代价是机器成本和迁移时间，但风险最小。我自己的经验是：小版本升级可以原地升，大版本升级如果业务不那么敏感，可以先在生产环境旁边搭一套新集群试运行两周再切流量。

5.3 日常运维清单：监控要盯，连接入口要规划

部署完成只是开始，日常运维才是长期的事情。TiUP 顺手部署的监控面板里，Grafana 默认在 3000 端口，Prometheus 在 9090 端口，TiDB Dashboard 挂在 PD 的 2379 端口上。我日常看得最多的是三个面板：

• TiDB Dashboard：看集群整体状态、慢查询、热点 Region。
• Grafana 的 TiKV Details：看写延迟、Raft 日志延迟、磁盘 IO。
• Grafana 的 PD：看 Region 的调度队列、心跳延迟。

接入业务之前，还应该想清楚应用怎么连 TiDB。客户端直连单个 TiDB 节点的 IP 是不行的，一是单点故障，二是多个 TiDB 节点的连接不均衡。生产环境建议前置一个负载均衡器，四层 TCP 转发到所有 TiDB 节点的 4000 端口。配置 JDBC 或者 MySQL 客户端时，连接串里的 URL 应该指向负载均衡的虚拟 IP，而不是某个具体节点。

另外有个细节：TiDB 的连接如果空闲太久，负载均衡器可能会掐断 TCP 连接，应用层要合理设置连接池的maxLifetime和空闲超时，避免频繁断连又频繁重连。

5.4 最后再分享一个部署心态

部署 TiDB 这件事，最容易翻车的地方往往是那些看起来不起眼的“小事”：时间对不对、内核参数对不对、磁盘快不快、端口通不通。TiUP 已经把集群编排做到足够简单，剩下的反而是环境工程。我现在的习惯是每次部署前都花半小时把环境检查清单完整过一遍，部署后花一小时按上面的验证流程跑一遍，确认数据能写、能读、能容错、能备份，然后才敢把集群交给业务方。这套流程看起来很基础，但它帮我省掉的故障排查时间远比想象的要多。如果你正准备部署一套新的 TiDB 集群，建议也把这条链路走完整，别急着把业务迁上去。