Cloud-native时代分布式数据库总是绕不开的话题。你们问“Tidb部署”其实问的是一个很时髦也很现实的题目TiDB这套从TiDB Server、PD到TiKV的多层架构到底怎么落地到自己的机器上能不能照着做就搭出一套能抗住线上压力的集群。我自己从TiDB 2.x开始踩坑到现在给客户做过不少套生产集群的部署和扩容里面确实有不少单看官方文档容易忽略的东西。这篇就按我实际动手的习惯把从零到生产可用的部署过程掰开揉碎讲一遍包括硬件规划、TiUP操作、参数调整、踩坑排查争取你看完就能动手。TiDB这东西部署门槛比传统数据库高一点因为它天生是分布式系统。但好消息是TiUP这个工具把大部分复杂度都封装掉了你不必手动一个个进程去启动。坏消息是如果你不懂架构原理、不会看日志出问题时就像在迷宫里找出口。花十几分钟把下面这些内容过一遍能少走很多弯路。1. TiDB整体架构与部署思路拆解要部署TiDB首先得知道它在跑些什么。很多新手上来就敲命令结果部署完发现TiKV一直起不来或者TiDB连不上其实就是没搞清组件之间的关系。1.1 核心组件TiDB、PD、TiKV、TiFlash各管什么TiDB最核心的三个角色分别是TiDB Server这是SQL层负责接收客户端连接、解析SQL、生成执行计划。它本身不存数据只是“大脑”和“嘴”。它是无状态服务前端挂负载均衡后可以横向扩展几十个实例。PDPlacement Driver集群的“管家”负责元数据管理、Region的调度、时间戳分配TSO。它必须有状态通常部署3个节点组成奇数副本保证可用性。TiKV真正的数据存储层以Region为单位保存数据分片每个Region默认3副本。TiKV是多副本、强一致、支持故障自动恢复的键值存储引擎。如果需要跑分析类复杂查询还可以加TiFlash。TiFlash是列存副本通过Raft Learner方式从TiKV异步复制数据专门加速OLAP场景比如那种几十个列的聚合查询。部署时可选择不装但如果你业务有混合负载建议一起部署。确认了这三四个角色你才能合理安排服务器资源。TiDB Server和PD对CPU要求略高TiKV对内存和磁盘要求高TiFlash对磁盘要求高且占用空间大。1.2 为什么用TiUP而不是手动安装TiUP是TiDB官方提供的集群运维工具链类似“包管理器集群管理器”。它解决了两个核心问题一是统一分发二进制文件和配置二是提供集群的启动、停止、升级、扩缩容等生命周期管理。你当然可以手动下载每个组件然后自己写好systemd服务一个进程一个进程启动再自己配监控。但那样维护成本极高而且TiDB的配置项非常多比如TiKV的配置改了以后不一定热生效需要在线reload或者滚动重启。TiUP把这些都统一了还内置了拓扑校验和巡检逻辑生产环境请务必使用TiUP。1.3 部署的网络规划思路部署一个分布式数据库网络是最容易被轻视的一环。TiKV和PD之间是gRPC通信数据副本同步走Raft如果网络抖动大、延迟高Raft心跳频繁超时会引发不必要的Leader切换。所以节点之间网络延迟建议控制在2ms以内至少同机房内网互通不能跨公网部署集群。另外必须错开端口。TiDB Server默认端口4000MySQL协议端口状态端口10080PD端口2379客户端端口和2380Raft通信端口TiKV端口20160TiFlash默认端口3930等。如果你的机器还装了其他服务要提前规划这些端口不被占用。部署时配置防火墙放行对应的端口范围最省事的做法是集群节点之间内网全通外部只暴露TiDB Server的4000端口给应用。2. 硬件与系统准备部署前的关键检查很多人部署失败不是因为TiUP命令写错而是因为操作系统环境不达标。TiDB官方其实列出了硬件要求但我发现不少人在实际准备机器时还是会漏掉几个点。2.1 机器规划建议不同规模的节点搭配如果只是测试环境3台机器就可以把TiDB、PD、TiKV拆开部署每台机器各跑一个TiDB、一个PD、一个TiKV。注意本机端口别冲突即可。这种混部在小集群里很常见但生产环境不求这样省。生产环境我推荐按以下规模规划最小生产集群3节点每台机器同时部署TiDB、PD、TiKV混部至少16C32G起步SSD。标准生产集群6节点3台部署TiDBPD另外3台独立部署TiKV。这样隔离资源TiKV吞吐更稳定。更高可用9节点3台TiDB、3台PD、3台TiKVPD和TiDB可以再分离各司其职。内存方面TiKV很吃内存通常建议按数据容量的10%~20%预留内存给Block Cache。比如单机挂2TB数据盘配合64G内存以上比较稳。2.2 文件系统与挂载目录设计TiKV底层用RocksDB存储文件对磁盘IO要求非常高。生产环境必须用SSD普通机械盘会造成大量写入延迟直接拖垮集群。文件系统建议ext4或xfs挂载时务必加上nodelalloc等优化参数。我经常用的挂载方式是mkfs.ext4 /dev/sdb mkdir -p /data/tidb mount -t ext4 /dev/sdb /data/tidb echo /dev/sdb /data/tidb ext4 defaults,noatime,nodelalloc 0 2 /etc/fstab这里有两个关键点noatime避免访问时间的更新减少不必要的写IOnodelalloc禁用延迟分配避免系统崩溃时数据块分配不一致这对数据库一致性很重要。另外TiKV多盘场景建议每块盘独立挂载目录不要用LVM做条带合并不然故障恢复更麻烦。防火墙内网互通要求高建议先关闭或者按端口白名单配置。2.3 系统参数优化TiDB官方有个tidb-ansible和后来的tiup自带的check工具跑完会提示需要调整的参数。我整理几个必调的关闭THPTransparent Huge PagesTHP对数据库类应用通常弊大于利容易造成内存分配卡顿和延迟抖动。通过内核启动参数或动态关闭echo never /sys/kernel/mm/transparent_hugepage/enabled echo never /sys/kernel/mm/transparent_hugepage/defrag为了让重启后也生效改/etc/default/grub或者用systemd service去设置。更稳妥的是在/etc/rc.local里加上这俩echo我给客户调优时就是放rc.local。调整IO调度器为 noop 或 noneSSD和高性能存储不需要cfq这类复杂调度。CentOS 7可以用echo noop /sys/block/sda/queue/scheduler如果是CentOS 8或Ubuntu内核已经默认none/或者通过udev规则。提高文件句柄数TiDB Server连接数高时需要大量fdTiKV也有大量文件句柄。在/etc/security/limits.conf中设置tidb soft nofile 1000000 tidb hard nofile 1000000 tidb soft stack 32768 tidb hard stack 32768部署时TiUP默认创建用户直接在集群机器执行ulimit -n检查是否生效。关闭swap或降低swappiness宁可让内存不足时OOM也不要用swap来撑否则RocksDB性能会崩。设置vm.swappiness0或1echo vm.swappiness1 /etc/sysctl.conf sysctl -p2.4 账户SSH免密与权限TiUP通过SSH登录目标机器执行操作所以控制机执行tiup的那台机器需要能免密SSH到所有目标机器。建议用专门的部署用户比如tidb并在控制机执行ssh-keygen然后分发公钥。注意TiDB部署目录通常放在/data/tidb或/home/tidb用户这个路径必须有读写权限。如果SSH连接有问题TiUP部署会直接报错测试时用ssh tidb192.168.1.10确认免密是否可用。3. TiUP部署流程详解环境准备好了接下来就是大家最想看的部署实操。我会用TiUP v1.x为例版本不同命令大同小异。建议使用当时最新的稳定版本。3.1 安装TiUP并准备拓扑文件在控制机上执行curl --proto https --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh之后会要求加载环境变量执行提示的source ~/.profile或重开终端。然后还需要安装集群组件tiup cluster如果公司网络不能访问外网可以提前下载tar包放到本地镜像修改TiUP的mirror这个有专门文档就不展开了。部署的核心是编写拓扑文件topology.yaml它描述每台机器的角色、端口、目录和参数。下面给一份典型混部三节点拓扑global: user: tidb ssh_port: 22 deploy_dir: /data/tidb-deploy data_dir: /data/tidb-data server_configs: tidb: log.level: info tikv: storage.block-cache.capacity: 8GB pd: replication.location-labels: [host] pd_servers: - host: 192.168.1.101 - host: 192.168.1.102 - host: 192.168.1.103 tidb_servers: - host: 192.168.1.101 - host: 192.168.1.102 - host: 192.168.1.103 tikv_servers: - host: 192.168.1.101 - host: 192.168.1.102 - host: 192.168.1.103 monitoring_servers: - host: 192.168.1.101 grafana_servers: - host: 192.168.1.101 alertmanager_servers: - host: 192.168.1.101这个文件里每个角色对应的host就是部署位置。server_configs里的日志级别、block-cache容量都可以提前配置。生产环境最好单独建--topology目录维护并加入版本管理这样回溯变更很清晰。3.2 执行部署命令deploy、start、verify拓扑文件写好后执行部署并指定集群名称比如tidb-prod和版本部署TiDB 8.x还是6.x请按自己需求tiup cluster deploy tidb-prod v8.5.0 ./topology.yaml --user tidb -p加上-p会提示你输入SSH密码如果你已经配好免密就不需要这个参数。过程中TiUP会自动检查目标机器的CPU、内存、磁盘、网络、端口占用等情况失败会明显红字提示。我见过比较常见的是端口占用和磁盘挂载选项问题。部署完成后启动集群tiup cluster start tidb-prod看到所有组件均为Up状态后检查PD是否正常tiup cluster display tidb-prod这个命令会列出每个组件的当前状态、运行目录、版本也是个很方便的日常巡检入口。3.3 连接并验证集群用MySQL客户端连接TiDBTiDB完全兼容MySQL协议但官方建议使用8.0以上的mysql client避免某些命令不兼容mysql -h 192.168.1.101 -P 4000 -uroot进去以后执行select tidb_version(); show databases;再建个表试试create database test; use test; create table t(id int primary key auto_increment, name varchar(32)); insert into t(name) values (hello); select * from t;重点可以看一下PD控制台http://192.168.1.101:2379/dashboard。这里能查到整个集群的Region数、存储容量、TiKV节点状态。如果TiKV没有检查通过或者Region数量一直不增长多半是集群调度问题或者数据复制有问题。3.4 扩容缩容操作生产环境业务增长后需要增加TiKV节点。扩容前先写好新的实例清单比如要把新机器192.168.1.104加进TiKVtikv_servers: - host: 192.168.1.104 server_configs: tikv: storage.block-cache.capacity: 16GB然后执行tiup cluster scale-out tidb-prod ./scale-out-tikv.yaml缩容就是移出节点tiup cluster scale-in tidb-prod --node 192.168.1.104:20160注意缩容前PD会先迁移该节点上的Region需要等所有Region迁移完成才真正移除。如果数据量大这个过程可能持续很久不要中途强制终止否则极端情况下可能导致Region无主集群不可用。4. 生产环境核心配置与性能调优部署只是第一步让集群跑得稳跑得快才是最难的。很多人在部署成功后就开始用结果没两天发现写入慢、查询不稳其实就是默认参数没有调到位。下面我挑几个平时调最大、影响最深的参数说说。4.1 TiKV参数内存与IO是命脉TiKV的storage.block-cache.capacity应该占总内存的30%~50%。比如机器总内存64G设为20GB就差不多太小则缓存命中率低读放大严重太大又会挤压其他模块内存可能导致OOM。还要关注raftstore相关参数。TiKV中每个Raft副本都维护一个store日志默认路径和数据目录在一起。生产建议单独为raft log准备一块性能好的盘或分区通过raftstore.raftdb.path参数指定。不要小看这一步高写入场景下raft log写入非常频繁如果和主数据抢IO延迟抖动会很严重。另外TiKV支持自动调整RocksDB参数如果不想深入调可以只设置一个raftstore.capacity表示本机存储容量其他让 rocksdb 自动选择。但生产需要关注rocksdb.defaultcf.write-buffer-size和max-write-buffer-number默认值在写入高峰期可能造成WAL频繁切换。可以适当调大比如write-buffer-size设为128MB注意要乘以列族数量能让写入吞吐提升不少。不过必须提醒一句参数没有放之四海而皆准每次调整后要观察监控和业务端响应别一把梭。4.2 PD调度参数影响数据分布和故障恢复PD负责Region调度参数集中在config里。常见的有schedule.leader-schedule-limitLeader调度的并发度默认4可以调大一些到8让读压力更均衡。schedule.region-schedule-limitRegion平衡并发度默认2048其实这个参数要看版本表达方式早期是整数后来是倍率。多提一句如果数据量持续增长调大Region调度能加速数据均衡。schedule.region-count和 store limit控制单TiKV的Region数量避免一个节点过载。通过tiup cluster edit-config tidb-prod可修改PD参数。但我建议用SQL在线修改PD提供HTTP接口比如动态调整leader调度curl -X POST http://192.168.1.101:2379/pd/api/v1/config/schedule -d {leader-schedule-limit: 8}生产环境修改PD调度参数一定要谨慎过快调度会导致大量Region迁移产生额外的IO与网络开销。宁可一次少改一点观察一段时间再继续。4.3 设置label实现感知拓扑高可用多数人部署完就把高可用理解成“多副本”但如果你所有副本都落在同一台物理机上那这台机器挂了数据照样全丢。TiDB支持通过PD的location-labels来感知物理拓扑将节点分配到不同机器、不同机架甚至不同机房。在拓扑文件里我们可以为每个TiKV打上labeltikv_servers: - host: 192.168.1.101 config: server.labels: { zone: zone-a, host: 192.168.1.101 } - host: 192.168.1.102 config: server.labels: { zone: zone-b, host: 192.168.1.102 } - host: 192.168.1.103 config: server.labels: { zone: zone-c, host: 192.168.1.103 }然后PD中设置tiup ctl pd pd -u http://192.168.1.101:2379 config set location-labels zone,host这样PD在放置副本时会优先让每个副本分布在不同zone。如果跨多机房部署还可以设置max-replicas为3或5并针对每个label约束副本数。这样即使整机房宕机集群仍然能提供读服务注意Raft协议要求多数派存活三副本至少要两台可用。4.4 监控与告警内置的Grafana大屏TiUP默认会部署Prometheus、Grafana和AlertManager。集群部署后直接打开Grafana默认3000端口账密admin/admin里面预置了很多面板比如TiDB、TiKV、PD等。我平时最频繁看的面板有TiDB-Server看QPS、连接数、慢查询、执行计划缓存命中TiKV-Details看磁盘IO、gRPC延迟、Raft propose数、总响应时间PD看leader分布、Region数量、调度速率告警规则也是默认的可以通过AlertManager配置钉钉或邮件。但说实话官方默认规则很多且容易误报我会根据生产经验调整阈值例如慢查询超过300ms的才报警TiKV写延迟超过1s才报警。这样能在故障刚开始时立刻收到消息。4.5 TiFlash部署与同步配置附带说明若想使用列存在拓扑文件里加上tiflash_servers部署时TiUP会自动安装。关键是确认TiFlash与TiKV之间的同步标签正确。部署后去TiDB执行ALTER TABLE test.t SET TIFLASH REPLICA 2;然后可以用explain select ...查看是否会走TiFlash列存。但要注意TiFlash同步会增加存储开销和一定的写入延迟不要把所有表都建TiFlash副本只挑真正跑聚合分析的大表。5. 常见问题与排查技巧实录这部分是我最想写的。TiDB部署的坑很多不是部署命令本身而是环境、版本和网络问题。把这些经验写出来能帮你节省好几个晚上的排查时间。5.1 部署失败SSH、磁盘和平台兼容问题报错ssh: handshake failed或者Permission denied。多半是免密公钥没配置好或者目标机器用户名不对。先手动SSH测一遍再看topology.yaml的user字段是否与实际用户名一致。用root部署虽然省事但TiUP建议用非root用户权限要包含数据目录挂载点的写权限。检查失败提示disk not enough。TiUP会自动检查剩余空间默认要求至少多少G建议多预留些。特别是/root分区和数据分区别搞混有时候数据目录挂载在/data但系统盘只有20G很容易误判。需要仔细看报错对应的目录。ARM平台或低配机器。TiDB虽然支持ARM64但部分分支版本在ARM上运维有些坑部署前先查版本矩阵别拿旧版本硬装ARM。另外4C8G这种低配先不说性能部署时检查内存不足直接拒绝。TiKV正常建议至少8C16G以上。5.2 启动后异常Region不均衡和节点状态Down集群启动了但TiKV状态一直显示Down。先去目标机器看日志路径一般在部署目录/data/tidb-deploy/tikv-20160/log/下打开tikv.log找ERROR级别日志。常见原因有磁盘权限不对TiKV进程无法写数据目录创建目录时chown正确即可。端口被占用多个TiKV实例部署在同一台机器用相同端口TiUP应该会在拓扑校验时发现但如果你手动改过端口注意冲突。启动参数中容量填错比如storage.capacity超过实际磁盘空间导致初始化失败TiKV会报Capacity错误。正确设置成略小于磁盘实际可用容量比如预留10%。Region数量不增长也可能因PD调度的store-limit为0导致禁调度。排查时看PD面板如果调度一直为0用pd-ctl查看调度状态tiup ctl pd pd -u http://192.168.1.101:2379 store limit5.3 性能问题慢查询和热点部署上线后出现慢SQL先看是不是优化器选错了索引查看执行计划EXPLAIN ANALYZE。如果执行计划没问题再查热点。热点一般两种写热点和读热点。写热点常见原因是表的主键自增大量写入都落在最后一个Region。解决思路使用AUTO_RANDOM类型的自增主键或者把表打散。TiDB中建表可以加SHARD_ROW_ID_BITS4让自增ID散开。读热点更多是因为业务查询集中在某个时间段的某片数据可以通过调整Region分裂或TiFlash分担读压力。如果TiKV延迟高先看磁盘IO。用iostat -x 1看%util和await是否长期接近100%。如果磁盘IO高检查慢查询是否存在全表扫描如果磁盘IO不高但gRPC延迟高可能内网抖动或CPU调度问题。TiDB慢查询日志一般在TiDB日志中设置了slow-query-file也可以用information_schema直接查SELECT * FROM INFORMATION_SCHEMA.SLOW_QUERY WHERE TIME 2025-01-01 00:00:00 ORDER BY Query_time DESC LIMIT 10;5.4 日常运维升级、备份和配置变更升级TiDB版本用TiUP很简单tiup cluster upgrade tidb-prod v7.5.0 --force但注意升级前务必备份并且确认目标版本和集群兼容。TiDB跨大版本升级可能有不兼容变更比如某些SQL语法或默认参数调整。建议先在测试集群验证再在生产升级。生产升级期间会有滚动重启最好在业务低峰期做。备份恢复方面常规逻辑备份工具是dumpling和lightning。比如tiup dumpling -u root -P 4000 -h 192.168.1.101 -f test.* -o /backup/test企业版还可以用BR做物理备份速度更快。但BR备份基于TiKV的SST文件跨版本恢复可能不兼容所以备份时记录清楚版本。配置变更推荐用tiup cluster edit-config编辑后执行tiup cluster reload。改参数后不一定全部热生效reload时会自动滚动重启相应组件。注意修改TiFlash参数需要重启TiFlash组件。5.5 典型故障速查表下面是我在部署运维中遇到比较多的问题按现象、可能原因和排查命令列成表方便你直接对号入座现象可能原因快速排查部署check失败提示CPU不满足机器低于最低要求4C用nproc和cat /proc/cpuinfo查CPU核数TiUP找不到节点ssh无法免密或用户名错误手动ssh tidbnode测试TiDB节点启动后连接拒绝端口占用或服务崩溃查看日志/data/tidb-deploy/tidb-4000/log/tidb.logTiKV状态Down磁盘满、目录权限、内存不足查看tikv日志df -h检查磁盘Region一直为0或无法调度PD scheduler异常或store limit限制pd-ctl store查看状态写入延迟高磁盘IO瓶颈或热点iostat检查IOTiKV-Details看Raft propose慢SQL优化不生效统计信息过期执行ANALYZE TABLE test.t更新统计信息跨机房副本不均衡location-labels未配置查看PD面板检查location-labelsGrafana端口打不开防火墙未放行firewall-cmd --add-port3000/tcp --permanent升级后集群启动失败版本不兼容或数据迁移中断用tiup cluster display看具体组件日志对照升级文档5.6 独家避坑心得别忽略TiUP的Fix操作: 集群处于异常状态时tiup cluster会提供tiup cluster check tidb-prod --cluster这种自愈或检查命令。有些启动失败后系统进程残留先执行tiup cluster stop再start清零状态比手动kill各进程靠谱得多。PD数据目录不要放在系统盘: PD虽小但它的meta数据很关键。系统盘挂了PD容易连带。最好放在独立的数据盘。TiKV的数据盘如果满了不要简单删日志先扩容或加节点否则可能引发一系列级联问题。日志是救命稻草遇事不要靠猜: 任何异常第一件事是去对应组件日志目录找到当前日志搜索panic、error。TiDB官方很多问题都能在日志中找到明确错误码再结合官方FAQ定位。不要看到一个connection refused就开始重装系统多半是服务没起来或网络不通。TiDB、TiKV、PD的日志级别在线上设置为warn或error除非排查性能问题时才临时调info。之前我试过在线上开着info日志几天后磁盘就满了因为日志量非常大。最后再啰嗦两句个人体会从第一次部署TiDB到现在我最大的感受是部署本身不算难难的是把部署当成一项工程来做。从节点规划到系统参数从拓扑文件到配置调优每一步都是为后续的稳定性打底。如果你现在只是要在笔记本上跑个测试环境直接一条tiup playground命令就够了但如果真的要在生产环境跑业务请务必花时间把上面这些细节过一遍。不少人会问没有tidb用户是否也能部署答案是可以但尽量为TiDB单独建用户并规划好目录。另一点是TiDB版本升级频繁建议每个大版本至少跟踪一段时间再上生产别一更新就马上跟。我在实际操作中还会做一个习惯把每次部署的拓扑文件、版本号、调参记录都整理成一个变更表存进仓库。后面出问题排查时能迅速知道当前集群配置和之前的差异而不是对着运行中的集群一点一点翻。这一招在后续运维中帮了我很多。这篇的内容基本覆盖了从规划到上线的关键流程剩下的就靠你多练了。TiDB部署不是背命令而是理解每个组件为什么存在、有哪些坑。等你踩过几个坑、亲手解决过一两次故障就会真正掌握这套分布式数据库。