基于物理复制的主备集群容灾

i

注意

物理复制为实验性特性，功能和行为可能在后续版本中调整，请谨慎在生产环境使用。

概述

平凯数据库物理复制用于在多个平凯数据库集群之间建立基于日志的主备复制关系。与逻辑复制相比，物理复制直接复制底层数据，适合主备容灾、主备切换和故障恢复场景。

物理复制支持同城双中心部署，提升集群级高可用能力。该能力支持跨集群同步复制（RPO = 0），也支持异步复制模式以满足异地容灾需求。

核心指标参考（实际以网络、拓扑和负载为准）：

• 故障自动切换时间 (RTO)：< 15 秒
• 演练切换时间 (RTO)：< 30 秒
• 同步复制数据丢失量 (RPO)：0
• 异步复制数据丢失量 (RPO)：< 5 秒
• 写入延迟：同步复制会增加集群的写入延迟，延迟的估计值为“本地落盘时间 + 跨集群网络一次 RTT + 远端落盘时间”。异步复制不会增加写入延迟。

基本概念

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

• primary / standby：表示集群当前的服务角色。
  • primary：可读可写。
  • standby：只读，不接受普通业务写入。
• source / replica：表示一对物理复制集群之间的数据流向。
  • source：上游，负责向下游提供日志和快照。
  • replica：下游，负责接收并应用复制数据。

在最常见的一主一备场景中，primary 通常也是 source，standby 通常也是 replica。但在链式复制拓扑中，一个中间 standby 集群既可以是上游链路的 replica，也可以是下游链路的 source。

使用限制

• 所有参与复制的集群中，最多只能存在一条同步保护模式（MAXIMUM_PROTECTION 或 MAXIMUM_AVAILABILITY）的复制链路，且只能在 primary 与 standby 之间。异步保护模式（MAXIMUM_PERFORMANCE）不受此限制。
• standby 集群必须为空（不能包含用户创建的数据库或表）。
• 复制链路两端的所有 TiKV 节点必须启用相关配置项（见使用前准备）。
• 客户端需能够处理 TiDB 在部分切换步骤中的自动重启，并能完成重连。

使用前准备

在开始前，请确认以下条件均满足：

• 集群的 TiDB、TiKV、PD 已全部升级到支持物理复制的版本。
• standby 集群必须为空（不能包含用户创建的数据库或表）。
• 复制链路两端的所有 TiKV 节点必须启用相关配置项（见下表）。
• replica 集群需要能够连接 source 集群的某个 TiDB SQL 地址。
• 执行 ADMIN CREATE LOG REPLICATION 的当前用户必须拥有 SUPER 权限。
• SOURCE_USER 对应的账号必须在 source 集群中拥有 SUPER 权限和 CONFIG、CONFIG_VIEW 中任一权限。
• 复制链路两端的集群必须能互相访问对方的 PD/TiKV 服务。
• 客户端需能够处理 TiDB 在部分切换步骤中的自动重启，并能完成重连。
• 如果主备集群的 TiDB 内存、TiKV 节点数量或整体资源规格不一致，建议提前阅读物理复制场景下的系统变量检查。
• 在开启 TLS 的集群间创建物理复制链路需要两个集群证书互信，包括集群证书和 TiDB SQL 证书。

下表所列 TiKV 配置项均为必需项，且要求启用。

可通过以下 SQL 检查 TiKV 配置（示例）：

SELECT `instance`, `key`, `value`
FROM information_schema.cluster_config
WHERE `type` = 'tikv'
  AND `key` IN (
    'replicator.enable',
    'raft-engine.enable',
    'raft-engine.enable-log-archive',
    'raft-engine.archive-retention-time',
    'resolved-ts.enable',
    'resolved-ts.advance-ts-interval'
  )
ORDER BY `instance`, `key`;

保护模式

物理复制支持三种保护模式：

DEGRADE_TIMEOUT 定义了 primary 在同步复制下等待 standby ACK 的超时阈值。超过该时间后，系统为保证业务连续性会自动降级为异步。该参数格式为正的 duration 字符串，如 '30s'、'1m'、'2h'，最小为 1s。

