升级 NebulaGraph 至 3.3.0 版本¶

本文以 NebulaGraph 2.6.1 版本升级到 3.3.0 版本为例，介绍 NebulaGraph 2.x、3.x 版本升级到 3.3.0 版本的方法。

适用版本¶

本文适用于将 NebulaGraph 从 2.0.0 及之后的 2.x、3.x 版本升级到 3.3.0 版本。不适用于 2.0.0 之前的历史版本（含 1.x 版本）。如需升级历史版本，将其根据最新的 2.x 版本文档升级到最新的 2.x 版本，然后根据本文的说明升级到 3.x 版本。

Caution

如需从 2.0.0 之前的版本（含 1.x 版本）升级到 3.3.0，还需找到 3.3.0 版本文件中share/resources目录下的date_time_zonespec.csv文件，将其复制到 NebulaGraph 安装路径下的相同目录内。也可从 GitHub 下载该文件。

升级限制¶

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

未提供升级脚本，需手动在每台服务器上依次执行。

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

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

已知会造成数据丢失的 4 种场景，和 alter schema 以及 default value 相关，参见 github known issues。

部分升级操作需要有 sudo 权限。

升级影响¶

客户端兼容

升级后旧版本客户端将无法连接 NebulaGraph，需将所有客户端都升级到兼容 NebulaGraph 3.3.0 的版本。

配置变化

少数配置参数发生改变，详情参考版本发布说明和参数文档。

语法兼容

nGQL 语法有部分不兼容：
- 禁用YIELD子句返回自定义变量。
- FETCH、GO、LOOKUP、FIND PATH、GET SUBGRAPH语句中必须添加YIELD子句。
- MATCH 语句中获取点属性时，必须指定 Tag，例如从return v.name变为return v.player.name。

Caution

可能存在其它暂未发现的影响，建议升级前详细查看版本发布说明和产品手册，并密切关注论坛与 GitHub 的最新动态。

升级准备¶

根据操作系统和架构下载 NebulaGraph 3.3.0 版本的包文件并解压，升级过程中需要其中的二进制文件。下载地址参见 Download 页面。

Note

编译源码或者下载 RPM/DEB、TAR 包都可以获取新版二进制文件。

根据 Storage 和 Meta 服务配置中data_path参数的值找到数据文件的位置，并备份数据。默认路径为nebula/data/storage和nebula/data/meta。

Danger

升级时不会自动备份原有数据。务必手动备份数据，防止丢失。

备份配置文件。

统计所有图空间升级前的数据量，供升级后比较。统计方法如下：
1. 运行SUBMIT JOB STATS。
2. 运行SHOW JOBS并记录返回结果。

升级步骤¶

停止所有 NebulaGraph 服务。
```
<nebula_install_path>/scripts/nebula.service stop all
```
nebula_install_path代表 NebulaGraph 的安装目录。

storaged 进程 flush 数据要等待约 1 分钟。运行命令后可继续运行nebula.service status all命令以确认所有服务都已停止。启动和停止服务的详细说明参见管理服务。

Note

如果超过 20 分钟不能停止服务，放弃本次升级，在论坛或 GitHub 提问。

Caution

从 3.0.0 开始，支持插入无 Tag 的点。如果用户需要保留无 Tag 的点，在集群内所有 Graph 服务的配置文件（nebula-graphd.conf）中新增--graph_use_vertex_key=true；在所有 Storage 服务的配置文件（nebula-storaged.conf）中新增--use_vertex_key=true。
在升级准备中下载的包的目的路径下，用此处bin目录中的新版二进制文件替换 NebulaGraph 安装路径下bin目录中的旧版二进制文件。

Note

每台部署了 NebulaGraph 服务的机器上都要更新相应服务的二进制文件。
编辑所有 Graph 服务的配置文件，修改以下参数以适应新版本的取值范围。如参数值已在规定范围内，忽略该步骤。
- 为session_idle_timeout_secs参数设置一个在 [1,604800] 区间的值，推荐值为 28800。
- 为client_idle_timeout_secs参数设置一个在 [1,604800] 区间的值，推荐值为 28800。
这些参数在 2.x 版本中的默认值不在新版本的取值范围内，如不修改会升级失败。详细参数说明参见Graph 服务配置。
启动所有 Meta 服务。
```
<nebula_install_path>/scripts/nebula-metad.service start
```
启动后，Meta 服务选举 leader。该过程耗时数秒。

启动后可以任意启动一个 Graph 服务节点，使用 NebulaGraph 连接该节点并运行SHOW HOSTS meta和SHOW META LEADER，如果能够正常返回 Meta 节点的状态，则 Meta 服务启动成功。

Note

如果启动异常，放弃本次升级，并在论坛或 GitHub 提问。
启动所有 Graph 和 Storage 服务。

Note

如果启动异常，放弃本次升级，并在论坛或 GitHub 提问。
连接新版 NebulaGraph，验证服务是否可用、数据是否正常。连接方法参见连接服务。

目前尚无有效方式判断升级是否完全成功，可用于测试的参考命令如下：
```
nebula> SHOW HOSTS;
nebula> SHOW HOSTS storage;
nebula> SHOW SPACES;
nebula> USE <space_name>
nebula> SHOW PARTS;
nebula> SUBMIT JOB STATS;
nebula> SHOW STATS;
nebula> MATCH (v) RETURN v LIMIT 5;
```
也可根据 3.3.0 版本的新功能测试，新功能列表参见发布说明。

升级失败回滚¶

如果升级失败，停止新版本的所有服务，从备份中恢复配置文件和二进制文件，启动历史版本的服务。

所有周边客户端也切换为旧版。

FAQ¶

升级过程中是否可以通过客户端写入数据？¶

不可以。升级过程中需要停止所有服务。

升级过程中出现`Space 0 not found`。¶

当升级过程中出现Space 0 not found告警信息时，用户可以忽略这个信息。升级过程会从磁盘读取所有 Space ID，而0（路径为<nebula_storagepath>/data/storage/nebula/0）并不会存在磁盘上。Space 0 用来存储 Storage 服务的元信息，并不包含用户数据，因此不会影响升级。

如果某台机器只有 Graph 服务，没有 Storage 服务，如何升级？¶

只需要升级 Graph 服务对应的二进制文件和配置文件。

操作报错 `Permission denied`。¶

部分命令需要有 sudo 权限。

是否有工具或者办法验证新旧版本数据是否一致？¶

没有。如果只是检查数据量，可以在升级完成后再次运行SUBMIT JOB STATS和SHOW STATS统计数据量，并与升级之前做对比。

Storage `OFFLINE`并且`Leader count`是`0`怎么处理？¶

运行以下命令手动添加 Storage 主机：

ADD HOSTS <ip>:<port>[, <ip>:<port> ...];

例如：

ADD HOSTS 192.168.10.100:9779, 192.168.10.101:9779, 192.168.10.102:9779;

如果有多个 Meta 服务节点，手动ADD HOSTS之后，部分 Storage 节点需等待数个心跳（heartbeat_interval_secs）的时间才能正常连接到集群。

如果添加 Storage 主机后问题仍然存在，在论坛或 GitHub 提问。

为什么升级后用`SHOW JOBS`查询到的 Job 的 ID 与升级前一样，但 Job 名称等信息不同了？¶

NebulaGraph 2.5.0 版本调整了 Job 的定义，详情参见 Pull request。如果是从 2.5.0 之前的版本升级，会出现该问题。

有哪些语法不兼容 ?¶

A: 参见Release Note Incompatibility 部分。

最后更新: March 28, 2023