使用 BR 进行日志备份与恢复
通过使用 br log 命令，你可以对 TiDB 集群进行日志备份。本文档介绍 br log 命令的使用方法。
前置条件
安装 BR
使用日志备份前，你需要安装 BR。你可以选择以下任一方式安装 BR：
启用日志备份
使用日志备份功能前，需将 TiKV 配置项 log-backup.enable 设为 true。修改配置参数的方法，请参考修改配置参数。
使用日志备份
你可以使用 br log 命令来备份日志，通过该命令的子命令，你可以完成如下操作：
- 启动日志备份
- 查询备份状态
- 暂停和重启备份
- 停止备份任务并删除备份数据
- 清理备份数据
- 查看元信息
本章节将介绍 br log 的子命令，并以示例介绍如何完成以上操作。
br log 子命令
执行如下命令，可获取 br log 的命令帮助信息：
./br log --help
backup stream log from TiDB/TiKV cluster
Usage:
br log [command]
Available Commands:
metadata get the metadata of log dir
pause pause a log backup task.
resume resume a log backup task
start start a log backup task
status get status for the log backup task
stop stop a log backup task
truncate truncate the log data until sometime
各个子命令的作用如下：
br log start：启动一个日志备份任务br log status：查询日志备份任务状态br log pause：暂停日志备份任务br log resume：重启暂停的备份任务br log stop：停止备份任务，并删除任务元信息br log truncate：从备份存储中清理日志备份数据br log metadata：查询备份存储中备份数据的元信息
启动日志备份任务
执行 br log start 命令，你可以在备份集群启动一个日志备份任务。该任务在 TiDB 集群持续地运行，及时地将 KV 变更日志保存到备份存储中。
运行 br log start --help 可获取该子命令使用介绍：
./br log start --help
start a log backup task
Usage:
br log start [flags]
Flags:
-h, --help help for start
--start-ts string usually equals last full backupTS, used for backup log. Default value is current ts. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'.
--task-name string The task name for the backup log task.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
以上命令行示例只展示了常用的参数，这些参数作用如下：
task-name：指定日志备份任务名。该名称也用于查询备份状态、暂停、重启和恢复备份任务等操作。--start-ts：指定开始备份日志的起始时间点。如果未指定，备份程序选取当前时间作为 start-ts。--pd：指定备份集群的 PD 访问地址。BR 需要访问 PD 发起日志备份任务。ca,cert,key：指定使用 mTLS 加密方式与 TiKV 和 PD 进行通讯。--storage：指定备份存储地址。日志备份暂时只支持共享的文件系统和 Amazon S3 作为备份存储，详细介绍请参考 AWS S3 storage。
使用示例：
./br log start --task-name=pitr --pd=172.16.102.95:2379 --storage='s3://tidb-pitr-bucket/backup-data/log-backup'
查询日志备份任务
执行 br log status 命令，你可以查询日志备份任务状态。
运行 br log status –-help 可获取该子命令使用介绍：
./br log status --help
get status for the log backup task
Usage:
br log status [flags]
Flags:
-h, --help help for status
--json Print JSON as the output.
--task-name string The task name for backup stream log. If default, get status of all of tasks (default "*")
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
以上示例中， task-name 为常用参数，它用来指定日志备份任务名。默认值为 *，即显示全部任务。
使用示例：
./br log status --task-name=pitr --pd=172.16.102.95:2379
命令输出如下：
● Total 1 Tasks.
> #1 <
name: pitr
status: ● NORMAL
start: 2022-07-14 20:08:03.268 +0800
end: 2090-11-18 22:07:45.624 +0800
storage: s3://tmp/store-by-storeid/log1
speed(est.): 0.82 ops/s
checkpoint[global]: 2022-07-25 22:52:15.518 +0800; gap=2m52s
命令输出中的字段含义如下：
status：任务状态，包括 NORMAL（正常）、ERROR（异常）和 PAUSE（暂停）三种状态。start：日志备份任务开始的时间，该值为备份任务启动时候指定的 start-ts。storage：备份存储。speed：日志备份任务的总 QPS（每秒备份的日志个数）。checkpoint [global]：集群中早于该 checkpoint 的数据都已经保存到备份存储，它也是备份数据可恢复的最近时间点。error [store]：存储节点上的日志备份组件运行遇到的异常。
暂停和重启日志备份任务
执行 br log pause 命令，你可以暂停正在运行中的日志备份任务。
运行 br log pause –help 可获取该子命令使用介绍：
./br log pause --help
pause a log backup task
Usage:
br log pause [flags]
Flags:
--gc-ttl int the TTL (in seconds) that PD holds for BR's GC safepoint (default 86400)
-h, --help help for status
--task-name string The task name for backup stream log.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
使用示例：
./br log pause --task-name=pitr --pd=172.16.102.95:2379
执行 br log resume 命令，你可以恢复被暂停的日志备份任务。
运行 br log resume --help 可获取该子命令使用介绍：
./br log resume --help
resume a log backup task
Usage:
br log resume [flags]
Flags:
-h, --help help for status
--task-name string The task name for backup stream log.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
暂停日志备份任务超过了 24 小时后，执行 br log resume 会报错，提示备份数据丢失。处理方法请参考恢复日志备份任务失败。
使用示例：
./br log resume --task-name=pitr --pd=172.16.102.95:2379
（永久）停止日志备份任务
执行 br log stop 命令，你可以永久地停止日志备份任务，该命令会清理备份集群中的任务元信息。
运行 br log stop --help 可获取该子命令使用介绍：
./br log stop --help
stop a log backup task
Usage:
br log stop [flags]
Flags:
-h, --help help for status
--task-name string The task name for the backup log task.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
使用示例：
./br log stop --task-name=pitr --pd=172.16.102.95:2379
清理日志备份数据
执行 br log truncate 命令，你可以从备份存储中删除过期或不再需要的备份日志数据。
运行 br log truncate --help 可获取该子命令使用介绍：
./br log truncate --help
truncate the incremental log until sometime.
Usage:
br log truncate [flags]
Flags:
--dry-run Run the command but don't really delete the files.
-h, --help help for truncate
--until string Remove all backup data until this TS.(support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'.)
-y, --yes Skip all prompts and always execute the command.
Global Flags:
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
该命令只需要访问备份存储，不需要访问备份集群。此外，常用的参数如下：
--dry-run：运行命令，但是不删除文件。--until：早于该参数指定时间点的日志备份数据会被删除。建议使用快照备份的时间点作为该参数值。--storage：指定备份存储地址。日志备份暂时只支持共享的文件系统和 Amazon S3 作为备份存储，详细介绍请参考 AWS S3 storage。
使用示例：
./br log truncate --until='2022-07-26 21:20:00+0800' –-storage='s3://tidb-pitr-bucket/backup-data/log-backup'
该子命令运行后输出以下信息：
Reading Metadata... DONE; take = 277.911599ms
We are going to remove 9 files, until 2022-07-26 21:20:00.0000.
Sure? (y/N) y
Clearing data files... DONE; take = 43.504161ms, kv-count = 53, kv-size = 4573(4.573kB)
Removing metadata... DONE; take = 24.038962ms
查看备份数据元信息
执行 br log metadata 命令，你可以查看备份存储中保存的日志备份的元信息，例如最早和最近的可恢复时间点。
运行 br log metadata –-help 可获取该子命令使用介绍：
./br log metadata --help
get the metadata of log backup storage
Usage:
br log metadata [flags]
Flags:
-h, --help help for metadata
Global Flags:
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
该命令只需要访问备份存储，不需要访问备份集群。
以上示例中，--storage 为常用参数，它用来指定备份存储地址。日志备份暂时只支持共享的文件系统和 Amazon S3 作为备份存储，使用 S3 作为 storage 的详细介绍请参考 AWS S3 storage。
使用示例：
./br log metadata –-storage='s3://tidb-pitr-bucket/backup-data/log-backup'
该子命令运行后输出以下信息：
[2022/07/25 23:02:57.236 +08:00] [INFO] [collector.go:69] ["log metadata"] [log-min-ts=434582449885806593] [log-min-date="2022-07-14 20:08:03.268 +0800"] [log-max-ts=434834300106964993] [log-max-date="2022-07-25 23:00:15.618 +0800"]
恢复日志备份数据
执行 br restore point 命令，你可以在新集群上进行 PiTR ，或者只恢复日志备份数据。
运行 br restore point --help 可获取该命令使用介绍：
./br restore point --help
restore data from log until specify commit timestamp
Usage:
br restore point [flags]
Flags:
--full-backup-storage string specify the backup full storage. fill it if want restore full backup before restore log.
-h, --help help for point
--restored-ts string the point of restore, used for log restore. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'
--start-ts string the start timestamp which log restore from. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
以上示例只展示了常用的参数，这些参数作用如下：
--full-backup-storage：指定快照（全量）备份的存储地址。如果你要使用 PiTR，需要指定该参数，并选择恢复时间点之前最近的快照备份；如果只恢复日志备份数据，则不需要指定该参数。如需使用 Amazon S3 作为存储地址，请参考 AWS S3 storage。--restored-ts：指定恢复到的时间点。如果没有指定该参数，则恢复到日志备份数据最后的可恢复时间点（备份数据的 checkpoint）。--start-ts：指定日志备份恢复的起始时间点。如果你只恢复日志备份数据，不恢复快照备份，需要指定这个参数。--pd：指定恢复集群的 PD 访问地址。ca,cert,key：指定使用 mTLS 加密方式与 TiKV 和 PD 进行通讯。--storage：指定日志备份的存储地址。日志备份暂时只支持 Amazon S3 作为备份存储，使用 S3 作为 storage 详细介绍请参考 AWS S3 storage。
使用示例：
./br restore point --pd=172.16.102.95:2379
--storage='s3://tidb-pitr-bucket/backup-data/log-backup'
--full-backup-storage='s3://tidb-pitr-bucket/backup-data/snapshot-20220512000000'
Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00%
[2022/07/19 18:15:39.132 +08:00] [INFO] [collector.go:69] ["Full Restore success summary"] [total-ranges=12] [ranges-succeed=12] [ranges-failed=0] [split-region=546.663µs] [restore-ranges=3] [total-take=3.112928252s] [restore-data-size(after-compressed)=5.056kB] [Size=5056] [BackupTS=434693927394607136] [total-kv=4] [total-kv-size=290B] [average-speed=93.16B/s]
Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00%
Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00%
[2022/07/19 18:15:39.325 +08:00] [INFO] [collector.go:69] ["restore log success summary"] [total-take=192.955533ms] [restore-from=434693681289625602] [restore-to=434693753549881345] [total-kv-count=33] [total-size=21551]