当 MAXIMUM_AVAILABILITY 模式发生自动降级后：

• PROTECTION_MODE 仍为 MAXIMUM_AVAILABILITY，但 REPLICATION_MODE 从 SYNC 变为 ASYNC，此时 RPO 不再为 0。
• 可通过 INFORMATION_SCHEMA.LR_STATUS_GLOBAL 的 PROTECTION_MODE 和 REPLICATION_MODE 列分别确认保护模式和当前实际复制模式。
• 自动降级后仍可执行计划内切换（SWITCHOVER），但数据可能存在延迟。
• 当 standby 恢复正常、心跳有效且 checkpoint lag 不超过 PD 配置项 log-replication.sync-switch-max-lag 后，系统会自动将 REPLICATION_MODE 恢复为 SYNC，无需再次执行 ADMIN ALTER LOG REPLICATION。

创建物理复制

语法

ADMIN CREATE LOG REPLICATION <name>
    SOURCE_HOST = '<source_tidb_host>'
    SOURCE_PORT = <source_tidb_port>
    SOURCE_USER = '<source_tidb_user>'
    SOURCE_PASSWORD = '<source_tidb_password>'
    [PROTECTION_MODE = MAXIMUM_PERFORMANCE | MAXIMUM_PROTECTION | MAXIMUM_AVAILABILITY]
    [DEGRADE_TIMEOUT = '<duration>']
    [DETACHED];

参数说明

ADMIN CREATE LOG REPLICATION 必须在将要成为 standby 的集群上执行。

为了避免在创建阶段影响 primary 写入，建议创建时不设置保护模式（使用默认的 MAXIMUM_PERFORMANCE），待初始化完成后再通过 ADMIN ALTER LOG REPLICATION 切换。

若确需设置为 MAXIMUM_AVAILABILITY，必须同时设置 DEGRADE_TIMEOUT。

创建后的行为

创建成功后，目标集群会进入 standby 模式：

• 普通写请求会被禁止。
• 一部分后台任务（如统计信息自动更新）会被阻塞，这些后台任务的功能完全由 primary 日志同步来实现。
• standby 集群的 TiKV 会启动日志复制组件连接上游，上游集群通过 region learner 将数据发送到下游。
• 状态可通过 INFORMATION_SCHEMA.LR_* 系统视图查看。若 INITIALIZING_PROGRESS 停滞，请检查网络连通性及 TiKV replicator 日志。

使用 DETACHED 异步创建

当使用 DETACHED 选项创建时：

1. 语句立即返回，输出结果中包含 WORKFLOW_ID。
2. 后台继续执行初始化流程。
3. 通过以下 SQL 查询工作流执行状态：

SELECT WORKFLOW_ID, WORKFLOW_TYPE, WORKFLOW_STATE, WORKFLOW_STATE_INFO
FROM information_schema.LR_WORKFLOW_HISTORY_GLOBAL
WHERE WORKFLOW_ID = '<returned_workflow_id>';

1. 当 WORKFLOW_STATE 变为 COMPLETED 时，表示初始化完成，可继续后续操作。

修改和管理复制链路

除 CREATE、ACTIVATE STANDBY、SWITCHOVER AS PRIMARY 外，其余管理命令可以在 primary 集群以及复制链路的直接上游/下游集群执行。

修改保护模式

ADMIN ALTER LOG REPLICATION <name>
    PROTECTION_MODE = MAXIMUM_PERFORMANCE | MAXIMUM_PROTECTION | MAXIMUM_AVAILABILITY
    [DEGRADE_TIMEOUT = '<duration>'];

i

注意

DEGRADE_TIMEOUT 仅在 PROTECTION_MODE = MAXIMUM_AVAILABILITY 时生效。设置 PROTECTION_MODE = MAXIMUM_AVAILABILITY 时必须同时指定 DEGRADE_TIMEOUT。

当复制从 ASYNC 切换到 SYNC 时，系统会等待 standby 心跳有效且 checkpoint lag 不超过 PD 配置项 log-replication.sync-switch-max-lag 指定的阈值。默认阈值为 10s。

