![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/images/blogs/2023.27th%20banner_%E7%94%BB%E6%9D%BF%201%20%E5%89%AF%E6%9C%AC.jpg)

在之前的《手把手教你用 NebulaGraph AI 全家桶跑图算法》中，除了介绍了 ngai 这个小工具之外，还提到了一件事有了 Jupyter Notebook 插件: [https://github.com/wey-gu/ipython-ngql](https://github.com/wey-gu/ipython-ngql)，可以更便捷地操作 NebulaGraph。

本文就手把手教你咋在 Jupyter Notebook 中，愉快地玩图数据库。

只要你仔细读完本文，一条 `%ngql MATCH p=(n:player)->() RETURN p` 命令就可以直接查询出数据，再接上 `%ng_draw` 就可以画出返回结果。

下面，进入今天的主菜——Jupyter Notebook 扩展：`ipython-ngql`。

其实，`ipython-ngql` 这个扩展断断续续地开发了两年，我一直没有开发完成。恰好之前有空，并完成了一直以来的心愿，把 `ipython-ngql` 重构并正式发布了。它除了完全适配 NebulaGrpah 3.x 所有查询之外，还支持了 Notebook 内的返回结果可视化。

在介绍 `ipython-ngql` 是什么之前，我先做个简单的 Jupyter Notebook 介绍，虽然大多数的 Python 开发都知道。

## 什么是 Jupyter Notebook

Jupyter Notebook / Jupyter Labs 项目最初起源自 IPython 这个项目，后者是一个命令行上的交互式 Python 解释环境。因为有很好的补全、高亮和丰富的扩展能力，IPython 很快就成为了 Python 的第一 IDLE 替代项目，并且后来衍生出来了可以在浏览器里做更多事情的笔记本模式。

Jupyter 的笔记本模式改变了数据科学和相关科研、工业领域里人们协作、开发、分享面向数据的工作方式。有了它，我们可以在一个笔记本中可复现、可分享地进行代码执行、科学计算、数据可视化等等操作，是数据科学家、科研工作者的非常喜欢的工具，而且它还早就引入了 Python 之外的很多其他语言作为执行内核支持。

因为在 Jupyter Notebook 中进行 NebulaGraph 的查询、计算、可视化一直是很多社区同学的心愿，在前阵子 NebulaGrpah AI Suite 的开发过程中，我并实现了 Jupyter 中方便进行 NetworkX / PySpark 的计算。既然有图计算了，索性我就把相关的查询、可视化功能一起做掉，并作为 Jupyter 的扩展一起发布出来给大家使用啦。

## ipython-ngql 的安装

因为 ipython-ngql 本文就是一个基于 Jupyter Notebook 的扩展，所以它的安装非常简单。只需要在 Jupyter Notebook 中执行 `%pip install ipython-ngql` ，再加载它就好：

```python
%pip install ipython-ngql
%load_ext ngql
```

然后，我们就可以用 `%ngql` 这个 Jupyter Magic word 连接 NebulaGraph 了：

```python
%ngql --address 127.0.0.1 --port 9669 --user root --password nebula #填入 ip 地址和 graphd 的端口号
```

当成功连接服务之后，`SHOW SPACES` 的结果会返回在 notebook cell 下。

除了上面的扩展安装方法之外，你可以从 Docker 桌面版的扩展市场里搜索 NebulaGraph，一键安装本地开发环境。安装完毕之后，进入 NebulaGraph Docker 扩展内部，点击 NebulaGraph AI ，点击 **Install NX Mode** 安装本地的 NebulaGraph + Jupyter Notebook 开发环境。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/jupyter-notebook/dd-extension-ai-playground.png)

## 数据查询

ipython-ngql 现在支持两种语法 `%ngql` 接单行查询和 `%%ngql` 接多行查询。

### 单行查询

例如：

```shell
%ngql USE basketballplayer;
%ngql MATCH (v:player{name:"Tim Duncan"})-->(v2:player) RETURN v2.player.name AS Name;
```

### 多行查询

例如：

```shell
%%ngql
ADD HOSTS "storaged3":9779,"storaged4":9779;
SHOW HOSTS;
```

## 渲染结果

在任意一个查询后面紧跟着一个 `%ng_draw` 指令，就可以把结果可视化渲染出来。像是这样：

```python
# one query
%ngql GET SUBGRAPH 2 STEPS FROM "player101" YIELD VERTICES AS nodes, EDGES AS relationships;
%ng_draw

# another query
%ngql match p=(:player)-[]->() return p LIMIT 5
%ng_draw
```

效果：

![render_result](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/jupyter-notebook/render_result.png)

