HugeGraph-Server Quick Start

HugeGraph-Server Quick Start

1 HugeGraph-Server 概述

HugeGraph-Server 是 HugeGraph 项目的核心部分，包含 Core、Backend、API 等子模块。

Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存储，目前支持的后端包括：Memory、Cassandra、ScyllaDB 以及 RocksDB，API 模块提供 HTTP Server，将 Client 的 HTTP 请求转化为对 Core 的调用。

文档中会大量出现 HugeGraph-Server 及 HugeGraphServer 这两种写法，其他组件也类似。这两种写法含义上并无大的差异，可以这么区分：HugeGraph-Server 表示服务端相关组件代码，HugeGraphServer 表示服务进程。

2 依赖

2.1 安装 Java 11 (JDK 11)

请优先考虑在 Java 11 的环境上启动 HugeGraph-Server，目前同时保留对 Java 8 的兼容

在往下阅读之前务必执行 java -version 命令查看 jdk 版本

java -version

3 部署

有四种方式可以部署 HugeGraph-Server 组件：

方式 1：下载 tar 包
方式 2：源码编译
方式 3：使用 Docker 容器 (便于测试)
方式 4：使用 tools 工具部署 (Outdated)

3.1 下载 tar 包

# use the latest version, here is 1.2.0 for example
wget https://downloads.apache.org/incubator/hugegraph/{version}/apache-hugegraph-incubating-{version}.tar.gz
tar zxf *hugegraph*.tar.gz

3.2 源码编译

源码编译前请确保安装了 wget 命令

下载 HugeGraph 源代码

git clone https://github.com/apache/hugegraph.git

编译打包生成 tar 包

cd hugegraph
mvn package -DskipTests

执行日志如下：

......
[INFO] Reactor Summary for hugegraph 1.2.0:
[INFO] 
[INFO] hugegraph .......................................... SUCCESS [  2.405 s]
[INFO] hugegraph-core ..................................... SUCCESS [ 13.405 s]
[INFO] hugegraph-api ...................................... SUCCESS [ 25.943 s]
[INFO] hugegraph-cassandra ................................ SUCCESS [ 54.270 s]
[INFO] hugegraph-scylladb ................................. SUCCESS [  1.032 s]
[INFO] hugegraph-rocksdb .................................. SUCCESS [ 34.752 s]
[INFO] hugegraph-mysql .................................... SUCCESS [  1.778 s]
[INFO] hugegraph-palo ..................................... SUCCESS [  1.070 s]
[INFO] hugegraph-hbase .................................... SUCCESS [ 32.124 s]
[INFO] hugegraph-postgresql ............................... SUCCESS [  1.823 s]
[INFO] hugegraph-dist ..................................... SUCCESS [ 17.426 s]
[INFO] hugegraph-example .................................. SUCCESS [  1.941 s]
[INFO] hugegraph-test ..................................... SUCCESS [01:01 min]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
......

执行成功后，在 hugegraph 目录下生成 *hugegraph-*.tar.gz 文件，就是编译生成的 tar 包。

3.3 使用 Docker 容器 (便于测试)

可参考 Docker 部署方式。

我们可以使用 docker run -itd --name=graph -p 8080:8080 hugegraph/hugegraph 去快速启动一个内置了 RocksDB 的 Hugegraph server.

可选项：

可以使用 docker exec -it graph bash 进入容器完成一些操作
可以使用 docker run -itd --name=graph -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph 在启动的时候预加载一个内置的样例图。可以通过 RESTful API 进行验证。具体步骤可以参考 5.1.1

另外，如果我们希望能够在一个文件中管理除了 server 之外的其他 Hugegraph 相关的实例，我们也可以使用 docker-compose完成部署，使用命令 docker-compose up -d，（当然只配置 server 也是可以的）以下是一个样例的 docker-compose.yml:

version: '3'
services:
  graph:
    image: hugegraph/hugegraph
    # environment:
    #  - PRELOAD=true
    # PRELOAD 为可选参数，为 True 时可以在启动的时候预加载一个内置的样例图
    ports:
      - 8080:8080

注意：

hugegraph 的 docker 镜像是一个便捷版本，用于快速启动 hugegraph，并不是官方发布物料包方式。你可以从 ASF Release Distribution Policy 中得到更多细节。