切换 source

ADMIN ALTER LOG REPLICATION <name> CHANGE SOURCE TO <new_source_cluster_id>;

限制如下：

• 仅支持在当前复制链路为 MAXIMUM_PERFORMANCE 时执行。
• CHANGE SOURCE 与其他 ALTER 选项互斥，不能在同一条语句中同时修改保护模式或降级超时。
• 新 source 不能是当前 source，也不能是 replica 自身。
• 新 source 不能位于当前 replica 的下游子树中（防止形成环）。
• 复制处于 PAUSED 状态时无法执行。

i

提示：

CHANGE SOURCE 主要用于链式复制拓扑调整。执行过程中可能触发 primary 短暂禁写，建议在业务低峰期操作。

重命名复制链路

ADMIN ALTER LOG REPLICATION <name> RENAME TO <new_name>;

新名称不能与旧名称相同，也不能与现有复制链路重名。RENAME 不能与其他 ALTER 选项组合使用。

暂停复制

ADMIN PAUSE LOG REPLICATION <name>;

暂停后：

• standby 停止复制，状态变为 PAUSED。
• 若原本为同步复制，系统会先将同步复制切换为异步复制再进入暂停。

恢复复制

ADMIN RESUME LOG REPLICATION <name>;

恢复后，系统保留暂停前的 PROTECTION_MODE。MAXIMUM_PERFORMANCE 的实际复制模式恢复为 ASYNC，MAXIMUM_PROTECTION 和 MAXIMUM_AVAILABILITY 的实际复制模式恢复为 SYNC。切换到 SYNC 前，系统会检查复制延迟是否满足 PD 配置项 log-replication.sync-switch-max-lag 的要求。

删除复制

ADMIN DROP LOG REPLICATION <name>;

删除后，系统会清理 primary 上的复制状态和相关元数据。若原本为同步复制，系统会先将复制切换为异步复制再执行 DROP，以避免同步复制在缺少 standby ACK 时导致业务阻塞。被 DROP 的集群（旧 standby）仍处于 standby 状态，如需退出 standby 请执行 ADMIN ACTIVATE STANDBY MODE = FLASHBACK。

主备切换

计划内切换（Switchover）

支持从 standby 侧或 primary 侧发起计划内切换。

从 standby 侧发起

在当前 standby 集群执行：

ADMIN SWITCHOVER AS PRIMARY;

此语句将当前 standby 集群提升为 primary，无需指定目标集群 ID。执行此语句时，系统会自动与原 primary 协调完成角色切换。

指定新 primary

执行以下语句将指定的 standby 集群提升为 primary：

ADMIN SWITCHOVER PRIMARY TO <new_primary_cluster_id>;

切换限制与建议

• 仅支持相邻 primary/standby 之间的切换。
• 切换前复制链路不能处于暂停状态。
• 建议先确认目标集群在 INFORMATION_SCHEMA.LR_CLUSTER_STATUS_GLOBAL 中的 SWITCHOVER_READY = 'YES'。
• 切换过程中，系统会自动完成 primary 禁止写入、追平数据和 primary/standby 角色切换。期间 TiDB 节点会自动重启。
• 切换完成后，请更新业务侧的 VIP、DNS 或连接串。建议在业务低峰期操作。
• 切换完成后，建议按物理复制场景下的系统变量检查复核新 primary 上资源相关全局系统变量的值。

计划外切换（Failover）

当确认 primary 集群已断开连接时，在当前 standby 集群执行：

-- 模式一：回退到一致性快照点
ADMIN ACTIVATE STANDBY MODE = FLASHBACK;

-- 模式二：强制提交已接收数据（仅限同步复制，可确保 RPO = 0）
ADMIN ACTIVATE STANDBY MODE = FORCE_COMMIT;

FLASHBACK 模式

将 standby 的数据回退到一个一致性快照点后激活为 primary。适用于：

• 异步复制场景
• 同步复制场景但无法确认原 primary 状态
• 已在原 primary 上执行过 ADMIN DROP LOG REPLICATION

