br-opts (#2344)

* br-opts * Update 2.compile-br.md * add caution * Update 1.what-is-br.md * Update 2.compile-br.md * br-opts Update 2.compile-br.md add caution Update 1.what-is-br.md Update 2.compile-br.md * Update 2.compile-br.md * Update 1.what-is-br.md
vesoft-inc · Nov 24, 2022 · 3289bfe · 3289bfe
1 parent a781b59
commit 3289bfe
Show file tree

Hide file tree

Showing 5 changed files with 143 additions and 36 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
@@ -1,6 +1,6 @@
 # 什么是 Backup&Restore
 
-Backup&Restore（简称 BR）是一款命令行界面（CLI）工具，可以帮助备份 Nebula Graph 的图空间数据，或者通过备份文件恢复数据。
+Backup&Restore（简称 BR）是一款命令行界面（CLI）工具，可以帮助备份 NebulaGraph 的图空间数据，或者通过备份文件恢复数据。
 
 ## 功能
 
@@ -13,16 +13,14 @@ Backup&Restore（简称 BR）是一款命令行界面（CLI）工具，可以帮
 
 ## 限制
 
-- Nebula Graph 版本需要为 v{{ nebula.release }}。
+- NebulaGraph 版本需要为 v{{ nebula.release }}。
 - 数据备份仅支持全量备份，不支持增量备份。
 - 仅支持单 metad 部署的本地文件的备份和恢复。
 - Nebula Listener 暂时不支持备份，且全文索引也不支持备份。
 - 如果备份数据到本地磁盘，备份的文件将会放置在每个服务器的本地路径中。也可以在本地挂载 NFS 文件系统，以便将备份数据还原到不同的主机上。
-- 备份图空间只能恢复到原集群，不能跨集群恢复。
 - 数据备份过程中，指定图空间中的 DDL 和 DML 语句将会阻塞，我们建议在业务低峰期进行操作，例如凌晨 2 点至 5 点。
-- 数据恢复仅支持在相同拓扑的集群上进行，即原集群和目标集群的主机数量必须相同。
+- 备份图空间只能恢复到原集群，不能跨集群恢复，并且集群的主机数量必须相同；还原指定图空间时将清除集群中其余所有图空间。
 - 数据恢复需要删除数据并重启，建议离线进行。
-- （实验性功能）如果备份 A 集群中的某个指定图空间，此备份无法还原至另一个集群 B，还原该指定图空间时将清除集群中其余所有图空间。
 <!-- - 备份或恢复部署在 Docker 中的数据时，需要做好网络配置，例如 IP 和端口的映射。 -->
 
 <!--
@@ -122,7 +120,7 @@ Backup&Restore（简称 BR）是一款命令行界面（CLI）工具，可以帮
 
 可以按照如下步骤使用 BR：
 
-1. [编译 BR](2.compile-br.md)
+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/backup-and-restore/nebula-br/2.compile-br.md b/docs-2.0/backup-and-restore/nebula-br/2.compile-br.md
@@ -1,14 +1,53 @@
-# 编译 BR
+# 安装 BR
 
-目前，BR 还没有作为一个包提供。需要先编译 BR。
+本文介绍如何安装 BR。
 
-## 准备工作
+## 安装说明
+
+使用 BR 工具备份和恢复 NebulaGraph 时，需要安装 NebulaGraph Agent 服务。Agent 是集群中每台机器的一个守护进程，用于启停 NebulaGraph 服务和上传、下载备份文件。BR 工具和 Agent 插件的安装方式如下文。
+
+## 版本兼容性
+
+|NebulaGraph|BR |Agent |
+|:---|:---|:---|
+|3.0 ~ 3.2|{{br.release}}|0.1.0 ~ 0.2.0|
+
+## 安装 BR
+
+### 使用二进制文件安装
+
+1. 下载 BR。
+
+  ```
+  wget https://github.com/vesoft-inc/nebula-br/releases/download/{{br.tag}}/br-{{br.release}}-linux-amd64
+  ```
+
+2. 修改文件名称为`br`。
+
+  ```
+  sudo mv br-{{br.release}}-linux-amd64 br
+  ```
+
+3. 授予 BR 执行权限。
+
+  ```
+  sudo chmod +x br
+  ```
+
+4. 执行`./br version`查看 BR 版本。
+
+  ```
+  [nebula-br]$ ./br version
+  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
@@ -36,3 +75,72 @@ Nebula Backup And Restore Utility Tool,V-{{br.release}}
    GitRef: master
 please run "help" subcommand for more infomation.
 ```
+
+
+## 安装 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`：可选项（Agent 0.2.0 及以后版本支持此选项），限制文件上传和下载的速度，防止带宽被占满导致其他服务不可用。单位：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,15 +1,13 @@
 # 使用 BR 备份数据
 
-BR 编译成功后，可以备份整个图空间的数据，本文介绍如何使用 BR 备份数据。
+成功安装 BR 工具后，可以备份整个图空间的数据，本文介绍如何使用 BR 备份数据。
 
 ## 准备工作
 
-- BR 编译完成。如何编译 BR，请参见[编译 BR](2.compile-br.md)。
+- [安装 BR 和 Agent](2.compile-br.md) 并在集群中的每个主机上运行 Agent。
 
 - 确认 Nebula Graph 服务正在运行中。
 
-- 已下载 [nebula-agent](https://github.com/vesoft-inc/nebula-agent) 并在集群中的每个主机上运行代理服务。
-
 - 如果在本地保存备份文件，需要在 Meta 服务器、Storage 服务器和 BR 机器上创建绝对路径相同的目录，并记录绝对路径，同时需要保证账号对该目录有写权限。
 
   !!! Note
@@ -18,19 +16,19 @@ BR 编译成功后，可以备份整个图空间的数据，本文介绍如何
 
 ## 操作步骤
 
-运行以下命令对整个集群进行全量备份操作。
+在 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
 
@@ -39,13 +37,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
   ```
 
 以下列出命令的相关参数。
@@ -56,7 +54,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。 |
@@ -65,4 +63,4 @@ $ ./bin/br backup full --meta <ip_address> --storage <storage_path>
 
 ## 下一步
 
-备份文件生成后，可以使用 BR 将备份文件的数据恢复到 Nebula Graph 中。具体操作，请参见[使用 BR 恢复数据](4.br-restore-data.md)。
+备份文件生成后，可以使用 BR 将备份文件的数据恢复到 NebulaGraph 中。具体操作，请参见[使用 BR 恢复数据](4.br-restore-data.md)。
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。
 
 - 确认没有应用程序连接到待恢复数据的 Nebula Graph 集群。
 
 - 确认集群的拓扑结构一致，即原集群和目标集群的主机数量一致，且每个主机数据文件夹数量分布一致。
 
 ## 操作步骤
 
+在 BR 工具的安装路径下（编译安装的默认路径为`./bin/br`），完成以下操作。
+
 1. 用户可以使用以下命令列出现有备份信息：
 
   ```bash
-  $ ./bin/br show --storage <ip_address>
+  $ ./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
@@ -183,6 +183,9 @@ extra:
     release: 0.6.1
     branch: master
     tag: v0.6.1
+  agent:
+    release: 0.2.0
+    tag: v0.2.0
   cpp:
     release: 3.0.2
     branch: v3.0.2
@@ -445,7 +448,7 @@ nav:
   - 备份与恢复:
       - Nebula 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
       - 管理快照: backup-and-restore/3.manage-snapshot.md