Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

upgrade nebula version #814

Merged
merged 4 commits into from
Aug 11, 2021
Merged

upgrade nebula version #814

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0a18855
upgrade nebula version
cooper-lzy Aug 10, 2021
f1afac9
update
cooper-lzy Aug 10, 2021
bec38d3
update
cooper-lzy Aug 11, 2021
d094a88
update
cooper-lzy Aug 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions ...yment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-from-200-to-201.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
# Nebula Graph v2.0.0升级至v2.0.1
# Nebula Graph v2.0.x升级至v{{nebula.release}}

Nebula Graph v2.0.0升级至v2.0.1，只需要使用v2.0.1的RPM/DEB包进行升级操作即可，或者[编译v2.0.1](2.compile-and-install-nebula-graph/1.install-nebula-graph-by-compiling-the-source-code.md)之后重新安装。
Nebula Graph v2.0.x升级至v{{nebula.release}}，只需要使用v{{nebula.release}}的RPM/DEB包进行升级操作即可，或者[编译v{{nebula.release}}](../2.compile-and-install-nebula-graph/1.install-nebula-graph-by-compiling-the-source-code.md)之后重新安装。

!!! note
如果Nebula Graph版本过低，需要先升级至v2.0.0，详情请参见[升级 Nebula Graph 历史版本至 v2.0.0](3.upgrade-nebula-graph.md)。

Nebula Graph v2.0.x指v2.0.0-GA和v2.0.1版本。如果Nebula Graph版本过低，请参见[升级 Nebula Graph 历史版本至 v{{nebula.release}}](upgrade-nebula-graph-to-200.md)。
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved

## RPM/DEB包升级步骤

