From 628ce7859679a6955171e3ef32cbb0eda43b7c65 Mon Sep 17 00:00:00 2001
From: guoningshen <guoningshen@xiaomi.com>
Date: Thu, 5 Jun 2025 15:42:35 +0800
Subject: [PATCH] update cold-backup.md in chinese

---
 _docs/zh/administration/cold-backup.md | 85 +++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 10 deletions(-)

diff --git a/_docs/zh/administration/cold-backup.md b/_docs/zh/administration/cold-backup.md
index a79b3891..b19b9938 100755
--- a/_docs/zh/administration/cold-backup.md
+++ b/_docs/zh/administration/cold-backup.md
@@ -4,30 +4,42 @@ permalink: administration/cold-backup
 
 ## 介绍
 
-Pegasus 的冷备份功能用来将 Pegasus 中的数据定期生成快照文件，并备份到其他存储介质上，从而为数据容灾多提供一层保障。但由于备份的是某个时间点的数据快照文件，所以冷备份并不保证可以保留所有最新的数据，也就是说，恢复的时候可能会丢失最近一段时间的数据。
+Pegasus 的冷备份功能用来将 Pegasus 中的数据定期生成快照文件，并备份到其他存储介质上，从而为数据容灾多提供一层保障。但由于备份的是某个时间点的数据快照文件，所以冷备份只能保证某个时间点之前写入的数据，也就是说，恢复的时候可能会丢失最近一段时间新写入的数据。
 
 冷备份功能主要涉及下列参数：
 
 * 存储介质（backup_provider)：指其他的文件存储系统或服务，如本地文件系统或者 HDFS。
 * 数据冷备份的周期（backup_interval)：周期的长短决定了备份数据的覆盖范围。如果周期是 1 个月，那么恢复数据时，就可能只恢复一个月之前的数据。但如果周期设的太短，备份就会太频繁，从而使得备份开销很大。在小米内部，冷备份的周期通常是 1 天。
-* 保留的冷备份个数（backup_history_count)：保留的备份个数越多，存储的空间开销就越大。在小米内部，一般保留最近的 3 个冷备份。
-* 进行冷备份的表的集合（backup_app_ids)：并不是所有的表都值得进行冷备份。在小米内部，对于经常重灌全量数据的表，我们是不进行冷备份的。
+* 保留的冷备份个数（backup_history_count)：保留的备份个数越多，存储的空间开销就越大。在工程实践中，一般保留最近的 3 个冷备份。
+* 进行冷备份的表的集合（backup_app_ids)：并不是所有的表都值得进行冷备份。在工程实践中，对于经常重灌全量数据的表，我们是不进行冷备份的。
 
 在 Pegasus 中，以上这几个参数的组合称为一个冷备份策略（backup_policy)。数据的冷备份就行按照 policy 为单位进行的。
 
 ## 存储介质
 
-目前 Pegasus 支持本地文件系统和 FDS 两种冷备份介质。如果需要支持更多的存储介质（如 S3)，请联系我们或者直接把 pull request 砸过来。
+目前 Pegasus 支持本地文件系统和 HDFS 两种冷备份介质。在2.5及之前的版本还支持FDS，但由于仅对小米的生态链业务开放，该特性在2.5后的社区版本被移除。此外，如果需要支持更多的存储介质（如 S3)，请联系我们或者直接把 pull request 砸过来。
+
+我们接下来会以本地文件系统为例，介绍冷备的创建和恢复的相关操作。然后，我们会介绍如何用 fuse 的方式将 HDFS 挂载到本地目录下。
 
-### FDS
 
