Docker 部署单机 TiDB：从零开始的完整指南

一、为什么选择 Docker 部署单机 TiDB？

TiDB 作为一款开源的分布式 NewSQL 数据库，其核心优势在于兼容 MySQL 协议、支持水平扩展和强一致性事务。但在开发阶段，开发者往往需要快速搭建一个轻量级的测试环境，此时 Docker 的容器化部署方案便展现出显著优势：

1. 环境隔离：通过容器技术，TiDB 及其依赖组件（如 PD、TiKV）可运行在独立的命名空间中，避免与宿主机环境冲突。
2. 快速部署：相比传统虚拟机或物理机部署，Docker 方案可将部署时间从小时级缩短至分钟级。
3. 资源可控：通过 docker run 命令的 -m 参数可精确限制容器内存使用，防止测试环境占用过多资源。
4. 版本一致性：使用官方提供的 Docker 镜像可确保不同环境下的 TiDB 版本完全一致。

二、部署前的环境准备

2.1 硬件要求

单机部署建议配置：

• CPU：4 核及以上（TiDB 默认启用 4 个线程）
• 内存：8GB 及以上（生产环境建议 32GB+）
• 磁盘：SSD 优先，建议至少 100GB 可用空间
• 网络：千兆以太网（避免无线连接）

2.2 软件依赖

1. Docker 引擎：

   • 推荐使用最新稳定版（测试时验证通过版本：24.0.5）
   • 安装命令（Ubuntu 22.04）：

     curl -fsSL https://get.docker.com | sh
     sudo usermod -aG docker $USER
     newgrp docker

2. Docker Compose（可选但推荐）：

   • 用于简化多容器编排，安装命令：

     sudo apt-get install docker-compose-plugin

3. 端口检查：

   • 确保以下端口未被占用：
     • 4000（TiDB Server）
     • 2379（PD 客户端端口）
     • 2380（PD 集群通信端口）
     • 20160（TiKV 状态端口）
     • 20180（TiKV 存储端口）

三、单机部署方案详解

方案一：使用官方 Docker 镜像快速启动

PingCAP 官方提供了预构建的 Docker 镜像，这是最简便的部署方式：

# 拉取最新稳定版镜像
docker pull pingcap/tidb:latest
# 启动容器（基础模式）
docker run -d \
  --name tidb-server \
  -p 4000:4000 \
  -p 10080:10080 \
  pingcap/tidb:latest \
  --store=mocktikv \
  --path="/var/lib/tidb"

参数说明：

• --store=mocktikv：使用内存模拟的 TiKV 存储，适合测试但数据不持久
• --path：指定数据存储路径（在 mocktikv 模式下实际不生效）

局限性：

• 数据非持久化，容器重启后数据丢失
• 性能远低于真实 TiKV 存储

方案二：完整组件部署（推荐生产测试）

更接近生产环境的部署需要同时运行 PD、TiKV 和 TiDB 三个组件：

3.1 使用 Docker Compose 编排

创建 docker-compose.yml 文件：

version: '3.8'
services:
  pd:
    image: pingcap/pd:latest
    command: ["--name=pd1",
              "--data-dir=/var/lib/pd",
              "--client-urls=http://0.0.0.0:2379",
              "--peer-urls=http://0.0.0.0:2380",
              "--advertise-client-urls=http://pd:2379",
              "--advertise-peer-urls=http://pd:2380",
              "--initial-cluster=pd=http://pd:2380"]
    volumes:
      - pd_data:/var/lib/pd
    ports:
      - "2379:2379"
    networks:
      - tidb-net
  tikv:
    image: pingcap/tikv:latest
    command: ["--addr=0.0.0.0:20160",
              "--advertise-addr=tikv:20160",
              "--data-dir=/var/lib/tikv",
              "--pd=pd:2379"]
    volumes:
      - tikv_data:/var/lib/tikv
    depends_on:
      - pd
    networks:
      - tidb-net
  tidb:
    image: pingcap/tidb:latest
    command: ["--store=tikv",
              "--path=pd:2379"]
    ports:
      - "4000:4000"
      - "10080:10080"
    depends_on:
      - pd
      - tikv
    networks:
      - tidb-net
volumes:
  pd_data:
  tikv_data:
networks:
  tidb-net:
    driver: bridge

启动命令：

docker-compose up -d

3.2 手动分步部署（理解原理）

对于需要深度定制的场景，可手动启动各组件：

# 启动 PD 节点
docker run -d --name pd \
  -v pd_data:/var/lib/pd \
  -p 2379:2379 \
  pingcap/pd:latest \
  --name=pd1 \
  --data-dir=/var/lib/pd \
  --client-urls=http://0.0.0.0:2379 \
  --advertise-client-urls=http://$(hostname -I | awk '{print $1}'):2379
