Docker 部署单机 TiDB：从环境准备到生产就绪的完整指南

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

在开发测试环境中，传统物理机或虚拟机部署 TiDB 存在资源占用高、环境复现困难等问题。Docker 容器化技术通过轻量级虚拟化实现了三大核心优势：

1. 资源隔离：每个容器独立分配 CPU、内存资源，避免服务间竞争
2. 环境标准化：通过 Dockerfile 定义依赖，确保开发、测试、生产环境一致性
3. 快速迭代：容器启动仅需数秒，支持持续集成场景下的快速环境重建

对于单机部署场景，Docker 特别适合：

• 开发人员本地验证 SQL 优化效果
• 测试团队进行功能回归测试
• 小型项目初期验证 TiDB 特性
• 数据库管理员学习 TiDB 运维管理

二、环境准备与前置条件

2.1 硬件配置要求

组件	最低配置	推荐配置
容器主机	4核8G	8核16G（SSD存储）
磁盘空间	100GB（数据盘）	500GB NVMe SSD
操作系统	Linux 3.10+	CentOS 7/Ubuntu 20.04+

2.2 软件依赖安装

# 安装 Docker CE（以 Ubuntu 为例）
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
# 验证安装
sudo docker run hello-world

2.3 网络配置要点

• 确保主机端口 4000（TiDB）、2379（PD）、9090（Prometheus）未被占用
• 如需外部访问，配置防火墙规则：

  sudo ufw allow 4000/tcp
  sudo ufw allow 2379/tcp

三、核心组件容器化部署

3.1 使用 Docker Compose 编排

创建 docker-compose.yml 文件：

version: '3.8'
services:
  pd:
    image: pingcap/pd:v6.5.0
    container_name: pd
    ports:
      - "2379:2379"
    volumes:
      - pd_data:/var/lib/pd
    command: ["--name=pd1", "--data-dir=/var/lib/pd", "--client-urls=http://0.0.0.0:2379"]
  tikv:
    image: pingcap/tikv:v6.5.0
    container_name: tikv
    depends_on:
      - pd
    volumes:
      - tikv_data:/var/lib/tikv
    command: ["--pd=http://pd:2379", "--data-dir=/var/lib/tikv", "--addr=0.0.0.0:20160"]
  tidb:
    image: pingcap/tidb:v6.5.0
    container_name: tidb
    ports:
      - "4000:4000"
    depends_on:
      - pd
    command: ["--store=tikv", "--path=http://pd:2379"]
  prometheus:
    image: prom/prometheus:v2.30.0
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
  grafana:
    image: grafana/grafana:8.3.3
    container_name: grafana
    ports:
      - "3000:3000"
    depends_on:
      - prometheus
volumes:
  pd_data:
  tikv_data:

3.2 关键配置参数解析

1. PD 配置：

   • --name：集群中唯一标识
   • --client-urls：客户端访问地址
   • 推荐添加 --peer-urls 配置集群内部通信

2. TiKV 配置：

   • --addr：服务监听地址
   • --status-addr：状态报告地址（监控使用）
   • 生产环境建议配置 --capacity 限制存储空间

3. TiDB 配置：

   • --log-level：建议设置为 “warn” 减少日志量
   • --status-addr：健康检查接口

四、部署流程与验证

4.1 完整部署步骤

1. 创建监控配置文件 prometheus.yml：
   ```yaml
   global:
   scrape_interval: 15s

scrape_configs:

• job_name: ‘tikv’
  static_configs:
  • targets: [‘tikv:20180’]
• job_name: ‘tidb’
  static_configs:
  • targets: [‘tidb:10080’]
    ```

1. 启动服务：

   docker-compose up -d

