added BR

docs-2.0/7.data-secrurity/2.backup-restore/1.what-is-br.md

@@ -0,0 +1,86 @@
+# 什么是Backup&Restore
+
+Backup&Restore（简称BR）是一款命令行界面（CLI）工具，可以帮助您备份Nebula Graph的图空间数据，或者通过备份文件恢复数据。
+
+## 功能
+
+- 支持备份一个或多个图空间的数据。
+- 支持基于本地磁盘（SSD或HDD）、阿里云对象存储（Alibaba Cloud OSS）或亚马逊对象存储（Amazon S3）中的备份文件恢复数据。
+
+## 限制
+
+- Nebula Graph版本需要为v2.0.0-RC或更新版本。
+- 数据备份仅支持全量备份，不支持增量备份。
+- 数据备份过程中，指定图空间中的DDL和DML语句将会阻塞，我们建议您在业务低峰期进行操作，例如凌晨2点至5点。
+- 数据恢复仅支持在相同拓扑的集群上进行，即原集群和目标集群的主机数量必须相同。
+- 数据恢复需要删除数据并重启，建议离线进行。
+- 备份或恢复部署在Docker中的数据时，需要做好网络配置，例如IP和端口的映射。
+
+## 工作原理
+
+### 备份
+
+为了备份数据，BR会发送备份请求给leader的metad进程，触发备份。详细说明如下：
+
+1. 验证BR访问Meta服务器和Storage服务器的SSH登录信息。
+   >**说明**：如果必须使用云存储，例如Alibaba Cloud OSS或Amazon S3，还需要验证它们的客户端安装和配置。
+2. BR发起请求创建备份文件。
+3. leader的metad进程被锁定。
+   >**注意**：从此时起至第9步结束，您无法在指定图空间内执行任何nGQL的DDL语句。
+4. leader的metad进程阻塞指定图空间的写请求。
+   >**注意**：从此时起至第7步结束，您无法在指定图空间内执行任何nGQL的DML语句，但是可以执行DQL语句。
+5. leader的metad进程发送请求至storaged进程，请求快照文件名称。
+6. leader的metad进程扫描本地RocksDB文件，输出为SST（Static Sorted Table）格式文件。
+7. leader的metad进程解除阻塞指定图空间的写请求。
+   >**说明**：从此时起，您可以在指定图空间内执行nGQL的DML语句。
+8. leader的metad进程回应BR，包含的Meta数据和快照信息如下：
+   - thrift格式信息
+   - 图空间分区信息
+   - 每个分区的Raft日志提交ID
+   - 快照信息（每个快照存储进程的目录）
+   - Meta服务器SST格式文件名称
+   - 备份文件名称
+9. leader的metad进程解除锁定。
+   >**说明**：从此时起，您可以在指定图空间内执行任何nGQL的DDL语句。
+10. BR通过SSH登录至leader所在的Meta服务器和所有Storage服务器，然后备份文件。
+11. 如果使用的是Alibaba Cloud OSS或Amazon S3，BR会调用命令将备份文件上传至云存储中。
+    >**注意**：本步骤会大量读取磁盘，建议使用万兆网络保证速率。如果上传过程中出现网络错误，备份会失败，必须重新执行备份操作。目前备份过程不支持断点续传。
+12. BR发起请求清理Storage服务器的快照，备份完成。
+
+下图展示了备份的具体流程。
+
+![The figure shows the backup procedure](https://docs.nebula-graph.io/2.0/figs/ng-ug-001.png "Implementation of backup")
+
+备份文件生成时会自动命名，命名格式为`BACKUP_YY_MM_DD_HH_mm_SS`：
+
+- `BACKUP`表示该文件是备份文件。
+- `YY_MM_DD_HH_mm_SS`表示该文件的生成时间。
+
+### 恢复
+
+>**警告**：恢复过程中，目标集群上已有的数据会被删除，然后替换为备份文件中的数据。建议您提前备份目标集群上的数据。
+
+恢复过程的详细说明如下：
+
+1. 验证BR访问Meta服务器和Storage服务器的SSH登录信息。
+   >**说明**：如果必须使用云存储，例如Alibaba Cloud OSS或Amazon S3，还需要验证它们的客户端安装和配置。
+2. BR从外部存储或云存储中下载Meta信息（非完整数据）。
+3. BR验证集群的拓扑结构，确保原集群和目标集群的主机数量一致。
+4. BR远程停止Meta服务和Storage服务。
+5. BR通过SSH登录至leader所在的Meta服务器和所有Storage服务器，然后删除现有的数据文件。
+6. 现有数据文件删除后，Meta服务器和所有Storage服务器从外部存储或云存储中下载备份文件。
+7. 备份文件下载完成后，BR启动Meta服务。
+8. BR调用`br restore`命令更改指定metad进程的分区信息。
+9. BR启动Storage服务，恢复过程完成。
+
+下图展示了恢复的具体流程。
+
+![The figure shows the restoration process](https://docs.nebula-graph.io/2.0/figs/ng-ug-002.png "Implementation of restoration")
+
+## 如何使用BR
+
+您可以按照如下步骤使用BR：
+
+1. [编译BR](2.compile-br.md)
+2. [使用BR备份数据](3.br-backup-data.md)
+3. [使用BR恢复数据](4.br-restore-data.md)

docs-2.0/7.data-secrurity/2.backup-restore/2.complie-br.md

@@ -0,0 +1,32 @@
+# 编译BR
+
+目前，BR还没有作为一个包提供。您需要先编译BR。
+
+[//]:   >**注意**：如果您需要将备份文件存储在本地，我们建议您在想要执行恢复操作的元服务器上编译BR。更多信息，请参见[从备份文件恢复数据](4.br-restore-data.md)。
+
+## 准备工作
+
+- 安装[Go](https://github.com/golang/go "Click to go to GitHub") 1.14或更新版本。
+- 安装make。
+
+## 操作步骤
+
+1. 克隆`nebula-storage`库至您的机器。
+
+    ```bash
+    git clone https://github.com/vesoft-inc/nebula-storage.git
+    ```
+
+2. 进入`br`目录。
+
+    ```bash
+    cd nebula-storage/util/br
+    ```
+
+3. 编译BR。
+
+    ```bash
+    make build && make test
+    ```
+
+如果BR编译成功，您可以在`nebula-storage/util/br/bin/`目录内找到二进制文件`br`。

docs-2.0/7.data-secrurity/2.backup-restore/3.br-backup-data.md

@@ -0,0 +1,116 @@
+# 使用BR备份数据
+
+BR编译成功后，您可以备份指定图空间的数据，本文介绍如何使用BR备份数据。
+
+## 准备工作
+
+- BR编译完成。如何编译BR，请参见[编译BR](2.compile-br.md)。
+
+- 确认Nebula Graph服务正在运行中。
+
+- 确认需要备份的图空间名称。本文示例为`nba`。
+
+- 确认Nebula Graph的绝对安装路径。本文示例为`/usr/local/nebula/`。
+
+- 确认Meta服务器和Storage服务器的IP和端口。
+
+  - 在Nebula Graph的安装路径内查看`nebula-metad.conf`文件(例如`/usr/local/nebula/etc/nebula-metad.conf`)，确认Meta服务器的IP和端口。本文示例为`192.168.8.161:9559`。
+
+  - 在Nebula Graph的安装路径内查看和`nebula-storaged.conf`文件(例如`/usr/local/nebula/etc/nebula-storaged.conf`)，确认Storage服务器的IP和端口。本文示例为`192.168.8.161:9779`。
+
+  >**注意**：确保配置文件中使用的是实际的IP地址，而不是`127.0.0.1`。
+
+- BR可以免密登录服务器，即您在BR机器上的账号可以通过SSH免密登录到Meta服务器和Storage服务器。详情请参见[SSH tunnels with keys](http://alexander.holbreich.org/ssh-tunnel-without-password/)。本文示例账号名称为`nebula`。
+
+- 如果您使用Alibaba Cloud OSS或Amazon S3保存备份文件，请确保Meta服务器、Storage服务器和BR机器都已安装相应的客户端。详情请参见[Alibaba Cloud ossutil文档](https://www.alibabacloud.com/help/zh/doc-detail/120075.htm#concept-303829)和[Amazon S3 CLI文档](https://docs.amazonaws.cn/cli/latest/userguide/cli-services-s3.html)。
+  >**注意**：请创建软链接方便使用ossutil命令。命令为`ln -s /<ossutil_tool_installation_path>/<ossutil64 or ossutil> /usr/local/bin/ossutil`，根据实际路径和系统替换内容。
+
+- 如果您在本地保存备份文件，需要在Meta服务器、Storage服务器和BR机器上创建绝对路径相同的目录，并记录绝对路径，同时需要保证账号对该目录有写权限。本文示例为`/home/user/backup/`。
+  >**注意**：在生产环境中，我们建议您将NFS (Network File System）存储设备挂载到Meta服务器、Storage服务器和BR机器上进行本地备份，或者使用Alibaba Cloud OSS、Amazon S3进行远程备份。否则当您需要通过本地文件恢复数据时，必须手动将这些备份文件移动到指定目录，会导致数据冗余和某些问题。更多信息，请参见[使用BR恢复数据](4.br-restore-data.md)。
+
+## 操作步骤
+
+1. 在`nebula-storage/util/br/config`目录内创建配置文件`backup.yaml`。您可以参考如下配置，目录内也有示例文件`backup_example.yaml`。
+
+   ```yaml
+   meta_nodes:
+     - # 配置一个Meta服务器的IP和端口
+      addrs: "192.168.8.161:9559"
+      # 配置Nebula Graph的绝对安装路径
+      root: "/usr/local/nebula/"
+      # 配置metad进程数据目录的绝对路径
+      data: "/usr/local/nebula/data/meta"
+      # 配置可以免密登录服务器的账号名称，需要对备份存储目录有读写权限
+      user: "nebula"
+     #- # 如果存在多个metad进程，请参考上述配置继续添加
+     #  addrs: "192.168.8.161:9559"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/meta"
+     #  user: "nebula"
+     #- addrs: "192.168.8.161:9559"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/meta"
+     #  user: "nebula"
+
+   storage_nodes:
+     - # 配置一个Storage服务器的IP和端口
+      addrs: "192.168.8.161:9779"
+      # 配置Nebula Graph的绝对安装路径
+      root: "/usr/local/nebula/"
+      # 配置storaged进程数据目录的绝对路径
+      data: "/usr/local/nebula/data/storage"
+      # 配置可以免密登录服务器的账号名称，需要对备份存储目录有读写权限
+      user: "nebula"
+     #- # 如果存在多个storaged进程，请参考上述配置继续添加
+     #  addrs: "192.168.8.161:9779"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/storage"
+     #  user: "nebula"
+     #- addrs: "192.168.8.161:9779"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/storage"
+     #  user: "nebula"
+
+     # 设置备份文件的存储路径
+     # 如果在本地存储备份文件，请设置： 
+   backend: "local:///home/user/backup/"
+     # 如果使用Alibaba Cloud OSS存储备份文件，请设置：
+     # backend: "oss://nebulabackup"
+     # 如果使用Amazon S3存储备份文件，请设置：
+     # backend: "s3://nebulabackup"
+
+     # 设置要备份的图空间
+     # 如果需要备份多个图空间，请设置：
+     # space_names: ["space_name1", "space_name2", ..., "space_name"]
+   space_name: ["nba"]
+    ```
+
+2. 切换到`nebula-storage/util/br/bin/`目录。
+
+   ```bash
+    cd nebula-storage/util/br/bin/
+   ```
+
+3. 执行如下命令备份数据。
+
+   ```bash
+   ./br backup full --config "/home/vesoft/nebula-storage/util/br/config/backup.yaml"
+   ```
+
+   - `backup full`: 表示备份数据。
+   - `--config "/home/vesoft/nebula-storage/util/br/config/backup.yaml"`: 填写配置文件的绝对路径，通过配置文件进行备份。
+
+4. （可选）默认情况下，备份完成后，所有快照都会被删除。如果删除过程中出错，您可以执行如下命令手动删除快照。
+
+   ```bash
+   ./br cleanup --backup_name [backup file name] --meta 192.168.8.161:9559
+   ```
+
+   - `cleanup`: 表示删除Meta服务器和Storage服务器上的所有临时文件，包括快照。
+   - `--backup_name BACKUP_YY_MM_DD_HH_mm_SS`: 指定要删除的备份文件名称。
+   - `--meta <IP address:port>`: 指定Meta服务器的IP和端口。
+
+## 下一步
+
+备份文件生成后，您可以使用BR将备份文件的数据恢复到Nebula Graph中。具体操作，请参见[使用BR恢复数据](4.br-restore-data.md)。
+

docs-2.0/7.data-secrurity/2.backup-restore/4.br-restore-data.md

@@ -0,0 +1,114 @@
+# 使用BR恢复数据
+
+如果您使用BR备份了Nebula Graph的数据，可以通过备份文件进行数据恢复。本文介绍如何通过备份文件恢复数据。
+
+>**警告**：恢复过程中，目标集群上已有的数据会被删除，然后替换为备份文件中的数据。建议您提前备份目标集群上的数据。
+
+>**注意**：数据恢复需要离线进行。
+
+## 准备工作
+
+- BR编译完成。如何编译BR，请参见[编译BR](2.compile-br.md)。
+
+- 确认没有应用程序连接到待恢复数据的Nebula Graph集群。
+
+- 确认集群的拓扑结构一致，即原集群和目标集群的主机数量一致。
+
+- 确认进行数据恢复的备份文件夹名称。本文示例为`BACKUP_2020_12_21_01_17_53`。
+
+- 确认目标集群中Meta服务器和Storage服务器的IP和端口。
+
+  - 在Nebula Graph的安装路径内查看`nebula-metad.conf`文件(例如`/usr/local/nebula/etc/nebula-metad.conf`)，确认Meta服务器的IP和端口。本文示例为`192.168.8.161:9559`。
+
+  - 在Nebula Graph的安装路径内查看和`nebula-storaged.conf`文件(例如`/usr/local/nebula/etc/nebula-storaged.conf`)，确认Storage服务器的IP和端口。本文示例为`192.168.8.161:9779`。
+
+  >**注意**：确保配置文件中使用的是实际的IP地址，而不是`127.0.0.1`。
+
+- BR可以免密登录服务器，即您在BR机器上的账号可以通过SSH免密登录到Meta服务器和Storage服务器。详情请参见[SSH tunnels with keys](http://alexander.holbreich.org/ssh-tunnel-without-password/)。本文示例账号名称为`nebula`。
+  >**注意**:该账号必须有Nebula Graph安装目录的写权限。
+
+- 如果您使用Alibaba Cloud OSS或Amazon S3保存备份文件，请确保Meta服务器、Storage服务器和BR机器都已安装相应的客户端。详情请参见[Alibaba Cloud ossutil文档](https://www.alibabacloud.com/help/zh/doc-detail/120075.htm#concept-303829)和[Amazon S3 CLI文档](https://docs.amazonaws.cn/cli/latest/userguide/cli-services-s3.html)。
+  >**注意**：请创建软链接方便使用ossutil命令。命令为`ln -s /<ossutil_tool_installation_path>/<ossutil64 or ossutil> /usr/local/bin/ossutil`，根据实际路径和系统替换内容。
+
+- 如果您的备份文件保存在本地，需要在Meta服务器、Storage服务器和BR机器上创建绝对路径相同的目录，然后手动将备份文件移动到该目录下。本文示例为`/home/user/backup/`。
+
+## 操作步骤
+
+1. 在`nebula-storage/util/br/config`目录内修改配置文件`backup.yaml`。您可以参考如下配置，目录内也有示例文件`restore_example.yaml`。
+
+   ```yaml
+   meta_nodes:
+     - # 配置一个Meta服务器的IP和端口
+      addrs: "192.168.8.161:9559"
+      # 配置Nebula Graph的绝对安装路径
+      root: "/usr/local/nebula/"
+      # 配置metad进程数据目录的绝对路径
+      data: "/usr/local/nebula/data/meta"
+      # 配置可以免密登录服务器的账号名称，需要对备份存储目录有读写权限
+      user: "nebula"
+     #- # 如果存在多个metad进程，请参考上述配置继续添加
+     #  addrs: "192.168.8.161:9559"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/meta"
+     #  user: "nebula"
+     #- addrs: "192.168.8.161:9559"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/meta"
+     #  user: "nebula"
+
+   storage_nodes:
+     - # 配置一个Storage服务器的IP和端口
+      addrs: "192.168.8.161:9779"
+      # 配置Nebula Graph的绝对安装路径
+      root: "/usr/local/nebula/"
+      # 配置storaged进程数据目录的绝对路径
+      data: "/usr/local/nebula/data/storage"
+      # 配置可以免密登录服务器的账号名称，需要对备份存储目录有读写权限
+      user: "nebula"
+     #- # 如果存在多个storaged进程，请参考上述配置继续添加
+     #  addrs: "192.168.8.161:9779"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/storage"
+     #  user: "nebula"
+     #- addrs: "192.168.8.161:9779"
+     #  root: "/usr/local/nebula/"
+     #  data: "/usr/local/nebula/data/storage"
+     #  user: "nebula"
+
+     # 设置备份文件的存储路径
+     # 如果是本地存储备份文件，请设置： 
+   backend: "local:///home/user/backup/"
+     # 如果使用Alibaba Cloud OSS存储备份文件，请设置：
+     # backend: "oss://nebulabackup"
+     # 如果使用Amazon S3存储备份文件，请设置：
+     # backend: "s3://nebulabackup"
+
+     # 设置要恢复的备份文件夹
+   backup_name: "BACKUP_2020_12_21_01_17_53"
+    ```
+
+2. 切换到`nebula-storage/util/br/bin/`目录。
+
+   ```bash
+    cd nebula-storage/util/br/bin/
+   ```
+
+3. 执行如下命令恢复数据。
+
+   ```bash
+   ./br restore full --config "/home/vesoft/nebula-storage/util/br/config/backup.yaml"
+   ```
+
+   - `restore full`: 表示恢复数据。
+   - `--config "/home/vesoft/nebula-storage/util/br/config/backup.yaml"`: 填写配置文件的绝对路径，通过配置文件进行恢复。
+
+   >**注意**：如果恢复过程中leader发生变更，会导致数据恢复出错，为保证数据正确性，请重新执行本步骤命令。
+
+   恢复成功后，您可以在Nebula Graph安装目录下的`data/storage`目录内找到数据文件，例如`/usr/local/nebula/data/storage/`。
+
+4. 等待一段时间，直至Meta数据和Schema同步，您可以登录数据库验证数据。例如运行[`SHOW STATS`](../../3.ngql-guide/7.general-query-statements/6.show/14.show-stats/) 验证图空间中点和边的数量是否正确。
+
+   >**注意**：恢复完成后，您需要注意以下两点：
+    >
+    >- 如果执行`USE <space_name>`返回错误，建议您重启Nebula Graph服务。
+    >- 如果查询数据时报错`Storage Error: part: 2, error code: -3.`，请检查Storage服务的状态，或者重启Storage服务后再次尝试查询。