跳转至

升级 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子句返回自定义变量。
    • FETCHGOLOOKUPFIND PATHGET 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/storagenebula/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 metaSHOW 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.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 STATSSHOW STATS统计数据量,并与升级之前做对比。

Storage OFFLINE并且Leader count0怎么处理?

运行以下命令手动添加 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