升级 Nebula Graph 历史版本至 v2.0.0

升级限制

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

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

  • 支持如下版本的升级。

  • 不支持基于 docker 容器 (包括 docker swarm, docker-compose, k8s) 的升级。

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

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

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

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

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

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

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

前置条件说明

旧版本安装目录

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

  • 在 ${nebula-old}/etc/nebula-storaged.conf 中找到 --data_path 项，其默认值为 data/storage; 为 storaged 数据目录位置。

  • 在 ${nebula-old}/etc/nebula-metad.conf 中找到 --data_path 项，其默认值为 data/meta; 为 metad 数据目录位置。

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

新版本安装目录

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

  1. > mkdir -p ${nebula-new}

升级步骤

  1. 停止所有客户端访问。也可以通过在每台服务器上关闭 graphd 服务避免脏写。在每台服务器上运行如下命令。
  1. > ${nebula-old}/scripts/nebula.service stop graphd
  2. [INFO] Stopping nebula-graphd...
  3. [INFO] Done
  1. 停止旧版本服务。在每台服务器上运行如下命令。
  1. > ${nebula-old}/scripts/nebula.service stop all
  2. [INFO] Stopping nebula-metad...
  3. [INFO] Done
  4. [INFO] Stopping nebula-graphd...
  5. [INFO] Done
  6. [INFO] Stopping nebula-storaged...
  7. [INFO] Done

运行 ps -ef | grep nebula 检查所有 nebula 服务都已停止。storaged 进程 flush 数据可能要等待 1 分钟。

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

  1. 在每台服务器上运行如下命令。

    3.1 安装新的二进制文件

  • 如果从 rpm/deb 安装,从release page下载对应操作系统的安装包。
  1. > sudo rpm --force -i --prefix=${nebula-new}  ${nebula-package-name.rpm} # for centos/redhat
  2. > sudo dpkg -i --instdir==${nebula-new} ${nebula-package-name.deb} # for ubuntu