FORCE_COMMIT 模式

强制提交 standby 已接收的所有数据后激活为 primary。使用前必须满足：

• 当前实际复制模式为 SYNC，可通过 INFORMATION_SCHEMA.LR_STATUS_GLOBAL.REPLICATION_MODE 检查。处于 MAXIMUM_AVAILABILITY 保护模式但实际复制模式为 ASYNC 时，不满足此条件。
• 原 primary 尚未执行 ADMIN DROP LOG REPLICATION
• 已确认原 primary 已彻底停机或网络隔离

i

警告：

在执行 ACTIVATE STANDBY 前，必须确认原 primary 已彻底停机或网络隔离，否则可能导致“脑裂”现象，造成不可逆的数据冲突和不一致。若无法确认，应先在原 primary 执行 ADMIN DROP LOG REPLICATION，但此时只能使用 FLASHBACK。

将旧 primary 重新接回（REINSTATE）

在实际复制模式为 SYNC 时完成 ACTIVATE STANDBY（原 standby 已切换为新的 primary）后，如需将原 primary 故障恢复并重新接回新的 primary，可执行 REINSTATE。这适用于 MAXIMUM_PROTECTION，也适用于未降级的 MAXIMUM_AVAILABILITY。旧 primary 故障恢复时可能因缺少 standby ACK 导致 TiDB 无法启动。此操作只能通过 pd-ctl 在旧 primary 集群对应的 PD 上发起。

通过 pd-ctl 在旧 primary 集群对应的 PD 上发起：

pd-ctl -u http://<old-primary-pd-host>:2379 log-replication reinstate <new-primary-id> <new-log-replication-name>

示例：

pd-ctl -u http://127.0.0.1:2379 log-replication reinstate 1024 dr_reinstate

REINSTATE 会把旧 primary 转成新 primary 的 standby，并建立新的复制链路。

primary 启动检查与只读保护

i

注意：该功能默认未启用。需配置 log-replication.primary-start-check-timeout 后才会执行启动检查。

primary 集群的全部 PD 重启时，如果配置了启动检查超时时间，系统会检查直接相连的 standby 的状态。检查超时或 standby 暂时无法访问时，原 primary 会继续提供服务；如果发现直连 standby 已切换 source，系统根据切换前的实际复制模式处理：

• 切换前为 SYNC 时，系统自动尝试将旧 primary 作为 standby 接回新的 primary。
• 切换前为 ASYNC 或模式未知时，旧 primary 自动进入只读保护状态，拒绝写操作以防止数据不一致。

仅切换 PD Leader 不会触发此检查。

解除只读保护

1. 确认复制链路已恢复正常。可通过 INFORMATION_SCHEMA.LR_STATUS_GLOBAL 查看 REPLICATION_STATE 是否为 REPLICATING，以及 REPLICATION_MODE 是否与期望的保护模式一致。
2. 通过 pd-ctl 解除只读保护：

pd-ctl -u http://<pd-host>:2379 log-replication read-only set false

standby 集群的快照读

在 standby 模式下，TiDB 提供快照读（Snapshot Read），其可用时间戳以 CHECKPOINT_TS 为准。

• 实时性：读取的是 standby 集群本地已应用的最新数据，可能落后于 primary。
• 一致性：同一条 SQL 语句内具备一致性快照。
• 快照读延迟：可通过 INFORMATION_SCHEMA.LR_STATUS_GLOBAL 中的 CHECKPOINT_LAG 观察延迟。

查看复制状态

核心状态视图说明

以下 LR_* 为 INFORMATION_SCHEMA 的系统视图（内存表），字段值来自 PD。部分字段在未就绪或不适用时为 NULL。

INFORMATION_SCHEMA.LR_STATUS_GLOBAL

物理复制的全局链路状态，主要字段如下：

当尚未产生 CHECKPOINT_TS 或尚未收到心跳时，CHECKPOINT_* 与 LAST_HEARTBEAT_TIME 为空。

INFORMATION_SCHEMA.LR_CLUSTER_STATUS_GLOBAL