2. 验证服务状态：
   ```bash

   检查容器状态

   docker-compose ps

验证 PD 集群状态

docker exec -it pd sh -c “pd-ctl member show”

测试 TiDB 连接

mysql -h 127.0.0.1 -P 4000 -u root -e “SELECT VERSION()”

### 4.2 常见问题处理
1. **TiKV 启动失败**：
   - 检查 `/var/lib/tikv` 目录权限
   - 确认 PD 服务已就绪
   - 查看日志：`docker logs tikv`
2. **连接超时**：
   - 检查防火墙设置
   - 验证端口映射：`netstat -tulnp | grep 4000`
3. **性能异常**：
   - 使用 `top` 命令检查容器资源使用
   - 调整 Docker 资源限制：
     ```yaml
     # 在 docker-compose.yml 中添加资源限制
     deploy:
       resources:
         limits:
           cpus: '2.0'
           memory: 8G

五、性能优化建议

5.1 存储配置优化

1. 使用本地 SSD：

   volumes:
     tikv_data:
       driver_opts:
         type: "local"
         device: "/dev/nvme0n1"
         o: "bind"

2. 调整 RocksDB 参数：

   # 在 TiKV 启动命令中添加
   --config=/path/to/tikv.toml
   # 示例配置内容
   [rocksdb]
   max-background-jobs = 8
   block-cache-size = "4GB"

5.2 内存配置建议

组件	内存分配建议	配置参数
TiDB	4GB+	--mem-quota-query=2147483648
TiKV	8GB+	--mem-table-size=128MB
PD	1GB+	无特殊配置

5.3 监控指标解读

关键监控项：

1. TiDB QPS：tidb_server_query_total
2. TiKV 延迟：tikv_grpc_msg_duration_seconds_bucket
3. PD 调度：pd_scheduler_balance_region_duration_seconds

通过 Grafana 仪表板设置告警规则：

• 单次查询超过 500ms
• TiKV 存储空间使用率 > 80%
• PD 领导选举频率异常

六、生产环境注意事项

1. 数据持久化：

   • 使用 volumes 替代匿名卷
   • 定期备份配置文件和数据目录

2. 升级策略：

   # 滚动升级示例
   docker-compose pull
   docker-compose up -d --no-deps --build tidb

3. 安全配置：

   • 启用 TLS 加密：

     # 在 TiDB 配置中添加
     command: ["--tls-enabled=true", "--tls-cert=/path/cert.pem", "--tls-key=/path/key.pem"]

   • 配置访问控制列表（ACL）

七、进阶使用场景

7.1 多实例部署

修改 docker-compose.yml 支持多 TiKV 实例：

tikv1:
  image: pingcap/tikv:v6.5.0
  command: ["--pd=http://pd:2379", "--data-dir=/var/lib/tikv1", "--addr=0.0.0.0:20160"]
  volumes:
    - tikv1_data:/var/lib/tikv1
tikv2:
  image: pingcap/tikv:v6.5.0
  command: ["--pd=http://pd:2379", "--data-dir=/var/lib/tikv2", "--addr=0.0.0.0:20161"]
  volumes:
    - tikv2_data:/var/lib/tikv2

7.2 与 CI/CD 集成

示例 Jenkins Pipeline 片段：

pipeline {
    agent any
    stages {
        stage('Deploy TiDB') {
            steps {
                sh 'docker-compose down'
                sh 'docker-compose pull'
                sh 'docker-compose up -d'
                sleep 60 // 等待服务就绪
            }
        }
        stage('Test') {
            steps {
                sh 'mysql -h 127.0.0.1 -P 4000 -u root -e "CREATE DATABASE IF NOT EXISTS testdb"'
                // 执行测试用例
            }
        }
    }
}

八、总结与最佳实践

1. 资源分配原则：

   • TiKV 实例数建议为 CPU 核心数的 1.5 倍
   • 预留 20% 资源用于系统进程

2. 备份策略：

   # 使用 mysqldump 备份
   docker exec -it tidb sh -c "mysqldump -h 127.0.0.1 -P 4000 -u root --all-databases > /backup/full.sql"

3. 日志管理：

   • 配置日志轮转：

     # 在 docker-compose.yml 中添加
     logging:
       driver: "json-file"
       options:
         max-size: "100m"
         max-file: "3"

通过 Docker 部署单机 TiDB 不仅简化了环境搭建流程，更提供了灵活的资源管理和快速迭代能力。实际生产环境中，建议在此基础上扩展为集群部署，并配合专业的监控告警系统实现稳定运行。