added BR (#162)

* added BR * added BR * added BR * added BR
vesoft-inc · Feb 26, 2021 · 6184d4b · 6184d4b
1 parent a401e22
commit 6184d4b
Show file tree

Hide file tree

Showing 4 changed files with 350 additions and 0 deletions.
diff --git a/docs-2.0/7.data-secrurity/2.backup-restore/1.what-is-br.md b/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）、Hadoop分布式文件系统（HDFS）、阿里云对象存储（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)
diff --git a/docs-2.0/7.data-secrurity/2.backup-restore/2.complie-br.md b/docs-2.0/7.data-secrurity/2.backup-restore/2.complie-br.md
@@ -0,0 +1,30 @@
+# 编译BR
+
+目前，BR还没有作为一个包提供。您需要先编译BR。
+
+## 准备工作
+
+- 安装[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`。
diff --git a/docs-2.0/7.data-secrurity/2.backup-restore/3.br-backup-data.md b/docs-2.0/7.data-secrurity/2.backup-restore/3.br-backup-data.md
@@ -0,0 +1,118 @@
+# 使用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/"
+ # 如果使用HDFS存储备份文件，请设置：
+ # hdfs://namenode:port/nebulabackup
+ # 如果使用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)。
+
diff --git a/docs-2.0/7.data-secrurity/2.backup-restore/4.br-restore-data.md b/docs-2.0/7.data-secrurity/2.backup-restore/4.br-restore-data.md
@@ -0,0 +1,116 @@
+# 使用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`，根据实际路径和系统替换内容。
+
+- 如果您的备份文件保存在本地磁盘，需要将BR机器上备份的Meta文件手动合并到Meta服务器和Storage服务器的备份目录内（和meta、storage目录平级）。本文示例为`/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/"
+ # 如果使用HDFS存储备份文件，请设置：
+ # hdfs://namenode:port/nebulabackup
+ # 如果使用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服务后再次尝试查询。