TiKV 节点安全停机维护指南

TiKV 节点安全停机维护指南

本文基于 v7.5.0 的 TiDB 集群。

你完全可以相信 TiDB 的可靠性，直接停机并不会带来数据丢失，但是你如果想尽量降低节点下线带来的影响的话可以参考本文

---

第一步：准备阶段

在进行停机维护前，需要进行一系列检查和预配置，确保集群稳定并为节点下线做好准备。

1. 检查集群健康状态

确认当前集群整体稳定，并且在停下一个节点后，剩余节点数仍能满足 Raft 协议的多数派要求。

# 检查集群健康状态
tiup cluster display tidb-prod

2. 临时放宽 Store 下线阈值

估算维护所需的时间，并临时调大 max-store-down-time 参数，以避免 PD 因节点长时间离线而触发报警或自动的数据迁移。

# 该示例设置为两小时，请根据实际维护时间调整
tiup ctl:v7.5.0 pd config set max-store-down-time 2h

3. 获取目标节点的 store_id

查询集群中所有 Store (TiKV 节点) 的列表，找到并记录下需要停机维护的节点的 store_id。

# 查询所有 store 列表
tiup ctl:v7.5.0 pd store

一个节点的输出信息可能如下所示：

{
  "store": {
    "id": 3,                                      // 【重点】store_id，TiKV 节点唯一标识
    "address": "10.198.xx.xx:20160",            // 节点对外服务地址
    "version": "7.5.0",                          // TiKV 版本
    "peer_address": "10.198.xx.xx:20160",       // 节点对等通信地址
    "status_address": "10.198.xx.xx:20180",     // 状态监控接口地址
    "git_hash": "bd8a0aabd08fd77687f788e0b45858ccd3516e4d", // 编译版本哈希
    "start_timestamp": 1716591840,               // 启动时间戳（秒级）
    "deploy_path": "/tidb-deploy/tikv-20160/bin", // 部署路径
    "last_heartbeat": 1751621812406653681,       // 最近心跳（纳秒时间戳）
    "state_name": "Up"                           // 节点状态，"Up"表示正常运行
  },
  "status": {
    "capacity": "491.1GiB",                      // 总容量
    "available": "397.4GiB",                     // 可用容量
    "used_size": "46.2GiB",                      // 已用容量
    "leader_count": 684,                          // 【重点】 当前该节点管理的 Region Leader 数
    "leader_weight": 1,                           // 【重点】 Leader 调度权重，默认1
    "leader_score": 684,                          // Leader 评分，衡量负载
    "leader_size": 42955,                         // Leader 关联的 Region 数量
    "region_count": 2060,                         // 节点持有的 Region 副本总数
    "region_weight": 1,                           // Region 调度权重
    "region_score": 213709.94318930135,           // Region 评分
    "region_size": 128738,                         // Region 相关的数量指标（如数据量等）
    "slow_score": 1,                              // 慢查询评分，数字越大越慢
    "slow_trend": {                               // 慢查询趋势相关指标
      "cause_value": 251076.98333333334,
      "cause_rate": 0,
      "result_value": 1303.5,
      "result_rate": 0
    },
    "start_ts": "2024-05-25T07:04:00+08:00",    // 节点启动时间（人类可读）
    "last_heartbeat_ts": "2025-07-04T17:36:52.406653681+08:00", // 最近心跳时间（人类可读）
    "uptime": "9730h32m52.406653681s"             // 运行时长
  }
}

第二步：执行迁移与停机

在准备工作完成后，开始将 Leader 迁离目标节点并执行维护。

1. 驱逐 Leader

假设需要操作的节点 store_id 为 3。通过将该节点的 Leader 权重设置为 0，来主动将 Leader 副本从该节点上迁移走，从而实现平滑下线。

# 将 store_id=3 的节点 leader_weight 设置为 0，region_weight 保持为 1
tiup ctl:v7.5.0 pd store weight 3 0 1
# 3 0 1 分别代表 store_id leader_weight region_weight

2. 确认 Leader 迁移状态

持续观察目标节点的状态，等待其 leader_count 指标降低至接近 0（它不会完全降低到零，待其个数只有一位或者两位数且不再下降即可）。

# 确认权重是否正确修改，并监控 leader_count 的变化
tiup ctl:v7.5.0 pd store 3

3. 执行维护操作

在 leader_count 降至安全水平后，即可开始进行实际的维护工作。

【可选】在停机之前，你可以选择备份一份数据库，如果你没有备份脚本的话可以搜索我文章中的 tidb 备份

第三步：恢复阶段

维护工作完成后，需要将节点恢复至正常工作状态，并还原集群配置。

1. 恢复节点 Leader 权重

在 TiKV 节点重启并恢复健康状态后，将其 Leader 权重恢复为默认值 1，使其能重新接收 Leader 调度。

# 假设节点已健康，恢复其 leader 权重和 region 权重
tiup ctl:v7.5.0 pd store weight 3 1 1

2. 恢复 Store 下线阈值

将 max-store-down-time 参数恢复为业务的默认值（例如 30 分钟），以确保集群的故障自愈能力处于正常水平。

# 恢复 max-store-down-time 到默认值
tiup ctl:v7.5.0 pd config set max-store-down-time 30m