TiDB单机部署全指南：从环境准备到生产就绪

2025年11月1日 互联网

TiDB单机部署全指南：从环境准备到生产就绪

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

TiDB作为一款开源的分布式NewSQL数据库，以其水平扩展性、强一致性和MySQL兼容性著称。但在开发测试、性能基准测试或学习场景中，单机部署具有显著优势：资源占用低（单节点可运行完整TiDB集群）、部署简单（无需配置多节点网络）、成本可控（适合个人开发者或小团队）。单机模式通过启动TiDB、TiKV和PD组件的单个实例，模拟分布式环境的核心功能，为本地开发提供高效验证平台。

二、环境准备：硬件与软件要求

硬件配置建议

  • CPU：4核及以上（开发环境推荐8核，避免高并发测试时性能瓶颈）
  • 内存：16GB以上（生产环境建议32GB+，TiKV对内存敏感）
  • 磁盘：SSD固态硬盘（IOPS≥5000，容量≥200GB，TiKV依赖高性能存储）
  • 网络：千兆以太网（单机模式无需特殊网络配置，但需确保端口开放）

软件依赖清单

  • 操作系统：Linux（推荐CentOS 7/8或Ubuntu 20.04+）
  • 依赖包：wget、curl、tar、net-tools（基础工具）
  • Go环境（可选）：若需从源码编译，需安装Go 1.18+
  • Docker（推荐）：简化依赖管理，避免直接安装TiDB二进制文件

三、单机部署方案对比与选择

方案1：Docker Compose快速部署（推荐）

适用场景：快速验证、开发测试、学习使用
步骤：

  1. 安装Docker和Docker Compose（参考官方文档）
  2. 下载TiDB官方Docker Compose文件： 
    1. wget https://raw.githubusercontent.com/pingcap/tidb-docker-compose/master/docker-compose.yml
  3. 启动集群： 
    1. docker-compose up -d
  4. 验证服务： 
    1. docker-compose exec tidb mysql -h 127.0.0.1 -P 4000 -u root -e "SELECT VERSION();"

    优势：隔离环境、一键启动、支持持久化存储
    注意：默认配置适合开发，生产需调整tikv.cfg中的rocksdb和raftdb路径。

方案2：二进制文件手动部署

适用场景：需要自定义配置、深入理解组件交互
步骤：

  1. 下载TiDB、TiKV、PD的二进制包（从GitHub Release页面）
  2. 配置文件示例（pd.toml）： 
    1. [log]
    2. level = "info"
    3. [schedule]
    4. max-merge-region-size = 20
    5. [replication]
    6. max-replicas = 1  # 单机模式设为1
  3. 启动顺序：PD → TiKV → TiDB 
    1. ./pd-server --name=pd1 --data-dir=pd_data --client-urls="http://127.0.0.1:2379"
    2. ./tikv-server --pd="127.0.0.1:2379" --data-dir=tikv_data
    3. ./tidb-server --store=tikv --path="127.0.0.1:2379"

    优势：完全控制配置、适合调试
    挑战：需手动处理依赖和端口冲突。

四、关键配置调优

TiKV内存限制

单机模式下，TiKV默认会占用较多内存，需通过config.toml限制：

  1. [server]
  2. grpc-concurrency = 4  # 根据CPU核心数调整
  3. [rocksdb]
  4. max-background-jobs = 4
  5. [raftdb]
  6. max-background-jobs = 4

日志与监控配置

启用Prometheus和Grafana监控（Docker方案已集成）：

  1. docker-compose exec prometheus curl http://localhost:9090

手动部署需配置prometheus.yml，添加TiDB、TiKV、PD的监控端口。

五、生产就绪检查清单

  1. 持久化存储：确认tikv_data和pd_data目录位于SSD且不会因重启丢失。
  2. 端口冲突：检查4000（TiDB）、2379（PD）、20160（TiKV）是否被占用。
  3. 资源监控：使用htop或nvidia-smi（如适用）观察CPU和内存使用率。
  4. 备份策略：配置dumpling或br工具进行定期备份。
  5. 压力测试：使用sysbench验证TPS和QPS： 
    1. 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
    2. sysbench oltp_read_write run

六、常见问题与解决方案

问题1：TiDB启动失败，报错“connection refused”

原因：PD未启动或端口未开放
解决：

  1. 检查PD日志：docker-compose logs pd或journalctl -u pd-server
  2. 确认PD的client-urls和peer-urls配置正确

问题2：写入性能低于预期

原因：TiKV默认配置未优化
解决：

  1. 调整rocksdb.defaultcf.block-cache-size（建议为内存的40%）
  2. 启用raftdb.enable-pipelined-write（TiDB 5.0+）

问题3：Docker容器无法访问主机网络

解决：在docker-compose.yml中添加：

  1. networks:
  2.   tidb-net:
  3.     driver: bridge
  4.     ipam:
  5.       config:
  6.         - subnet: 172.20.0.0/16

七、进阶建议

  1. 混合部署：在单机上同时运行MySQL和TiDB，通过ProxySQL实现读写分离测试。
  2. 版本升级：使用tiup upgrade tidb工具平滑升级到最新版本。
  3. 安全加固：启用TLS加密和用户认证（修改tidb.toml中的security部分）。

通过以上步骤，开发者可以在1小时内完成TiDB单机环境的搭建与验证。对于生产环境，建议逐步迁移到分布式架构，但单机模式仍是快速迭代和学习的理想选择。

最新文章