Br community opts (#2351)

* br-community-opts * Update 3.br-backup-data.md * Update 2.compile-br.md
vesoft-inc · Nov 24, 2022 · 220d7a3 · 220d7a3
1 parent 35fb750
commit 220d7a3
Show file tree

Hide file tree

Showing 5 changed files with 107 additions and 30 deletions.
diff --git a/docs-2.0/backup-and-restore/nebula-br/1.what-is-br.md b/docs-2.0/backup-and-restore/nebula-br/1.what-is-br.md
@@ -17,9 +17,8 @@ Backup&Restore（简称 BR）是一款命令行界面（CLI）工具，可以帮
 - 数据备份仅支持全量备份，不支持增量备份。
 - NebulaGraph Listener 暂时不支持备份，且全文索引也不支持备份。
 - 如果备份数据到本地磁盘，备份的文件将会放置在每个服务器的本地路径中。也可以在本地挂载 NFS 文件系统，以便将备份数据还原到不同的主机上。
-- 备份图空间只能恢复到原集群，不能跨集群恢复。
+- 备份图空间只能恢复到原集群，不能跨集群恢复，并且集群的 Storage 主机数量及 IP 需一致。
 - 数据备份过程中，指定图空间中的 DDL 和 DML 语句将会阻塞，我们建议在业务低峰期进行操作，例如凌晨 2 点至 5 点。
-- 数据恢复需要原集群和目标集群的 Storage 主机数量及 IP 一致。
 - 数据恢复期间有一段时间服务会被停止。
 - （实验性功能）如果备份 A 集群中的某个指定图空间，并恢复这个图空间数据至集群 B 时，集群 B 中其他图空间数据将被清除。
 - 不支持在容器部署的 NebulaGraph 集群中使用 BR。

diff --git a/docs-2.0/backup-and-restore/nebula-br/2.compile-br.md b/docs-2.0/backup-and-restore/nebula-br/2.compile-br.md
@@ -2,7 +2,19 @@
 
 本文介绍如何安装 BR。
 
-## 使用二进制文件安装
+## 安装说明
+
+使用 BR 工具备份和恢复 NebulaGraph 时，需要安装 NebulaGraph Agent 服务。Agent 是集群中每台机器的一个守护进程，用于启停 NebulaGraph 服务和上传、下载备份文件。BR 工具和 Agent 插件的安装方式如下文。
+
+## 版本兼容性
+
+|NebulaGraph 社区版|BR 社区版 |Agent |
+|:---|:---|:---|
+|3.3.0|3.3.0|0.2.0|
+
+## 安装 BR
+
+### 使用二进制文件安装
 
 1. 下载 BR。
 
@@ -29,13 +41,14 @@
   Nebula Backup And Restore Utility Tool,V-{{br.release}}
   ```
 
-## 使用源码安装
+### 使用源码安装
 
 使用源码安装 BR 前，准备工作如下：
 
 - 安装 [Go](https://github.com/golang/go "Click to go to GitHub") 1.14.x 或更新版本。
 - 安装 make。
 
+
 1. 克隆`nebula-br`库至机器。
 
     ```bash
@@ -60,3 +73,70 @@
 [nebula-br]$ bin/br version
 NebulaGraph Backup And Restore Utility Tool,V-{{br.release}}
 ```
+
+## 安装 Agent
+
+NebulaGraph Agent 以二进制形式存在各个机器的安装目录中，通过 RPC 协议对 BR 工具提供服务。
+
+在**每台机器**中，进行以下操作：
+
+1. 下载 Agent。
+
+  ```
+  wget https://github.com/vesoft-inc/nebula-agent/releases/download/v{{agent.release}}/agent-{{agent.release}}-linux-amd64
+  ```
+
+2. 修改 Agent 的名称为`agent`。
+
+  ```
+  sudo mv agent-{{agent.release}}-linux-amd64 agent
+  ```
+
+3. 授予 Agent 可执行权限。
+
+  ```
+  sudo chmod +x agent
+  ```
+
+4. 执行以下命令启动 Agent。
+
+  !!! note
+
+        启动 Agent 前，确保已经启动集群中的 Meta 服务，并且 Agent 有对应 NebulaGraph 服务目录和备份目录的读写权限。
+
+  ```
+  sudo nohup ./nebula_agent --agent="<agent_node_ip>:8888" --meta="<metad_node_ip>:9559" > nebula_agent.log 2>&1 &
+  ```
+
+  - `--agent`：Agent 所在机器的 IP 地址和访问端口。
+  - `--meta`：集群中任一 Meta 服务所在机器的 IP 地址和访问端口。
+  - `--ratelimit`：可选项，限制文件上传和下载的速度，防止带宽被占满导致其他服务不可用。单位：Bytes。
+
+  例如：
+
+  ```
+  sudo nohup ./nebula_agent --agent="192.168.8.129:8888" --meta="192.168.8.129:9559" --ratelimit=1048576 > nebula_agent.log 2>&1 &
+  ```
+
+  !!! caution
+
+        `--agent`配置的 IP 地址需要和[配置文件](../../5.configurations-and-logs/1.configurations/1.configurations.md)中 Meta 和 Storage 服务的地址格式保持一致，即都使用真实 IP 地址或者都使用`127.0.0.1`，否则 Agent 无法启动。
+
+
+1. 连接服务并查看 Agent 的运行状态。
+
+  ```
+  nebula> SHOW HOSTS AGENT;
+  +-----------------+------+----------+---------+--------------+---------+
+  | Host            | Port | Status   | Role    | Git Info Sha | Version |
+  +-----------------+------+----------+---------+--------------+---------+
+  | "192.168.8.129" | 8888 | "ONLINE" | "AGENT" | "96646b8"    |         |
+  +-----------------+------+----------+---------+--------------+---------+  
+  ```
+
+
+## 常见问题
+
+### 报错`E_LIST_CLUSTER_NO_AGENT_FAILURE`
+
+如果操作过程中遇见`E_LIST_CLUSTER_NO_AGENT_FAILURE`错误，可能是由于 Agent 服务没有启动或者 Agent 服务没有被注册至 Meta 服务。首先执行`SHOW HOSTS AGENT`查看集群上所有节点的 Agent 服务的状态，当时状态显示为`OFFLINE`时表示注册 Agent 失败， 然后检查启动 Agent 服务的命令中的`--meta`参数是否正确。
diff --git a/docs-2.0/backup-and-restore/nebula-br/3.br-backup-data.md b/docs-2.0/backup-and-restore/nebula-br/3.br-backup-data.md
@@ -1,36 +1,34 @@
 # 使用 BR 备份数据
 
-BR 编译成功后，可以备份整个图空间的数据，本文介绍如何使用 BR 备份数据。
+成功安装 BR 工具后，可以备份整个图空间的数据，本文介绍如何使用 BR 备份数据。
 
 ## 准备工作
 
-- BR 编译完成。如何编译 BR，请参见[编译 BR](2.compile-br.md)。
-
-- 确认 NebulaGraph 服务正在运行中。
+- [安装 BR 和 Agent](2.compile-br.md) 并在集群中的每个主机上运行 Agent。
 
-- 已下载 [nebula-agent](https://github.com/vesoft-inc/nebula-agent) 并在集群中的每个主机上运行代理服务。
+- 确认 NebulaGraph 服务正在运行中。
 
 - 如果在本地保存备份文件，需要在 Meta 服务器、Storage 服务器和 BR 机器上创建绝对路径相同的目录，并记录绝对路径，同时需要保证账号对该目录有写权限。
-
+  
   !!! Note
 
         在生产环境中，我们建议用户将 NFS (Network File System）存储设备挂载到 Meta 服务器、Storage 服务器和 BR 机器上进行本地备份，或者使用 Alibaba Cloud OSS、Amazon S3 进行远程备份。否则当需要通过本地文件恢复数据时，必须手动将这些备份文件移动到指定目录，会导致数据冗余和某些问题。更多信息，请参见[使用 BR 恢复数据](4.br-restore-data.md)。
 
 ## 操作步骤
 
-运行以下命令对整个集群进行全量备份操作。
+在 BR 工具的安装路径下（编译安装的默认路径为`./bin/br`）运行以下命令对整个集群进行全量备份操作。
 
 !!! Note
 
     确保备份文件的路径存在。
 
 ```bash
-$ ./bin/br backup full --meta <ip_address> --storage <storage_path>
+$ ./br backup full --meta <ip_address> --storage <storage_path>
 ```
 
 例如：
 
-- 运行以下命令对 meta 服务的地址为`127.0.0.1:9559`的整个集群进行全量备份操作，并将备份文件保存到本地的 `/home/nebula/backup/`路径下。
+- 运行以下命令对 meta 服务的地址为`192.168.8.129:9559`的整个集群进行全量备份操作，并将备份文件保存到本地的 `/home/nebula/backup/`路径下。
 
   !!! caution
 
@@ -41,13 +39,13 @@ $ ./bin/br backup full --meta <ip_address> --storage <storage_path>
         备份至本地时，默认只备份 leader metad 的数据，因此当有多个 metad 节点时，需要手动将备份后的 leader metad 的目录（路径为`<storage_path>/meta`）拷贝并覆盖其他 follower meatd 节点的对应目录。
 
   ```bash
-  $ ./bin/br backup full --meta "127.0.0.1:9559" --storage "local:///home/nebula/backup/"
+  $ ./br backup full --meta "192.168.8.129:9559" --storage "local:///home/nebula/backup/"
   ```
 
-- 运行以下命令对 meta 服务的地址为`127.0.0.1:9559`的整个集群进行全量备份操作，并将备份文件保存到兼容 s3 协议的对象存储服务 `br-test` 桶下的`backup`中。
+- 运行以下命令对 meta 服务的地址为`192.168.8.129:9559`的整个集群进行全量备份操作，并将备份文件保存到兼容 s3 协议的对象存储服务 `br-test` 桶下的`backup`中。
 
   ```bash
-  $ ./bin/br backup full --meta "127.0.0.1:9559" --s3.endpoint "http://127.0.0.1:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
+  $ ./br backup full --meta "192.168.8.129:9559" --s3.endpoint "http://192.168.8.129:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
   ```
 
 以下列出命令的相关参数。
@@ -58,7 +56,7 @@ $ ./bin/br backup full --meta <ip_address> --storage <storage_path>
 | `--debug` | - | 否 | 无 | 查看更多日志信息。 |
 | `--log` | string | 否 | `"br.log"` | 日志路径。 |
 | `--meta` | string | 是| 无 | meta 服务的地址和端口号。 |
-| `--spaces` | stringArray | 否 | 无 | (实验性功能)指定要备份的图空间名字，未指定将备份所有图空间。 |
+| `--spaces` | stringArray | 否 | 无 |（实验性功能）指定要备份的图空间名字，未指定将备份所有图空间。可指定多个图空间，用法为`--spaces nba_01 --spaces nba_02`。 |
 | `--storage` | string | 是 | 无 | BR 备份数据存储位置，格式为：`<Schema>://<PATH>` <br>Schema：可选值为 `local` 和 `s3`。选择 s3 时，需要填写`s3.access_key`、`s3.endpoint`、`s3.region`和 `s3.secret_key`。<br>PATH：存储位置的路径。|
 | `--s3.access_key` | string | 否 | 无 | 用于标识用户。 |
 | `--s3.endpoint` | string | 否 | 无 | S3 对外服务的访问域名的 URL，指定 http 或 https。 |

diff --git a/docs-2.0/backup-and-restore/nebula-br/4.br-restore-data.md b/docs-2.0/backup-and-restore/nebula-br/4.br-restore-data.md
@@ -12,25 +12,25 @@
 
 ## 准备工作
 
-- BR 编译完成。如何编译 BR，请参见[编译 BR](2.compile-br.md)。
-
-- 已下载 [nebula-agent](https://github.com/vesoft-inc/nebula-agent) 并在集群中的**每个**主机上运行代理服务。
+- [安装 BR 和 Agent](2.compile-br.md) 并在集群中的每个主机上运行 Agent。
 
 - 确认没有应用程序连接到待恢复数据的 NebulaGraph 集群。
 
 - 确认集群的拓扑结构一致，即原集群和目标集群的主机数量一致，且每个主机数据文件夹数量分布一致。
 
 ## 操作步骤
 
+在 BR 工具的安装路径下（编译安装的默认路径为`./bin/br`），完成以下操作。
+
 1. 用户可以使用以下命令列出现有备份信息：
 
   ```bash
-  $ ./bin/br show --storage <storage_path>
+  $ ./br show --storage <storage_path>
   ```
 
   例如，可以使用以下命令列出在本地 `/home/nebula/backup` 路径中的备份的信息。
   ```bash
-  $ ./bin/br show --storage "local:///home/nebula/backup"
+  $ ./br show --storage "local:///home/nebula/backup"
   +----------------------------+---------------------+------------------------+-------------+------------+
   |            NAME            |     CREATE TIME     |         SPACES         | FULL BACKUP | ALL SPACES |
   +----------------------------+---------------------+------------------------+-------------+------------+
@@ -41,7 +41,7 @@
 
   或使用以下命令列出在兼容 s3 协议的对象存储服务 `br-test` 桶下的`backup`中的备份的信息。
   ```bash
-  $ ./bin/br show --s3.endpoint "http://127.0.0.1:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
+  $ ./br show --s3.endpoint "http://192.168.8.129:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
   ```
 
   以下列出命令的相关参数。
@@ -59,18 +59,18 @@
 
 2. 用户可以使用以下命令恢复数据：
   ```
-  $ ./bin/br restore full --meta <ip_address> --storage <storage_path> --name <backup_name>
+  $ ./br restore full --meta <ip_address> --storage <storage_path> --name <backup_name>
   ```
 
-  例如，可以使用以下命令，将本地 `/home/nebula/backup/` 路径中的数据恢复到为 meta 地址为`127.0.0.1:9559`集群中：
+  例如，可以使用以下命令，将本地 `/home/nebula/backup/` 路径中的数据恢复到为 meta 地址为`192.168.8.129:9559`集群中：
 
   ```
-  $ ./bin/br restore full --meta "127.0.0.1:9559" --storage "local:///home/nebula/backup/" --name BACKUP_2021_12_08_18_38_08
+  $ ./br restore full --meta "192.168.8.129:9559" --storage "local:///home/nebula/backup/" --name BACKUP_2021_12_08_18_38_08
   ```
 
-  或者使用以下命令，将兼容 s3 协议的对象存储服务 `br-test` 桶下的`backup`的备份，恢复到 meta 服务的地址为`127.0.0.1:9559`的集群中。
+  或者使用以下命令，将兼容 s3 协议的对象存储服务 `br-test` 桶下的`backup`的备份，恢复到 meta 服务的地址为`192.168.8.129:9559`的集群中。
   ```bash
-  $ ./bin/br restore full --meta "127.0.0.1:9559" --s3.endpoint "http://127.0.0.1:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region="default" --name BACKUP_2021_12_08_18_38_08
+  $ ./br restore full --meta "192.168.8.129:9559" --s3.endpoint "http://192.168.8.129:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region="default" --name BACKUP_2021_12_08_18_38_08
   ```
 
   如果返回如下信息，表示数据已经恢复成功。
@@ -100,7 +100,7 @@
 3. 如果在备份期间发现任何错误，用户可以使用以下命令清理临时文件。该命令将清理集群和外部存储中的文件，同时用户也可以使用该命令清理外部存储中的旧的备份文件。
 
   ```
-  $ ./bin/br cleanup --meta <ip_address> --storage <storage_path> --name <backup_name>
+  $ ./br cleanup --meta <ip_address> --storage <storage_path> --name <backup_name>
   ```
 
   以下列出命令的相关参数。

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -490,7 +490,7 @@ nav:
   - 备份与恢复:
       - NebulaGraph BR（社区版）:
         - BR（社区版）概述: backup-and-restore/nebula-br/1.what-is-br.md
-        - 编译 BR: backup-and-restore/nebula-br/2.compile-br.md
+        - 安装 BR: backup-and-restore/nebula-br/2.compile-br.md
         - 使用 BR 备份数据: backup-and-restore/nebula-br/3.br-backup-data.md
         - 使用 BR 恢复数据: backup-and-restore/nebula-br/4.br-restore-data.md
 #ent