TiDB单机部署指南：从零开始搭建分布式数据库

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

在分布式数据库架构中，TiDB通常以多节点集群形式运行以实现高可用和水平扩展。然而，单机部署模式在开发测试、功能验证、小型项目初期等场景下具有显著价值：

1. 开发环境快速搭建：开发者可在本地环境模拟TiDB核心功能，避免依赖远程集群
2. 学习与教学场景：教学机构可通过单机版演示TiDB架构原理
3. 功能验证与POC测试：在正式集群部署前验证兼容性和功能
4. 边缘计算场景：资源受限环境下需要轻量级数据库方案

需要特别说明的是，单机部署的TiDB在数据可靠性、高可用性方面存在天然限制，不建议用于生产环境。其核心价值在于提供低成本的TiDB技术体验途径。

二、环境准备与前置条件

硬件配置要求

组件	最低配置	推荐配置
CPU	4核	8核及以上
内存	8GB	16GB及以上
磁盘	100GB SSD	500GB NVMe SSD
操作系统	Linux CentOS 7+	Ubuntu 20.04 LTS

软件依赖清单

1. 系统工具：wget, curl, tar, systemd
2. 编程语言：Go 1.18+（编译TiDB时需要）
3. 网络配置：开放4000(TiDB)、2379(PD)、9000(TiKV)等端口

三、单机部署实施步骤

1. 下载安装包

# 获取最新稳定版（示例为6.5.0版本）
wget https://download.pingcap.org/tidb-community-server-v6.5.0-linux-amd64.tar.gz
tar -xzf tidb-community-server-*.tar.gz
cd tidb-community-server-v6.5.0-linux-amd64

2. 配置文件优化

编辑conf/tidb.toml关键参数：

[performance]
max-procs = 8  # 匹配CPU核心数
[log]
level = "info"
[tikv-client]
grpc-connection-count = 16  # 单机环境适当减少

PD服务配置conf/pd.toml：

[schedule]
leader-schedule-limit = 1
region-schedule-limit = 1

3. 启动服务顺序

# 1. 启动Placement Driver
nohup ./bin/pd-server --name=pd1 \
  --data-dir=pd \
  --client-urls="http://127.0.0.1:2379" \
  --peer-urls="http://127.0.0.1:2380" \
  --config=conf/pd.toml > pd.log 2>&1 &
# 2. 启动TiKV
nohup ./bin/tikv-server --pd="127.0.0.1:2379" \
  --data-dir=tikv \
  --config=conf/tikv.toml > tikv.log 2>&1 &
# 3. 启动TiDB
nohup ./bin/tidb-server --store=tikv \
  --path="127.0.0.1:2379" \
  --config=conf/tidb.toml > tidb.log 2>&1 &

4. 验证服务状态

# 检查PD状态
curl http://127.0.0.1:2379/pd/api/v1/members
# 检查TiKV状态
curl http://127.0.0.1:20160/status
# 连接TiDB测试
mysql -h 127.0.0.1 -P 4000 -u root -e "SELECT VERSION();"

四、性能调优建议

内存配置优化

在conf/tikv.toml中调整：

[rocksdb]
max-open-files = 65535
[raftdb]
max-open-files = 65535
[server]
grpc-concurrency = 4  # 默认值调整为CPU核心数的50%

存储引擎调优

1. 启用enable-pipelined-write提升写入性能
2. 调整defaultcf.block-cache-size为可用内存的40%
3. 配置writecf.block-cache-size为可用内存的20%

网络参数优化

# 在/etc/sysctl.conf中添加
net.core.somaxconn = 32768
net.ipv4.tcp_max_syn_backlog = 16384
net.ipv4.tcp_tw_reuse = 1

五、常见问题解决方案

1. 启动失败排查流程

1. 检查日志文件（pd.log, tikv.log, tidb.log）
2. 验证端口占用：netstat -tulnp | grep -E "2379|2380|20160|4000"
3. 检查磁盘空间：df -h
4. 验证Go环境（编译时需要）：go version

2. 性能瓶颈分析

使用TiDB自带的监控工具：

# 启动Prometheus监控
./bin/prometheus --config.file=conf/prometheus.yml
# 启动Grafana看板
./bin/grafana-server --config=conf/grafana.ini

关键监控指标：

• TiKV RocksDB写入延迟
• PD调度器负载
• TiDB QPS和延迟

3. 数据备份与恢复

单机环境推荐使用dumpling工具：

./bin/dumpling -u root -P 4000 -h 127.0.0.1 \
  --output /tmp/backup \
  --filetype sql

恢复数据使用tidb-lightning：

./bin/tidb-lightning -config tidb-lightning.toml \
  -d /tmp/backup

六、进阶使用建议

1. 混合部署方案

在资源充足的单机上可部署：

• 1个PD实例
• 3个TiKV实例（使用不同端口）
• 1个TiDB实例

配置示例：

# TiKV1配置
[server]
addr = "0.0.0.0:20160"
status-addr = "0.0.0.0:20180"
# TiKV2配置
[server]
addr = "0.0.0.0:20161"
status-addr = "0.0.0.0:20181"

2. 集成测试框架

建议使用go-test结合TiDB的测试工具：

package main
import (
    "database/sql"
    _ "github.com/go-sql-driver/mysql"
    "testing"
)
func TestTiDBConnection(t *testing.T) {
    db, err := sql.Open("mysql", "root:@tcp(127.0.0.1:4000)/test")
    if err != nil {
        t.Fatalf("连接失败: %v", err)
    }
    defer db.Close()
    _, err = db.Exec("CREATE TABLE IF NOT EXISTS test (id INT)")
    if err != nil {
        t.Fatalf("建表失败: %v", err)
    }
}

3. 持续集成方案

推荐在CI/CD流程中加入：

# GitLab CI示例
stages:
  - test
tidb_test:
  stage: test
  image: pingcap/tidb:latest
  script:
    - ./scripts/start_tidb_single.sh
    - go test -v ./...
    - ./scripts/stop_tidb_single.sh

七、总结与最佳实践

单机部署TiDB的核心要点：

1. 资源隔离：使用Docker容器或systemd服务实现进程隔离
2. 配置精简：关闭生产环境特有的高可用参数
3. 监控完备：即使单机环境也应配置基础监控
4. 数据安全：定期备份关键数据
5. 版本管理：记录使用的TiDB版本和配置参数

典型部署架构图：

[客户端] --> [TiDB 4000]
             |
[PD 2379] <--> [TiKV 20160]

通过本文介绍的部署方案，开发者可在30分钟内完成TiDB单机环境的搭建，为后续的集群部署、性能调优和功能开发奠定基础。建议将此环境用于非生产场景，并定期更新到最新稳定版本以获得最佳体验。