Docker部署TiDB集群技术文档

ruxshui

889人浏览 · 2026-01-20 09:39:01

ruxshui · 2026-01-20 09:39:01 发布

Docker部署TiDB集群完整技术文档（含安装/部署/登录/调度配置/运维/扩容/安全加固）

一、前置核心准备与依赖要求

1.1 TiDB集群核心架构（必知）

PD (Placement Driver) ：集群大脑，负责全局元数据管理、Region调度、负载均衡、集群配置管理，所有调度规则均在PD配置。
TiKV ：分布式存储引擎，负责持久化存储全量数据，数据分片存储，支持多副本高可用。
TiDB Server ：SQL请求入口，无状态节点，兼容MySQL5.7协议，接收SQL请求并调度执行，返回结果。

1.2 宿主机硬性环境要求（启动失败核心诱因）

内存：最低 4GB RAM ，推荐8GB及以上
CPU：2核及以上
Docker版本：20.10.0+ 稳定版，Docker Compose：2.0+
磁盘：≥20GB空闲空间，优先SSD磁盘，TiKV对磁盘IO敏感
系统：Linux(CentOS7+/Ubuntu18+)、MacOS、Windows10+(WSL2)，生产环境首选Linux

1.3 Docker环境安装与状态验证

# 检查Docker版本
docker -v
# 检查Docker Compose版本
docker compose version
# Linux一键安装Docker+Compose（阿里镜像源，稳定无坑）
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
# 启动Docker服务+开机自启
systemctl start docker
systemctl enable docker
# 验证Docker运行状态
systemctl status docker

二、TiDB集群Docker部署两种核心方式

2.1 方式一：单机伪集群（官方推荐，开发/测试/学习首选，99%场景适配）

适用场景：开发调试、SQL验证、TiDB功能学习、轻量级数据开发、单元测试
核心优势：一键部署、零手动配置、单节点模拟完整分布式架构、开箱即用、启动速度快

# 克隆官方镜像仓库（国内源，拉取速度快）
git clone https://gitee.com/mirrors/tidb-docker-compose.git
cd tidb-docker-compose && cd docker-compose
# 一键后台启动完整集群（PD+TiKV+TiDB自动编排）
docker compose up -d
# 验证集群容器运行状态
docker compose ps

伪集群核心端口映射（永久必记）
- TiDB Server (SQL登录入口)：4000
- PD (集群调度管控入口)：2379
- TiKV (组件内部通信)：20160

2.2 方式二：轻量分布式集群（生产级规范部署，推荐）

适用场景：生产预发环境、小型业务上线、数仓ODS层部署、高可用需求、数据持久化场景
核心优势：组件完全解耦、数据永久持久化、支持弹性扩容、时区统一、开机自启、资源可控

# 步骤1：创建TiDB集群专属桥接网络（组件内网通信必备）
docker network create --driver bridge --subnet=172.20.0.0/16 tidb-cluster-net
# 步骤2：启动PD节点（集群大脑，必须最先启动）
docker run -d 
--name tidb-pd 
--net tidb-cluster-net 
--ip 172.20.0.2 
-p 2379:2379 
-p 2380:2380 
-v /data/tidb/pd:/var/lib/pd 
-e TZ=Asia/Shanghai 
--restart=always 
pingcap/pd:latest 
--name=pd1 --data-dir=/var/lib/pd --client-urls=http://0.0.0.0:2379 --peer-urls=http://0.0.0.0:2380 --initial-cluster=pd1=http://172.20.0.2:2380
# 步骤3：启动TiKV节点（分布式存储，依赖PD节点）
docker run -d 
--name tidb-tikv 
--net tidb-cluster-net 
--ip 172.20.0.3 
-p 20160:20160 
-v /data/tidb/tikv:/var/lib/tikv 
-e TZ=Asia/Shanghai 
--restart=always 
pingcap/tikv:latest 
--addr=0.0.0.0:20160 --pd=172.20.0.2:2379 --data-dir=/var/lib/tikv
# 步骤4：启动TiDB Server节点（SQL入口，依赖PD+TiKV）
docker run -d 
--name tidb-server 
--net tidb-cluster-net 
--ip 172.20.0.4 
-p 4000:4000 
-p 10080:10080 
-v /data/tidb/tidb:/var/lib/tidb 
-e TZ=Asia/Shanghai 
--restart=always 
pingcap/tidb:latest 
--store=tikv --path=172.20.0.2:2379 --log-file=/var/lib/tidb/tidb.log
# 验证集群运行状态
docker ps | grep tidb

