敏捷模式支持两节点部署

i

警告：

敏捷模式两副本功能从平凯数据库 v7.1.9-0.2 起成为正式功能（GA）。该功能在 v7.1.9-0.1 及更早版本中为实验特性，不建议在生产环境中使用。如果已在生产环境中使用上述非 GA 版本，请及时联系平凯星辰技术支持。

i

注意

当前 even-replicas 仅在敏捷模式下生效；如果仅修改 replication-mode = "even-replicas" 但未按敏捷模式部署，属于未支持用法。

基本概念

阅读本文时，建议先区分以下概念：

• SYNC：集群按双节点同步形态运行。
• ASYNC：集群已经进入单节点接管状态。
• arbiter：自动降级前的仲裁机制，用于判断发生故障后，哪一个节点可以自动接管服务。
• 存活节点：当前仍可对外提供服务的节点。
• 故障节点：当前发生故障、无法继续对外提供服务的节点。

概述

普通的基于 Raft 协议的两节点部署，不能容忍单节点故障，一个节点彻底失联后，另一个节点不能继续安全读写。

even-replicas 解决该场景下的基本思路如下：

• 正常情况下，集群以两个节点运行，状态为 SYNC。
• 当一个节点持续故障超过阈值，且另一个节点通过仲裁后，集群会切换到 ASYNC 状态。
• 集群进入 ASYNC 后，仅存活节点对外提供服务，故障节点不再提供服务。
• 对于已经完成部署的集群，如果启动时仅有一侧可用，PD 会等待 restart-downgrade-timeout，并在仲裁通过后恢复单侧的 PD 控制面；后续降级流程继续将集群恢复到 ASYNC。
• 故障节点恢复后，系统会持续检查恢复情况，持续尝试恢复到 SYNC 状态。

部署与模式选择

了解两节点方案规划，建议先阅读以下文档：

• 两节点的拓扑模版和关键参数，请参考敏捷模式两节点部署拓扑。
• 各个仲裁模式的适用场景、选择建议和脚本仲裁示例，请参考敏捷模式两节点仲裁模式使用场景。

仲裁方式概览

even-replicas 支持三种仲裁方式：

关于各个仲裁模式的使用场景、选择建议，以及 custom-script 的编写逻辑与示例，请参考敏捷模式两节点仲裁模式使用场景。

状态与观测

查看复制模式状态

可通过以下接口查看状态：

curl "http://<pd>/pd/api/v1/replication_mode/status"

SYNC 状态：

{
  "mode": "even-replicas",
  "even-replicas": {
    "state": "SYNC"
  }
}

ASYNC 状态：

{
  "mode": "even-replicas",
  "even-replicas": {
    "state": "ASYNC",
    "available_label": "dc1",
    "replay_progress": 0.42
  }
}

其中：

• available_label 用于表示当前集群在 ASYNC 降级状态下，哪一个节点还在继续提供服务
• replay_progress 用于表示同步恢复进度。

运维手段 force-degrade

接口说明

系统提供一个本地 unsafe 运维 API，可用于对目标存活节点发起强制降级请求：

• POST /pd/api/v1/admin/unsafe/even-replicas/force-degrade

该接口必须直接请求目标 PD 节点，由目标节点本地处理。

i

注意

手动 force-degrade 会跳过仲裁审批，但不会绕过故障判定，也不会绕过 downgrade-timeout。

force-degrade 仅用于故障接管。对侧 PD 和 TiKV 都健康时，请求会被拒绝。计划内缩容请使用 tiup cluster scale-in --even-replicas，不要用 force-degrade 代替。

i

警告：

执行 force-degrade 前，必须确认另一个节点已经永久丢失且无法恢复。如果该节点仍可能恢复，不要执行强制降级；否则两侧可能分别成为降级节点并同时对外提供服务，形成脑裂，进而造成数据不一致或数据损坏。

请求参数

请求体如下：

{
  "target_label": "dc1",
  "timeout": 600
}

说明：

• target_label：必填；必须等于当前收到请求的 PD 节点本地 label。
• timeout：可选；单位为秒；默认 600。

备注：

• 应当将请求直接发送到需要降级的 PD 节点端口。
• 不要依赖随机负载均衡入口。

接口行为

200 OK 仅表示后台降级任务已成功提交，不表示降级或 Region 恢复已经完成。请求返回后，请持续查询复制模式状态，直到状态和可用标签符合预期。

常见返回码

扩容与缩容

even-replicas 支持在不中断整个集群的情况下，将两节点缩容为单节点维护形态，再扩回两节点。请始终通过 TiUP 执行，不要手动修改 placement rule、max-replicas 或 etcd 成员。

操作前检查

1. 执行 tiup cluster display <cluster-name>，确认目标节点 ID 和两侧 TiDBX 的对应关系。
2. 查询复制模式状态。计划缩容前建议确认状态为 SYNC；扩容前必须为单侧 ASYNC。
3. 备份重要数据，并确认保留侧的 PD、TiKV 和 TiDBX 能正常运行。

从两节点缩容为单节点

缩容会删除目标侧整个 TiDBX，包括同侧的 TiDB、PD 和 TiKV 实例及其数据。一次只能缩容一侧。

