br: backup checkpoint (#12075)

TOC.md

@@ -150,6 +150,7 @@
       - BR 特性
         - [自动调节](/br/br-auto-tune.md)
         - [批量建表](/br/br-batch-create-table.md)
+        - [断点备份](/br/br-checkpoint.md)
       - [使用 Dumpling 和 TiDB Lightning 备份与恢复](/backup-and-restore-using-dumpling-lightning.md)
       - [备份与恢复 RawKV](/br/rawkv-backup-and-restore.md)
       - [增量备份与恢复](/br/br-incremental-guide.md)

br/br-checkpoint.md

@@ -0,0 +1,52 @@
+---
+title: 断点备份
+summary: 了解断点备份功能，包括它的使用场景、使用方法以及实现原理。
+---
+
+# 断点备份
+
+快照备份会因为一些可恢复性错误导致提前结束，例如硬盘空间占满、节点宕机等等一些突发情况。在 TiDB v6.5.0 之前，在错误被处理之后，之前备份的数据会作废，你需要重新进行备份。对大规模集群来说，会造成大量额外成本。
+
+为了尽可能继续上一次的备份，从 TiDB v6.5.0 起，备份恢复特性引入了断点备份的功能，此功能默认开启。开启该功能后，备份在意外退出后可以保留上一次备份的大部分进度。
+
+## 使用场景
+
+如果你的 TiDB 集群规模很大，无法接受备份失败后需要重新备份的情况，那么，你可以开启断点备份功能。开启该功能后，br 工具会定期记录已备份的分片，使得在下一次重试备份时回到离上一次退出时较近的进度。
+
+## 使用限制
+
+断点备份功能依赖于 GC 机制，且无法恢复所有已备份的数据，具体描述如下。
+
+### 确保在 GC 前重试
+
+在备份过程中，br 命令行工具会定期向 PD 更新备份 snapshot 的 `gc-safepoint`，从而避免在备份过程中数据被 GC。当 br 工具退出后，PD 中备份 snapshot 的 `gc-safepoint` 将无法及时更新。因此，在下一次重试备份前，数据有可能已经被 GC。
+
+为了避免数据被 GC，当 br 工具没有指定具体的 `gcttl` 时，br 工具在默认情况下会让 `gc-safepoint` 保留大约 1 小时。如果你需要延长这个时间，可以设置参数 `gcttl`。
+
+例如，设置 `gcttl` 为 15 小时（54000 秒）来延长 `gc-safepoint` 的保留时间：
+
+```shell
+br backup full \
+--storage local:///br_data/ --pd "${PD_IP}:2379" \
+--gcttl 54000
+```
+
+> **注意：**
+>
+> 快照备份结束后会将备份前创建的 `gc-safepoint` 删除，不需要手动删除。
+
+### 部分数据需要重新备份
+
+在重试备份时，部分已备份的数据可能需要重新备份，包括正在备份的数据和还未被断点记录的数据。
+
+- 由错误引起的退出，br 工具会在退出前将已备份的数据元信息持久化到外部存储中，因此只有正在备份的数据需要在下一次重试中重新备份。
+
+- 如果 br 工具进程被系统中断，那么 br 将无法把已备份的数据元信息持久化到外部存储中。br 工具持久化已备份的数据元信息的周期为 30 秒，因此大约最近 30 秒内的已完成备份的数据无法持久化到外部存储，在下次重试时需要重新备份。
+
+## 实现原理
+
+在快照备份过程中，br 工具将表编码成对应的键空间，并生成备份的 RPC 请求发送给所有 TiKV 节点。接收到备份请求后，TiKV 节点会选择请求范围内的数据进行备份。每当 TiKV 节点备份完一个 `region` 级别的数据，就会返回给 br 工具这段范围相关的备份信息。
+
+通过记录这些返回的备份信息，br 工具能够及时获知已备份完成的键范围。断点备份功能会定期将这些新增的相关备份信息上传至外部存储中，从而持久化存储该备份任务已完成的键范围。
+
+在重试备份时，br 工具会从外部存储读取已经备份的键范围，再与所需备份的键范围做比较，获得一个差集，从而得出断点备份还需要备份的键范围。