三、TiDB集群核心登录方式（完全兼容MySQL5.7协议，零学习成本）

3.1 方式一：宿主机原生MySQL客户端登录（推荐，无依赖，开发/运维通用）

# TiDB默认无密码，直接登录，核心固定端口4000
mysql -h 127.0.0.1 -P 4000 -u root

# 登录成功后必执行验证命令（确认集群可用）
select tidb_version();
show databases;
create database tidb_dev_db;
use tidb_dev_db;
create table test_tbl(id int primary key, name varchar(50));
insert into test_tbl values(1, 'TiDB-Docker-Cluster');
select * from test_tbl;

3.2 方式二：可视化工具登录（DataGrip/Navicat/DBeaver，数据开发主力方式）

数据库类型：选择 MySQL （TiDB完美兼容MySQL协议，无需专属驱动）
主机地址：127.0.0.1（本地部署）/ 服务器内网IP（远程部署）
端口：4000（TiDB固定SQL登录端口，不可修改容器内端口）
用户名：root
密码：留空（默认无密码，生产环境建议立即配置）
数据库：可选填，登录后支持自由切换

四、TiDB集群核心调度配置（PD管控核心，动态生效无需重启）

4.1 前置操作：进入PD容器+pd-ctl工具基础使用

核心说明 ：TiDB所有集群调度规则、负载均衡策略、高可用配置、性能参数，全部在PD节点配置；通过内置pd-ctl工具操作，所有配置动态生效，无需重启集群。

# 进入PD容器（伪集群/分布式集群通用，替换容器名即可）
docker exec -it tidb-pd sh
# 进入pd-ctl交互模式（所有调度配置的核心入口）
pd-ctl -u http://127.0.0.1:2379
# 验证PD连接成功+查看集群状态
cluster
# 退出pd-ctl交互模式命令
exit

4.2 生产级高频核心调度配置（pd-ctl交互模式执行，必配）

# 1. 副本数配置（高可用核心，生产环境强制3副本，测试环境1副本）
config set max-replicas 3
config show max-replicas
# 2. 负载均衡调度优化（解决TiKV节点负载不均、查询卡顿）
config set schedule-region-split-size 368640000
config set schedule-load-balance-threshold 5
config set enable-hot-region-schedule true
# 3. Leader节点均衡调度（性能核心，均匀分摊读写压力）
config set enable-leader-balance true
config set leader-balance-ratio 0.45
# 4. 历史数据自动清理（数仓专属，TTL过期策略，单位：秒）
config set tikv-data-ttl 2592000
# 5. 查看所有调度配置项（验证配置生效+运维排查）
config show all

4.3 TiDB SQL层全局参数优化（登录TiDB后执行，数据开发必备）

# 设置TiDB最大并发查询数（根据宿主机CPU核数调整，8核推荐100）
set global tidb_max_concurrent_queries = 100;
# 强制开启分布式事务（TiDB核心特性，生产必开）
set global tidb_enable_2pc = on;
# 设置单查询内存阈值（避免内存溢出，单位：字节，1GB=1073741824）
set global tidb_mem_quota_query = 1073741824;
# 查看所有TiDB全局参数配置
show global variables like '%tidb%';

五、TiDB集群全量运维核心命令（全覆盖，无冗余，通用所有部署方式）

5.1 伪集群专属运维命令（Docker Compose一键操作，极简高效）

# 一键停止TiDB集群（优雅关闭，数据不丢失，核心命令）
docker compose down
# 一键启动TiDB集群
docker compose up -d
# 一键重启TiDB集群
docker compose restart
# 查看指定组件实时日志（排障核心，按需选择）
docker compose logs -f tidb
docker compose logs -f pd
docker compose logs -f tikv

5.2 分布式集群运维命令（独立组件操作，精准管控）

# 启停单个组件（不影响其他服务，按需操作）
docker start tidb-pd && docker start tidb-tikv && docker start tidb-server
docker stop tidb-pd && docker stop tidb-tikv && docker stop tidb-server
# 重启单个组件
docker restart tidb-pd
# 查看单个组件实时日志（排障核心）
docker logs -f tidb-pd
docker logs -f tidb-tikv
docker logs -f tidb-server

5.3 通用运维命令（所有部署方式通用，必备收藏）

