TiDB单机部署指南：从零开始搭建本地数据库环境

一、单机部署TiDB的核心价值与适用场景

TiDB作为一款开源的分布式HTAP数据库，其单机部署模式在开发测试、学习研究及轻量级业务场景中具有显著优势。相较于集群部署，单机模式无需复杂网络配置，资源占用低（建议8核16G以上配置），且能完整体验TiDB的核心功能，包括事务处理、分布式SQL引擎及自动分片机制。

典型适用场景包括：

1. 开发环境搭建：开发者可在本地快速验证SQL语法、存储过程及事务逻辑
2. 功能测试验证：测试团队可独立部署进行兼容性测试、性能基准测试
3. 教学演示用途：教育机构或培训场景下展示NewSQL数据库特性
4. 边缘计算场景：资源受限环境下的轻量级数据存储需求

需要特别说明的是，单机部署仅建议用于非生产环境。其数据持久性、高可用性均弱于集群模式，生产环境必须采用至少3节点的集群部署方案。

二、环境准备与前置条件

硬件配置要求

• CPU：建议8核以上（测试环境可放宽至4核）
• 内存：16GB以上（TiDB组件总内存占用约8GB）
• 磁盘：SSD固态硬盘，容量不低于200GB
• 网络：千兆以太网（单机部署可忽略网络要求）

软件依赖安装

1. 操作系统：推荐CentOS 7.x/8.x或Ubuntu 20.04 LTS

   # CentOS系统基础依赖安装
   sudo yum install -y wget curl tar gzip

2. Docker环境（推荐使用Docker Compose）

   # 安装Docker CE
   curl -fsSL https://get.docker.com | sh
   sudo systemctl enable docker
   sudo systemctl start docker
   # 安装Docker Compose
   sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
   sudo chmod +x /usr/local/bin/docker-compose

3. 系统参数调优

   # 修改内核参数（临时生效）
   sudo sysctl -w vm.swappiness=0
   sudo sysctl -w fs.file-max=1000000
   # 永久生效需写入/etc/sysctl.conf
   echo "vm.swappiness=0" >> /etc/sysctl.conf
   echo "fs.file-max=1000000" >> /etc/sysctl.conf
   sudo sysctl -p

三、TiDB单机部署实施步骤

方法一：Docker Compose快速部署（推荐）

1. 下载部署模板

   curl -O https://raw.githubusercontent.com/pingcap/tidb-docker-compose/master/docker-compose-single.yml

2. 修改配置参数
   编辑docker-compose-single.yml文件，重点调整以下参数：

   services:
     tidb:
       image: pingcap/tidb:v6.5.0
       ports:
         - "4000:4000"  # MySQL协议端口
         - "10080:10080" # 状态监控端口
       environment:
         - LOG_LEVEL=info
         - MEMORY_LIMIT=8GB  # 根据实际内存调整

3. 启动服务

   docker-compose -f docker-compose-single.yml up -d

4. 验证部署

   # 使用MySQL客户端连接
   mysql -h 127.0.0.1 -P 4000 -u root -p
   # 默认无密码，直接回车
   # 执行验证SQL
   SHOW DATABASES;
   CREATE DATABASE test_db;
   USE test_db;
   CREATE TABLE test_table (id INT PRIMARY KEY, name VARCHAR(50));
   INSERT INTO test_table VALUES (1, 'TiDB Demo');
   SELECT * FROM test_table;

方法二：二进制包手动部署

1. 下载官方二进制包

   wget https://download.pingcap.org/tidb-v6.5.0-linux-amd64.tar.gz
   tar -xzf tidb-v6.5.0-linux-amd64.tar.gz
   cd tidb-v6.5.0-linux-amd64

2. 配置服务文件
   创建/etc/systemd/system/tidb.service：

   [Unit]
   Description=TiDB Server
   After=network.target
   [Service]
   User=tidb
   Group=tidb
   ExecStart=/path/to/tidb-server --store=tikv --path="127.0.0.1:2379" --log-file=/var/log/tidb.log
   Restart=on-failure
   [Install]
   WantedBy=multi-user.target

3. 启动服务

   sudo systemctl daemon-reload
   sudo systemctl start tidb
   sudo systemctl enable tidb

四、关键配置优化建议

内存参数调优

# tidb.toml 配置示例
[performance]
max-procs = 8  # 设置为CPU核心数
txn-total-size-limit = 104857600  # 事务大小限制(100MB)
[log]
level = "info"
file-max-days = 7

存储引擎配置

# tikv.toml 配置示例
[storage]
block-cache = {capacity = "1GB"}  # RocksDB块缓存
write-buffer-size = "64MB"

监控集成方案

1. Prometheus+Grafana监控栈

   # docker-compose.yml 片段
   prometheus:
     image: prom/prometheus:v2.30.0
     ports:
       - "9090:9090"
     volumes:
       - ./prometheus.yml:/etc/prometheus/prometheus.yml

2. 关键监控指标

   • tidb_server_query_total：SQL查询总量
   • tikv_storage_block_cache_hit_ratio：块缓存命中率
   • pd_cluster_status：集群健康状态

五、常见问题解决方案

启动失败排查流程

1. 检查日志

   docker-compose logs tidb
   # 或
   journalctl -u tidb -f

2. 端口冲突处理

   # 检查4000端口占用
   sudo netstat -tulnp | grep 4000
   # 终止冲突进程
   sudo kill -9 <PID>

3. 内存不足问题

   • 调整--memory-limit参数
   • 增加交换空间（不推荐生产环境）

     sudo fallocate -l 4G /swapfile
     sudo chmod 600 /swapfile
     sudo mkswap /swapfile
     sudo swapon /swapfile

性能优化技巧

1. SQL优化建议

   -- 添加索引示例
   ALTER TABLE test_table ADD INDEX idx_name(name);
   -- 避免全表扫描
   EXPLAIN SELECT * FROM test_table WHERE id = 1;

2. 连接池配置

   // Go客户端示例
   dsn := "root:@tcp(127.0.0.1:4000)/test_db?charset=utf8mb4&parseTime=True&loc=Local"
   db, err := sql.Open("mysql", dsn)
   if err != nil {
       log.Fatal(err)
   }
   db.SetMaxIdleConns(10)
   db.SetMaxOpenConns(20)

六、进阶使用建议

1. 数据备份恢复

   # 使用Dumpling备份
   dumpling -u root -h 127.0.0.1 -P 4000 -o /data/backup
   # 使用TiDB Lightning恢复
   tidb-lightning -config lightning.toml

2. 与ORM框架集成

   # Python SQLAlchemy示例
   from sqlalchemy import create_engine
   engine = create_engine("mysql+pymysql://root:@127.0.0.1:4000/test_db")

3. 安全加固措施

   • 修改默认端口
   • 启用TLS加密
   • 配置权限控制

     CREATE USER 'app_user'@'%' IDENTIFIED BY 'SecurePass123!';
     GRANT SELECT, INSERT ON test_db.* TO 'app_user'@'%';

通过本文的详细指导，开发者可以在30分钟内完成TiDB的单机部署，并掌握基础运维技能。建议后续深入学习TiDB的分布式架构原理、事务模型及HTAP特性，为实际生产环境部署打下坚实基础。