backup: adjust concurrency description after v8.2 (pingcap#20231)

Author: 3pointer

br/br-snapshot-guide.md

@@ -28,14 +28,12 @@ aliases: ['/zh/tidb/dev/br-usage-backup/','/zh/tidb/dev/br-usage-restore/','/zh/
 tiup br backup full --pd "${PD_IP}:2379" \
     --backupts '2022-09-08 13:30:00 +08:00' \
     --storage "s3://backup-101/snapshot-202209081330?access-key=${access-key}&secret-access-key=${secret-access-key}" \
-    --ratelimit 128 \
 ```
 
 以上命令中：
 
 - `--backupts`：快照对应的物理时间点，格式可以是 [TSO](/tso.md) 或者时间戳，例如 `400036290571534337` 或者 `2018-05-11 01:42:23 +08:00`。如果该快照的数据被垃圾回收 (GC) 了，那么 `tiup br backup` 命令会报错并退出。使用日期方式备份时，建议同时指定时区，否则 br 默认使用本地时间构造时间戳，可能导致备份时间点错误。如果你没有指定该参数，那么 br 会选取备份开始的时间点所对应的快照。
 - `--storage`：数据备份到的存储地址。快照备份支持以 Amazon S3、Google Cloud Storage、Azure Blob Storage 为备份存储，以上命令以 Amazon S3 为示例。详细存储地址格式请参考[外部存储服务的 URI 格式](/external-storage-uri.md)。
-- `--ratelimit`：**每个 TiKV** 备份数据的速度上限，单位为 MiB/s。
 
 在快照备份过程中，终端会显示备份进度条。在备份完成后，会输出备份耗时、速度、备份数据大小等信息。其中：
 
@@ -247,8 +245,16 @@ TiDB 备份功能对集群性能（事务延迟和 QPS）有一定的影响，
 
 你可以通过如下方案手动控制备份对集群性能带来的影响。但是，这两种方案在减少备份对集群的影响的同时，也会降低备份任务的速度。
 
-- 使用 `--ratelimit` 参数对备份任务进行限速。请注意，这个参数限制的是**把备份文件存储到外部存储**的速度。计算备份文件的大小时，请以备份日志中的 `backup data size(after compressed)` 为准。设置 `--ratelimit` 后，为了避免任务数过多导致限速失效，br 的 `concurrency` 参数会自动调整为 1。
-- 调节 TiKV 配置项 [`backup.num-threads`](/tikv-configuration-file.md#num-threads-1)，限制备份任务使用的工作线程数量。内部测试数据表明，当备份的线程数量不大于 `8`、集群总 CPU 利用率不超过 60% 时，备份任务对集群（无论读写负载）几乎没有影响。
+- 优先推荐: 调节 TiKV 配置项 [`backup.num-threads`](/tikv-configuration-file.md#num-threads-1)，该配置用于限制备份任务使用的工作线程数。由于备份过程属于 CPU 密集型操作，通过控制线程数可以更精确地限制备份对 TiKV 的 CPU 使用，从而实现更可控、更可预测的资源隔离。在绝大多数场景中，仅调整 `num-threads` 就足以控制备份对集群的影响。内部测试表明，当线程数小于或等于 8、且集群总 CPU 利用率小于 60% 时，备份对业务负载的影响可忽略不计。
+
+- 次选方案：如果你已将 `num-threads` 设置为较低值（如 `1`），但仍希望进一步降低备份对集群的影响，此时可以考虑使用 `--ratelimit` 参数。该参数限制的是备份文件写入外部存储的带宽，单位为 MiB/s。实际限速效果取决于压缩后的数据体积。详情请参考日志中的 `backup data size (after compressed)` 字段。启用后，BR 会自动将 `--concurrency` 调整为 `1`，以减少并发请求数量。
+
+> **注意：** 
+>
+> 开启 `--ratelimit` 会进一步降低备份速度。在大多数情况下，如果你在业务低峰期执行备份，并且已经将 `num-threads` 降为 `1`，但仍然担心备份影响业务，通常说明**集群资源已接近瓶颈**。此时，建议考虑以下替代方案：
+>
+> - [扩容 TiKV 节点](/tiup/tiup-cluster.md#扩容节点)以提升可用资源。
+> - 开启日志备份 [`Log Backup`](/br/br-log-architecture.md)，以降低对在线业务的干扰。
 
 通过限制备份的线程数量可以降低备份对集群性能的影响，但是这会影响到备份的性能，以上的多次备份测试结果显示，单 TiKV 存储节点上备份速度和备份线程数量呈正比。在线程数量较少的时候，备份速度约为 20 MiB/线程数。例如，单 TiKV 节点 5 个备份线程可达到 100 MiB/s 的备份速度。
 

br/br-snapshot-manual.md

@@ -36,14 +36,12 @@ tiup br backup full \
     --pd "${PD_IP}:2379" \
     --backupts '2022-09-08 13:30:00 +08:00' \
     --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \
-    --ratelimit 128 \
     --log-file backupfull.log
 ```
 
 以上命令中：
 
 - `--backupts`：快照对应的物理时间点，格式可以是 [TSO](/tso.md) 或者时间戳，例如 `400036290571534337` 或者 `2024-06-28 13:30:00 +08:00`。如果该快照的数据已经被 GC，那么 `tiup br backup` 命令会报错退出；如果没有指定该参数，br 命令行工具会选取备份开始的时间点所对应的快照。
-- `--ratelimit`：**每个 TiKV** 执行备份任务的速度上限（单位 MiB/s）。
 - `--log-file`：备份日志写入的目标文件。
 
 > **注意：**
@@ -72,7 +70,6 @@ tiup br backup db \
     --pd "${PD_IP}:2379" \
     --db test \
     --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \
-    --ratelimit 128 \
     --log-file backuptable.log
 ```
 
@@ -90,7 +87,6 @@ tiup br backup table \
     --db test \
     --table usertable \
     --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \
-    --ratelimit 128 \
     --log-file backuptable.log
 ```
 
@@ -107,7 +103,6 @@ tiup br backup full \
     --pd "${PD_IP}:2379" \
     --filter 'db*.tbl*' \
     --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \
-    --ratelimit 128 \
     --log-file backupfull.log
 ```
 

br/use-br-command-line-tool.md

@@ -57,7 +57,7 @@ tiup br backup full --pd "${PD_IP}:2379" \
 * `--cert`：指定 PEM 格式的 SSL 证书文件路径。
 * `--key`：指定 PEM 格式的 SSL 证书密钥文件路径。
 * `--status-addr`：向 Prometheus 提供统计数据的监听地址。
-* `--concurrency`：备份阶段的任务并发数。
+* `--concurrency`：控制备份阶段如何将任务拆分为多个请求，并以指定的并发数 (Concurrency) 发送到同一个 TiKV 节点。该参数主要影响 BR 发送给 TiKV 的请求拆分粒度，而不再直接决定备份的吞吐性能。通常无需修改默认值，如需提升备份性能，建议通过调整 [`tikv.backup.num-threads`](/tikv-configuration-file.md#num-threads-1) 参数来优化。
 * `--pitr-concurrency`：日志恢复阶段的任务并发数。
 * `--tikv-max-restore-concurrency`：快照恢复阶段的单个 TiKV 节点的任务最大并发数。
 * `--compression`：备份生成文件的压缩算法，支持 `lz4`、`snappy`、`zstd`，默认 `zstd`（多数情况下无须修改）。如何选择不同的压缩算法，可以参考[文档](https://github.com/EighteenZi/rocksdb_wiki/blob/master/Compression.md)。