如果使用 preset 仲裁，不能缩容 primary-label 对应的主侧，只能缩容从侧。使用其他仲裁模式时，也应先明确哪一侧继续提供服务。

如果 preset 模式必须保留原从侧，请先按“配置来源与在线修改限制”中的步骤，把 primary-label 改为保留侧标签并重新加载配置；确认两侧恢复为 Up 且复制模式为 SYNC 后，再缩容原主侧。

执行以下命令，其中 <node-id> 可以是待删除侧的 TiDBX、TiDB、PD 或 TiKV 节点 ID。TiUP 会将其展开为同一侧的完整 TiDBX：

tiup cluster scale-in <cluster-name> -N <node-id> --even-replicas

--even-replicas 不能与 --force 同时使用。确认提示中的集群名和待删除节点后再继续。

TiUP 默认最多等待 600 秒确认单节点控制面目标。需要延长时，可在命令中增加 --transfer-timeout <seconds>。

TiUP 会先让保留侧 PD 把控制面切换为单节点目标，确认成功后才停止并删除目标侧实例、清理数据并更新拓扑。命令成功后：

1. 再次执行 tiup cluster display <cluster-name>，确认只剩保留侧 TiDBX。
2. 查询复制模式状态，确认状态为 ASYNC，且 available_label 是保留侧标签。

如果命令在 PD 已切换为单节点目标后中断，可以使用相同参数重新执行。该流程会识别已经完成的阶段并继续清理。

从单节点扩容回两节点

扩容使用普通 scale-out，不需要也不支持 --even-replicas 参数。新增侧必须同时包含相互绑定的 TiDB、PD 和 TiKV，并满足以下标签要求：

• 新增侧的 PD 和 TiKV 使用相同的隔离标签键和值。
• 新增侧的标签值与保留侧不同。

例如，保留侧标签为 dc1，需要把 10.0.1.2 作为 dc2 扩回集群时，创建 scale-out.yaml：

tidb_servers:
  - host: 10.0.1.2

pd_servers:
  - host: 10.0.1.2
    config:
      labels: { dc: "dc2" }

tikv_servers:
  - host: 10.0.1.2
    config:
      server.labels: { dc: "dc2" }

执行扩容：

tiup cluster scale-out <cluster-name> scale-out.yaml

新侧加入后，PD 会自动完成节点恢复。命令成功后，持续查询复制模式状态，直到状态变为 SYNC；同时执行 tiup cluster display <cluster-name>，确认两侧 TiDBX 均为 Up。

配置来源与在线修改限制

两节点配置以配置文件为准

replication-mode、仲裁方式、两个降级超时，以及 enable-placement-rules、初始 max-replicas 和隔离标签，均以 PD 启动时读取的配置文件为准，不能通过 pd-ctl config set 或 PD 配置 API 在线修改。

执行两节点缩容或扩容时，PD 会自动维护运行时的 placement rule 和节点数。不要手动把拓扑文件中的 max-replicas 改为 1，也不要手动修改 placement rule。

使用 TiUP 管理集群时，应通过以下方式修改 PD 配置：

tiup cluster edit-config <cluster-name>
tiup cluster reload <cluster-name>

reload 会分发配置并重启敏捷模式 TiDBX 服务。不要添加 --skip-restart，否则新配置只会写入文件，当前进程不会生效。

replication-mode、仲裁和超时等 even-replicas 配置必须放在 server_configs.pd 中，保证所有 PD 一致，不能放在单个 pd_servers[].config 中。如果修改隔离标签，还必须同时保证同一 TiDBX 内 PD 与 TiKV 的标签键和值一致，并保证两侧标签值不同。

启动恢复等待时间

even-replicas.restart-downgrade-timeout 控制已部署集群仅启动一侧时，PD 等待对侧恢复的时间。默认值为 1m，且不会小于 downgrade-timeout。设置为 0 会关闭启动恢复；非 0 值不能小于 20s，也不能小于 downgrade-timeout。

placement rule 写操作限制

在 even-replicas 模式下，placement rule 仅支持查询，不支持热更新，以下 placement rule 写接口会直接返回 412 Precondition Failed：

• POST /pd/api/v1/config/rule
• POST /pd/api/v1/config/rules
• POST /pd/api/v1/config/rules/batch
• DELETE /pd/api/v1/config/rule/{group}/{id}
• POST /pd/api/v1/config/rule_group
• DELETE /pd/api/v1/config/rule_group/{id}
• POST /pd/api/v1/config/placement-rule
• POST /pd/api/v1/config/placement-rule/{group}
• DELETE /pd/api/v1/config/placement-rule/{group}

其他在线修改限制

在 even-replicas 模式下，除 placement rule 写操作外，还存在以下在线修改限制：

• /config/replication：不支持在线修改 enable-placement-rules、max-replicas、location-labels、isolation-level。
• /config/replication-mode：不支持在线修改 replication-mode.even-replicas.downgrade-timeout、replication-mode.even-replicas.restart-downgrade-timeout、replication-mode.even-replicas.arbitration 及其所有子字段。
• /config/replication-mode：不支持在运行时把复制模式从 majority / dr-auto-sync 切换到 even-replicas，或从 even-replicas 切回其他模式。