此外，你的渲染的结果还会被保存为[单文件 html](https://github.com/wey-gu/ipython-ngql/blob/main/examples/nebulagraph_draw_match.html) ，方便我们可以内嵌到任意网页中。

像是下面，其实就是一个内嵌的页面：

![render_result](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/jupyter-notebook/result-zoom.gif)

## 高阶用法

下面，我们来展示一些便捷的高阶用法。比如 `%ngql help`，可以获得更多帮助信息。

### 操作查询结果为 pandas DF

你的每次查询，返回的结果会被存到 `_` 变量中，方便我们对它进行读取。像是这样：

![load_result](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/jupyter-notebook/load_result.png)

### 返回原始 ResultSet

ipython-ngql 默认返回的结果格式是 pandas DF，如果我们想在 Jupyter Notebook 中交互地调试 Python 的 NebulaGraph 应用代码，可以将返回结果设置为原始的 ResultSet 格式，方便直观进行 query 与结果解析。例如：

```python
In [1] : %config IPythonNGQL.ngql_result_style="raw"

In [2] : %%ngql USE pokemon_club;
    ...: GO FROM "Tom" OVER owns_pokemon YIELD owns_pokemon._dst as pokemon_id
    ...: | GO FROM $-.pokemon_id OVER owns_pokemon REVERSELY YIELD owns_pokemon._dst AS Trainer_Name;
    ...:
    ...:
Out[3]:
ResultSet(ExecutionResponse(
    error_code=0,
    latency_in_us=3270,
    data=DataSet(
        column_names=[b'Trainer_Name'],
        rows=[Row(
            values=[Value(
                sVal=b'Tom')]),
...
        Row(
            values=[Value(
                sVal=b'Wey')])]),
    space_name=b'pokemon_club'))

In [4]: r = _

In [5]: r.column_values(key='Trainer_Name')[0].cast()
Out[5]: 'Tom'
```

### 查询模板

除了上面那些功能，我还支持了模板功能，语法沿用了 [Jinja2](https://jinja.palletsprojects.com/) 的 `{{ variable }}`。详见这个例子：

![query_template](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/jupyter-notebook/query_template.png)

## 未来

后续，我打算增强可视化的自定义选项，也欢迎社区里的大伙来贡献新的 feature、idea。

项目的 repo 在 👉🏻[https://github.com/wey-gu/ipython-ngql](https://github.com/wey-gu/ipython-ngql)

手把手教你咋在 Jupyter Notebook 中，愉快地玩转 NebulaGraph 图数据库。

Jupyter Notebook 遇上 NebulaGraph，可视化探索图数据库

本文旨在帮助 NebulaGraph 新手快速了解查询语句调优，读懂查询计划。

nGQL 简明教程 vol.02 执行计划详解与调优 转至元数据结尾





![NebulaGraph 可视化产品新功能尝鲜](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/nebulagraph%20%E5%8F%AF%E8%A7%86%E5%8C%96%E4%BA%A7%E5%93%81_%E7%94%BB%E6%9D%BF%201.jpg)

## 一、NebulaGraph Explorer 
NebulaGraph Explorer 是一款可以通过 Web 访问的可视化图探索工具。基于 NebulaGraph 内核与图数据进行可视化交互，支持从复杂关系和大量数据中快速查找友邻关系、分析可疑目标、执行图计算分析，并以可视化的方式展示图数据。帮助用户轻松地进行业务数据的分析和探索，快速发现数据中的关联关系。

![NebulaGraph Explorer](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/1.png)
![NebulaGraph Explorer](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/2.png)

### 发版信息
**版本号**：NebulaGraph Explorer v3.2.0

**发版日期**：2022.11.08

### 可用性说明
NebulaGraph Explorer 为企业版产品，如需获取安装包，请联系我们。

- 点击开启 [Explorer 30 天免费试用](https://wj.qq.com/s2/10158890/69a8)

- 点击[云上快速开始（30 天免费）](https://computenest.console.aliyun.com/user/cn-hangzhou/serviceInstanceCreate?ServiceId=service-39f4f251e9484369a778&ServiceVersion=13&isTrial=true)

**部署环境**：支持 Linux 系统和 Ubuntu 系统，目前仅支持 x86_64 架构。提供 tar/deb/rpm 三种格式的包供安装部署，同时也支持在云上部署。

**浏览器兼容情况**：Chrome >= 84

**内核兼容情况**：兼容 NebulaGraph v3.3.0

### 亮点功能
本次发布的最新版本 v3.2.0 主要在产品易用性和安全性方面做了较大的提升。

易用性方面，一是优化了图查询+图计算+图交互式分析等方面的操作，包括可视化建模、iFrame 模式，二是在性能、加载速度上有了很大提升。

安全性方面，此版本开始支持 OAuth2.0 认证，进一步提升平台与数据安全性。

### 更新详情
#### 功能
- **图建模**

    - **Schema 草图**：支持直接在画板上通过拖拉方式设计 Schema，并一键应用至图空间，便于更加高效直观地建立业务场景模型
[图建模](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/3.png)

<video width="100%" height="500" controls>
  <source src="https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/%E5%B1%8F%E5%B9%95%E5%BD%95%E5%88%B62022-11-04%20%E4%B8%8B%E5%8D%881.19.02.mp4" type="video/mp4">
</video>

- **图查询**

    - **查询语句模版化**：支持在控制台直接将nGQL语句制作为模版，后续可直接调用模版，填入参数即可查询。

 <video width="100%" height="500" controls>
  <source src="https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/%E5%B1%8F%E5%B9%95%E5%BD%95%E5%88%B62022-11-04%20%E4%B8%8B%E5%8D%881.32.21.mp4" type="video/mp4">
</video>

- **图分析**
    - **边聚合**：支持对画布上起点、终点、边类型相同的边进行聚合，使得哪些点之间存在大量关系一目了然。并支持对聚合边的属性进行计算。

![图分析](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/4.png)

 <video width="100%" height="500" controls>
  <source src="https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/%E5%B1%8F%E5%B9%95%E5%BD%95%E5%88%B62022-11-04%20%E4%B8%8B%E5%8D%881.39.37.mp4" type="video/mp4">
</video>
   
   - **自定义图标库及点边样式**：内置十种不同类型图标分类，并支持上传自定义图标图片，使得图分析过程更加直观生动。
    
![图分析](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/5.png)
- **图计算**

    - **工作流添加 Node2Vec 算法**：新增图特征算法 Node2Vec，适用于节点功能相似性比较、节点结构相似性比较、社团聚类等场景。
    
- **可集成**

    - **iFrame 模式**：支持将画布直接 iframe 集成至第三方页面中使用，减少大量开发成本。

- **数据安全**

    - **数据库用户管理**：支持以可视化的方式管理数据库用户、对指定图空间授权等操作，隔离不同业务领域，保证数据安全。

![数据安全](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/6.png)
    - **OAuth 2.0 认证**：支持开启 OAuth2.0 认证，保证平台和数据安全，轻松进行企业管理。

- **体验优化**
    - **欢迎页改版**：按照使用途径改版欢迎页，降低使用门槛。

 ![体验优化](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/7.png)

    - **内置数据集 Demo**：内置新手和行业数据集，支持一键下载，快速开始体验。更多数据集敬请期待～
 
 <video width="100%" height="500" controls>
  <source src="https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/11%E6%9C%888%E6%97%A5.mp4" type="video/mp4">
</video>

#### 性能
- **相比上个版本，页面整体加载速度提升 200%**

#### 优化

- **图计算**
    - 安装包内置 Dag Controller，可通过命令直接启动 Dag Controller
    - 工作流对于缺失的入参，会提示手动输入
    - 工作流资源配置支持编辑
- **控制台**

    - 控制台支持添加注释
   - 控制台收藏夹内容支持在服务端保存
- **体验优化**

   - 可视化效果增加节点拖动动效
   - 图空间列表支持搜索图空间名
   - 新增白屏崩溃兜底页
#### 修复
- 修复右键面板点击后无法自动收起问题
- 修复添加筛选条件，画布自动缩放问题
- 修复大数据量下切换至3D模式，展示抖动问题
- 修复数据导入 int8、16、32 、fixed_string 数据类型错误的问题

## 二、NebulaGraph Studio 
NebulaGraph Studio 是一款可以通过 Web 访问的开源图数据库可视化工具，搭配 NebulaGraph 内核使用，可提供模式管理（schema）、数据导入、构图、编写 nGQL 查询等一站式服务。

![NebulaGraph Studio](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/8.png)

![NebulaGraph Studio](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/9.png)

### 发版信息
**版本号**：NebulaGraph Studio v3.5.0

**发版日期**：2022.11.08

### 可用性说明
点击[快速部署部署 NebulaGraph Studio](https://docs.nebula-graph.com.cn/3.3.0/nebula-studio/deploy-connect/st-ug-deploy/)

- 部署环境：Linux系统，目前仅支持 x86_64 架构。可以使用 Docker 服务、RPM 服务、tar 包和 DEB 包安装部署 Studio，并连接到 NebulaGraph 数据库。
- 浏览器兼容情况：Chrome >= 84
- 内核兼容情况：兼容 NebulaGraph v3.3.0

> NebulaGraph Explorer 在 Studio 的基础上增加了更强大的图探索和图计算功能，试用链接：[https://wj.qq.com/s2/10158890/69a8](https://wj.qq.com/s2/10158890/69a8)

### 亮点功能
本次发布的最新版本 v3.5.0 主要增加了 Schema 草图新功能，通过可视化方式帮助用户更加高效直观地建立业务场景模型。

### 更新详情
#### 功能

- **Schema 草图**：直接在画板上通过拖拉方式设计Schema，并一键应用至图空间，点边关系更加直观。功能演示详情可见上文 Explorer 对应内容。

![Schema 草图](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/10.png)

![Schema 草图](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/11.png)

#### 增强
- 欢迎页改版，内置数据集 demo：按照使用途径改版欢迎页，内置行业数据集，支持一键下载快速开始体验，新手友好，进一步降低使用门槛。
- 控制台支持添加注释
- 图空间列表支持搜索图空间名
- 收藏夹内容支持在服务端保存
- 新增白屏崩溃兜底页
#### 修复
修复数据导入 int8、16、32 、fixed_string 数据类型错误的问题


## 三、NebulaGraph Dashboard 
NebulaGraph Dashboard 是一款针对 NebulaGraph 开发的多集群可视化运维工具，可服务于 DBA 和运维人员进行日常多集群机器和服务的运维 & 监控管理工具。用户可以通过 Dashboard 快速创建或导入 NebulaGraph 集群并进行实时监控告警，同时还支持多种集群运维操作，如集群升级、扩缩容、备份恢复、服务起停等；此外，还可以通过集群诊断立即帮助定位问题所在，提供数据辅助分析，让集群运维管理工作更加简单直观。

![NebulaGraph Dashboard ](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/12.jpeg)

![NebulaGraph Dashboard ](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/visualization%20tool%20release%20note/13.jpeg)

### 发版信息：
**版本号**：NebulaGraph Dashboard v3.2.0

**发版日期**：2022.11.08

### 可用性说明
NebulaGraph Dashboard 分为企业版和社区版，企业版如需获取安装包，可点击[联系我们](https://www.nebula-graph.com.cn/contact)。

点击[快速部署 Dashboard 社区版]

点击申请 [Dashboard 企业版 30 天免费试用](https://wj.qq.com/s2/10158890/69a8)

点击[云上快速开始（30 天免费）](https://computenest.console.aliyun.com/user/cn-hangzhou/serviceInstanceCreate?ServiceId=service-39f4f251e9484369a778&ServiceVersion=13&isTrial=true)

- 部署环境：Linux 系统和 Ubuntu 系统，x86_64 架构（目前提供 tar/deb/rpm 三种格式的包供安装部署），同时支持云上部署。
- 浏览器兼容情况：Chrome >= 84
- 内核兼容情况：兼容 NebulaGraph v3.3.0

## 企业版 v3.2.0

### 亮点功能
本次发布的新版本主要围绕集群安全以及监控、告警能力做了提升。

集群安全方面，Dashboard 登录方式中新增支持 OAuth2.0 认证，使得当前 Dashboard SSO 登录中支持了 LDAP 和 OAuth2.0 两种方式。

监控告警方面，主要是新增了各服务单进程指标监控，以及一条告警规则中支持添加多个条件。

### 更新详情

#### 功能
- 集群安全
   - OAuth2.0 认证：单点登录方式增加支持 OAuth2.0 协议
#### 优化
- 监控

   - 新增服务单进程指标监控
   - 磁盘监控优化
   - 新增部分 storage 监控指标
- 告警
   - 支持配置多条件告警，条件同时满足时触发告警
   - 磁盘告警优化
- 安全
   - 支持 ssh 密钥连接方式
- 易用性
   - 包结构调整，保证通过 Dashboard 安装的 NebulaGraph 集群和单独安装部署的集群包结构一致
   - 新增展示各节点操作系统信息
   - 支持修改 prometheus、alertmanager 端口号
   - 支持搜索监控指标及查看指标详情
   - 支持服务运行日志分片以及设置日志保留天数
#### 修复
- 修复服务管理页面查看监控页面不跳转问题
- 修复服务监控无法设置基线问题
- 修复导入集群授权失败问题

## 社区版 v3.2.0 

- 磁盘监控优化
- 新增部分 storage 监控指标
- 新增服务单进程指标监控
- 新增集群信息总览
- 支持搜索监控指标及查看指标详情

---
NebulaGraph 的开源地址：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula) 觉得使用体验还不错的话，给我们的 GitHub 点个 ❤️ 鼓励下开源路上的我们呢~

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

可视化产品新版 v3.2.0 主要在产品易用性和安全性方面做了较大的提升，如可视化建模、iFrame 模式，且开始支持 OAuth2.0 认证。

NebulaGraph 可视化产品新功能尝鲜

在 Nebula 生态中，有 3 个 Spark 成员：Nebula Spark Connector、Nebula Exchange、Nebula Algorithm，如何方便地使用三者呢？甚至在自己的场景下组合应用？来一文了解它们吧。

一文了解 NebulaGraph 上的 Spark 项目


![隐藏在 graph-ocean 背后的星辰大海](https://www-cdn.nebula-graph.com.cn/nebula-blog/graph-ocean.jpg)

# 作者介绍

大家好，我是 Anyzm，graph-ocean（GitHub：https://github.com/nebula-contrib/graph-ocean）项目发起人，目前就职于 360数科，岗位是高级 JAVA 开发工程师。

介绍完自己，这里来介绍下 graph-ocean 是什么？

# graph-ocean 简介

graph-ocean 是一款基于 nebula-java 客户端的 ORM（Object Relational Mapping）框架，熟悉 ORM 的小伙伴应该都知道 ORM 是创建可在编程语言里使用的“虚拟对象数据库”，让开发人员更高效地开发业务。

而我将 Java ORM 取名为 graph-ocean 源自 Ocean 与 NebulaGraph 的 Nebula（星辰）相呼应，意为星辰大海。

# 为什要设计一款 Java ORM

社区用户如果对 360数科熟悉的话，读过我们技术团队写的《JanusGraph 到 NebulaGraph 迁移》（链接：https://discuss.nebula-graph.com.cn/t/topic/1172）便知道我们在 NebulaGraph 很早期便开始使用它，在官方正式发布 v1.0.0 之前就已经在测试环境跑起来了。

在 360数科使用 NebulaGraph v1.0.0 过程中，我们 Java 客户端是用枚举来呈列用到的 Tag 和 Edge 数据，而将 API 解析成 nGQL 的过程中也强依赖枚举，**对业务代码侵入性强**。

所以，在后来接触项目的过程中我就决心改变这种局面。

# 解决代码入侵问题

我们都知道无论是什么框架与数据库连接，框架最终都是会解析成数据库所能识别的语言。对于 NebulaGraph 而言，用户可以使用 openCypher，也可以使用 NebulaGraph 原生查询语言 nGQL。

在我们项目中习惯于使用 nGQL，所以将业务代码解析成 nGQL 这一步骤在使用 v1.0.0 的过程中已经完成了很大一部分。业务代码侵入性的特性是由于顶点和边的枚举所带来的，枚举的作用是定位 Tag 或者 Edge，而想要从实体类上无侵入地获取这些信息，我想到了模仿 JPA（Java Persistence API）注解的方式。

于是，graph-ocean 在脑海中便有了初步模样，实体类一旦确定，对应的 Tag 或者 Edge 应该也是确定的，所以可以用到缓存来提高性能。

![隐藏在 graph-ocean 背后的星辰大海](https://www-cdn.nebula-graph.com.cn/nebula-blog/graph-ocean-01.jpeg)

（整体设计图）

简单设计之后，graph-ocean 就诞生了。开发出来之后，我和同事们用起来都感觉很爽，于是便决定将框架开源出来反哺给社区。

# graph-ocean 特性

graph-ocean 可以让开发者更加优雅、更加灵活地对 NebulaGraph 读写，并且可以帮助我们快速地将实体和数据库数据实现互转（这也是 ORM 框架的特点），同时因为有缓存存在，所以性能方面也不必担心。

# graph-ocean 的简单使用

graph-ocean 是由 Java 注解、反射、缓存、字符串拼接、nebula-java 连接池、session 管理等部分组成的。使用者如果有熟练的反射和连接池的开发经验就可以快速上手了，如果没有也没关系，主要抓住 NebulaSessionPoolManager（session 管理）、GraphMapper（基础的数据库操作类）、@GraphEdge（边注解）、@GraphVertex（顶点注解）、@GraphProperty（属性注解）、GraphQuery（查询API）、QueryResult（查询结果）这几个类或者接口就可以了。

# graph-ocean 的未来规划

graph-ocean 目前还未支持 Nebula  Graph 所有的内置函数（不过也已经满足大部分业务场景），由于 graph-ocean 依赖 nebula-java，所以随着 nebula-java 的版本更替，graph-ocean 也需要长期维护版本问题。

由于 graph-ocean 目前基本是由我一人在维护，文档也还不齐全，还有很多需要完善的点。

所以，下阶段是逐步完善使用文档，以及完善 API，同时希望有更多志同道合的人一起参与进来，维护 [graph-ocean](https://github.com/nebula-contrib/graph-ocean) 这片星辰大海。

---

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

graph-ocean 是一款基于 nebula-java 客户端的 ORM，将 Java ORM 取名为 graph-ocean 是源自 Ocean 与 NebulaGraph 的 Nebula（星辰）相呼应，意为星辰大海。

隐藏在 graph-ocean 背后的星辰大海


![快速解决集群异常和机器性能波动](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story.jpg)

# 从集群性能波动讲起

前几天，我们收到某公司 Nebula 数据库维护人员小张同学的反馈：发现集群 A 性能波动，同样的语句有时查询快，但是有时慢，帮忙看看是机器还是服务本身的问题呢？

想到了小张同学之前安装过 Nebula Dashboard 社区版，便推荐他进去查看监控情况。小张进入平台后，查看当前机器的 CPU、内存、磁盘、网络情况，发现同之前相比并没有明显异常情况，机器们都在正常运行。如下图所示：

![Nebula Dashboard](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story-01.png)

但，你如果仔细查看这张图，会发现集群 A 个别时间段确实存在网络和 CPU 使用率飙升的问题。

于是，我们继续让小张再查看该集群的服务运行情况，发现在这段时间内查询数量会突然激增，而且有周期性。如下图：

![Nebula Dashboard](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story-02.png)

发现周期性问题之后，我们询问小张在这个时间段该集群的使用场景。经排查发现，小张同学在这个时间每天会有定期运行一个数据库 nGQL 执行脚本。经他重新 review 脚本逻辑，发现查询中涉及多跳查询并且跳数超过 5 跳。问题定位后，小张建议相关的业务同学对语句脚本进行了优化解决了资源波动问题。

# 让人头疼的集群问题

解决了这个问题，小张同学又向我们提出了新问题：我能及时感知集群内的服务和机器的异常情况吗？我是不是可以接入告警服务，通过钉钉、微信、短信方式告知服务异常？

碰巧的是，另一个公司团队的小刘也反馈了个异常问题：某个集群连接不上，不知道是不是服务挂了。而且对外业务流量入口现在已经关闭了，怎么排查问题呢？由于 Nebula Dashbaord 社区版并未提供查看集群状态管理功能，在我们发现服务的监控查询数确实都是 0 之后，建议小刘同学挨个检查机器。小刘检查之后，反应集群 A 的机器能正常登录，但挨个查看发现端口的 graphd 和 storaged 服务并不在线，存在服务异常情况。为了不影响业务正常运行，小刘需要一个个手动启动服务异常的机器，花费了他不少启停时间。经过这次之后，小刘说他打算写个集群快速启动脚本，不然每次手动启停太麻烦。

无独有偶，除了上面两个运维同学反馈的问题之外，其实，我们还收到了这样的反馈：流量小的情况下，集群正常运行；一旦流量超过某个阈值，便会发生服务连不上、连接超时、某个查询服务离线等等问题…一般来说，因为集群服务比例分布不合理、分片不均的情况，集群或存在某台机器一直处在高负载状态。以上面这位同学为例，他平时业务流量比较均衡，但最近刚好是某个活动期，参与了多项推广活动，流量骤升是平时流量的几百倍。基于这种情况，我们建议他对集群进行弹性扩容，增加 5 台服务以应对突发的大流量。这波活动过去之后，再缩容，节省成本。

其实集群除了弹性扩缩容问题之外，常见以下几类反馈：

1：如何快速创建集群，默认 3 节点配置就好？
2：我能看到某台集群某个时间段的操作记录吗?
3：我能删除某个集群，并回收资源吗？
4：昨天查看日志信息，我发现集群 B 的存储服务 storaged2 启停了一次，能帮忙排查是什么问题问题造成的吗？是否后续上生产环境也会出现？
5：graph 服务查不到，怎么定位问题？
6：集群的某个服务能查到，但是状态一直是退出状态，怎么快速拉起？

# 最终解决方案

基于用户的各种场景反馈，我们计划打造一款比 Dashboard 社区版更便捷管理 Nebula 数据库集群的工具——是的，它便是今天的主角 Nebula Dashboard 企业版，上面提到的那些集群问题以及性能波动问题，在新发布的 Nebula Dashboard v3.0 面前均不是问题：Nebula Dashboard 企业版，专治集群的疑难杂症。

为了让数据库运维、DBA 同学更方便地管理 Nebula 数据库集群，基于社区版的 Nebula Dashboard 我们扩展多个功能场景，这里可以简单介绍下部分功能，更多信息可以关注我们下周的 Dashboard v3.0 Demo SHOW 直播和官方介绍哟~

## 简化运维

提到简化操作，肯定得有对快速部署/导入集群功能的支持；再者，加上扩缩容，这样你就不用关心复杂繁琐的 shell 命令就能完成加减机器操作。最后，加入可视化元素更直观地了解集群机器和服务分布情况。

![Nebula Dashboard](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story-03.png)

## 科学的监控&告警

此外，企业版 Nebula Dashboard 优化监控总览，以便更灵活、科学地监控服务。它支持对监控数据规则的自定义配置，并接入异常通知可及时同步异常情况给指定接收人，默认通知平台提示和邮件通知提供了 Webhooks 用来支持快速对接钉钉、企业微信等第三方通信平台；

![Nebula Dashboard](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story-04.png)

![Nebula Dashboard](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story-05.png)

## 服务/节点的可视化操作

在企业版 Nebula Dashboard 中还支持对服务/节点可视化管理，实时显示服务状态。此外，Dashboard 企业版还支持快速启停，再也不用挨个上故障机器手动启动服务。最后，Nebula Dashboard 企业版结合机器信息展示了集群服务的分布情况、类型，运行路径等信息，以便你更好地操作集群；

![Nebula Dashboard](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story-06.jpeg)

## And More...

此外，我们还有许多实用的功能：

* 集群诊断：不但可以对问题集群进行问题定位，还可以对亚健康集群进行诊断分析，根据报告指定更好的维护计划；
* 可视化大屏：数据投在大屏幕上，实时关注集群，特别是需要压测和活动场景时更能直观感受集群的运行负载；
* 查看集群元数据信息：查看 leader、partition 分布，并支持 BALANCE 操作，还有其他服务运行的元数据信息展示等；
* 集群配置更新：检测集群配置，并自定义修改；
* 账号和权限管理体现：邀请多人同时管理，支持多集群权限管理；

![Nebula Dashboard](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashboard-story-07.png)

最后，慢查询治理、一键数据备份 / 恢复 / Nebula 集群升级、job 管理、单进程监控、黑匣子等其他功能已在 Nebula Dashboard 企业版迭代计划中，感兴趣同学可以多关注下 Dashboard 企业版的后续版本发布。

欢迎访问 [https://wj.qq.com/s2/9437467/b3b1/](https://wj.qq.com/s2/9437467/b3b1/) 申请试用 Nebula Dashboard，并给我们提产品反馈建议，以便更好地完善 Nebula Dashboard 服务大家的集群运维~ btw，目前 Nebula Dashboard 试用期延长至 30 天，记得来体验它呀。

---

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

如何快速解决线上集群的异常故障，本文给你带来一个新思路。

快速解决集群异常和机器性能波动


![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive.jpg)

在 #云原生# 主题分享中，来自 Nebula 云组的 Cloud 专家乔雷同大家分享云的相关知识，本文整理自该次[主题直播](https://www.bilibili.com/video/BV1cY4y1v7ZS)。

# 云原生是什么

![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive-01.png)

这里简单介绍下云原生是什么，包括 DBaaS 又是什么？它在云的整套体系内又处于一个什么样的层级？

云原生从本质上来说，是一个不断演进的技术理念。一开始并不存在云原生这一概念，它从早期的虚拟化 VM 演进到容器化，再发展到到今天的 FaaS，逐步发展成一整套体系化的事物。换而言之，云原生便是将基础设施打包在一起构建成的整套技术，而这套技术在不断地向周边延伸。可以看下云原生金字塔这幅图，IaaS 层基于硬件虚拟化提供存储、计算、网络，安全防火墙等产品；再上层是 CaaS 层，基于 Kubernetes 编排系统提供容器化产品；最上层是基于云原生理念构建的应用服务，整套组合构成了云原生概念体系。

某种技术产生一定是服务某项业务，所以我们要明白，云原生最终要服务于什么？云原生是希望更好地将业务同基础设施进行解耦，让大家更专注于业务层面的开发，无需去关心运维操作，比如：机器资源不够；流量爆发时，进行资源的扩容；流量高峰期过后进行缩容…这些常见的运维操作都是可以把它沉淀到整个基础设施体系内的。

# DBaaS 是什么

DBaaS 是依托云原生技术体系内的一个概念，就是 Database as a Service。DBaaS 的理念是希望规模化我们理解的单机版数据库应用技术，使其用起来更简洁、更轻量，让用户感受到开箱即用、用完即走。虽然用户是用完即走，但 DBaaS 的平台运行也是要依托于这套云原生体系，所以我们可以把 DBaaS 依托在 PaaS 层上构建，使用容器的相关技术使数据库具备快速弹性的能力，使用硬件虚拟化技术，提升数据库的性能，这些技术组合使用作为 DBaaS 平台的基座。

# NebulaGraph Cloud

下面结合 NebulaGraph 的 DBaaS 产品来直观地讲解下 DBaaS 平台应该是什么样子。

![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive-02.png)

上图为 DBaaS 平台架构，用户角色分为云用户、运营人员、运维人员、开发人员。DBaaS 平台是面向多类人群的，既面向云用户，也面向运营人员、开发运维人员。平台会针对不同的用户角色呈现不同的视图。
举个例子，云用户通过简单的操作点击、选择所需规格实例之后，会有一套完整的流水线作业创建实例并初始化配置，实例就绪后用户可以登录到 Portal 进行图探索、图查询操作，但是实例如何创建、节点如何扩容、数据如何备份用户是无感知的。这里也体现了 DBaaS 概念中很重要的一点，通过 DBaaS 平台将数据库应用跟基础设施分离，用户尽可能地关注数据库层面的操作，数据库运维管理等复杂的工作全部都由 DBaaS 服务商来完成。这样，用户使用 NebulaGraph 的时候会更加方便。

## NebulaGraph Cloud 实例

![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive-03.png)

上图为 NebulaGraph 实例创建后，登录可查看到的视图，在左侧的菜单栏可以针对创建的实例进行数据库层面的操作，比如权限管理或者用户管理。
在上图所示的【Applications】页面，页面中罗列了社区用户比较熟悉的 3 款产品：Nebula Studio、Nebula Dashboard、Nebula Explorer，点击上图的【Open】即可登录到对应的应用连接图数据库进行操作。

如果你想更简洁地通过类似终端的方式来使用 NebulaGraph，在 Connectivity 界面我们对接了 Azure 的 VLink，你可以感受到一个直连终端的体验。

## NebulaGraph Cloud 的应用

![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive-04.gif)

可以直观地感受到，其实在云上使用 Nebula Explorer 和本地部署一套可视化 Nebula Explorer 组件，体验并无差别。

![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive-05.png)

上图为另外一个可视化产品——Nebula Dashboard 展示的监控数据大盘，可以通过数据大盘看到整个集群的机器状况，你也可以基于 Nebula Dashboard 进行简单的运维操作管理。

# NebulaGraph Cloud 背后的 Operator

![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive-06.png)

整套 NebulaGraph Cloud 体系基于 K8s 生态实现，通过 Nebula Operator 管理数据库产品。支持下列功能：

* 实例创建、删除
* 实例扩容、缩容
* 实例滚动升级
* 实例备份恢复（开发中）
* 实例监控、告警
* 实例故障自愈
* 实例日志查看
* 实例配置参数变更

基于上述产品规划，可将运维人员可能遇到的部署、升级问题，比如：通过 rpm 包安装了 NebulaGraph，修改配置文件之后启动失败，需要捞取日志定位问题；某个机器数据库版本过低需要升级版本…交由 Nebula Operator 自动完成，节省运维人力。目前来说，NebulaGraph Cloud 和 Nebula Operator 都处于持续迭代中，如果你有其他的产品建议可以前往：https://discuss.nebula-graph.com.cn/ 同我们交流。

# NebulaGraph Cloud 背后的基础设施

![云原生 on nLive：云上 NebulaGraph](https://www-cdn.nebula-graph.com.cn/nebula-blog/cloud-native-on-nlive-07.png)

为了将云服务器、网络等云端资源实现安全自动化的创建、配置和组装，这里使用了基础设施及代码（IaC）工具 。不仅仅是上图展示的 Terraform，每个云厂商都提供相对应的产品。像 Azure 的 ARM 模版，AWS 的 Cloud information，但每个云厂商的模版语言并非是通用语言，而是类似 DSL 的语言。如果要多云对接的话，可以使用 Terraform 定义成一套作业流水模板，在初始化基础设施后，再基于此搭建 DBaaS 平台。

# 社区用户的云交流

这里摘录了部分社区用户的提问，你可以观看视频：[https://www.bilibili.com/video/BV1rR4y1T73V](https://www.bilibili.com/video/BV1rR4y1T73V) 或文末的视频查看本次所有的互动提问。

## NebulaGraph Cloud 解决了什么问题

目前同大家见面的 NebulaGraph Cloud 其实是一个 DBaaS 平台，采用全托管模式，用户通过简单的配置在云市场（目前是 Azure）订阅服务，DBaaS 用户为用户创建一整套数据库产品，用户登陆账户即可使用图数据库 NebulaGraph。在未来规划中，会推出半托管的产品，即用户在最近的云租户下选择 Nebula 官方提供的 Nebula 模版，模版里提供了相关的数据库配置参数，通过参数来起对应的 graph、storage、meta 节点，所有相关的数据由用户拥有，可对其进行管理。

总的来说，NebulaGraph Cloud 是屏蔽同业务无关的操作，专注于业务层面的开发，繁琐的部署、运维工作交给 NebulaGraph Cloud 实现。

## NebulaGraph Cloud 如何收费

需要根据你的使用方式来选择，如果采用 OP 的方式，可以咨询商务同学如何购买 license；如果选择开箱即用的方式，并拥有 Azure 账号，可以访问 Azure 的 MarketPlace 订阅产品，目前 Azure NebulaGraph Cloud 3 折优惠中：[https://azuremarketplace.microsoft.com/en-us/marketplace/apps/vesoftcompanylimited1625556994617.nebula_graph_cloud?tab=Overview](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/vesoftcompanylimited1625556994617.nebula_graph_cloud?tab=Overview)

## NebulaGraph Cloud 的未来规划

今年年底之前，会对接国内大家比较熟悉的云厂商，比如阿里云、腾讯云、华为云…，海外的话，我们也会争取在 AWS 上线 NebulaGraph Cloud。

---

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

![关注公众号](https://www-cdn.nebula-graph.com.cn/nebula-blog/WeChatOffical.png)


云原生是什么？DBaaS 是什么？NebulaGraph Cloud 又是什么？在本文，来自 Nebula 云组的 Cloud 专家乔雷同大家分享云的相关知识。

云原生 on nLive：云上 NebulaGraph


![NebulaGraph DBaaS 产品 NebulaGraph Cloud 已经在 Azure Marketplace 上线啦](https://user-images.githubusercontent.com/90186547/158126069-7b936ffd-0ed5-46eb-ad5e-4c6b4a131545.jpg)

NebulaGraph DBaaS 产品 NebulaGraph Cloud 已经在 Azure Marketplace 与大家正式见面了！ 

NebulaGraph Cloud 支持在 Azure 云平台上一键部署 NebulaGraph，屏蔽了数据库部署、性能调优、运维等繁杂过程，并快速扩展计算、存储等资源。同时，NebulaGraph Cloud 集成了多款 Nebula 周边可视化图数据库管理工具，可一键玩转图数据库。

![NebulaGraph Cloud 支持在 Azure 云平台上一键部署 NebulaGraph](https://user-images.githubusercontent.com/90186547/158095798-71f90b16-17fd-4410-9606-d87a24ff1ce2.png)

# NebulaGraph Cloud 特性

* ### 多样化配置

NebulaGraph Cloud 为用户提供多种配置选择，可视情况选择 Storage Engine 和 Query Engine 对应机型和磁盘大小满足您多样的业务需求。配合业务发展需要，您可随时创建或停止 NebulaGraph 实例。如果您想保证服务的高可用，建议选择至少 2 个 Query Engine 和 3 个 Storage Engine。

![NebulaGraph Cloud 为用户提供多种配置选择](https://user-images.githubusercontent.com/90186547/158096003-49a55dda-ff1d-4b08-a348-647e224c8752.png)

* ### 便捷安全的 Solution 管理

Solution 指运行在 NebulaGraph Cloud 上的 NebulaGraph 数据库。您可在 【Solution info】中随时查看您的订阅信息、执行日志，以及执行停止或转移 Solution 操作。NebulaGraph Cloud 内置多种角色，您可以为指定图空间设定不同角色权限的数据库用户，实现权限管理，保证业务数据安全。

![NebulaGraph Cloud 便捷安全的 Solution 管理](https://user-images.githubusercontent.com/90186547/158096136-b4a903e6-63b7-4cd8-bff6-4f499a6b0160.png)

![NebulaGraph Cloud 便捷安全的 Solution 管理](https://user-images.githubusercontent.com/90186547/158096339-11ab5ea2-7bd1-4ae3-b5cd-cff353457822.png)

* ### 集成图数据库管理工具

在 NebulaGraph Cloud 中，您不仅可以使用 NebulaGraph 内核的功能，还可以使用我们提供的一系列完整配套周边工具，包括 Nebula  Studio， Nebula Explorer，和 Nebula Dashboard。您可以利用它们轻松导入图数据，进行图探索分析以及集群全生命周期管理，体验更便捷的一站式云端服务。

![NebulaGraph Cloud 集成图数据库管理工具](https://user-images.githubusercontent.com/90186547/158096434-48d63b86-2c14-49a8-972c-fd24b60fff63.png)

![NebulaGraph Cloud 集成图数据库管理工具](https://user-images.githubusercontent.com/90186547/158096478-b8607ba5-9725-4b68-9658-891c080dfee9.png)

![NebulaGraph Cloud 集成图数据库管理工具](https://user-images.githubusercontent.com/90186547/158096526-69710448-0d28-4748-9d1c-c9b9039d6500.png)

* ### 安全可靠的服务保障

使用 NebulaGraph Cloud 创建的集群自动采用 Raft 协议，结合云厂商提供的同城多机房功能，实现数据冗余备份，保证云计算基础框架的高可用性、数据的可靠性以及云服务器的高可用性。同时，NebulaGraph Cloud 配有技术专家提供技术支持，以便在线快速响应用户的问题反馈。

![NebulaGraph Cloud 安全可靠的服务保障](https://user-images.githubusercontent.com/90186547/158096626-2ca5909a-18b1-4744-8f27-7633d76b9ce6.png)

# 限时公测 3 折优惠

NebulaGraph Cloud 的公测截止于 2022 年 3 月 31 日 ，在公测期间购买 NebulaGraph Cloud 服务可以享受到公测阶段的独有优惠：**全面 3 折优惠**，最低配置价格低约为 $ 0.35 / 小时。

距离即用即启，用完即走的图数据库服务，就差一个 NebulaGraph Cloud !

NebulaGraph Cloud 可选机型及其价格参见下图配置选择，更多详情请见 Azure 定价页面：[NebulaGraph Cloud Pricing](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/vesoftcompanylimited1625556994617.nebula_graph_cloud?tab=PlansAndPrice)

![NebulaGraph Cloud 限时公测 3 折优惠](https://user-images.githubusercontent.com/90186547/158096889-e638e572-05b2-4c7e-ae12-a8d98b00a92a.png)

# 如何使用 NebulaGraph Cloud？

在您的 Azure 控制面板搜索 NebulaGraph Cloud 可找到 NebulaGraph Cloud Marketplace 主页。点击进入 Marketplace → 点击订阅→ 配置实例→ 创建solution，或者可以直接访问 Azure Marketplace 订阅链接：[NebulaGraph Cloud](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/vesoftcompanylimited1625556994617.nebula_graph_cloud?tab=Overview) 开启订阅之后即可使用 NebulaGraph Cloud。

具体使用教程参见：https://docs.nebula-graph.io/2.6.1/nebula-cloud/1.what-is-cloud

如果您对 NebulaGraph Cloud 有任何疑问，欢迎到社区发起讨论：[NebulaGraph community](https://discuss.nebula-graph.com.cn/)，或者发送邮件 [inquiry@vesoft.com](inquiry@vesoft.com) 与我们的 Cloud 专家连线交流。

NebulaGraph DBaaS 产品 NebulaGraph Cloud 已经在 Azure Marketplace 上线啦！2022 年 3 月 31 日前购买可享受 3 折优惠

NebulaGraph 首个云产品 – NebulaGraph Cloud 上线 Azure Marketplace，赋能企业数据关联价值


![高性能图计算系统 Plato 在 NebulaGraph 中的实践](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-plato-practice-00.jpeg)

## 1.图计算介绍

### 1.1 图数据库 vs 图计算

图数据库是面向 OLTP 场景，强调增删改查，并且一个查询往往只涉及到全图中的少量数据，而图计算是面向 OLAP 场景，往往是针对全图数据进行分析计算。

### 1.2 图计算系统分布架构

按照分布架构，图计算系统分为单机和分布式。

单机图计算系统优势在于模型简单，无需考虑分布式通讯，也无需进行图切分，但受制于单机系统资源，无法进行更大规模的图数据分析。

分布式图计算平台将图数据划分到多个机器上，从而处理更大规模的图数据，但不可避免的引入了分布式通讯的开销问题。

### 1.3 图的划分

图划分主要有两种方式边切割（Edge- Cut）和点切割（Vertex-Cut）。

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

边分割：每个点的数据只会存储在一台机器上，但有的边会被打断分到多台机器上。
如图(a)所示，点 A 的数据只存放在机器 1 上，点B 的数据只存放在机器 2 上。对于边 AB 而言，会存储在机器 1 和机器 2 上。由于点 A 和点 B 分布在不同的机器上，在迭代计算过程中，会带来通讯上的开销。

点分割：每条边只会存储在一台机器上，但有的点有可能分割，分配在多台机器上。
如图(b)所示, 边 AB 存储在机器 1 上，边 BC 存储在机器 2 上，边 CD 存储在机器 3 上，而点 B 被分配到了 1, 2 两台机器上，点 C 被分配到了 2，3 两台机器上。由于点被存储在多台机器上，维护顶点数据的一致性同样也会带来通讯上的开销。

### 1.4 计算模型

编程模型是针对图计算应用开发者，可分为以节点为中心的编程模型、以边或路径为中心的编程模型、以子图为中心的编程模型。

计算模型是图计算系统开发者面临的问题，主要有同步执行模型和异步执行模型。比较常见的有 BSP 模型（Bulk Synchronous Parallel Computing Model）和 GAS 模型。

BSP 模型：BSP 模型的计算过程是由一系列的迭代步组成，每个迭代步被称为超步。采用 BSP 模型的系统主要有 Pregel、Hama、Giraph 等。
BSP 模型具有水平和垂直两个方面的结构。垂直上看，BSP 模型有一系列串行的超步组成。水平上看（如图所示），一个超步又分三个阶段：

- 本地计算阶段，每个处理器只对存储本地内存中的数据进行计算。
- 全局通信阶段，机器节点之间相互交换数据。
- 栅栏同步阶段，等待所有通信行为的结束。

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

GAS 模型：GAS 模型是在 PowerGraph 系统提出，分为信息收集阶段（Gather）、应用阶段（Apply）和分发阶段（Scatter）。

- **Gather 阶段**，负责从邻居顶点收集信息。
- **Apply 阶段**，负责将收集的信息在本地处理，更新到顶点上。
- **Scatter 阶段**，负责发送新的信息给邻居顶点。

## 2. Gemini 图计算系统介绍

Gemini 在工业界较有影响力，它的主要技术点包括：CSR/CSC、push/pull、master 和 mirror、稀疏和稠密图、通信与计算协同工作、chunk-based 式分区、NUMA 感知的子分区等。

Gemini 采用边切割方式将图数据按照 chunk-based 的方式分区，并支持 Numa 结构。分区后的数据，用 CSR 存储出边信息，用 CSC 存储入边信息。在迭代计算过程中，对稀疏图采用 push 的方式更新其出边邻居，对稠密图采用 pull 的方式拉取入边邻居的信息。

如果一条边被切割，边的一端顶点为 master，另一端顶点则为 mirror。mirror 被称为占位符（placeholder) ，在 pull 的计算过程中，各个机器上的 mirror 顶点会拉取其入边邻居 master 顶点的信息进行一次计算，在 BSP 的计算模型下通过网络同步给其 master 顶点。在 push 的计算过程中，各个机器的 master 顶点会将其信息先同步给它的 mirror 顶点，再由 mirror 更新其出边邻居。

在 BSP 的通信阶段，每台机器 `Node_i` 发送给它的下一个机器 `Node_i+1`，最后一个机器会发送给第一个机器。在每台机器发送的同时也会收到 `Node_i-1` 的信息，收到信息后会立即执行本地计算。通讯和计算的重叠可以隐藏通信时间，提升整体的效率。

更多细节可以参考论文[《Gemini: A Computation-Centric Distributed Graph Processing System》](https://www.usenix.org/conference/osdi16/technical-sessions/presentation/zhu)。

## 3. Plato 图计算系统与 NebulaGraph 的集成

### 3.1 Plato 图计算系统介绍

Plato 是腾讯开源的基于 Gemni 论文实现的工业级图计算系统。Plato 可运行在通用的 x86 集群，如 Kubernetes 集群、Yarn 集群等。在文件系统层面，Plato 提供了多种接口支持主流的文件系统，如 HDFS、Ceph 等等。

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

### 3.2 与 NebulaGraph 的集成

我们基于 Plato 做了二次开发，以接入 NebulaGraph 数据源。

#### 3.2.1 NebulaGraph 作为输入和输出数据源

增加 Plato 的数据源，支持将 NebulaGraph 作为输入和输出数据源，直接从 NebulaGraph 中读取数据进行图计算，并将计算结果直接写回到 NebulaGraph 中。

NebulaGraph 的存储层提供了针对 partition 的 scan 接口，很容易通过该接口批量扫出顶点和边数据:

```cpp
ScanEdgeIter scanEdgeWithPart(std::string spaceName,
                                  int32_t partID,
                                  std::string edgeName,
                                  std::vector<std::string> propNames,
                                  int64_t limit = DEFAULT_LIMIT,
                                  int64_t startTime = DEFAULT_START_TIME,
                                  int64_t endTime = DEFAULT_END_TIME,
                                  std::string filter = "",
                                  bool onlyLatestVersion = false,
                                  bool enableReadFromFollower = true);

ScanVertexIter scanVertexWithPart(std::string spaceName,
                                      int32_t partId,
                                      std::string tagName,
                                      std::vector<std::string> propNames,
                                      int64_t limit = DEFAULT_LIMIT,
                                      int64_t startTime = DEFAULT_START_TIME,
                                      int64_t endTime = DEFAULT_END_TIME,
                                      std::string filter = "",
                                      bool onlyLatestVersion = false,
                                      bool enableReadFromFollower = true);
```
实践中，我们首先获取指定 space 下的 partition 分布情况，并将每个 partition 的 scan 任务分别分配给 Plato 集群的各个节点上，每个节点再进一步将 partition 的 scan 任务分配给运行在该节点的各个线程上，以达到并行快速的读取数据。图计算完成之后，将计算结果通过 Nebula client 并行写入 NebulaGraph。

#### 3.2.2 分布式 ID 编码器

Gemini 和 Plato 的要求顶点 ID 从 0 开始连续递增，但绝大多数的真实数据顶点 ID 并不满足这个需求，尤其是 NebulaGraph 从 2.0 版本开始支持 string 类型 ID。

因此，在计算之前，我们需要将原始的 ID 从 int 或 string 类型转换为从 0 开始连续递增的 int。Plato 内部实现了一个单机版的 ID 编码器，即 Plato 集群的每台机器均冗余存储所有 ID 的映射关系。当点的数量比较多时，每台机器仅 ID 映射表的存储就需上百 GB 的内存，因为我们需要实现分布式的 ID 映射器，将 ID 映射关系切成多份，分开存储。

我们通过哈希将原始 ID 打散在不同的机器，并行地分配全局从 0 开始连续递增的 ID。生成 ID 映射关系后，每台机器都会存有 ID 映射表的一部分。随后再将边数据分别按起点和终点哈希，发送到对应的机器进行编码，最终得到的数据即为可用于计算的数据。当计算运行结束后，需要数据需要映射回业务 ID，其过程和上述也是类似的。

#### 3.2.3 补充算法

我们在 Plato 的基础上增加了 sssp、apsp、jaccard similarity、三角计数等算法，并为每个算法增加了输入和输出到 NebulaGraph 数据源的支持。目前支持的算法有：

| 文件名 | 算法名称 | 分类 |
| :----- | ------ |------ |
| apsp.cc | 全对最短路径 | 路径 |
| sssp.cc  | 单源最短路径 | 路径 |
| tree_stat.cc  | 树深度/宽度 | 图特征 |
| nstepdegrees.cc  | n阶度 | 图特征 |
| hyperanf.cc  | 图平均距离估算 | 图特征 |
| triangle_count.cc  | 三角计数 | 图特征 |
| kcore.cc  |  | 节点中心性 |
| pagerank.cc  | Pagerank | 节点中心性 |
| bnc.cc | Betweenness | 节点中心性 |
| cnc.cc | 接近中心性(Closeness Centrality) | 节点中心性 |
| cgm.cc | 连通分量计算 | 社区发现 |
| lpa.cc  | 标签传播 | 社区发现 |
| hanp.cc  | HANP | 社区发现 |
| metapath_randomwalk.cc  |  | 图表示学习 |
| node2vec_randomwalk.cc  |  | 图表示学习 |
| fast_unfolding.cc | louvain | 聚类 |
| infomap_simple.cc  |  |聚类 |
| jaccard_similarity.cc  |  | 相似度 |
| mutual.cc  |  | 其他 |
| torch.cc  |  | 其他 |
| bfs.cc  | 广度优先遍历 | 其他 |

## 4. Plato 部署安装与运行

### 4.1 集群部署

Plato 采用 MPI 进行进程间通信，在集群上部署 Plato 时，需要将 Plato 安装在相同的目录下，或者使用 NFS。操作方法见：[https://mpitutorial.com/tutorials/running-an-mpi-cluster-within-a-lan/](https://mpitutorial.com/tutorials/running-an-mpi-cluster-within-a-lan/)

### 4.2 运行算法的脚本及配置文件

#### scripts/run_pagerank_local.sh

```bash
#!/bin/bash

PROJECT="$(cd "$(dirname "$0")" && pwd)/.."

MAIN="./bazel-bin/example/pagerank" # process name

WNUM=3
WCORES=8

#INPUT=${INPUT:="$PROJECT/data/graph/v100_e2150_ua_c3.csv"}
INPUT=${INPUT:="nebula:${PROJECT}/scripts/nebula.conf"}
#OUTPUT=${OUTPUT:='hdfs://192.168.8.149:9000/_test/output'}
OUTPUT=${OUTPUT:="nebula:$PROJECT/scripts/nebula.conf"}
IS_DIRECTED=${IS_DIRECTED:=true}  # let plato auto add reversed edge or not
NEED_ENCODE=${NEED_ENCODE:=true}
VTYPE=${VTYPE:=uint32}

ALPHA=-1
PART_BY_IN=false

EPS=${EPS:=0.0001}
DAMPING=${DAMPING:=0.8}
ITERATIONS=${ITERATIONS:=5}

export MPIRUN_CMD=${MPIRUN_CMD:="${PROJECT}/3rd/mpich-3.2.1/bin/mpiexec.hydra"}

PARAMS+=" --threads ${WCORES}"
PARAMS+=" --input ${INPUT} --output ${OUTPUT} --is_directed=${IS_DIRECTED} --need_encode=${NEED_ENCODE} --vtype=${VTYPE}"
PARAMS+=" --iterations ${ITERATIONS} --eps ${EPS} --damping ${DAMPING}"

# env for JAVA && HADOOP
export LD_LIBRARY_PATH=${JAVA_HOME}/jre/lib/amd64/server:${LD_LIBRARY_PATH}

# env for hadoop
export CLASSPATH=${HADOOP_HOME}/etc/hadoop:`find ${HADOOP_HOME}/share/hadoop/ | awk '{path=path":"$0}END{print path}'`
export LD_LIBRARY_PATH="${HADOOP_HOME}/lib/native":${LD_LIBRARY_PATH}

chmod 777 ./${MAIN}
${MPIRUN_CMD} -n ${WNUM} -f ${PROJECT}/scripts/cluster ./${MAIN} ${PARAMS}
exit $?
```
参数说明

- `INPUT` 参数和 `OUPUT` 参数分别指定算法的输入数据源和输出数据源，目前支持本地 csv 文件、HDFS文件、 NebulaGraph。当输入输出数据源为 NebulaGraph 时，`INPUT` 和 `OUPUT` 形式为 `nebula:/path/to/nebula.conf`
- WNUM 为集群所有机器所运行的进程数之和，推荐每台机器运行为 1 或者 NUMA node 数个进程，WCORE 为每个进程的线程数，推荐最大设置为机器的硬件线程数。

#### scripts/nebula.conf

```
## read/write
--retry=3 # 连接 NebulaGraph 时的重试次数
--space=sf30 # 要读取或写入的 space 名称

## read from nebula
--meta_server_addrs=192.168.8.94:9559 # NebulaGraph 的 metad 服务地址
--edge=LIKES # 要读取的边的名称
#--edge_data_field # 要读取的作为边的权重属性的名称
--read_batch_size=10000 # 每次 scan 时的 batch 的大小

## write to nebula
--graph_server_addrs=192.168.8.94:9669 # NebulaGraph 的 graphd 服务地址
--user=root # graphd 服务的登陆用户名
--password=nebula # graphd 服务的登陆密码
# insert or update
--mode=insert # 写回 NebulaGraph 时采用的模式: insert/update
--tag=pagerank # 写回到 NebulaGraph 的 tag 名称
--prop=pr # 写回到 NebulaGraph 的 tag 对应的属性名称
--type=double # 写回到 NebulaGraph 的 tag 对应的属性的类型
--write_batch_size=1000 # 写回时的 batch 大小
--err_file=/home/plato/err.txt # 写回失败的数据所存储的文件
```

#### scripts/cluster
cluster 文件指定要运行该算法所在的集群机器的 IP
```
192.168.15.3
192.168.15.5
192.168.15.6
```

以上为 Plato 在 NebulaGraph 中的应用，目前该功能集成在 NebulaGraph 企业版中，如果你使用的是开源版本的 NebulaGraph，需按照自己的需求自己对接 Plato。

---

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

![关注公众号](https://www-cdn.nebula-graph.com.cn/nebula-blog/WeChatOffical.png)


Nebula 基于开源的图计算框架 Plato 的二次开发，看 Nebula 是如何插上图计算的翅膀的吧~

高性能图计算系统 Plato 在 NebulaGraph 中的实践


![详解 Nebula Dashboard 企业版多集群监控运维工具](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise.webp)

# 背景

分布式数据库多节点存储数据带来高性能的同时，伴随着运维服务复杂度的提升以及稳定性监控的实时性要求。在日常的数据库维护过程，维护人员可能会面临以下问题：

1. 集群创建、节点&服务管理操作难，需要专业的运维人员；
2. 无法实时监控集群线上的运行情况，做到及时报警；
3. 多集群管理繁琐，耗时巨大；
4. 集群备份升级易出错，且升级复杂度高。

为了解决上述问题，可视化集群管理工具 Nebula Dashboard 应运而生。**Nebula Dashboard 旨在帮助运维和 DBA 降低日常维护集群成本，轻松管理集群，让相关人员对线上的稳定性心中有数**。

Nebula Dashboard 试用地址：[https://dashboard.nebula-graph.com.cn/](https://dashboard.nebula-graph.com.cn/)

![Nebula Dashboard架构图](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-01.webp)

简单来说，Nebula Dashboard 功能如上，包括 6 大部分：集群管理、监控、告警、单集群配置、权限管控以及常规的系统设置。下面来讲下 Nebula Dashboard 的三大特性：

# 多集群全生命周期管理

一个 Nebula 集群的生命周期我们定义为：新集群-集群管理-集群回收。

![多集群生命周期管理](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-02.png)

Nebula Dashboard 可以对集群的整个生命周期进行系统可视化管理，如果集群还未创建，通过可视化操作可快速拉起一个全新集群。考虑到用户可能已有集群在运行 NebulaGraph，所以 **Nebula Dashboard 也支持通过导入集群的方式把已有集群纳入监控系统进行管理**。

## 创建集群

Nebula Dashboard 建集群非常快捷：

![集群创建](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-03.webp)

如图，创建一个集群需要 5 步：

1. 输入集群名称，以方便区分不同的集群。
2. 指定要创建集群的 Nebula 内核版本，Nebula Dashboard 支持 Nebula 内核 v2.0 以上版本，系统默认内置 v2.6.1、v2.5.1、v2.0.1 三个发行版安装包。对于即将在春节之后发布的 v3.0 版本，Nebula Dashboard 已完成兼容开发工作，v3.0 内核发布之后便会在 Nebula Dashboard 中内置该发行版。
3. 添加集群中的节点，这一步需要 SSH 授权。
4. 定制化配置节点，按需在不同节点上要部署其对应服务。为了减少配置工作量，Nebula Dashboard 内置默认配置“自动添加服务选项”，系统会根据配置设定均衡部署服务到不同节点上。
5. 确认创建集群信息（包括节点以及服务分布信息）无误后，点击创建集群即创建好一个 Nebula 集群。

## 导入集群

对于运行的线上集群，Nebula Dashboard 提供了快速导入的功能帮助已有集群接入 Nebula Dashboard 做统一管理，具体操作如下所示：

![集群导入](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-04.webp)

![集群导入](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-05.webp)

通过输入 graphd 所在地址，如：`127.0.0.1:9669`，并提供 Nebula 线上数据库的连接账号和密码，点击连接数据库即可。

系统连上 Nebula 数据库后，会从 metad 中获取集群的服务信息，并进入集群管理页面（图二）进行集群命名、提供节点 SSH 信息操作，完成后即可导入集群方便 Nebula Dashboard 管理。

## 运维集群

通过创建和导入集群的方式，Nebula Dashboard 可以开始帮助用户管理集群了。对于运维人员而言，对集群节点的管理、服务管理是高频操作，这些操作枯燥乏味且容易出错，而通过 Nebula Dashboard 可以将这部分繁琐操作工具化。

Nebula Dashboard 在运维上集成了以下的功能：

### 节点 & 服务管理

节点管理和服务管理模块，直观显示当前集群正在运行的节点信息以及各个节点中运行的服务信息，从而随心所欲地对节点以及服务进行操作，包括在集群中新增空节点、对节点中正在运行的服务启停等操作。

![节点 & 服务管理](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-06.webp)

![节点 & 服务管理](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-07.webp)

### 集群扩缩容

注：该功能目前只能在 playground 中体验 [https://dashboard.nebula-graph.com.cn/](https://dashboard.nebula-graph.com.cn/)

扩缩容操作是运维日常中经常碰到的情况，当数据量突然变大或者访问 QPS 激增时，为了保证集群高可用常会进行扩容操作；反之，当访问量下降、服务请求变少时，会考虑适当地缩容。对于运维人员来说，扩缩容操作是一个不常用但务必谨慎进行的操作，因为线上稳定是系统运行的第一要务，一旦扩缩容导致系统服务出现问题不只是运维人员“加班加点”的事情了。为了确保维护人员“身心健康”，Nebula Dashboard 可帮助集群快速地扩缩容，相关人员无需关心复杂繁琐的 shell 命令即可完成加机器减机器操作。此外，Nebula Dashboard 系统会在 storage 缩容后自动进行 `DATA BALANCE` 操作。

![集群扩缩容](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-08.webp)

上图所示，Nebula Dashboard 可视化扩缩容，只需要执行以下 3 步：

1. 如果需要添加节点，点击“添加节点”按钮，并提供机器 SSH 信息即可。
2. 给对应的节点添加服务（扩容）或者删除现有服务（缩容）。在扩缩容页面，底色淡绿色为新增节点，底色淡红色表示将删除节点，节点列表罗列即将扩缩容的节点详细信息。
3. 在确认具体扩缩容的节点和服务信息后，点击确认按钮，系统会自动对集群执行扩缩容任务。

### Nebula 运维

NebulaGraph 有较多的可配置选项，通过 Nebula Dashboard 可清晰地看到当前集群的配置信息，可根据业务情况更新最佳集群的配置。此外，用户可以在 Nebula Dashboard 上对数据库的详细信息进行查看和管理操作。

1. 查看 Storage Leader 分布情况并进行 `BALANCE LEADER` 操作。
2. 查看不同 Space 的 Partition 分布情况，并支持一键 `BALANCE DATA` 操作
3. 查看长时任务

# 监控告警——线上稳定性心中有数

作为一款 Dashboard 产品，集群的稳定性监控是整个工具的重中之重。**企业版 Nebula Dashboard 系统提供了集群总览、节点指标监控、服务指标监控以及告警通知的能力**。

## 集群总览

在集群总览中，运维人员可以快速了解当前集群的整体情况，包括节点中服务的分布信息、运行状态、自定义的核心监控指标以及重要告警项，从而做到快速掌握信息、快速应对。

![集群总览](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-09.webp)

## 节点监控

节点监控主要对采集节点的信息进行监控，内容包括 CPU水位、内存水位、负载情况、磁盘使用情况等，用户还可以设置基线，这样可以更加清楚得知道当前机器水位是否超过水位线，从而及时做出反应。

![节点监控](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-10.webp)

## 服务监控

服务监控主要针对当前 Nebula 集群的三个服务（graphd、metad和 storaged）的指标进行可视化监控，目前 Nebula 集群可以采集到几十种指标，并根据指标数值的聚类以及平均值进行监控。**常见的指标有 Graph 的慢查询数量、查询报错数、Storage 点边的 latency，以及 Meta 心跳的 latency 等指标**。对于不同的指标，除了可以设置基线，还可以选择要监控的指标平均值的周期。

![服务监控](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-11.webp)

## 告警模块

Nebula Dashboard 的告警模块是对 NebulaGraph 集群的监控指标进行报警的服务，用户可以查看告警信息，设置告警规则和告警接收方。首先用户根据自己关心的指标设置当前自己业务需要的警戒线，同时支持设置告警触发的频率以及持续时间，以及消息通知的信息模版，这样当系统的指标触发了对应规则时，系统会自动发送邮件出来进行告警提醒。

整个告警模块分为告警历史消息、告警站内提醒、邮件 & Webhook通知、告警规则等 4 个模块。常规的告警使用方式如下：

1. 创建自定义告警规则或者打开内置规则的开关。
2. 当系统监控到指标符合告警规则，会触发告警发出一条告警消息。
3. 告警消息在 Nebula Dashboard 站内会做一个全局通知，同时如果有配置告警邮件信息的话，系统会自动发出邮件至邮件接收人列表中去。
4. 用户根据告警消息进行问题排查。

![告警模块](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-12.webp)

![告警模块](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-dashbaord-enterprise-13.webp)

# 系统角色 & 权限

Nebula Dashboard 面向的是多集群管理，因此针对不同的业务，需要做权限上的划分，做到平台化。首先 Nebula Dashboard 设计了 Admin 和 User 两种角色，Admin 可以针对整个平台做全局的设置，如系统的 Logo 名称、全局的告警发件人信息等，也可以管理当前系统上的账号体系。User 只能对有读写权限的集群进行操作。在集群内部，设置了成员的角色，被加入到该集群的成员分组后才可以对该集群进行操作。

# LDAP 统一登陆

考虑到大部分用户都有一套企业账号体系，为了让 Nebula Dashboard 更好地融入对应的企业系统中去，Nebula Dashboard 支持 LDAP 登陆：只需要在部署时，配置 LDAP 信息即可使用对应的企业邮箱账号进行登陆。后续管理员发送邮件邀请用户加入 Dashboard，用户点击链接激活后即可作为普通用户来使用 Nebula Dashboard。

# 未来规划

Nebula Dashboard 致力于帮助 Nebula 运维人员以及 DBA 降低日常工作的复杂度，因此会持续推出更多相关的硬核功能。虽然本文简述功能已覆盖基础的运维工作，但接下来的版本迭代中 Nebula Dashboard 将会支持以下功能：

1. **集群一键备份升级能力，主要面对 v3.0+ Nebula 集群**。作为一个分布式集群，数据的安全性不言而喻，同时由于 NebulaGraph 本身也在快速的迭代中，因此让存量的集群升级版本以使用新版本的新特性是非常有必要的。而集群的备份升级对运维人员的专业度要求比较高，而 Nebula Dashboard 也希望通过可视化的方式帮助运维人员快速搞定 Nebula 的备份与升级。
2. 支持可视化管理 Storage Zone
3. 可视化监控大屏升级，从功能和视觉角度做全方位的升级
4. 自定义监控，定制自己专属监控大屏
5. 慢查询管理，帮助 DBA 快速定位性能问题

# 如何申请试用

通过 Nebula Dashboard playground（链接：[https://dashboard.nebula-graph.com.cn/](https://dashboard.nebula-graph.com.cn/) ）可快速了解 Nebula Dashboard 是否满足公司的运维需求，如果想要进阶使用可点击申请链接（链接：[https://wj.qq.com/s2/10158890/69a8](https://wj.qq.com/s2/10158890/69a8) ）申请试用企业版 Nebula Dashboard。
---

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

![关注公众号](https://www-cdn.nebula-graph.com.cn/nebula-blog/WeChatOffical.png)


强大的可视化集群监控工具 Nebula Dashboard 到底是怎么样的存在呢？

详解 Nebula Dashboard 企业版多集群监控运维工具


![如何打造多版本文档中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/buildi-your-own-docs-website.jpg)

世界上没有完美的产品，每个不完美的产品都需要一份文档。

## 为什么需要文档

打造出一款产品后，我们需要一份文档来回答以下问题：

* 设计这款产品的原因是什么（Why）
* 这是一款什么样的产品（What）
* 产品面向的用户是谁（Who）
* 在哪些场景下可以用这款产品（Where&When）
* 怎样使用（How）
* 产品的使用限制与其它需要注意的问题（Notes and limitations）
* ……

通过文档介绍这些信息，新读者才能更直观地了解产品，决定是否要用它，而产品的用户则能更顺利地使用它。

NebulaGraph也是这样一款不完美的产品。因此我们需要文档，更需要一个文档中心来集中保存并有序排列文档，供读者阅读和查找。

## 文档的需求

在最开始的时候，我们的第一位文档工程师@Amber只有一个需求，那就是搭建一个英文文档网站。然而很快她就发现这可不仅仅是一个需求。

![如何打造多版本文档中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-01.jpeg)

经过初步分析，我们至少需要做以下事情：

* 确定用什么写文档
* 找个地方存放文档文件
* 让读者可以方便地阅读文档

随着时间的推移和进一步思考，可达鸭发现了更多需求：

* P0：
    * 有中英文文档网站
    * 文档变更后自动发布
* P1：
    * 文档版本分离
    * 内容搜索
* P2：
    * 断链检查
    * 生成 PDF
* P3：
    * 复用
    * 隐藏
* 等等……

于是，可达鸭开始了打造文档中心的探索之路。

## 打造文档中心

下面来讲解下 Nebula 内容与文档团队是如何使用 MkDocs 和 GitHub 搭建文档中心的。在阅读本文的同时，可以从 NebulaGraph 文档中心（链接：[https://docs.nebula-graph.com.cn/3.0.1/](https://docs.nebula-graph.com.cn/3.0.1/)）和 GitHub 库（链接：[https://github.com/vesoft-inc/nebula-docs-cn](https://github.com/vesoft-inc/nebula-docs-cn)）查看相应的代码和效果示例。

### MkDocs

MkDocs 是一个快速、简单、美观的开源静态网站生成器，用于构建项目文档。文档源文件为 Markdown 格式，配置写在 YAML 文件中。

Mkdocs 支持：

* 多主题，每种主题有不同的功能。
* 自定义功能。
* 预览网站。

### Material for MkDocs

Material for MkDocs 是最流行的 MkDocs 主题之一，支持通过 Python、Docker、Git 等方式安装。NebulaGraph 文档中心有若干功能由该主题提供。

Material for MkDocs 的安装和基础使用方式参考 [Material 官方文档](https://squidfunk.github.io/mkdocs-material/getting-started/#installation)。

> 说明：无需单独安装 MkDocs，Material 会将其一起安装。

### 部署文档中心

我们使用 [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages) 和 [GitHub Actions](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions) 将 GitHub 文档库部署到文档中心，并实现修改文档后页面自动更新。

GitHub Pages 默认使用的域名为 `{<user> | <organization>}.github.io`，我们使用了[自定义域名](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)。

### 设置基本功能

#### 设置网站基本信息

设置基本信息需要使用的 `mkdocs.yml` 配置如下：

```
# 网站名称
site_name: NebulaGraph Database 手册
# 网站描述
site_description: Documentation for NebulaGraph Database
# 作者信息
site_author: NebulaGraph
# 网站（文档中心）的链接
site_url: https://docs.nebula-graph.com.cn/master/
# 版权信息
copyright: Copyright © 2021 NebulaGraph - 浙ICP备20010487号
```

#### 设置 GitHub 信息

Nebula 文档库托管在 GitHub 上，因此需要在 `mkdocs.yml` 中设置 GitHub 相关信息。

```
# GitHub库的名称
repo_name: 'vesoft-inc/nebula-docs-cn'
# GitHub库的链接
repo_url: 'https://github.com/vesoft-inc/nebula-docs-cn'
# 添加正确的路径后文档右上角会出现编辑按钮，点击可直接跳转到编辑文件的页面
edit_uri: 'edit/master/docs-2.0/'
# 指定包含文档源Markdown文件的目录
docs_dir: docs-2.0
edit_uri 参数设置成功后，每篇文档的如下位置会出现编辑按钮，用于修改单篇文档非常方便。
```

![如何打造多版本文档中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-02.png)

#### 设置导航栏

Markdown 文件在导航栏的显示顺序可以通过 `mkdocs.yml` 文件中的 `nav` 字段配置。格式示例如下：
```
nav:
  - 前言: README.md
  - 简介:
      - 什么是 NebulaGraph: 1.introduction/1.what-is-nebula-graph.md
      - 数据模型: 1.introduction/2.data-model.md
      - ...
      - 服务架构:
        - 架构总览: 1.introduction/3.nebula-graph-architecture/1.architecture-overview.md
        - ...
 
  - 快速入门:
      - 快速入门流程: 2.quick-start/1.quick-start-workflow.md
      - 步骤1：安装 NebulaGraph: 2.quick-start/2.install-nebula-graph.md
      - ...
```
显示效果如下：

![如何打造多版本文档中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-03.png)

#### 丰富文档中心功能

刚刚部署的文档中心仅有类似下图的默认的页面样式，我们需要挑选配置项和插件实现更多功能。

![如何打造多版本文档中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-04.png)

#### 应用 Material 主题

在 `mkdocs.yml` 文件中加入以下配置：
```
theme:
  name: material
```
并在 `requirements.txt` 文件中加入一行，内容为 mkdocs-material。这样就应用了 Material 主题的基本样式：

![如何打造多版本文档中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-05.png)

#### 设置站点语言

Material for MkDocs 支持多种语言。例如，如果是中文文档，做如下设置：
```
theme:
  language: 'zh'
```

#### 更改页面颜色

Material for MkDocs 提供了两类颜色主题，浅色背景的 default 和深色背景的 slate。编辑 `mkdocs.yml` 文件，加入 palette 字段：
```
theme:
  name: material
  palette:
    scheme: default
```

#### 切换页面主题

我们可以在深色和浅色主题之间切换，实现日间模式和夜间模式的效果。编辑 mkdocs.yml 文件，修改 palette 字段：
```
palette:
    - scheme: default
      primary: cyan
      accent: cyan
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - scheme: slate
      primary: deep orange
      accent: deep orange
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
```
除此以外，还可以[自定义颜色](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#custom-colors)。

#### 自定义 logo

可以使用文档库内的各类型图片，包括但不限于 PNG、SVG 格式，或者外部网络上的图片，作为页面 logo。这样编辑 `mkdocs.yml` 文件：
```
theme:
  logo: assets/logo.png
```
如果是外链，直接在 `logo:` 后面设置链接即可。

#### 关于搜索

Material for MkDocs 内置了页面搜索功能，这样编辑 `mkdocs.yml` 文件即可使用：
```
plugins:
  - search
```
但是，该搜索功能对中文和英文混合的场景的支持有很多问题，我们也还在寻找方案。

#### 设置社交主页链接

NebulaGraph 是在 GitHub 开源的产品，因此文档中心设置了 GitHub 主页的 logo 和链接，方式如下：
```
  social:
    - icon: 'fontawesome/brands/github'
      link: 'https://github.com/vesoft-inc/nebula-docs-cn'
```

#### 设置标题行自动隐藏

为了不让标题行遮挡内容，优化阅读体验，我们设置了让标题行在页面下滑后自动隐藏。
```
theme:
  features:
    - header.autohide
```

### 版本分离

版本分离是 Nebula 文档中心的关键功能之一。开源开发的 NebulaGraph 迭代快，每个版本的特性都有区别，因此文档也根据产品功能分为不同版本。

#### 版本管理

我们使用 [mike](https://github.com/jimporter/mike) 做版本管理。

mike 的使用方式如下：

1. 在 requirements.txt 文件中加入一行，内容为：mike

2. 在 `mkdocs.yml` 中设置：

```
  version:
    method: mike
```

3. 在 `/.github/workflows/deploy.yaml` 中设置：

```
jobs:
  deploy:
    steps:
      - name: Mike Deploy master
        run: |
# 指定要部署的版本
          mike deploy 2.5.1 -p --rebase
# 指定文档中心默认跳转的版本，同时在历史版本中删除这句话。
          mike set-default 2.5.1 -p --rebase
```

#### 版本发布

NebulaGraph 文档的版本与内核版本保持一致，发布文档新版本的方式如下：

1. 在 master 分支完成新版本文档开发，将相关 PR 合并。
2. 创建新的 GitHub 分支。
    1. 在文档的 GitHub 主页，点击分支切换按钮。
    2. 在 `Find or create a branch...` 文本框中输入新版本的名称，例如 v2.6.0。
    3. 点击下拉列表底部（倒数第二行）的 Create brach: xxx from master 。
3. 修改配置文件。
    1. 修改新分支中的 `/.github/workflows/deploy.yaml` 文件，需修改的字段参考[示例 commit](https://github.com/vesoft-inc/nebula-docs-cn/commit/a09d50c7447ab02f5101ac811deeff16829c5db3#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2)。
    2. 修改新分支中的 /mkdocs.yml 文件，需修改的字段参考[示例 commit](https://github.com/vesoft-inc/nebula-docs-cn/commit/a09d50c7447ab02f5101ac811deeff16829c5db3#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2)。其中 palette 部分为主题颜色，详细说明参考本文##更改页面颜色##部分。
    3. 修改上个版本对应分支中的 `/.github/workflows/deploy.yaml` 文件，将 run 字段下的 `mike set-default x.x.x -p --rebase` 行删除，以取消老版本的重定向。详情参考[示例 commit](https://github.com/vesoft-inc/nebula-docs-cn/commit/4bfb3f29291adaf307772498d01d30cbc15e796f)。
4. 删除新分支的 `overrides/partials/header.html` 文件，取消顶部通知栏文件。该文件会影响 PDF 的生成，因此仅在 master 版本保留，用于告知读者 master 版本是开发版本，并指向最新的发布版本。
5. 在 GitHub [Actions] 页面查看最后一个 Action，检查 Mike Deploy xxx 部署，如有断链等报错即时解决。将非断链但暂时不适合发布的文件设置在 /mkdocs.yml 中的 [exclude 字段](https://github.com/vesoft-inc/nebula-docs-cn/blob/master/mkdocs.yml#L505)，这样能起到隐藏效果，详细说明参考注释。
6. 修改前一个版本的前言，建议用户升级新版本。参考[示例](https://github.com/vesoft-inc/nebula-docs-cn/commit/3a0afee231f7692451463ceb672acad20d303fbd#diff-0b80360ed703766905bd5f8a59e4434a6fc05090e62dcba37e35021e0a3fbf6d)。

#### 版本号自动变更

文档中的版本号有时需要根据版本修改，使用 macros 插件设置宏变量后，只要修改了 mkdocs.yml 文件中的设置，就可以方便地实现文档中的版本号自动变更。macros 的设置步骤如下：

1. 在 `requirements.txt` 文件中加入一行，内容为：`mkdocs-macros-plugin`

2.在 `mkdocs.yml` 中的 `extra` 字段设置版本号的 macros 键值对，示例如下：
```
extra:
  nebula:
    release: 2.6.2
```

设置后，在 Markdown 代码中使用 \{\{<key>.<value>\}\} 的形式即可生成相应的版本号。进行了上述设置后，\{\{nebula.release\}\} 即代表 2.6.1。

源码和显示效果的对比如下：

![如何打造多版本文档中心](https://www-cdn.nebula-graph.com.cn/nebula-blog/build-your-own-docs-website-06.png)

这其实也是短语级别的内容复用。

以上，为 Nebula 内容与文档团队文档搭建实践。

当然我们还有一些内容并未在本文展示，下面内容将在后面的文章中娓娓道来：

* mkdocs_latest_release_plugin
* mkdocs-git-revision-date-localized-plugin
* note
* mdx_truly_sane_lists
* pymdownx.superfences
* pymdownx.snippets
* pymdownx.arithmatex
* exclude
* mkdocs-with-pdf
* pydown-snippets
* Action 错误排查
* 关于中文的特殊处理 [https://github.com/vesoft-inc/nebula-docs-cn/blob/master/pkglist.txt](https://github.com/vesoft-inc/nebula-docs-cn/blob/master/pkglist.txt)

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


世界上没有完美的产品，每个不完美的产品都需要一份文档…那么，同本文一块打造一个“完美”的文档中心。

如何打造多版本文档中心


> 本文整理于 Norm on nLive 播客，播客见下音频

Norm 是由知乎反欺诈团队工程师——吴振胜开源的 ORM 工具。项目由 Golang 编写，对分布式图数据库 NebulaGraph 的查询语言 nGQL 进行映射封装，极大地降低了后端工程师使用图数据库的门槛，只用实例对象即可进行图数据查询。GitHub 地址：[https://github.com/zhihu/norm](https://github.com/zhihu/norm)

# ORM 是什么

对象关系映射（英语：Object Relational Mapping，简称ORM，或O/RM，或O/R mapping），是一种程序设计技术，用于实现面向对象编程语言里不同类型系统的资料之间的转换。从效果上说，它其实是创建了一个可在编程语言里使用的“虚拟对象数据库”。

# 关于 Norm 的作者

吴振胜，现就职知乎，在反欺诈团队任工程师。

# Norm 的由来

早在 19 年时，出于更好展示网站信息的关联性的需要，吴振胜第一次接触了图数据库。随后知乎反欺诈业务所需的图谱关联、图实时计算能力都依赖于图数据库、图技术提供，在此过程中他发现 **ORM 存在大量的需求**。无论在知乎内部，或者是 Nebula 社区中，ORM 的需求讨论一直很热烈。而 Nebula 官方提供的 SDK 提供了一些核心的功能，比如连接池的创建、数据库的交互。倘若在业务上直接使用，会**增加业务同学的心智负担——需要解析语句的结构体、拼接 SQL、nGQL 等等**。

而另外一个原因则是 ORM 是一个好玩的功能需求，实现它的话需要了解反射机制，这是他一直感兴趣的技术点。于是便动手实现，将其开源了。

Norm GitHub 地址：[https://github.com/zhihu/norm](https://github.com/zhihu/norm)

# Norm 的开发

Norm 这个项目的代码部分一共花了不到一周的时间完成。从周一开始写的，大概周四的时候就上线了第一版。但测试、文档编写部分，花的时间就比较久，主要是陆陆续续地在做。

由于吴振胜对 ORM 这块相对比较了解，所以整个项目主要是由吴振胜一人完成，开发过程中有个热心的社区同学提了个 bug 并修复掉了。

吴振胜表示，Norm 开发的主要难点在于两方面，一部分是**学习成本**，要去学一些技术才能去解决对应的问题。需要学习的点主要是三个方面，第一个是**反射**，做 ORM 项目的话肯定离不开反射：怎么去把值反射到结构体、map…。第二个就是常见的怎么做分层，比如说，把**数据库连接同 ORM 分开**，以便支持更多使用 nGQL 场景，这是一种连接的方式。另外一种连接是**链式调用的编程方式**，如何实现链式编程、链式调用，都是思考点。基本上技术难点就这三个，其中比较可能学的比较多的是反射。

Norm 的难点还有个方面是业务上的问题，当中最大的难点是**性能和功能的权衡**、业务边界、应用场景。比如说，满足功能 A 的时候，可能存在部分性能损耗，这就会出现性能损耗和便携性到底是哪个比较重要的问题。什么情况下可以牺牲便携性，什么情况下牺牲性能，这是一个需要权衡的地方，也是个比较复杂的点。

此外业务边界问题还涉及了功能规划问题，这个产品要提供哪些功能、不提供哪些功能，都是需要考量的点。如果 ORM 提供的功能一开始就很丰富，就要开发花很多开发时间。而且过于丰富的功能需求，也会存在一些需求遗漏问题。

最后是应用场景，只有研发在很多场景中用过 ORM 才能知道哪些地方是真正需要的，哪些地方是可有可无的。顺便提一嘴，在 Norm 开发过程中，知乎更多的是把图数据库当作数据库去用的，去查询关系、做些 count 计数不涉及图模型的算法（这种情况下不适合用 ORM）。

此外，Norm 的开发主要参考了知名 ORM 项目——gorm 的设计思路和实现方式。当然 Norm 还有不完善的地方，欢迎大家来 Norm 项目的 GitHub 提功能或者问题修复 pr：[https://github.com/zhihu/norm](https://github.com/zhihu/norm)

# Norm 下阶段的规划

下一个阶段现在主要是**优化链式调用**，因为链式调用这个版本只是做了下简单实现，并没有完善一些功能，比如说，WHERE、MATCH 更好地组合使用。另外个方面是连接池，就之前说的 session 连接池。剩下的就是文档的完善和单元测试。

# 知乎的开源态度

在此之前，先说下吴振胜的开源看法：

知乎的开源和主产品类似，帮助大家更好的找到答案——开源也是这样，它会让充满好奇心的人，或者说需要开发中遇到问题的人，在社区开源社区找到自己的答案。

*而知乎也有自己的开源愿景：让代码流动，让开源发生。知乎开源需要更好地结合并服务技术规划，促进架构落地。同时，通过开源，我们希望赋予每名知乎工程师透明共创的氛围感、舵向明确的归属感、专业声誉提升的自豪感；通过开源，我们希望向外传达知乎开源精神，使开源成为塑造知乎技术影响力的新引擎。我们致力于让这个时代充满好奇心的开发者能够通过开源，找到答案*。

最后这是知乎开源组织：[https://github.com/zhihu](https://github.com/zhihu)

以上。

本文中如有任何错误或疏漏，欢迎去 GitHub：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula) issue 区向我们提 issue 或者前往官方论坛：[https://discuss.nebula-graph.com.cn/](https://discuss.nebula-graph.com.cn/) 的 `建议反馈` 分类下提建议 👏；交流图数据库技术？加入 Nebula 交流群请先[填写下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手会拉你进群~~

Norm 是由知乎反欺诈团队工程师——吴振胜开源的 ORM 工具。项目由 Golang 编写，对分布式图数据库 NebulaGraph 的查询语言 nGQL 进行映射封装，极大地降低了后端工程师使用图数据库的门槛…