TiDB v8.5.5 配置文件详解

目标：全面解读 TiDB v8.5.5 部署相关的四类配置——拓扑文件 topology.yaml（集群定义，唯一事实来源）、pd.toml（PD 元数据/调度）、tikv.toml（数据引擎）、tidb.toml（SQL 层）。文中 .toml 均取自本环境三节点集群 tidb-node1 上 TiUP 实际生成并经 SHOW CONFIG 验证的文件，参数说明对照官方 config.toml.example 与运行时默认值。Compose 单机部署以命令行参数替代配置文件，文中以映射表对照说明。本文档纯服务视角，假定环境为 Ubuntu 22.04 虚拟机节点（非物理服务器），因此给出虚拟化资源裁剪建议；物理机大内存场景可适当放大。

重要前置说明：本环境为虚拟机节点，非物理服务器

请务必知悉：配置梳理基于 虚拟机节点（非物理服务器） 环境，因此下述多数参数为虚拟化资源的显式裁剪，包括通过 resource_control/systemd CPUQuota、MemoryLimit 限定进程资源，以及 TiKV 的 block-cache.capacity、线程池、后台任务等。生产物理机若 CPU 核数与内存充足，这些裁剪值应相应放大，避免人为造成性能瓶颈。各节均会标注「虚拟化裁剪」与「物理机建议 / 默认值」的差异。

一、配置体系总览

注意：TiUP 生成的 .toml 文件头标注 "auto-generated, Do not edit"，直接改会被覆盖。正确做法是在 topology.yaml 的 server_configs 或组件段补参数，再执行 tiup cluster reload。本文档给出的 .yaml 写法即 topology.yaml 内的 server_configs.* 段（本环境实际使用此写法），与独立的 .toml 文件一一对应。

二、topology.yaml 详解

本环境 /root/topology.yaml 实际内容（含 server_configs）：

global:
  user: "root"
  ssh_port: 22
  deploy_dir: /opt/data/tidb/deploy
  data_dir: /opt/data/tidb/data
  log_dir: /opt/data/tidb/log
  os: "linux"
  arch: "amd64"
  resource_control:
    cpu_quota: 2
    memory_limit: "7g"

server_configs:
  pd:
    log.level: "info"
    replication.max-replicas: 3
    schedule.max-snapshot-count: 4
  tikv:
    log.level: "info"
    server.grpc-concurrency: 2
    raftstore.apply-pool-size: 2
    raftstore.store-pool-size: 2
    storage.block-cache.capacity: "1GB"
    rocksdb.max-background-jobs: 4
    raftdb.max-background-jobs: 2
  tidb:
    log.level: "warn"
    performance.max-procs: 2

pd_servers:
  - host: tidb-node1
  - host: tidb-node2
  - host: tidb-node3

tidb_servers:
  - host: tidb-node1
  - host: tidb-node2
  - host: tidb-node3

tikv_servers:
  - host: tidb-node1
  - host: tidb-node2
  - host: tidb-node3

说明：本环境将组件参数写在 server_configs 段（TiUP 据此生成 .toml）。也可写在 global.server_configs 或在对应组件段下逐组件覆盖。下文讲述的 pd.toml/tikv.toml/tidb.toml 均由上表生成。

2.1 global 段

虚拟机裁剪：resource_control 让 TiUP 生成的 systemd 单元带 CPUQuota=/MemoryLimit=，从进程级严格限制资源，避免同机 PD/TiKV/TiDB 互相争抢。

2.2 组件段

2.3 组件级可配项（TiUP 写入对应 .toml）

见第三、四、五节；server_configs.pd/tikv/tidb 下的键即对应 .toml 的同名段/键，故下文以 .toml 形式讲解，其等价 yaml 写法为 server_configs.<组件>.<段>.<键> = 值。

三、pd.toml 详解（Placement Driver）

本环境实际生成文件（TiUP 由 server_configs.pd 生成）：

[log]
level = "info"

[replication]
max-replicas = 3

[schedule]
max-snapshot-count = 4

3.1 [log] 日志

3.2 [replication] 副本/标签

3.3 [schedule] 调度

3.4 [pd-server]/[security]/[dashboard]/[quota]

3.5 [raftstore]（PD 内嵌的 Raft 相关）

四、tikv.toml 详解（数据引擎）

本环境实际生成文件：

[log]
level = "info"

[raftdb]
max-background-jobs = 2

[raftstore]
apply-pool-size = 2
store-pool-size = 2

[rocksdb]
max-background-jobs = 4

[server]
grpc-concurrency = 2

[storage]
[storage.block-cache]
capacity = "1GB"

4.1 顶层与 [server]

4.2 [storage] 与 [storage.block-cache]

block-cache.capacity 实测经 SHOW CONFIG 无独立输出（本环境 1GB 生效）。物理机建议为总内存 30-40%，避免与 TiDB/PD 竞争。

4.3 [raftstore]

4.4 [rocksdb]（KV 引擎）与 [raftdb]

4.5 [readpool]/[coprocessor]/[pessimistic-txn]

五、tidb.toml 详解（SQL 层）

本环境实际生成文件：

[log]
level = "warn"

[performance]
max-procs = 2

5.1 [log]

5.2 [performance]

5.3 常用补充项（写 server_configs.tidb 或运行时变量）

内存类变量（tidb_mem_quota_query 等）可用 SET SESSION/GLOBAL 在线调整，无需改配置文件；见《命令与运维指南》。

六、Compose 单机：配置以命令行参数承载

Compose 部署无 .toml，等价项通过 command: 传参。映射关系：

Compose 架构为 1 PD + 3 TiKV 的"小集群"，PD 单点、副本默认 3。生产追求 PD 高可用请用三节点 topology 部署。

七、修改配置的正确流程

# 1. 编辑集群配置（写入 server_configs 或组件段）
tiup cluster edit-config tidb-prod

# 2. 重新部署使配置生效（滚动，可限定组件/实例）
tiup cluster reload tidb-prod
tiup cluster reload tidb-prod -R tikv        # 只重载 tikv
tiup cluster reload tidb-prod -N tidb-node1:2379

# 3. 确认生效
tiup cluster display tidb-prod
# 或直接查看目标文件 / 运行时配置
cat /opt/data/tidb/deploy/tikv-20160/conf/tikv.toml
mysql -h127.0.0.1 -P4000 -u root -e "SHOW CONFIG WHERE Name='performance.txn-total-size-limit';"

Compose 则：改 docker-compose.yml → docker compose up -d（自动重建变更服务）。

八、调优速查（虚拟机 vs 物理机）