-FDS 是小米生态云提供的存储产品，目前仅面向小米的生态链业务开放。更多详细的介绍 [请戳这里](https://cnbj6.cloud.mi.com/#/index/product/fds?_k=rq2znr)。
 
 ### 本地文件系统
 
-通过使用 Pegasus 本地文件系统（local service）的备份接口，可以把 Pegasus 的数据备份到某个目录下。如果第三方存储介质支持以 nfs 或者 Linux Fuse 的方式挂载到本地某个目录下的话，该介质就可以通过 local service 来作为 pegasus 的备份介质。目前 HDFS 就是通过 fuse 的方式来支持的。
+通过使用 Pegasus 本地文件系统（local service）的备份接口，可以把 Pegasus 的数据备份到某个目录下。
+
+
+
+### HDFS
+
+如果第三方存储介质支持以 nfs 或者 Linux Fuse 的方式挂载到本地某个目录下的话，该介质就可以通过 local service 来作为 pegasus 的备份介质。HDFS 就是通过 fuse 的方式来支持的。
+
+
+
+### FDS
+
+FDS 是小米生态云提供的存储产品，目前仅面向小米的生态链业务开放，故不做过多介绍。更多详细的介绍 [请戳这里](https://cnbj6.cloud.mi.com/#/index/product/fds?_k=rq2znr)。
+
 
-我们接下来会以本地文件系统为例，介绍冷备的创建和恢复的相关操作。然后，我们会介绍如何用 fuse 的方式将 HDFS 挂载到本地目录下。
 
 ## 怎样开始冷备份
 
@@ -69,7 +81,7 @@ FDS 是小米生态云提供的存储产品，目前仅面向小米的生态链
 
 在上面的配置中，一定要区分清楚 [replication].cold_backup_root 和 [block_service.my_backup_media].args 所配置的两个路径：
 * 前者指定了数据在某种存储介质下的存放目录。
-* 后者是存储介质本身的初始化参数，是和 type 相关的。对于 local_service 而言，这个参数是一个绝对路径。换种说法，** 本地文件系统的某个目录 **，就是一种存储介质。
+* 后者是存储介质本身的初始化参数，是和 type 相关的。对于 local_service 而言，这个参数是一个绝对路径。换种说法，**本地文件系统的某个目录**，就是一种存储介质。
 * 对于当前的配置情况而言，冷备数据会保存到 `/home/weijiesun/pegasus_cold_backup/onebox` 这个目录下。
 
 ### 创建冷备份策略
@@ -256,6 +268,59 @@ annotations:
     unknown : invalid, should login server and check it
 ```
 
+
+
 ## 怎样将数据备份到 HDFS
 
-采用 HDFS fuse 即可，可以参考 [这篇文章](https://www.jianshu.com/p/1beb5325c6d8)。
+我们采用 HDFS fuse 的方式，具体可以参考 [这篇文章](https://www.jianshu.com/p/1beb5325c6d8)。
+
+在生产实践中，我们会在集群配置中block_service的类型和连接方式，然后通过admin client中的backup命令发送RPC进行单次冷备。具体步骤如下：
+
+```
+1. 在 config.ini 中配置 block_service 的类型
+[block_service.hdfs_example1]
+type = hdfs_service
+args = hdfs://hdfs_example1-hadoop /
+
+2. 启动集群
+
+3. 在源集群使用admin-cli 执行命令连接集群
+ ./admin-cli -m 10.xxx.xxx.5:33601,10.xxx.xxx.6:33601
+ 
+4. 根据需求开启限速
+server-config replica hdfs_write_batch_size_bytes set 524288
+
+5. 指定冷备份目标路径，执行备份命令。三个参数分别为表id、hdfs位置、hdfs路径
+backup 4 hdfs_example1 /user/pegasus/backup
+
+6. 查询冷备进度。两个参数分别为表id、backup id
+query-backup-status 4 1697508662432 
+```
+
+
+
+### restore恢复HDFS上的冷备份数据
+
+1. 同样使用admin-cli连接目标集群，使用命令查看限速
+
+   ```
+   >> server-config replica list
+   
+   // 查看参数
+   >> hdfs_read_batch_size_bytes=67108864
+   
+   // 通过调整hdfs_read_limit_rate_megabytes，进行限速。单位为MB
+   >> hdfs_read_limit_rate_megabytes=100
+   ```
+
+2. 执行命令进行restore
+
+   参数说明：-c 为源集群名称，-a 为旧表名称，-i 为旧表id，-t 为backup id，-b 为hdfs位置，-r 为hdfs路径。
+
+   ```
+   // 目标集群不能存在表名相同的表
+   restore -c your_cluster_name -a your_table_name -i 4 -t 1697508662432 -b hdfs_example1 -r /user/pegasus/backup
+   ```
+
+   
+