# 查看所有运行中的TiDB相关容器
docker ps | grep tidb
# 进入TiDB Server容器排查SQL层问题
docker exec -it tidb-server sh
# 删除指定TiDB容器（谨慎执行，数据已挂载则不丢失）
docker rm tidb-pd tidb-tikv tidb-server
# 清理TiDB无用镜像（释放磁盘空间）
docker rmi pingcap/pd pingcap/tikv pingcap/tidb
# 查看宿主机磁盘挂载情况（验证数据持久化）
df -h | grep /data/tidb

六、TiDB Docker部署高频避坑指南（生产级必备，杜绝99%故障）

6.1 核心致命坑点及解决方案

坑点1：宿主机内存不足 → 集群启动卡死/容器闪退 | 解决方案：宿主机内存≥4GB，关闭无用进程释放内存，重启Docker后重新启动集群
坑点2：组件启动顺序错误 → TiKV/TiDB启动失败 | 解决方案：严格遵循 PD → TiKV → TiDB Server 启动顺序，PD为核心依赖
坑点3：时区不一致 → 数据库时间与系统差8小时 | 解决方案：所有容器启动命令添加 -e TZ=Asia/Shanghai 参数，强制东八区
坑点4：端口被占用 → 容器启动失败 | 解决方案：修改宿主机映射端口，如4000→4001、2379→2380，容器内端口不变
坑点5：未配置数据挂载 → 容器删除数据丢失 | 解决方案：生产部署必须配置 -v 宿主机目录挂载，实现数据永久持久化
坑点6：防火墙拦截端口 → 无法远程登录TiDB | 解决方案：放行宿主机4000/2379端口，开发环境可临时关闭防火墙

6.2 额外高频异常快速解决

异常1：TiKV容器启动后立即退出 | 解决方案：检查PD是否正常启动，检查TiKV的PD地址配置是否正确
异常2：能登录TiDB但执行SQL卡顿 | 解决方案：进入PD开启负载均衡调度，调整Leader均衡比例
异常3：pd-ctl连接失败 | 解决方案：检查PD容器是否运行，检查2379端口是否正常映射

七、TiDB生产环境核心安全加固配置（必做，杜绝数据泄露）

7.1 TiDB数据库用户密码配置（核心，默认无密码风险）

# 登录TiDB后执行，为root用户设置强密码（生产必备）
set password for root@'%' = 'TiDB@Prod2026';
flush privileges;
# 密码登录验证
mysql -h127.0.0.1 -P4000 -uroot -pTiDB@Prod2026

7.2 访问权限管控（生产级规范）

限制TiDB的4000端口仅对内网开放，禁止公网直接访问
非必要不开放PD的2379端口，调度配置仅在宿主机操作
为业务开发创建独立数据库用户，分配最小权限，避免使用root账号

八、TiDB集群极简弹性扩容方案（Docker专属，分布式核心能力）

8.1 TiKV存储节点扩容（核心扩容，解决存储不足/读写压力大）

核心说明 ：TiDB的存储能力由TiKV节点数量决定，新增TiKV节点即可实现存储水平扩容，PD自动调度数据分片，无需停机，无缝扩容

# 新增TiKV节点容器（复用原有集群网络，修改容器名和IP即可）
docker run -d 
--name tidb-tikv-2 
--net tidb-cluster-net 
--ip 172.20.0.5 
-p 20161:20160 
-v /data/tidb/tikv2:/var/lib/tikv 
-e TZ=Asia/Shanghai 
--restart=always 
pingcap/tikv:latest 
--addr=0.0.0.0:20160 --pd=172.20.0.2:2379 --data-dir=/var/lib/tikv

8.2 TiDB Server节点扩容（解决SQL并发查询压力大）

核心说明 ：TiDB Server为无状态节点，新增节点即可分摊SQL请求压力，所有节点共用TiKV存储，业务无感知

# 新增TiDB Server节点容器
docker run -d 
--name tidb-server-2 
--net tidb-cluster-net 
--ip 172.20.0.6 
-p 4001:4000 
-e TZ=Asia/Shanghai 
--restart=always 
pingcap/tidb:latest 
--store=tikv --path=172.20.0.2:2379

8.3 扩容验证

# 进入PD容器查看集群节点状态，确认新节点已加入
docker exec -it tidb-pd sh
pd-ctl -u http://127.0.0.1:2379
cluster

九、TiDB核心特性与数据开发适配说明（数据开发工程师专属）

9.1 核心兼容特性（降低学习成本）

