From 220d7a313debc17aeb926edb3a1055c350f5236b Mon Sep 17 00:00:00 2001 From: "abby.huang" <78209557+abby-cyber@users.noreply.github.com> Date: Thu, 24 Nov 2022 17:55:29 +0800 Subject: [PATCH] Br community opts (#2351) * br-community-opts * Update 3.br-backup-data.md * Update 2.compile-br.md --- .../nebula-br/1.what-is-br.md | 3 +- .../nebula-br/2.compile-br.md | 84 ++++++++++++++++++- .../nebula-br/3.br-backup-data.md | 24 +++--- .../nebula-br/4.br-restore-data.md | 24 +++--- mkdocs.yml | 2 +- 5 files changed, 107 insertions(+), 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 index cc16d07204..3b1e4a59fc 100644 --- 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 index 8aac72d040..6c08917956 100644 --- 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=":8888" --meta=":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`参数是否正确。 \ No newline at end of file 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 index 2dadd163a9..bb87f3c20f 100644 --- 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 --storage +$ ./br backup full --meta --storage ``` 例如： -- 运行以下命令对 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 --storage 备份至本地时，默认只备份 leader metad 的数据，因此当有多个 metad 节点时，需要手动将备份后的 leader metad 的目录（路径为`/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 --storage | `--debug` | - | 否 | 无 | 查看更多日志信息。 | | `--log` | string | 否 | `"br.log"` | 日志路径。 | | `--meta` | string | 是| 无 | meta 服务的地址和端口号。 | -| `--spaces` | stringArray | 否 | 无 | (实验性功能)指定要备份的图空间名字，未指定将备份所有图空间。 | +| `--spaces` | stringArray | 否 | 无 |（实验性功能）指定要备份的图空间名字，未指定将备份所有图空间。可指定多个图空间，用法为`--spaces nba_01 --spaces nba_02`。 | | `--storage` | string | 是 | 无 | BR 备份数据存储位置，格式为：`://`
Schema：可选值为 `local` 和 `s3`。选择 s3 时，需要填写`s3.access_key`、`s3.endpoint`、`s3.region`和 `s3.secret_key`。
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 index 859765f847..f6b5fc92fa 100644 --- 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,9 +12,7 @@ ## 准备工作 -- BR 编译完成。如何编译 BR，请参见[编译 BR](2.compile-br.md)。 - -- 已下载 [nebula-agent](https://github.com/vesoft-inc/nebula-agent) 并在集群中的**每个**主机上运行代理服务。 +- [安装 BR 和 Agent](2.compile-br.md) 并在集群中的每个主机上运行 Agent。 - 确认没有应用程序连接到待恢复数据的 NebulaGraph 集群。 @@ -22,15 +20,17 @@ ## 操作步骤 +在 BR 工具的安装路径下（编译安装的默认路径为`./bin/br`），完成以下操作。 + 1. 用户可以使用以下命令列出现有备份信息： ```bash - $ ./bin/br show --storage + $ ./br show --storage ``` 例如，可以使用以下命令列出在本地 `/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 --storage --name + $ ./br restore full --meta --storage --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 --storage --name + $ ./br cleanup --meta --storage --name ``` 以下列出命令的相关参数。 diff --git a/mkdocs.yml b/mkdocs.yml index 85463d7df2..04f08abe90 100644 --- 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