参与复制链路的各集群角色与就绪状态，主要字段如下：

该视图会包含一行 PRIMARY 记录；其余 STANDBY 行对应各条复制链路。

INFORMATION_SCHEMA.LR_WORKFLOW_HISTORY_GLOBAL

物理复制的工作流执行历史，主要字段如下：

WORKFLOW_STATE 用于展示工作流的执行状态；如需进一步排查，可结合 WORKFLOW_STATE_INFO 与时间字段进行判断。

INFORMATION_SCHEMA.LR_STATUS_LOCAL

当前连接集群的本地复制元数据（结构化视图），主要字段如下：

标注为“仅 STANDBY”的字段在 PRIMARY 和 STANDARD 角色的集群上查询时返回 NULL。

示例查询

SELECT REPLICATION_NAME, REPLICATION_STATE, REPLICATION_MODE, PROTECTION_MODE, CHECKPOINT_LAG
FROM information_schema.LR_STATUS_GLOBAL;

输出参考：

REPLICATION_NAME | REPLICATION_STATE | REPLICATION_MODE | PROTECTION_MODE    | CHECKPOINT_LAG
------------------+-------------------+------------------+--------------------+---------------
dr_east          | REPLICATING       | SYNC             | MAXIMUM_PROTECTION | 3

查看集群角色与切换就绪状态：

SELECT CLUSTER_ID, ROLE, SWITCHOVER_READY, FAILOVER_READY
FROM information_schema.LR_CLUSTER_STATUS_GLOBAL;

查看本地复制状态：

SELECT REPLICATION_NAME, REPLICATION_STATE, CHECKPOINT_LAG, INITIALIZING_PROGRESS
FROM information_schema.LR_STATUS_LOCAL;

取消工作流

可以使用工作流 ID 取消尚处于可取消阶段的 ALTER ... CHANGE SOURCE 或 SWITCHOVER 工作流：

ADMIN CANCEL LOG REPLICATION WORKFLOW <workflow_id>;

只有上述两类工作流支持取消，且工作流必须仍处于可取消的内部状态。取消请求成功后，WORKFLOW_STATE 先变为 CANCELLING，取消完成后变为 CANCELLED。详情参见 ADMIN CANCEL LOG REPLICATION WORKFLOW。

监控

Grafana 提供 Log-Replication Dashboard。你可以使用该 Dashboard 查看集群角色、物理复制状态、复制延迟、工作流耗时和 TiKV 复制指标。

典型运维路径

1. 检查配置：部署 primary/standby 集群并验证 TiKV 配置。
2. 建立链路：在 standby 集群执行 ADMIN CREATE LOG REPLICATION。
3. 观察初始化：通过 INFORMATION_SCHEMA.LR_STATUS_GLOBAL 确认 INITIALIZING_PROGRESS 达到 100%。
4. 调整保护模式：初始化完成后，按需切换到 MAXIMUM_PROTECTION 或 MAXIMUM_AVAILABILITY。
5. 日常管理：按需执行暂停、恢复、切换 source 或修改保护模式。
6. 故障处理：根据故障类型选择计划内切换或计划外激活。
7. 接回旧主：旧 primary 恢复后，按需执行 REINSTATE 将其接回链路。
8. 清理链路：执行 ADMIN DROP LOG REPLICATION 清理状态，并使用 ADMIN ACTIVATE STANDBY MODE = FLASHBACK 让集群退出 standby 状态。

相关配置参考

TiKV 配置

以下配置项与物理复制相关，除标记为必需的配置外，其余为可选调优项。

必需配置

replicator 可选配置

replicator server 配置

replicator 内部 raftstore 配置

resolved-ts 可选配置

PD 配置

learner 数量配置值不应超过 replica 集群的 TiKV 节点数量。创建物理复制时，如果可用节点尚未就绪，系统会等待配置数量的节点；节点已就绪时，实际 learner 数量取配置值与可用节点数两者中的较小值。修改以上配置项后，需要重启 PD。新配置不会立即更改现有复制；修改保护模式或执行 REINSTATE 时，新配置才会生效。