具体步骤可以见从RPM/DEB安装。

  • 如果从源代码安装。具体步骤见从源代码安装。这里列出几个关键命令：

    + clone 源代码

    1. > git clone --branch v2.0.0 https://github.com/vesoft-inc/nebula-graph.git

    + 设置 CMake

    1. > 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 ..

    3.2 拷贝配置文件

  1. > cp -rf ${nebula-old}/etc ${nebula-new}/
  1. 在曾经运行 metad 的服务器上（通常为3台），拷贝 metad 数据、配置文件到新目录。

  • 拷贝 metad 数据

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

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

    1. > mkdir -p ${nebula-new}/data/meta/
    2. > cp -r ${nebula-old}/data/meta/* ${nebula-new}/data/meta/

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

  • 拷贝并修改配置文件

    + 编辑新的 metad 配置文件：

    1.   ```bash
    2.   > vim ${nebula-new}/nebula-metad.conf
    3.   ```
    5.   * [可选]增加配置项：
    7.   `--null_type=false`: 升级后的schema的属性是否要支持 [`NULL`](https://docs.nebula-graph.io/2.0/3.ngql-guide/3.data-types/5.null/)，**默认为 true**。不希望支持 NULL 的话，设置为 false。此时，升级后的 schema 如果要增加属性（alter tag/edge)必须指定 [default 值](https://docs.nebula-graph.io/2.0/3.ngql-guide/10.tag-statements/1.create-tag/)，否则会读不出数据。
    9.    `--string_index_limit=32`: 升级后 string 对应的[索引的长度](https://docs.nebula-graph.io/2.0/3.ngql-guide/14.native-index-statements/1.create-native-index/)，不加的话系统默认为 64。

检查：每个 metad 都完成操作。

  1. 在每个 storaged 服务器上, 修改 storaged 配置文件。

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

    1. > vim ${nebula-new}/nebula-storaged.conf

    --data_path设置为新的 storaged 数据目录地址。

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

    1. > mkdir -p ${nebula-new}/data/storage/

    如果${nebula-new}/etc/nebula-storaged.conf 中的 --data_path 有改动，请按实际路径创建。

  2. 启动新版本的 metad 进程。

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

    1. $ sudo ${nebula-new}/scripts/nebula.service start metad
    2. [INFO] Starting nebula-metad...
    3. [INFO] Done

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

    1. $ ps -ef |grep nebula-metad

    - 检查 metad 日志${nebula-new}/logs/ 下的 ERROR 日志。

如果服务异常：请查看目录${nebula-new}/logs内的 metad 相关日志，并在论坛提交问题。放弃本次升级，在原目录正常启动 nebula 服务。

  1. 升级 storaged 数据格式。

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

    1. $ sudo ${nebula-new}/bin/db_upgrader  \
    2. --src_db_path=<old_storage_directory_path> \
    3. --dst_db_path=<new_storage_directory_path>  \
    4. --upgrade_meta_server=<meta_server_ip1>:<port1>[,<meta_server_ip2>:<port2>,...] \
    5. --upgrade_version=<old_nebula_version> \

    参数说明：

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

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

    警告: 两者顺序不要搞反了，否则会写坏旧版本的数据。

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

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

    例如，从 v1.2.0 升级：

    1. $ sudo /usr/local/nebula_new/bin/db_upgrader \
    2. --src_db_path=/usr/local/nebula/data/storage/data1/,/usr/local/nebula/data/storage/data2/ \
    3. --dst_db_path=/usr/local/nebula_new/data/storage/data1/,/usr/local/nebula_new/data/storage/data2/\
    4. --upgrade_meta_server=192.168.8.14:45500,192.168.8.15:45500,192.168.8.16:45500 \
    5. --upgrade_version=1

    从 v2.0.0-RC 升级：

    1. $ sudo /usr/local/nebula_new/bin/db_upgrader \
    2. --src_db_path=/usr/local/nebula/data/storage/ \
    3. --dst_db_path=/usr/local/nebula_new/data/storage/ \
    4. --upgrade_meta_server=192.168.8.14:9559,192.168.8.15:9559,192.168.8.16:9559 \
    5. --upgrade_version=2

    如果工具抛出异常请在论坛提交问题。放弃本次升级，关闭所有已经启动的 metad，在原目录正常启动 nebula 服务。

    检查：每个 storaged 服务器都完成数据升级。

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

    1. $ sudo ${nebula-new}/scripts/nebula.service start storaged
    2. $ sudo ${nebula-new}/scripts/nebula.service status storaged

    说明：如果有 storaged 未正常启动，请将日志${nebula-new}/logs/在论坛提交问题。放弃本次升级，关闭所有已经启动的 metad和storaged，在原目录正常启动 nebula 服务。

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

    1. $ sudo ${nebula-new}/scripts/nebula.service start graphd
    2. $ sudo ${nebula-new}/scripts/nebula.service status graphd

    说明：如果有graphd未正常启动，请将日志${nebula-new}/logs/在论坛提交问题。放弃本次升级，关闭所有已经启动的 metad,storaged,graphd. 在原目录正常启动 nebula 服务。

  3. 使用新版本Nebula Console 连接新的Nebula Graph，验证服务是否可用、数据是否正常。命令行参数，如 graphd 的 IP、端口都不变。

    1. nebula> SHOW HOSTS;
    2. nebula> SHOW SPACES;
    3. nebula> USE <space_name>
    4. nebula> SHOW PARTS;
    5. nebula> SUBMIT JOB STATS;
    6. nebula> SHOW STATS;

    禁止：不可使用v2.0.0之前的 nebula console。

  4. 升级其他客户端

所有的客户端都必须升级到对应 v2.0.0 版本。包括但不限于studio, python, java, go, c++, flink-connector, spark-util, benchmark。请找到各 repo 对应的 v2.0.0 branch。

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

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

升级失败回滚

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

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

附1：升级测试环境

本文测试升级的环境如下：

  • 机器配置：32核CPU、62 GB内存、SSD

  • 数据规模：Nebula Graph 1.2 版本 LDBC 测试数据 100 GB（1个图空间、24个分片、data目录 92 GB）

  • 并发参数：--max_concurrent=5、--max_concurrent_parts=24、--write_batch_num=100

升级共耗时21分钟（其中 compaction 耗时13分钟）。工具并发参数说明如下：

参数名称默认值
—max_concurrent5
—max_concurrent_parts10
—write_batch_num100

附2：Nebula Graph v2.0.0 代码地址和 commit id

地址commit id
graphd91639db
storaged 和 metad761f22b
commonb2512aa

FAQ

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

A：不可以。这个过程中写入的数据状态是未定义的。

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

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

Q: 升级完服务端后，客户端如何升级？

A：所有的客户端都必须升级到对应 v2.0.0 版本。包括但不限于 console, studio, python, java, go, c++, flink-connector, spark-util, benchmark。请找到各repo对应的v2.0.0 branch (TODO： 部分branch还未发布）。不兼容旧版本的通信协议。

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

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

Q: 操作报错 Permission denied。

A: 部分命令需要有 sudo 权限。

Q: 是否有 gflags 发生改变？

A: 目前已知的 gflags 改变整理在github issues.

Q: 删除数据重新安装，和升级有何不同？

A: v2.x 的默认配置（包括端口）与 v1.x 不同。升级方案沿用老的配置，删除重新安装沿用新的配置。

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

A：没有。