跳转至

升级 NebulaGraph 至 3.4.0 版本

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

适用版本

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

Caution

如需从 2.0.0 之前的版本（含 1.x 版本）升级到 3.4.0，还需找到 3.4.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.4.0 的版本。

  • 配置变化

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

  • 语法兼容

    nGQL 语法有部分不兼容：

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

  • 全文索引

    在升级部署了全文索引的 NebulaGraph 前，需要手动删除 Elasticsearch (ES) 中的全文索引。在升级后需要重新使用SIGN IN语句登录 ES 并重新创建全文索引。用户可通过 cURL 命令手动删除 ES 中全文索引。命令为curl -XDELETE -u <es_username>:<es_password> '<es_access_ip>:<port>/<fullindex_name>'，例如curl -XDELETE -u elastic:elastic 'http://192.168.8.223:9200/nebula_index_2534'。如果 ES 没有设置用户名及密码，则无需指定-u选项。

Caution

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

升级准备

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

    Note

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

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

    Danger

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

  • 备份配置文件。

  • 统计所有图空间升级前的数据量，供升级后比较。统计方法如下：

    1. 运行SUBMIT JOB STATS。
    2. 运行SHOW JOBS并记录返回结果。

升级步骤

  1. 停止所有 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。

  2. 在升级准备中下载的包的目的路径下，用此处bin目录中的新版二进制文件替换 NebulaGraph 安装路径下bin目录中的旧版二进制文件。

    Note

    每台部署了 NebulaGraph 服务的机器上都要更新相应服务的二进制文件。

  3. 编辑所有 Graph 服务的配置文件，修改以下参数以适应新版本的取值范围。如参数值已在规定范围内，忽略该步骤。

    • 为session_idle_timeout_secs参数设置一个在 [1,604800] 区间的值，推荐值为 28800。
    • 为client_idle_timeout_secs参数设置一个在 [1,604800] 区间的值，推荐值为 28800。

    这些参数在 2.x 版本中的默认值不在新版本的取值范围内，如不修改会升级失败。详细参数说明参见Graph 服务配置。

  4. 启动所有 Meta 服务。

    <nebula_install_path>/scripts/nebula-metad.service start

    启动后，Meta 服务选举 leader。该过程耗时数秒。

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

    Note

    如果启动异常，放弃本次升级，并在论坛或 GitHub 提问。

  5. 启动所有 Graph 和 Storage 服务。

    Note

    如果启动异常，放弃本次升级，并在论坛或 GitHub 提问。

  6. 连接新版 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.4.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 部分。

最后更新: July 6, 2023