1. 下载[RPM/DEB包](https://github.com/vesoft-inc/nebula-graph/releases/tag/v2.0.1)。
1. 下载[RPM/DEB包](https://github.com/vesoft-inc/nebula-graph/releases/tag/v{{nebula.release}})。

2. 停止所有Nebula Graph服务。详情请参见[管理Nebula Graph服务](../2.quick-start/5.start-stop-service.md#_1)。
2. 停止所有Nebula Graph服务。详情请参见[管理Nebula Graph服务](../../2.quick-start/5.start-stop-service.md)。

3. 执行如下命令升级：

Expand Down
162 changes: 79 additions & 83 deletions ...ployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-graph-to-200.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,69 +1,69 @@
# 升级 Nebula Graph 历史版本至 v2.0.0
# 升级 Nebula Graph 历史版本至 v{{nebula.release}}

## 升级限制
Nebula Graph历史版本指低于Nebula Graph v2.0.0-GA的版本，本文介绍如何升级历史版本至v{{nebula.release}}。

- 不支持轮转热升级，需完全停止整个集群服务。
!!! note

- 未提供升级脚本，需手动在每台服务器上依次执行。
Nebula Graph v2.0.0-GA或更新版本升级至v{{nebula.release}}，请参见[Nebula Graph v2.0.x升级至v{{nebula.release}}](upgrade-nebula-from-200-to-201.md)。

- **支持**如下版本的升级。
## 升级限制

- Nebula Graph [v1.2.0](https://github.com/vesoft-inc/nebula/releases/tag/v1.2.0) 升级至 [Nebula Graph v2.0.0](https://github.com/vesoft-inc/nebula-graph/releases/tag/v2.0.0)。
- 不支持轮转热升级，需完全停止整个集群服务。

- Nebula Graph [v2.0.0-RC1](https://github.com/vesoft-inc/nebula-graph/releases/tag/v2.0.0-rc1) 升级至 Nebula Graph 2.0.0。
- 未提供升级脚本，需手动在每台服务器上依次执行。

- **不支持**基于Docker容器（包括Docker Swarm，Docker Compose，K8s）的升级。
- **不支持**基于Docker容器（包括Docker Swarm、Docker Compose、K8s）的升级。

- 必须在原服务器上原地升级，不能修改原机器的IP地址、配置文件，不可更改集群拓扑。

- 硬盘空间要求：各机器硬盘剩余空间都需要是原数据目录的**三倍**。

- 已知会造成数据丢失的4种场景，和alter schema以及default value相关，具体见[github known issues](https://github.com/vesoft-inc/nebula-graph/issues/857)。
- 已知会造成数据丢失的4种场景，和alter schema以及default value相关，请参见[github known issues](https://github.com/vesoft-inc/nebula-graph/issues/857)。

- 所有的客户端均需要升级，通信协议不兼容。

- 升级时间大约需要30分钟（取决于具体配置），参见文末测试环境。
- 升级时间大约需要30分钟（取决于具体配置），请参见文末测试环境。

- 数据目录不要使用软连接切换，避免失效。

- 升级操作需要有sudo权限。

## 前置条件说明

### 旧版本安装目录
### 历史版本安装目录

默认情况下，旧版本安装的根目录为`/usr/local/nebula/`（下文记为 `${nebula-old}`）。默认配置文件目录为 `${nebula-old}/etc/`。
默认情况下，历史版本安装的根目录为`/usr/local/nebula/`（下文记为 `${nebula-old}`）。默认配置文件目录为 `${nebula-old}/etc/`。

- `${nebula-old}/etc/nebula-storaged.conf`文件中的`--data_path`参数指定了storaged数据目录的位置，其默认值为`data/storage`。

- `${nebula-old}/etc/nebula-metad.conf`文件中的`--data_path`参数指定了metad数据目录位置，其默认值为`data/meta`。

!!! Note

Nebula Graph的实际安装路径可能和本文示意不同，请使用实际路径。用户也可以用 `ps -ef | grep nebula` 中的参数来找到实际使用的配置文件地址。
Nebula Graph的实际安装路径可能和本文示例不同，请使用实际路径。用户也可以用 `ps -ef | grep nebula` 中的参数来找到实际使用的配置文件地址。

### 新版本安装目录

本文中新版本安装目录记为 `${nebula-new}` (例如 `/usr/local/nebula-new/`)。

```bash
> mkdir -p ${nebula-new}
```
# mkdir -p ${nebula-new}
```

## 升级步骤

1. **停止所有客户端访问**。也可以通过在每台服务器上关闭 graphd 服务避免脏写。在每台服务器上运行如下命令。

```bash
> ${nebula-old}/scripts/nebula.service stop graphd
```
# ${nebula-old}/scripts/nebula.service stop graphd
[INFO] Stopping nebula-graphd...
[INFO] Done
```

2. 停止旧版本服务。在每台服务器上运行如下命令。
2. 停止历史版本服务。在每台服务器上运行如下命令。

```bash
> ${nebula-old}/scripts/nebula.service stop all
```
# ${nebula-old}/scripts/nebula.service stop all
[INFO] Stopping nebula-metad...
[INFO] Done
[INFO] Stopping nebula-graphd...
Expand All @@ -82,33 +82,33 @@

1. 安装新的二进制文件。

- 如果从 rpm/deb 安装,从[release page](https://github.com/vesoft-inc/nebula-graph/releases)下载对应操作系统的安装包。
- 如果从 RPM/DEB 安装,从[release page](https://github.com/vesoft-inc/nebula-graph/releases)下载对应操作系统的安装包。

```bash
> sudo rpm --force -i --prefix=${nebula-new} ${nebula-package-name.rpm} # for centos/redhat
> sudo dpkg -i --instdir==${nebula-new} ${nebula-package-name.deb} # for ubuntu
```
# sudo rpm --force -i --prefix=${nebula-new} ${nebula-package-name.rpm} # for centos/redhat
# sudo dpkg -i --instdir==${nebula-new} ${nebula-package-name.deb} # for ubuntu
```

具体步骤可以见[从RPM/DEB安装](https://docs.nebula-graph.com.cn/2.0/4.deployment-and-installation/2.compile-and-install-nebula-graph/2.install-nebula-graph-by-rpm-or-deb/)。
具体步骤请参见[从RPM/DEB安装](../2.compile-and-install-nebula-graph/2.install-nebula-graph-by-rpm-or-deb.md)。

- 如果从源代码安装。具体步骤见[从源代码安装](https://docs.nebula-graph.com.cn/2.0/4.deployment-and-installation/2.compile-and-install-nebula-graph/1.install-nebula-graph-by-compiling-the-source-code/)。这里列出几个关键命令：
- 如果从源代码安装。具体步骤请参见[从源代码安装](../2.compile-and-install-nebula-graph/1.install-nebula-graph-by-compiling-the-source-code.md)。这里列出几个关键命令：

- clone 源代码

```bash
> git clone --branch v2.0.0 https://github.com/vesoft-inc/nebula-graph.git
```
# git clone --branch v{{nebula.release}} https://github.com/vesoft-inc/nebula-graph.git
```

- 设置 CMake

```bash
> cmake -DCMAKE_INSTALL_PREFIX=${nebula-new} -DENABLE_BUILD_STORAGE=on -DENABLE_TESTING=OFF -DCMAKE_BUILD_TYPE=Release -DNEBULA_COMMON_REPO_TAG=v2.0.0 -DNEBULA_STORAGE_REPO_TAG=v2.0.0 ..
```
# cmake -DCMAKE_INSTALL_PREFIX=${nebula-new} -DENABLE_BUILD_STORAGE=on -DENABLE_TESTING=OFF -DCMAKE_BUILD_TYPE=Release -DNEBULA_COMMON_REPO_TAG=v{{nebula.release}} -DNEBULA_STORAGE_REPO_TAG=v{{nebula.release}} ..
```

2. 拷贝配置文件。

```bash
> cp -rf ${nebula-old}/etc ${nebula-new}/
```
# cp -rf ${nebula-old}/etc ${nebula-new}/
```

4. 在曾经运行 metad 的服务器上（通常为3台），拷贝 metad 数据、配置文件到新目录。
Expand All @@ -117,28 +117,28 @@

在 `${nebula-old}/etc/nebula-metad.conf` 中找到 `--data_path` 项（其默认值为 `data/meta`）

- 如果旧版本配置**未更改** `--data_path` 项，则可以运行如下命令，将metad数据拷贝到新目录。
- 如果历史版本配置**未更改** `--data_path` 项，则可以运行如下命令，将metad数据拷贝到新目录。

```bash
> mkdir -p ${nebula-new}/data/meta/
> cp -r ${nebula-old}/data/meta/* ${nebula-new}/data/meta/
```
# mkdir -p ${nebula-new}/data/meta/
# cp -r ${nebula-old}/data/meta/* ${nebula-new}/data/meta/
```

- 如果旧版本配置更改了默认的 metad 目录，请根据实际目录拷贝。
- 如果历史版本配置更改了默认的 metad 目录，请根据实际目录拷贝。

- 拷贝并修改配置文件

- 编辑新的 metad 配置文件：

```bash
> vim ${nebula-new}/nebula-metad.conf
```
# vim ${nebula-new}/nebula-metad.conf
```

- [可选]增加配置项：

`--null_type=false`: 升级后的schema的属性是否要支持 [`NULL`](https://docs.nebula-graph.com.cn/2.0/3.ngql-guide/3.data-types/5.null/)，**默认为 true**。不希望支持 NULL 的话，设置为 false。此时，升级后的 Schema 如果要增加属性（ALTER TAG/EDGE）必须指定 [default 值](https://docs.nebula-graph.com.cn/2.0/3.ngql-guide/10.tag-statements/1.create-tag/)，否则会读不出数据。
`--null_type=false`: 升级后的Schema的属性是否要支持 [`NULL`](../../3.ngql-guide/3.data-types/5.null.md)，**默认为 true**。不希望支持 NULL 的话，设置为 false。此时，升级后的 Schema 如果要增加属性（ALTER TAG/EDGE）必须指定 [default 值](../../3.ngql-guide/10.tag-statements/1.create-tag.md)，否则会读不出数据。

`--string_index_limit=32`: 升级后 string 对应的[索引的长度](https://docs.nebula-graph.com.cn/2.0/3.ngql-guide/14.native-index-statements/1.create-native-index/)，不加的话系统默认为 64。
`--string_index_limit=32`: 升级后 string 对应的[索引的长度](../../3.ngql-guide/14.native-index-statements/1.create-native-index.md)，不加的话系统默认为 64。

!!! Note

Expand All @@ -147,17 +147,17 @@
5. 在每个 storaged 服务器上, 修改 storaged 配置文件。


+ [可选]如果旧版本 storaged 数据目录 `--data_path=data/storage` 不是默认值，有更改。
+ [可选]如果历史版本 storaged 数据目录 `--data_path=data/storage` 不是默认值，有更改。

```bash
> vim ${nebula-new}/nebula-storaged.conf
```
# vim ${nebula-new}/nebula-storaged.conf
```
`--data_path`设置为新的 storaged 数据目录地址。

+ 创建新版本 storaged 数据目录。

```bash
> mkdir -p ${nebula-new}/data/storage/
```
# mkdir -p ${nebula-new}/data/storage/
```

如果`${nebula-new}/etc/nebula-storaged.conf` 中的 `--data_path` 有改动，请按实际路径创建。
Expand All @@ -166,16 +166,16 @@

- 在每个 metad 的服务器上运行如下命令。

```bash
$ sudo ${nebula-new}/scripts/nebula.service start metad
```
# ${nebula-new}/scripts/nebula.service start metad
[INFO] Starting nebula-metad...
[INFO] Done
```

- 检查每个 metad 进程是否正常。

```bash
$ ps -ef |grep nebula-metad
```
# ps -ef |grep nebula-metad
```

- 检查 metad 日志`${nebula-new}/logs/` 下的 ERROR 日志。
Expand All @@ -188,8 +188,8 @@

在每个 storaged 服务器运行如下命令。

```bash
$ sudo ${nebula-new}/bin/db_upgrader \
```
# ${nebula-new}/bin/db_upgrader \
--src_db_path=<old_storage_directory_path> \
--dst_db_path=<new_storage_directory_path> \
--upgrade_meta_server=<meta_server_ip1>:<port1>[,<meta_server_ip2>:<port2>,...] \
Expand All @@ -198,35 +198,35 @@

参数说明：

- `--src_db_path`为**老版本**storaged的数据目录的绝对路径，多个目录用逗号分隔，不加空格。
- `--src_db_path`：**历史版本**storaged的数据目录的绝对路径，多个目录用逗号分隔，不加空格。

- `--dst_db_path`为**新版本**storaged的数据目录的绝对路径，多个目录用逗号分隔。逗号分隔的目录必须和`--src_db_path`中一一对应。
- `--dst_db_path`：**新版本**storaged的数据目录的绝对路径，多个目录用逗号分隔。逗号分隔的目录必须和`--src_db_path`中一一对应。

- `--upgrade_meta_server` 为步骤6中启动的所有新 metad 的地址.
- `--upgrade_meta_server` ：步骤6中启动的所有新 metad 的地址.

- `--upgrade_version`如果老版本为v1.2.0，则填写1；如果老版本为v2.0.0-RC，则填写2.不可填写其他数字。
- `--upgrade_version`：如果历史版本为v1.2.x，则填写1；如果历史版本为v2.0.0-RC，则填写2。不可填写其他数字。

!!! danger

请勿颠倒`--src_db_path`和`--dst_db_path`的顺序，否则会升级失败且破坏老版本的数据。
请勿颠倒`--src_db_path`和`--dst_db_path`的顺序，否则会升级失败且破坏历史版本的数据。

例如，从 v1.2.0 升级：
例如，从 v1.2.x 升级：

```bash
$ sudo /usr/local/nebula_new/bin/db_upgrader \
```
# /usr/local/nebula_new/bin/db_upgrader \
--src_db_path=/usr/local/nebula/data/storage/data1/,/usr/local/nebula/data/storage/data2/ \
--dst_db_path=/usr/local/nebula_new/data/storage/data1/,/usr/local/nebula_new/data/storage/data2/\
--upgrade_meta_server=192.168.8.14:45500,192.168.8.15:45500,192.168.8.16:45500 \
--upgrade_meta_server=192.168.*.14:45500,192.168.*.15:45500,192.168.*.16:45500 \
--upgrade_version=1
```

从 v2.0.0-RC 升级：

```bash
$ sudo /usr/local/nebula_new/bin/db_upgrader \
```
# /usr/local/nebula_new/bin/db_upgrader \
--src_db_path=/usr/local/nebula/data/storage/ \
--dst_db_path=/usr/local/nebula_new/data/storage/ \
--upgrade_meta_server=192.168.8.14:9559,192.168.8.15:9559,192.168.8.16:9559 \
--upgrade_meta_server=192.168.*.14:9559,192.168.*.15:9559,192.168.*.16:9559 \
--upgrade_version=2
```

Expand All @@ -237,9 +237,9 @@

8. 在每个storaged服务器启动新版本的storaged服务。

```bash
$ sudo ${nebula-new}/scripts/nebula.service start storaged
$ sudo ${nebula-new}/scripts/nebula.service status storaged
```
# ${nebula-new}/scripts/nebula.service start storaged
# ${nebula-new}/scripts/nebula.service status storaged
```

!!! Note
Expand All @@ -248,9 +248,9 @@

9. 在每个 graphd 服务器启动新版本的 graphd 服务。

```bash
$ sudo ${nebula-new}/scripts/nebula.service start graphd
$ sudo ${nebula-new}/scripts/nebula.service status graphd
```
# ${nebula-new}/scripts/nebula.service start graphd
# ${nebula-new}/scripts/nebula.service status graphd
```
!!! Note

Expand All @@ -269,23 +269,23 @@

!!! Note

不可使用v2.0.0之前的 nebula console。
历史版本Nebula Console可能会有兼容性问题。

11. 升级其他客户端。

所有的客户端都必须升级到对应 v2.0.0 版本。包括但不限于[studio](https://github.com/vesoft-inc/nebula-docker-compose), [python](https://github.com/vesoft-inc/nebula-python), [java](https://github.com/vesoft-inc/nebula-java), [go](https://github.com/vesoft-inc/nebula-go), [c++](https://github.com/vesoft-inc/nebula-cpp), [flink-connector](https://github.com/vesoft-inc/nebula-flink-connector), [spark-util](https://github.com/vesoft-inc/nebula-spark-utils), [benchmark](https://github.com/vesoft-inc/nebula-bench)。请找到各 repo 对应的 v2.0.0 branch。
所有的客户端都必须升级到支持Nebula Graph v{{nebula.release}} 的版本。包括但不限于[Studio](https://github.com/vesoft-inc/nebula-docker-compose), [Python](https://github.com/vesoft-inc/nebula-python), [Java](https://github.com/vesoft-inc/nebula-java), [go](https://github.com/vesoft-inc/nebula-go), [C++](https://github.com/vesoft-inc/nebula-cpp), [Flink-connector](https://github.com/vesoft-inc/nebula-flink-connector), [Spark-util](https://github.com/vesoft-inc/nebula-spark-utils), [Benchmark](https://github.com/vesoft-inc/nebula-bench)。请找到各 repo 对应的 branch。

!!! Note

不兼容旧版本的通信协议。需重新源代码编译或者下载二进制包。
不兼容历史版本的通信协议。需重新源代码编译或者下载二进制包。

(运维)提醒：升级后的数据目录为`${nebula-new}/`。如有硬盘容量监控、日志 ELK 等，相应改动。
运维提醒：升级后的数据目录为`${nebula-new}/`。如有硬盘容量监控、日志、ELK 等，请做相应改动。

## 升级失败回滚

如果升级失败，请停止新版本的所有服务，启动旧版的所有服务。
如果升级失败，请停止新版本的所有服务，启动历史版本的所有服务。

所有周边客户端切换为**旧版**。
所有周边客户端也切换为**历史版本**。

## 附1：升级测试环境

Expand Down Expand Up @@ -319,17 +319,13 @@ Q：升级过程中是否可以通过客户端写入数据？

A：不可以。这个过程中写入的数据状态是未定义的。
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved

Q: 除了 v1.2.0 和 v2.0.0-RC 外，其他版本是否支持升级？

A: 未验证过。理论上 v1.0.0 - v1.2.0 都可以采用 v1.2.0 的升级版本。 v2.x 的日常研发版本(nightly)无升级方案。

Q: 升级完服务端后，客户端如何升级？
Q: 除了 v1.2.x 和 v2.0.0-RC 外，其他版本是否支持升级？

A：所有的客户端都必须升级到对应 v2.0.0 版本。包括但不限于 [console](https://github.com/vesoft-inc/nebula-console)，[studio](https://github.com/vesoft-inc/nebula-docker-compose)，[python](https://github.com/vesoft-inc/nebula-python)，[java](https://github.com/vesoft-inc/nebula-java)，[go](https://github.com/vesoft-inc/nebula-go)，[c++](https://github.com/vesoft-inc/nebula-cpp)，[flink-connector](https://github.com/vesoft-inc/nebula-flink-connector)，[spark-util](https://github.com/vesoft-inc/nebula-spark-utils)，[benchmark](https://github.com/vesoft-inc/nebula-bench)。请找到各repo对应的v2.0.0 branch（TODO： 部分branch还未发布）。不兼容旧版本的通信协议。
A: 未验证过。理论上 v1.0.0 - v1.2.0 都可以采用 v1.2.x 的升级版本。 v2.0.0-RC之前的日常研发版本（nightly）无升级方案。

Q: 如果某台机器只有 graphd 服务，没有 storaged 服务，如何升级？

A: 那只需要升级 graphd 对应的 binary （或者rpm包）。
A: 只需要升级 graphd 对应的 binary （或者RPM包）。

Q: 操作报错 `Permission denied`。

Expand Down