推荐使用 release tag(如 1.2.0) 以获取稳定版。使用 latest tag 可以使用开发中的最新功能。

3.4 使用 tools 工具部署 (Outdated)

HugeGraph-Tools 提供了一键部署的命令行工具，用户可以使用该工具快速地一键下载、解压、配置并启动 HugeGraph-Server 和 HugeGraph-Hubble，最新的 HugeGraph-Toolchain 中已经包含所有的这些工具，直接下载它解压就有工具包集合了

# download toolchain package, it includes loader + tool + hubble, please check the latest version (here is 1.2.0)
wget https://downloads.apache.org/incubator/hugegraph/1.2.0/apache-hugegraph-toolchain-incubating-1.2.0.tar.gz
tar zxf *hugegraph-*.tar.gz
# enter the tool's package
cd *hugegraph*/*tool*

注：${version} 为版本号，最新版本号可参考 Download 页面，或直接从 Download 页面点击链接下载

HugeGraph-Tools 的总入口脚本是 bin/hugegraph，用户可以使用 help 子命令查看其用法，这里只介绍一键部署的命令。

bin/hugegraph deploy -v {hugegraph-version} -p {install-path} [-u {download-path-prefix}]

{hugegraph-version} 表示要部署的 HugeGraphServer 及 HugeGraphStudio 的版本，用户可查看 conf/version-mapping.yaml 文件获取版本信息，{install-path} 指定 HugeGraphServer 及 HugeGraphStudio 的安装目录，{download-path-prefix} 可选，指定 HugeGraphServer 及 HugeGraphStudio tar 包的下载地址，不提供时使用默认下载地址，比如要启动 0.6 版本的 HugeGraph-Server 及 HugeGraphStudio 将上述命令写为 bin/hugegraph deploy -v 0.6 -p services 即可。

4 配置

如果需要快速启动 HugeGraph 仅用于测试，那么只需要进行少数几个配置项的修改即可（见下一节）。

详细的配置介绍请参考配置文档及配置项介绍。

5 启动

5.1 使用启动脚本启动

启动分为”首次启动”和”非首次启动”，这么区分是因为在第一次启动前需要初始化后端数据库，然后启动服务。

而在人为停掉服务后，或者其他原因需要再次启动服务时，因为后端数据库是持久化存在的，直接启动服务即可。

HugeGraphServer 启动时会连接后端存储并尝试检查后端存储版本号，如果未初始化后端或者后端已初始化但版本不匹配时（旧版本数据），HugeGraphServer 会启动失败，并给出错误信息。

如果需要外部访问 HugeGraphServer，请修改 rest-server.properties 的 restserver.url 配置项（默认为 http://127.0.0.1:8080），修改成机器名或 IP 地址。

由于各种后端所需的配置（hugegraph.properties）及启动步骤略有不同，下面逐一对各后端的配置及启动做介绍。

如果想要使用 HugeGraph 鉴权模式，在后面正式启动 Server 之前应按照 Server 鉴权配置进行配置。

5.1.1 RocksDB

点击展开/折叠 RocksDB 配置及启动方法

RocksDB 是一个嵌入式的数据库，不需要手动安装部署，要求 GCC 版本 >= 4.3.0（GLIBCXX_3.4.10），如不满足，需要提前升级 GCC

修改 hugegraph.properties

backend=rocksdb
serializer=binary
rocksdb.data_path=.
rocksdb.wal_path=.

初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）

cd *hugegraph-${version}
bin/init-store.sh

启动 server

bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

提示的 url 与 rest-server.properties 中配置的 restserver.url 一致

5.1.2 HBase

点击展开/折叠 HBase 配置及启动方法

用户需自行安装 HBase，要求版本 2.0 以上，下载地址

修改 hugegraph.properties

backend=hbase
serializer=hbase
# hbase backend config
hbase.hosts=localhost
hbase.port=2181
# Note: recommend to modify the HBase partition number by the actual/env data amount & RS amount before init store
# it may influence the loading speed a lot
#hbase.enable_partition=true
#hbase.vertex_partitions=10
#hbase.edge_partitions=30

初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）

cd *hugegraph-${version}
bin/init-store.sh

启动 server

bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

更多其它后端配置可参考配置项介绍

5.1.3 MySQL

点击展开/折叠 MySQL 配置及启动方法

由于 MySQL 是在 GPL 协议下，与 Apache 协议不兼容，用户需自行安装 MySQL，下载地址

下载 MySQL 的驱动包，比如 mysql-connector-java-8.0.30.jar，并放入 HugeGraph-Server 的 lib 目录下。

修改 hugegraph.properties，配置数据库 URL，用户名和密码，store 是数据库名，如果没有会被自动创建。

backend=mysql
serializer=mysql
store=hugegraph
# mysql backend config
jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://127.0.0.1:3306
jdbc.username=
jdbc.password=
jdbc.reconnect_max_times=3
jdbc.reconnect_interval=3
jdbc.ssl_mode=false

初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）

cd *hugegraph-${version}
bin/init-store.sh

启动 server

bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

5.1.4 Cassandra

点击展开/折叠 Cassandra 配置及启动方法

用户需自行安装 Cassandra，要求版本 3.0 以上，下载地址

修改 hugegraph.properties

backend=cassandra
serializer=cassandra
# cassandra backend config
cassandra.host=localhost
cassandra.port=9042
cassandra.username=
cassandra.password=
#cassandra.connect_timeout=5
#cassandra.read_timeout=20
#cassandra.keyspace.strategy=SimpleStrategy
#cassandra.keyspace.replication=3

初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）

cd *hugegraph-${version}
bin/init-store.sh
Initing HugeGraph Store...
2017-12-01 11:26:51 1424  [main] [INFO ] org.apache.hugegraph.HugeGraph [] - Opening backend store: 'cassandra'
2017-12-01 11:26:52 2389  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Failed to connect keyspace: hugegraph, try init keyspace later
2017-12-01 11:26:52 2472  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Failed to connect keyspace: hugegraph, try init keyspace later
2017-12-01 11:26:52 2557  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Failed to connect keyspace: hugegraph, try init keyspace later
2017-12-01 11:26:53 2797  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Store initialized: huge_graph
2017-12-01 11:26:53 2945  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Store initialized: huge_schema
2017-12-01 11:26:53 3044  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Store initialized: huge_index
2017-12-01 11:26:53 3046  [pool-3-thread-1] [INFO ] org.apache.hugegraph.backend.Transaction [] - Clear cache on event 'store.init'
2017-12-01 11:26:59 9720  [main] [INFO ] org.apache.hugegraph.HugeGraph [] - Opening backend store: 'cassandra'
2017-12-01 11:27:00 9805  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Failed to connect keyspace: hugegraph1, try init keyspace later
2017-12-01 11:27:00 9886  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Failed to connect keyspace: hugegraph1, try init keyspace later
2017-12-01 11:27:00 9955  [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Failed to connect keyspace: hugegraph1, try init keyspace later
2017-12-01 11:27:00 10175 [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Store initialized: huge_graph
2017-12-01 11:27:00 10321 [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Store initialized: huge_schema
2017-12-01 11:27:00 10413 [main] [INFO ] org.apache.hugegraph.backend.store.cassandra.CassandraStore [] - Store initialized: huge_index
2017-12-01 11:27:00 10413 [pool-3-thread-1] [INFO ] org.apache.hugegraph.backend.Transaction [] - Clear cache on event 'store.init'

启动 server

bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

5.1.5 Memory

点击展开/折叠 Memory 配置及启动方法

修改 hugegraph.properties

backend=memory
serializer=text

Memory 后端的数据是保存在内存中无法持久化的，不需要初始化后端，这也是唯一一个不需要初始化的后端。

启动 server

bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

提示的 url 与 rest-server.properties 中配置的 restserver.url 一致

5.1.6 ScyllaDB

点击展开/折叠 ScyllaDB 配置及启动方法

用户需自行安装 ScyllaDB，推荐版本 2.1 以上，下载地址

修改 hugegraph.properties

backend=scylladb
serializer=scylladb
# cassandra backend config
cassandra.host=localhost
cassandra.port=9042
cassandra.username=
cassandra.password=
#cassandra.connect_timeout=5
#cassandra.read_timeout=20
#cassandra.keyspace.strategy=SimpleStrategy
#cassandra.keyspace.replication=3

由于 scylladb 数据库本身就是基于 cassandra 的”优化版”，如果用户未安装 scylladb，也可以直接使用 cassandra 作为后端存储，只需要把 backend 和 serializer 修改为 scylladb，host 和 post 指向 cassandra 集群的 seeds 和 port 即可，但是并不建议这样做，这样发挥不出 scylladb 本身的优势了。

初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）

cd *hugegraph-${version}
bin/init-store.sh

启动 server

bin/start-hugegraph.sh
Starting HugeGraphServer...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

5.1.7 启动 server 的时候创建示例图

在脚本启动时候携带 -p true参数，表示 preload, 即创建示例图图

bin/start-hugegraph.sh -p true
Starting HugeGraphServer in daemon mode...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK

并且使用 RESTful API 请求 HugeGraphServer 得到如下结果：

> curl "http://localhost:8080/graphs/hugegraph/graph/vertices" | gunzip
{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}

代表创建示例图成功。

5.2 使用 Docker

在 3.3 使用 Docker 容器中，我们已经介绍了如何使用 docker 部署 hugegraph-server, 我们还可以使用其他的后端存储或者设置参数在 sever 启动的时候加载样例图

5.2.1 使用 Cassandra 作为后端

点击展开/折叠 Cassandra 配置及启动方法

在使用 Docker 的时候，我们可以使用 Cassandra 作为后端存储。我们更加推荐直接使用 docker-compose 来对于 server 以及 Cassandra 进行统一管理

样例的 docker-compose.yml 可以在 github 中获取，使用 docker-compose up -d 启动。(如果使用 cassandra 4.0 版本作为后端存储，则需要大约两个分钟初始化，请耐心等待)

version: "3"
services:
  graph:
    image: hugegraph/hugegraph
    container_name: cas-graph
    ports:
      - 8080:8080
    environment:
      hugegraph.backend: cassandra
      hugegraph.serializer: cassandra
      hugegraph.cassandra.host: cas-cassandra
      hugegraph.cassandra.port: 9042
    networks:
      - ca-network
    depends_on:
      - cassandra
    healthcheck:
      test: ["CMD", "bin/gremlin-console.sh", "--" ,"-e", "scripts/remote-connect.groovy"]
      interval: 10s
      timeout: 30s
      retries: 3
  cassandra:
    image: cassandra:4
    container_name: cas-cassandra
    ports:
      - 7000:7000
      - 9042:9042
    security_opt:
      - seccomp:unconfined
    networks:
      - ca-network
    healthcheck:
      test: ["CMD", "cqlsh", "--execute", "describe keyspaces;"]
      interval: 10s
      timeout: 30s
      retries: 5
networks:
  ca-network:
volumes:
  hugegraph-data:

在这个 yaml 中，需要在环境变量中以 hugegraph.<parameter_name>的形式进行参数传递，配置 Cassandra 相关的参数。

具体来说，在 hugegraph.properties 配置文件中，提供了 backend=xxx, cassandra.host=xxx 等配置项，为了配置这些配置项，在传递环境变量的过程之中，我们需要在这些配置项前加上 hugegrpah.，即 hugegraph.backend 和 hugegraph.cassandra.host。

其他配置可以参照 4 配置

5.2.2 启动 server 的时候创建示例图

在 docker 启动的时候设置环境变量 PRELOAD=true, 从而实现启动脚本的时候加载数据。

使用docker run

使用 docker run -itd --name=graph -p 8080:8080 -e PRELOAD=true hugegraph/hugegraph:latest
使用docker-compose

创建docker-compose.yml，具体文件如下，在环境变量中设置 PRELOAD=true。其中，example.groovy 是一个预定义的脚本，用于预加载样例数据。如果有需要，可以通过挂载新的 example.groovy 脚本改变预加载的数据。
```
version: '3'
  services:
    graph:
      image: hugegraph/hugegraph:latest
      container_name: graph
      environment:
        - PRELOAD=true
      volumes:
        - /path/to/yourscript:/hugegraph/scripts/example.groovy
      ports:
        - 8080:8080
```
使用命令 docker-compose up -d 启动容器

使用 RESTful API 请求 HugeGraphServer 得到如下结果：

> curl "http://localhost:8080/graphs/hugegraph/graph/vertices" | gunzip
{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}

代表创建示例图成功。

6 访问 Server

6.1 服务启动状态校验

jps 查看服务进程

jps
6475 HugeGraphServer

curl 请求 RESTful API

echo `curl -o /dev/null -s -w %{http_code} "http://localhost:8080/graphs/hugegraph/graph/vertices"`

返回结果 200，代表 server 启动正常

6.2 请求 Server

HugeGraphServer 的 RESTful API 包括多种类型的资源，典型的包括 graph、schema、gremlin、traverser 和 task

graph 包含 vertices、edges
schema 包含 vertexlabels、propertykeys、edgelabels、indexlabels
gremlin 包含各种 Gremlin 语句，如 g.v()，可以同步或者异步执行
traverser 包含各种高级查询，包括最短路径、交叉点、N 步可达邻居等
task 包含异步任务的查询和删除

6.2.1 获取 `hugegraph` 的顶点及相关属性

curl http://localhost:8080/graphs/hugegraph/graph/vertices

说明

由于图的点和边很多，对于 list 型的请求，比如获取所有顶点，获取所有边等，Server 会将数据压缩再返回，所以使用 curl 时得到一堆乱码，可以重定向至 gunzip 进行解压。推荐使用 Chrome 浏览器 + Restlet 插件发送 HTTP 请求进行测试。
```
curl "http://localhost:8080/graphs/hugegraph/graph/vertices" | gunzip
```
当前 HugeGraphServer 的默认配置只能是本机访问，可以修改配置，使其能在其他机器访问。
```
vim conf/rest-server.properties
restserver.url=http://0.0.0.0:8080
```

响应体如下：

{
    "vertices": [
        {
            "id": "2lop",
            "label": "software",
            "type": "vertex",
            "properties": {
                "price": [
                    {
                        "id": "price",
                        "value": 328
                    }
                ],
                "name": [
                    {
                        "id": "name",
                        "value": "lop"
                    }
                ],
                "lang": [
                    {
                        "id": "lang",
                        "value": "java"
                    }
                ]
            }
        },
        {
            "id": "1josh",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": [
                    {
                        "id": "name",
                        "value": "josh"
                    }
                ],
                "age": [
                    {
                        "id": "age",
                        "value": 32
                    }
                ]
            }
        },
        ...
    ]
}

详细的 API 请参考 RESTful-API 文档。

另外也可以通过访问 localhost:8080/swagger-ui/index.html 查看 API。

在使用 Swagger UI 调试 HugeGraph 提供的 API 时，如果 HugeGraph Server 开启了鉴权模式，可以在 Swagger 页面输入鉴权信息。

当前 HugeGraph 支持基于 Basic 和 Bearer 两种形式设置鉴权信息。

7 停止 Server

$cd *hugegraph-${version}
$bin/stop-hugegraph.sh

8 使用 IntelliJ IDEA 调试 Server

请参考在 IDEA 中配置 Server 开发环境

Last modified January 22, 2024: fix: server quickstart swagger-ui image link (#325) (f4b65194)

Install/Build HugeGraph-Server

HugeGraph-Server Quick Start

1 HugeGraph-Server 概述

2 依赖

2.1 安装 Java 11 (JDK 11)

3 部署

3.1 下载 tar 包

3.2 源码编译

3.3 使用 Docker 容器 (便于测试)

3.4 使用 tools 工具部署 (Outdated)

4 配置

5 启动

5.1 使用启动脚本启动

5.1.1 RocksDB

5.1.2 HBase

5.1.3 MySQL

5.1.4 Cassandra

5.1.5 Memory

5.1.6 ScyllaDB

5.1.7 启动 server 的时候创建示例图

5.2 使用 Docker

5.2.1 使用 Cassandra 作为后端

5.2.2 启动 server 的时候创建示例图

6 访问 Server

6.1 服务启动状态校验

6.2 请求 Server

6.2.1 获取 hugegraph 的顶点及相关属性

7 停止 Server

8 使用 IntelliJ IDEA 调试 Server

6.2.1 获取 `hugegraph` 的顶点及相关属性