# 启动 TiKV 节点（需先获取 PD 地址）
PD_ADDR=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' pd)
docker run -d --name tikv \
  -v tikv_data:/var/lib/tikv \
  pingcap/tikv:latest \
  --addr=0.0.0.0:20160 \
  --advertise-addr=$(hostname -I | awk '{print $1}'):20160 \
  --data-dir=/var/lib/tikv \
  --pd=$PD_ADDR:2379
# 启动 TiDB 节点
docker run -d --name tidb \
  -p 4000:4000 \
  -p 10080:10080 \
  pingcap/tidb:latest \
  --store=tikv \
  --path=$PD_ADDR:2379

四、部署后的验证与优化

4.1 连接验证

使用 MySQL 客户端连接测试：

mysql -h 127.0.0.1 -P 4000 -u root -D test

执行基础 SQL 验证：

CREATE TABLE t (id INT PRIMARY KEY);
INSERT INTO t VALUES (1);
SELECT * FROM t;

4.2 性能监控

1. TiDB Dashboard：

   • 访问 http://localhost:10080 查看集群状态
   • 重点监控：
     • QPS/TPS 指标
     • 连接数
     • 存储空间使用

2. Prometheus 集成（高级）：
   修改 docker-compose.yml 添加监控组件：

   prometheus:
     image: prom/prometheus:v2.44.0
     command: ["--config.file=/etc/prometheus/prometheus.yml"]
     volumes:
       - ./prometheus.yml:/etc/prometheus/prometheus.yml
     ports:
       - "9090:9090"
     networks:
       - tidb-net

4.3 参数调优建议

1. 内存配置：

   # 启动 TiDB 时添加内存限制参数
   docker run ... pingcap/tidb:latest \
     --mem-quota-query=1073741824 \  # 1GB 查询内存限制
     --performance.max-procs=4       # 限制 CPU 核心数

2. 日志级别调整：

   # 在 docker-compose 中设置环境变量
   environment:
     - LOG_LEVEL=info

五、常见问题解决方案

问题1：容器启动后立即退出

原因：

• 参数配置错误导致进程崩溃
• 依赖服务（如 PD）未就绪

解决方案：

# 查看容器日志
docker logs tidb-server
# 增加启动延迟（适用于依赖问题）
command: ["sh", "-c", "sleep 10 && /tidb-server ..."]

问题2：性能低于预期

优化方向：

1. 调整 TiKV 块缓存大小：

   docker run ... pingcap/tikv:latest \
     --config=/etc/tikv/config.toml

   在 config.toml 中设置：

   [storage]
   block-cache = { capacity = "1GB" }

2. 启用并行扫描：

   SET GLOBAL tidb_distsql_scan_concurrency = 16;

问题3：数据持久化失败

正确做法：

1. 确保使用 -v 参数挂载卷：

   volumes:
     - tikv_data:/var/lib/tikv

2. 定期备份数据目录：

   docker exec tikv tar czf /backup/tikv.tar.gz /var/lib/tikv

六、进阶使用建议

1. 多版本测试：

   # 测试不同 TiDB 版本
   docker pull pingcap/tidb:v6.5.0
   docker tag pingcap/tidb:v6.5.0 my-tidb:v6.5.0

2. 与 CI/CD 集成：

   # 在 GitLab CI 中示例
   test_tidb:
     image: docker:latest
     services:
       - docker:dind
     script:
       - docker-compose up -d
       - sleep 30  # 等待服务启动
       - mysql -h tidb -P 4000 -u root -e "SHOW DATABASES;"

3. 混合负载测试：
   使用 Sysbench 进行基准测试：

   sysbench oltp_read_write \
     --db-driver=mysql \
     --mysql-host=127.0.0.1 \
     --mysql-port=4000 \
     --mysql-user=root \
     --tables=10 \
     --table-size=100000 \
     prepare

七、总结与最佳实践

1. 开发环境配置：

   • 内存限制：建议 4GB 起步，8GB 更佳
   • 存储：使用 SSD 或内存盘（tmpfs）加速测试
   • 网络：使用 host 网络模式减少性能开销（测试环境）

2. 生产环境警示：

   • 绝对不要在生产环境使用 mocktikv
   • 确保部署三个以上 PD 节点实现高可用
   • 配置正确的时区（TZ=Asia/Shanghai）

3. 版本选择策略：

   • 开发测试：使用最新稳定版
   • 兼容性测试：指定版本号（如 v6.5.0）
   • 长期支持：选择 LTS 版本

通过 Docker 部署单机 TiDB 不仅简化了环境搭建过程，更为开发者提供了一个可控、可复现的测试平台。掌握这种部署方式后，开发者可以更高效地进行功能验证、性能调优和故障复现，显著提升开发效率。