完全兼容MySQL5.7协议、SQL语法、函数，原有MySQL业务无缝迁移
支持MySQL所有客户端工具、数据同步工具（DataX/Sqoop/Flink CDC）
支持分布式事务、ACID特性，满足金融级数据一致性要求

9.2 核心优势特性（数据开发首选）

海量数据存储：支持PB级数据量，无需分库分表，原生分布式存储
水平扩容：存储/计算能力按需扩容，无需停机，业务无感知
高性能查询：支持行存+列存混合架构，OLTP+OLAP一体化，数仓开发最优解
自动分片：数据按Region自动分片，无需手动规划分片规则

十、全文核心总结

10.1 部署选型建议

开发/测试/学习：优先选择 单机伪集群 ，一键部署、零配置、快速启停
生产预发/小型业务/数仓部署：优先选择 轻量分布式集群 ，解耦、持久化、可扩容、高可用

10.2 核心操作核心

登录核心：TiDB兼容MySQL协议，4000端口为固定SQL入口，可视化工具直接选择MySQL连接
配置核心：所有集群调度规则在PD节点通过pd-ctl配置，动态生效无需重启
运维核心：Docker Compose一键启停伪集群，独立命令管控分布式集群，日志排查为核心排障手段

10.3 核心避坑原则

内存必达标：宿主机内存≥4GB，否则集群无法正常运行
顺序必遵守：PD先启动，TiKV次之，TiDB最后启动
数据必挂载：生产环境必须配置宿主机目录挂载，实现数据持久化
时区必统一：所有容器添加东八区时区配置，避免数据时间错误

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

亚马逊云科技技术品牌专区

所有评论(0)

查看更多评论

ruxshui

@weixin_43864993

已为社区贡献7条内容

Docker部署TiDB集群技术文档

ruxshui

Docker部署TiDB集群 完整技术文档（含安装/部署/登录/调度配置/运维/扩容/安全加固）

一、前置核心准备与依赖要求

1.1 TiDB集群核心架构（必知）

1.2 宿主机硬性环境要求（启动失败核心诱因）

1.3 Docker环境安装与状态验证

二、TiDB集群Docker部署两种核心方式

2.1 方式一：单机伪集群（官方推荐，开发/测试/学习首选，99%场景适配）

2.2 方式二：轻量分布式集群（生产级规范部署，推荐）

三、TiDB集群核心登录方式（完全兼容MySQL5.7协议，零学习成本）

3.1 方式一：宿主机原生MySQL客户端登录（推荐，无依赖，开发/运维通用）

3.2 方式二：可视化工具登录（DataGrip/Navicat/DBeaver，数据开发主力方式）

四、TiDB集群核心调度配置（PD管控核心，动态生效无需重启）

4.1 前置操作：进入PD容器+pd-ctl工具基础使用

4.2 生产级高频核心调度配置（pd-ctl交互模式执行，必配）

4.3 TiDB SQL层全局参数优化（登录TiDB后执行，数据开发必备）

五、TiDB集群全量运维核心命令（全覆盖，无冗余，通用所有部署方式）

5.1 伪集群专属运维命令（Docker Compose一键操作，极简高效）

5.2 分布式集群运维命令（独立组件操作，精准管控）

5.3 通用运维命令（所有部署方式通用，必备收藏）

六、TiDB Docker部署高频避坑指南（生产级必备，杜绝99%故障）

6.1 核心致命坑点及解决方案

6.2 额外高频异常快速解决

七、TiDB生产环境核心安全加固配置（必做，杜绝数据泄露）

7.1 TiDB数据库用户密码配置（核心，默认无密码风险）

7.2 访问权限管控（生产级规范）

八、TiDB集群极简弹性扩容方案（Docker专属，分布式核心能力）

8.1 TiKV存储节点扩容（核心扩容，解决存储不足/读写压力大）

8.2 TiDB Server节点扩容（解决SQL并发查询压力大）

8.3 扩容验证

九、TiDB核心特性与数据开发适配说明（数据开发工程师专属）

9.1 核心兼容特性（降低学习成本）

9.2 核心优势特性（数据开发首选）

十、全文核心总结

10.1 部署选型建议

10.2 核心操作核心

10.3 核心避坑原则

所有评论(0)

温馨提示：您尚未绑定手机号

ruxshui

Docker部署TiDB集群完整技术文档（含安装/部署/登录/调度配置/运维/扩容/安全加固）