
![Nebula Operator](https://www-cdn.nebula-graph.com.cn/nebula-blog/Nebula-Operator.png)

# 从 NebulaGraph 的架构谈起

![NebulaGraph 架构图](https://www-cdn.nebula-graph.com.cn/nebula-blog/ng-architecture-drawio.png)

[NebulaGraph](https://github.com/vesoft-inc/nebula) 是一个高性能的分布式开源图数据库，从架构上可以看出，一个完整的 NebulaGraph 集群由三类服务组成，即 Meta Service, Query Service（Computation Layer）和 Storage Service（Storage Layer）。

每类服务都是一个由多副本组件组成的集群，在 Nebula Operator 中，我们分别称这三类组件为: Metad / Graphd / Storaged。

- Metad：主要负责提供和存储图数据库的元数据，并承担集群中调度器的角色，指挥存储扩容和数据迁移，leader 变更等运维操作。
- Graphd：主要负责处理 Nebula 查询语言语句（nGQL），每个 Graphd 都运行着一个无状态的查询计算引擎，且彼此间无任何通信关系。计算引擎仅从 Metad 集群中读取元信息，并和 Storaged 集群进行交互。同时，它也负责不同客户端的接入和交互。
- Storaged：主要负责 Graph 数据存储。图数据被切分成很多的分片 Partition，相同 ID 的 Partition 组成一个 Raft Group，实现多副本一致性。NebulaGraph 默认的存储引擎是 RocksDB 的 Key-Value 存储。

在了解了 NebulaGraph 核心组件的功能后，我们可以得出一些结论：

1. NebulaGraph 在设计上采用了存储计算分离的架构，组件间分层清晰，职责明确，这意味着各个组件都可以根据自身的业务需求进行独立地弹性扩容、缩容，非常适合部署在 Kubernetes 这类容器编排系统上，充分发挥 NebulaGraph 集群的弹性扩缩能力。
1. NebulaGraph 是一个较为复杂的分布式系统，它的部署和运维操作需要比较深入的领域知识，这带来了颇高的学习成本和负担。即使是部署运行在 Kubernetes 系统之上，有状态应用的状态管理、异常处理等需求，原生的Kubernetes 控制器也不能很好的满足，导致 NebulaGraph 集群不能发挥出它最大的能力。

因此，为了充分发挥 NebulaGraph 原生具备的弹性扩缩、故障转移等能力，也为了降低对 NebulaGraph 集群的运维管理门槛，我们开发了 Nebula Operator。

**Nebula Operator 是 NebulaGraph 在 Kubernetes 系统上的自动化部署运维插件**，依托于 Kubernetes 自身优秀的扩展机制，我们把 NebulaGraph 运维领域的知识，以 `CRD + Controller` 的形式全面注入到 Kubernetes 系统中，让 NebulaGraph 成为真正的云原生图数据库。

为了能够更好的理解 Nebula Operator 的工作原理，让我们先回顾一下什么是 Operator

# 什么是 Nebula Operator

Operator 并不是什么很新的概念，早在 2017 年，就有 CoreOS 公司推出了 Etcd Operator。Operator 的初衷是为了扩展 Kubernetes 功能，以更好的管理有状态应用，这得益于 Kubernetes 的两大核心概念：声明式 API 和控制循环（Control Loop)。


我们可以用一段伪代码来描述这一过程。
```go
在集群中声明对象X的期望状态并创建X
for {
  实际状态 := 获取集群中对象 X 的实际状态
  期望状态 := 获取集群中对象 X 的期望状态
  if 实际状态 == 期望状态 {
    什么都不做
  } else {
    执行事先规定好的编排动作，将实际状态调协为期望状态
  }
}
```
在 Kubernetes 系统内，每一种内置资源对象，都运行着一个特定的控制循环，将它的实际状态通过事先规定好的编排动作，逐步调整为最终的期望状态。


对于 Kubernetes 系统内不存在的资源类型，我们可以通过添加自定义 API 对象的方式注册。常见的方法是使用 CustomResourceDefinition（CRD）和 Aggregation ApiServer（AA）。Nebula Operator 就使用 CRD 注册了一个 "Nebula Cluster" 资源，和一个 "Advanced Statefulset" 资源。

在注册了上述自定义资源之后，我们就可以通过编写自定义控制器的方式来感知自定义资源的状态变化，并按照我们编写的策略和逻辑去自动地运维 NebulaGraph，让集群的实际状态朝着期望状态趋近。这也是 Nebula Operator 降低用户运维门槛的核心原理。

```yaml
apiVersion: nebula.com/v1alpha1
kind: NebulaCluster
metadata:
  name: nebulaclusters
  namespace: default
spec:
  graphd:
    replicas: 1
    baseImage: vesoft/nebula-graphd
    imageVersion: v2-preview-nightly
    service:
      type: NodePort
      externalTrafficPolicy: Cluster
    storageClaim:
      storageClassName: fast-disks
  metad:
    replicas: 3
    baseImage: vesoft/nebula-metad
    imageVersion: v2-preview-nightly
    storageClaim:
      storageClassName: fast-disks
  storaged:
    replicas: 3
    baseImage: vesoft/nebula-storaged
    imageVersion: v2-preview-nightly
    storageClaim:
      storageClassName: fast-disks
  schedulerName: nebula-scheduler
  imagePullPolicy: Always

```

我们在这里展示了一个简单的 Nebula Cluster 实例，如果你想要扩展 Storaged 的副本数量至 10，你只需要简单修改 `.spec.storaged.replicas` 参数为 10，剩下的运维操作则由 Nebula Operator 通过控制循环来完成。

至此，想必你已经对 NebulaGraph 和 Operator 有了一个初步的认知，接下来，让我们来列举目前 Nebula Operator 已经具备了哪些能力，让你能更加深刻的体会到使用 Nebula Operator 带来的一些实际好处。

- **部署、卸载**：我们将一整个 NebulaGraph 集群描述成一个 CRD 注册进 ApiServer 中，用户只需提供对应的 CR 文件，Operator 就能快速拉起或者删除一个对应的 NebulaGraph 集群，简化了用户部署、卸载集群的过程。
- **扩容、缩容**：通过在控制循环中调用 NebulaGraph 原生提供的扩缩容接口，我们为 Nebula Operator 封装实现了扩缩容的逻辑，可以通过 yaml 配置进行简单的扩容，缩容，且保证数据的稳定性。
- **原地升级**：我们在 Kubernetes 原生提供的 StatefulSet 基础上为其扩展了镜像原地替换的能力，它节省了 Pod 调度的耗时，并且在升级时，Pod 的位置、资源都不发生变化，极大提高了升级时集群的稳定性和确定性。
- **故障迁移**：Nebula Operator 会内部调用 NebulaGraph 集群提供的接口，动态的感知服务是否正常运行，一旦发现异常，会自动的去做故障迁移操作，并根据错误类型配有对应的容错机制。
- **WebHook**：一个标准的 NebulaGraph 最少需要三个 Metad 副本，如果用户错误地修改了此参数，可能会导致集群不可用，我们会通过 WebHook 的准入控制来检查一些必要参数是否设置正确，并通过变更控制来强制修改一些错误的声明，使集群始终能够稳定运行。

> 作者有话说：Hi，我是李梦捷，图数据库 NebulaGraph 的研发工程师，如果你对此文有疑问，欢迎来我们的 [NebulaGraph 论坛](https://discuss.nebula-graph.com.cn/)交流下心得~~

喜欢这篇文章？来来来，给我们的 [GitHub](https://github.com/vesoft-inc/nebula-graph) 点个 star 表鼓励啦~~ 🙇‍♂️🙇‍♀️ [手动跪谢]

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

Nebula Operator 是 NebulaGraph 在 Kubernetes 系统上的自动化部署运维插件。在本文，你将了解到 Nebula Operator 的特性及它的工作原理。

云上 NebulaGraph 自动化部署运维工具 —— Nebula Operator

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink01.png)

# 前言

本文由 NebulaGraph 实习生@王杰贡献。

最近 @Yener 开源了史上最大规模的中文知识图谱——[OwnThink](https://www.ownthink.com/)（链接：[https://github.com/ownthink/KnowledgeGraphData](https://github.com/ownthink/KnowledgeGraphData) ），数据量为 1.4 亿条。

本文介绍如何将这份数据快速导入图数据库 NebulaGraph，全过程大约需要 30 分钟。

# 中文知识图谱 OwnThink 简介

## 思知（OwnThink）

知识图谱是由 Google 在 2012 年提出来的一个概念。主要是用来**描述真实世界中存在的各种实体和概念，以及他们之间的关系**。在搜索引擎、问答机器人、知识抽取等多个领域有着诸多应用。

最近 Yener 开源了史上最大规模的中文知识图谱—— [OwnThink](https://www.ownthink.com/)（链接：[https://github.com/ownthink/KnowledgeGraphData](https://github.com/ownthink/KnowledgeGraphData)），数据量为 1.4 亿条。数据以 `(实体, 属性, 值)` 和 `(实体, 关系, 实体)` 混合的**三元组**形式存储，数据格式为 csv。


## 查看原始文件

由于 ownthink_v2.csv 数据过多，摘录部分数据为例：

```
红色食品,描述,红色食品是指食品为红色、橙红色或棕红色的食品。

红色食品,是否含防腐剂,否
红色食品,主要食用功效,预防感冒，缓解疲劳
红色食品,用途,增强表皮细胞再生和防止皮肤衰老
大龙湫,描述,雁荡山景区分散，东起羊角洞，西至锯板岭；南起筋竹溪，北至六坪山。
大龙湫,中文名称,大龙湫
大龙湫,外文名称,big dragon autrum
大龙湫,门票价格,50元
大龙湫,著名景点,芙蓉峰
姚明[中国篮球协会主席、中职联公司董事长],妻子,叶莉
```

这里的 `(红色食品,是否含防腐剂,否)` 就是典型的 `(实体, 属性, 值)` 形式的三元组数据; 而 `(姚明[中国篮球协会主席、中职联公司董事长],妻子,叶莉)` 是典型的 `(实体, 关系, 实体)` 形式的三元组数据。

# Step 1. 数据建模与清洗准备

## 建模

NebulaGraph 是一个开源的分布式图数据库（链接：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula)），相比 Neo4j 来说，它的主要特点是完全的分布式，因此**图数据库 NebulaGraph 适合处理数据量超过单机的场景**。

![github-nebula](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink02.png)

图数据库**通常支持的数据模型为有向属性图（directed property graph）**。图中的每个顶点（vertex）可以用标签（tag）来表示类型（Neo4j 叫做 Label），顶点和顶点之间的关系用边（edge）连接起来。每种 tag 和 edge 还可以带有属性。——然而，这些功能对于知识图谱的三元组数据没什么意义:

![modeling](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink03.png)

分析上图的三元组数据，发现无论是 `(实体, 属性, 值)` 形式的三元组数据，还是 `(实体, 关系, 实体)` 形式的三元组数据，每条三元组数据均可以建模成**两个点**和**一条边**的形式。前者三元组中的“**实体**”和“**值**”建模为**两个点**（起点、终点），“**属性**”建模为**一条边**，后者三元组中的两个“**实体**”也建模为**两个点**（起点、终点），“**关系**”建模为**一条边**.

而且，所有的点都是相同类型（取名叫`entity` ），只需要一个属性（叫 `name` )，所有的边也都是同一类型(取名叫 `relation` ），边上也只有一个属性（叫 `name` ）。

![modeling](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink04.png)

比如 `(大龙湫,著名景点,芙蓉峰)` 可以表示成下图这个样子：

![modeling](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink05.png)

## 数据清洗和预处理

按照前一节的分析，原始的每条**三元组数据**，还需要清洗**转换为两个点和一条边**才能变成属性图的模型。

### 下载清洗工具

本文测试的时候，使用的操作系统是 CentOS 7.5，工具由 Golang 语言编写而成。

你可以在这里（链接：[https://github.com/jievince/rdf-converter](https://github.com/jievince/rdf-converter)）下载这个简单的清洗工具源代码并编译使用。

该工具会把转换后的顶点的数据写入到 vertex.csv 文件、边数据写入到 edge.csv 文件。

说明：在测试过程中，发现有大量的重复点数据，所以工具里面也做了去重。完全去重后的点的数据大概是 4600 万条，完全去重后的边的数据大概是 1 亿 4000 万条。

清洗完的 `vertex.csv` 文件长这样：
```
-2469395383949115281,过度包装
-5567206714840433083,Over  Package
3836323934884101628,有的商品故意增加包装层数
1185893106173039861,很多采用实木、金属制品
3455734391170888430,非科学
9183164258636124946,教育
5258679239570815125,成熟市场
-8062106589304861485,"成熟市场是指低增长率,高占有率的市场。"
```

说明：每一行是一个顶点，第一列整型 `-2469395383949115281` 是顶点的 ID（叫做 `VID`），它是由第二列文字通过 `hash` 计算出来的，例如 `-2469395383949115281` 就是由 `std::hash("过度包装")` 计算出来的值。

清洗完的 `edge.csv` 文件:

```
3413383836870836248,-948987595135324087,含义
3413383836870836248,8037179844375033188,定义
3413383836870836248,-2559124418148243756,标签
3413383836870836248,8108596883039039864,标签
2587975790775251569,-4666568475926279810,描述
2587975790775251569,2587975790775251569,中文名称
2587975790775251569,3771551033890875715,外文名称
2587975790775251569,2900555761857775043,地理位置
2587975790775251569,-1913521037799946160,占地面积
2587975790775251569,-1374607753051283066,开放时间
```

说明：第一列是起点的 VID，第二列是终点的 VID，第三列是这条边的"**属性**"或者"**描述**"。

在本机完全去重的清洗程序运行时间大约是 6 分钟。

# Step 2. NebulaGraph 启动准备

## 下载和安装

登陆 GitHub 后，在这里（链接：[https://github.com/vesoft-inc/nebula/actions](https://github.com/vesoft-inc/nebula/actions)）找到 Nebula 的安装包。

![action](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink06.png)

找到你所用系统对应的下载链接：

![package](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink07.png)

笔者系统是 CentOS 7.5，下载 CentOS 7.5 最新的压缩包，解压后能找到 rpm 安装包 `nebula-5ace754.el7-5.x86_64.rpm`，注意 `5ace754` 是 git commit 号，使用时可能会有所不同。下载好后解压，输入下面命令进行安装，记得替换成新的 git commit：

```
$ rpm -ivh nebula-5ace754.el7-5.x86_64.rpm
```

### 启动 NebulaGraph 服务

在 `命令行 CLI` 输入下面命令启动服务

```
$ /usr/local/nebula/scripts/nebula.service start all
```

命令执行结果如下：

![result](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink08.png)

可以执行以下命令检查服务是否成功启动

```
$ /usr/local/nebula/scripts/nebula.service status all
```

命令执行结果如下：

![result](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink09.png)

## 连接 NebulaGraph 服务

输入下面命令连接 NebulaGraph：

```
$ /usr/local/nebula/bin/nebula -u user -p password
```

命令执行结果如下：

![result](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink10.png)

## 准备 schema 等元数据

NebulaGraph 的使用风格有点接近 MySQL，需要先准备各种元信息。

### 新建图空间 space

create space 的概念接近 MySQL 里面 create database。在 nebula console 里面输入下面这个命令。

```
nebula> CREATE SPACE test;
```

### 进入 test space

```
nebula> USE test;
```

### 创建点类型（entity）

```
nebula> CREATE TAG entity(name string);
```

### 创建边类型 (relation)

```
nebula> CREATE EDGE relation(name string);
```

最后简单确认下元数据是不是正确。

**查看 entity 标签的属性**：

```
nebula> DESCRIBE TAG entity;
```

结果如下：

![result](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink11.png)

**查看 relation 边类型的属性**：

```
nebula> DESCRIBE EDGE relation;
```

结果如下：

![result](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink12.png)

# Step 3. 使用 nebula-importer 导入数据

登陆 GitHub 进入 [https://github.com/vesoft-inc/nebula-importer](https://github.com/vesoft-inc/nebula-importer) ，nebula-importer 这个工具也是 Golang 语言写的，在这里下载并编译源代码。

![importer](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink13.png)

另外，准备一个 YAML 配置文件，告诉这个 importer 工具去哪里找 csv 文件。（可直接复制下面这段）

```yaml
version: v1rc1
description: example
clientSettings:
  concurrency: 10 # number of graph clients
  channelBufferSize: 128
  space: test
  connection:
    user: user
    password: password
    address: 127.0.0.1:3699
logPath: ./err/test.log
files:
  - path: ./vertex.csv
    failDataPath: ./err/vertex.csv
    batchSize: 100
    type: csv
    csv:
      withHeader: false
      withLabel: false
    schema:
      type: vertex
      vertex:
        tags:
          - name: entity
            props:
              - name: name
                type: string
  - path: ./edge.csv
    failDataPath: ./err/edge.csv
    batchSize: 100
    type: csv
    csv:
      withHeader: false
      withLabel: false
    schema:
      type: edge
      edge:
        name: relation
        withRanking: false
        props:
          - name: name
            type: string
```

说明：测试时候发现 csv 数据文件中有大量转义字符 (\\) 和换行字符 (\\r)，nebula-importer 也做了处理。

最后：开始导入数据 👏👏

```
go run importer.go --config ./config.yaml
```

执行过程如下：

![result](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink14.png)

可以看到, 本次导入 QPS 大约在 40 w/s。全部导入总耗时大约 15 min。

# Step 4. 随便读点什么试试

导入完毕后，我们可以使用 NebulaGraph 服务做一些简单的查询。回到 NebulaGraph 的`命令行 CLI` ：

```
$ /usr/local/nebula/bin/nebula -u user -p password
```

进入刚才导入的三元组数据的 test 空间：

```
nebula> USE test;
```

现在，我们可以做一些简单查询

- 例 1：与姚明有直接关联的边的类型和点的属性

```
(user@127.0.0.1) [test]> GO FROM hash("姚明[中国篮球协会主席、中职联公司董事长]") OVER relation  YIELD relation.name AS Name, $$.entity.name AS Value;
```

执行结果如下：

![command](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink15.png)

可以看到：本次查询返回 51 条数据，耗时 3 ms 左右；

- 例2：查询姚明和其妻子叶莉在三跳之内的所有路径

```
(user@127.0.0.1) [test]> FIND ALL PATH FROM hash("姚明[中国篮球协会主席、中职联公司董事长]")  TO hash("叶莉") OVER relation UPTO 3 STEPS; 
```

执行结果如下：

![command-result](https://www-cdn.nebula-graph.com.cn/nebula-blog/OwnThink16.png)

当数据量较大时，查找全路径/最短经之类的操作会比较耗时。可以看到：本次查询返回 8 条数据，说明姚明和其妻子叶莉在三跳之内共有 8 条直接或间接的关系。

# 总结

本篇文章涉及到的一些概念和链接：

- OwnThink 的中文知识图谱数据：[https://github.com/ownthink/KnowledgeGraphData](https://github.com/ownthink/KnowledgeGraphData)。它的数据以三元组形式保存为 csv
- NebulaGraph 是一个开源的图数据库，GitHub 地址：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula)，和 Neo4j 相比，它是分布式的
- 数据清洗工具，GitHub 地址：[https://github.com/jievince/rdf-converter](https://github.com/jievince/rdf-converter)。因为原始的图谱 ownthink_v2.csv 数据以三元组形式保存，并和一般图数据库的属性图模型略微有些不同，所以写了一个 Go 语言工具将原始 ownthink_v2.csv 变成 vertex.csv 和 edge.csv
- 数据导入工具，GitHub 地址：[https://github.com/vesoft-inc/nebula-importer](https://github.com/vesoft-inc/nebula-importer)。将清洗完的 vertex.csv 和 edge.csv 批量写入到 NebulaGraph。

## 后面的工作

- 调整 Nebula 的参数。似乎默认的日志级别和内存都不是很好，可以用下面这个命令关闭日志，这样导入性能可以好很多。

```
curl "http://127.0.0.1:12000/set_flags?flag=minloglevel&value=4"
```

- 写个对应的 Python 版本示例

## 附录

NebulaGraph GitHub 地址：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula) 

交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

> NebulaGraph：一个开源的分布式图数据库。

> GitHub：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula)

> 知乎：[https://www.zhihu.com/org/nebulagraph/posts](https://www.zhihu.com/org/nebulagraph/posts)

> 微博：[https://weibo.com/nebulagraph](https://weibo.com/nebulagraph)


本文介绍如何将知识图谱数据快速导入图数据库 Nebula Graph 中并做简单的 CRUD