使用指南

• 1: HugeGraph 架构概览
• 2: HugeGraph 设计理念
• 3: HugeGraph Plugin 机制及插件扩展流程
• 4: HugeGraph工具链本地测试指南
• 5: Backup Restore
• 6: HugeGraph Docker 集群部署指南
• 7: FAQ
• 8: 报告安全问题

1 - HugeGraph 架构概览

全栈组件

HugeGraph 生态由职责不同的图数据库、图计算、图 AI 和工具链组件组成。HugeGraph Server 提供 OLTP 图数据库服务；HugeGraph-Computer 与 Vermeer 是独立的 OLAP 图计算引擎；HugeGraph-AI 提供图 AI 能力。Toolchain 中的客户端、数据导入、可视化和运维工具为应用及运维人员提供配套入口。

图：Server 以 HStore 后端为例；RocksDB、HBase 等独立后端见下方 Mermaid。Vermeer 和 HugeGraph-Computer 是独立的 OLAP 引擎，虚线表示可选接入。

生态接入

flowchart TB
  Apps["应用 / 运维"] --> Toolchain["Toolchain"] --> Server["Server REST API"]
  AI["AI"] -. REST .-> Server
  Computer["Computer"] -. REST .-> Server
  Vermeer["Vermeer"] -. PD .-> PD["PD"]
  Vermeer -. 扫描 .-> Store["Store"]
  Vermeer -. 写回 .-> Server

虚线表示可选的 HugeGraph 接入，不代表所有 AI、Computer 或 Vermeer 任务都必须连接 Server、PD 或 Store。Computer 和 AI 通过 Server REST API 读写图数据。Vermeer 的 HugeGraph 输入模式向 PD 查询分区元数据，并直接向 Store 扫描 HStore 分区；选择 HugeGraph 结果输出时，再通过 Server REST API 写回结果。

Server 内部结构

flowchart TB
  API["REST API / Gremlin"] --> Core["Core"] --> Adapter["后端适配"]
  Adapter --> RocksDB["RocksDB"]
  Adapter --> HBase["HBase"]
  Adapter --> HStore["HStore"]
  HStore --> PD["PD"]
  HStore --> Store["Store"]

Server 的 REST API 和 Gremlin 接口把请求交给 Core，再由存储后端适配器执行读写。RocksDB 和 HBase 是独立后端；HStore 适配器从 PD 获取集群元数据和分区信息，并向 Store 节点发送图数据操作。PD 管理集群元数据与分区，不承载图数据读写路径。

当前 Server 提供 RocksDB、HBase、HStore 和内存后端实现。内存后端主要用于测试或临时使用，不属于正式持久化部署选项；生产部署方式见 Server 快速上手。

Toolchain 的主要组件如下：

• Hubble：通过 Web 界面连接图数据库，管理 Schema、导入数据并执行查询。
• Loader：转换多种数据源并批量导入图数据。
• Tools：提供部署、管理和备份恢复命令。
• Client：封装 Server 连接、Schema 管理、图数据读写和查询；支持 Java、Python 和 Go 客户端，Rust 客户端仍在开发中。

独立图计算引擎

• Vermeer：提供独立的图计算服务及算法接口。
• HugeGraph-Computer：基于 BSP/Pregel 模型的 Java 分布式图计算引擎。

历史架构图

下图保留作历史参考，其中 Server 同时承担 OLTP 与 OLAP、以及多种旧后端的标注不代表 当前主线实现。

展开旧版架构图

2 - HugeGraph 设计理念

1. 属性图模型

版本说明：本页保留早期设计内容。属性图模型和顶点 ID 策略仍与 当前主线源码相符；图示、分区结论及事务实现描述按各节注明的范围阅读，不能直接当作当前部署或存储实现说明。

常见的图数据表示模型有两种，分别是RDF（Resource Description Framework）模型和属性图模型。 RDF和Property Graph都是最基础、最有名的图表示模式，都能够表示各种图的实体关系建模。 RDF是W3C标准，而Property Graph是工业标准，受到广大图数据库厂商的广泛支持。HugeGraph目前采用Property Graph。

HugeGraph采用属性图模型。下图以人物和图书为例，展示顶点与有向边各自的标签和属性；这是逻辑模型示意，不描述 当前主线的内部数据布局。

图：顶点和边分别携带自己的标签与属性。

在HugeGraph内部，每个顶点 / 边由唯一的 VertexId / EdgeId 标识，属性存储在对应点 / 边内部。而顶点与顶点之间的关系 / 映射则是通过边来存储的。

顶点属性值通过边指针方式存储时，如果要更新一个顶点特定的属性值直接通过覆盖写入即可，其弊端是冗余存储了VertexId；如果要更新关系的属性需要通过read-and-modify方式，先读取所有属性，修改部分属性，然后再写入存储系统，更新效率较低。 从经验来看顶点属性的修改需求较多，而边的属性修改需求较少，例如PageRank和Graph Cluster等计算都需要频繁修改顶点的属性值。

2. 图分区方案

版本说明：Edge Cut 与 Vertex Cut 的比较属于历史设计背景。当前主线的 PD 与 Store 源码没有把“HugeGraph 采用 Edge Cut”定义为实现契约，因此下文该结论不适用于描述 当前主线的实际分区与副本机制；当前分布式部署请参考 HStore 快速上手。

对于分布式图数据库而言，图的分区存储方式有两种：分别是边分割存储（Edge Cut）和点分割存储（Vertex Cut），如下图所示。使用Edge Cut方式存储图时，任何一个顶点只会出现在一台机器上，而边可能分布在不同机器上，这种存储方式有可能导致边多次存储。 使用Vertex Cut方式存储图时，任何一条边只会出现在一台机器上，而每相同的一个点可能分布到不同机器上，这种存储方式可能会导致顶点多次存储。

采用EdgeCut分区方案可以支持高性能的插入和更新操作，而VertexCut分区方案更适合静态图查询分析，因此EdgeCut适合OLTP图查询，VertexCut更适合OLAP的图查询。早期设计资料曾记载 HugeGraph 采用 Edge Cut。此处保留该历史结论，不将其视为当前分区实现说明。

3. VertexId 策略

HugeGraph的Vertex支持四种ID策略，在同一个图数据库中不同的VertexLabel可以使用不同的Id策略，目前HugeGraph支持的Id策略分别是：

• 自动生成（AUTOMATIC）：使用Snowflake算法自动生成全局唯一Id，Long类型；
• 主键（PRIMARY_KEY）：通过VertexLabel+PrimaryKeyValues生成Id，String类型；
• 自定义（CUSTOMIZE_STRING|CUSTOMIZE_NUMBER）：用户自定义Id，分为String和Long类型两种，需自己保证Id的唯一性；
• 自定义UUID（CUSTOMIZE_UUID）：用户自定义UUID形式的Id，需自己保证Id的唯一性；

默认的Id策略是AUTOMATIC，如果用户调用primaryKeys()方法并设置了正确的PrimaryKeys，则自动启用PRIMARY_KEY策略。启用PRIMARY_KEY策略后HugeGraph能根据PrimaryKeys实现数据去重。

1. AUTOMATIC ID策略

1schema.vertexLabel("person")
2     .useAutomaticId()
3     .properties("name", "age", "city")
4     .create();
5graph.addVertex(T.label, "person","name", "marko", "age", 18, "city", "Beijing");

2. PRIMARY_KEY ID策略

1schema.vertexLabel("person")
2     .usePrimaryKeyId()
3     .properties("name", "age", "city")
4     .primaryKeys("name", "age")
5     .create();
6graph.addVertex(T.label, "person","name", "marko", "age", 18, "city", "Beijing");

3. CUSTOMIZE_STRING ID策略

1schema.vertexLabel("person")
2     .useCustomizeStringId()
3     .properties("name", "age", "city")
4     .create();
5graph.addVertex(T.label, "person", T.id, "123456", "name", "marko","age", 18, "city", "Beijing");

4. CUSTOMIZE_NUMBER ID策略

1schema.vertexLabel("person")
2     .useCustomizeNumberId()
3     .properties("name", "age", "city")
4     .create();
5graph.addVertex(T.label, "person", T.id, 123456, "name", "marko","age", 18, "city", "Beijing");

5. CUSTOMIZE_UUID ID策略

1schema.vertexLabel("person")
2     .useCustomizeUuidId()
3     .properties("name", "age", "city")
4     .create();
5graph.addVertex(T.label, "person", T.id, UUID.randomUUID(), "name", "marko","age", 18, "city", "Beijing");

如果用户需要Vertex去重，有三种方案分别是：

1. 采用PRIMARY_KEY策略，自动覆盖，适合大数据量批量插入，用户无法知道是否发生了覆盖行为
2. 采用AUTOMATIC策略，read-and-modify，适合小数据量插入，用户可以明确知道是否发生覆盖
3. 采用CUSTOMIZE_STRING或CUSTOMIZE_NUMBER策略，用户自己保证唯一

4. EdgeId 策略

当前实现提示：本节的四项组合是历史简化描述。当前 EdgeId 还区分边方向及父、子边标签；其实际字段见 Server 源码中的 EdgeId 实现。需要依赖 ID 格式或持久化键时，应以对应版本源码为准。

HugeGraph的EdgeId是由srcVertexId+edgeLabel+sortKey+tgtVertexId四部分组合而成。其中sortKey是HugeGraph的一个重要概念。在Edge中加入sortKey作为Edge的唯一标识的原因有两个：

1. 如果两个顶点之间存在多条相同Label的边可通过sortKey来区分
2. 对于SuperNode的节点，可以通过sortKey来排序截断。

由于EdgeId是由srcVertexId+edgeLabel+sortKey+tgtVertexId四部分组合，多次插入相同的Edge时HugeGraph会自动覆盖以实现去重。需要注意的是如果批量插入模式下Edge的属性也将会覆盖。

另外由于HugeGraph的EdgeId采用自动去重策略，对于self-loop（一个顶点存在一条指向自身的边）的情况下HugeGraph认为仅有一条边，对于采用AUTOMATIC策略的图数据库（例如TitianDB ）则会认为该图存在两条边。

HugeGraph的边仅支持有向边，无向边可以创建Out和In两条边来实现。

5. HugeGraph 事务概览

版本范围：下文关于 HugeGraph 隔离级别、线程绑定和后端原子性的描述保留为历史实现说明。各后端的事务隔离与失败回滚边界应以对应实现为准，不应将下述历史描述当作跨后端保证。

TinkerPop事务概述

TinkerPop 事务是对数据库执行操作的工作单元，一个事务内的一组操作要么执行成功，要么全部失败。详细介绍请参考TinkerPop官方文档：http://tinkerpop.apache.org/docs/current/reference/#transactions

TinkerPop事务操作接口

• open 打开事务
• commit 提交事务
• rollback 回滚事务
• close 关闭事务

TinkerPop事务规范

• 事务必须显式提交后才可生效（未提交时修改操作只有本事务内查询可看到）
• 事务必须打开之后才可提交或回滚
• 如果事务设置自动打开则无需显式打开（默认方式），如果设置手动打开则必须显式打开
• 可设置事务关闭时：自动提交、自动回滚（默认方式）、手动（禁止显式关闭）等3种模式
• 事务在提交或回滚后必须是关闭状态
• 事务在查询后必须是打开状态
• 事务（非threaded tx）必须线程隔离，多线程操作同一事务互不影响

更多事务规范用例见：Transaction Test

HugeGraph事务实现

• 一个事务中所有的操作要么成功要么失败
• 一个事务只能读取到另外一个事务已提交的内容（Read committed）
• 所有未提交的操作均能在本事务中查询出来，包括：
  • 增加顶点能够查询出该顶点
  • 删除顶点能够过滤掉该顶点
  • 删除顶点能够过滤掉该顶点相关边
  • 增加边能够查询出该边
  • 删除边能够过滤掉该边
  • 增加/修改（顶点、边）属性能够在查询时生效
  • 删除（顶点、边）属性能够在查询时生效
• 所有未提交的操作在事务回滚后均失效，包括：
  • 顶点、边的增加、删除
  • 属性的增加/修改、删除

示例：一个事务无法读取另一个事务未提交的内容

 1    static void testUncommittedTx(final HugeGraph graph) throws InterruptedException {
 2
 3        final CountDownLatch latchUncommit = new CountDownLatch(1);
 4        final CountDownLatch latchRollback = new CountDownLatch(1);
 5
 6        Thread thread = new Thread(() -> {
 7            // this is a new transaction in the new thread
 8            graph.tx().open();
 9
10            System.out.println("current transaction operations");
11
12            Vertex james = graph.addVertex(T.label, "author",
13                                           "id", 1, "name", "James Gosling",
14                                           "age", 62, "lived", "Canadian");
15            Vertex java = graph.addVertex(T.label, "language", "name", "java",
16                                          "versions", Arrays.asList(6, 7, 8));
17            james.addEdge("created", java);
18
19            // we can query the uncommitted records in the current transaction
20            System.out.println("current transaction assert");
21            assert graph.vertices().hasNext() == true;
22            assert graph.edges().hasNext() == true;
23
24            latchUncommit.countDown();
25
26            try {
27                latchRollback.await();
28            } catch (InterruptedException e) {
29                throw new RuntimeException(e);
30            }
31
32            System.out.println("current transaction rollback");
33            graph.tx().rollback();
34        });
35
36        thread.start();
37
38        // query none result in other transaction when not commit()
39        latchUncommit.await();
40        System.out.println("other transaction assert for uncommitted");
41        assert !graph.vertices().hasNext();
42        assert !graph.edges().hasNext();
43
44        latchRollback.countDown();
45        thread.join();
46
47        // query none result in other transaction after rollback()
48        System.out.println("other transaction assert for rollback");
49        assert !graph.vertices().hasNext();
50        assert !graph.edges().hasNext();
51    }

事务实现原理

• 服务端内部通过将事务与线程绑定实现隔离（ThreadLocal）
• 本事务未提交的内容按照时间顺序覆盖老数据以供本事务查询最新版本数据
• 底层依赖后端数据库保证事务原子性操作（如RocksDB的batch接口保证原子性）

注意

REST API 未提供独立的事务生命周期接口；写操作接口会在服务端调用相应的事务提交逻辑。

TinkerPop API允许打开事务，请求完成时会自动关闭(Gremlin Server强制关闭)

3 - HugeGraph Plugin 机制及插件扩展流程

背景

1. HugeGraph 不仅开源开放，而且要做到简单易用，一般用户无需更改源码也能轻松增加插件扩展功能。
2. HugeGraph 支持多种内置存储后端，也允许用户无需更改现有源码的情况下扩展自定义后端。
3. HugeGraph 支持全文检索，全文检索功能涉及到各语言分词，目前已内置 7 种分词器（ansj、hanlp、smartcn、jieba、jcseg、mmseg4j、ikanalyzer），也允许用户无需更改现有源码的情况下扩展自定义分词器。

可扩展维度

目前插件方式提供如下几个维度的扩展项：

• 后端存储
• 序列化器
• 自定义配置项
• 分词器

插件实现机制

1. HugeGraph 提供插件接口 HugeGraphPlugin，通过 Java SPI 机制支持插件化
2. HugeGraph 在 HugeGraphPlugin 接口上以静态方法提供了 4 个扩展项注册函数：registerOptions()、registerBackend()、registerSerializer()、registerAnalyzer()
3. 插件实现者实现相应的 Options、Backend、Serializer 或 Analyzer 的接口
4. 插件实现者实现 HugeGraphPlugin 接口的register()方法，在该方法中注册上述第 3 点所列的具体实现类，并打成 jar 包
5. 插件使用者将 jar 包放在 HugeGraph Server 安装目录的plugins目录下，修改相关配置项为插件自定义值，重启即可生效

插件实现流程实例

1 新建一个 maven 项目

1.1 项目名称取名：hugegraph-plugin-demo

1.2 添加hugegraph-core Jar 包依赖

maven pom.xml 详细内容如下。hugegraph.version 应与要兼容的 Server 版本一致；此处以当前主线版本 1.7.0 为例：

 1<?xml version="1.0" encoding="UTF-8"?>
 2
 3<project xmlns="http://maven.apache.org/POM/4.0.0"
 4         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 5         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 6
 7    <modelVersion>4.0.0</modelVersion>
 8    <groupId>org.apache.hugegraph</groupId>
 9    <artifactId>hugegraph-plugin-demo</artifactId>
10    <version>1.0.0</version>
11    <packaging>jar</packaging>
12
13    <name>hugegraph-plugin-demo</name>
14
15    <properties>
16        <hugegraph.version>1.7.0</hugegraph.version>
17    </properties>
18
19    <dependencies>
20        <dependency>
21            <groupId>org.apache.hugegraph</groupId>
22            <artifactId>hugegraph-core</artifactId>
23            <version>${hugegraph.version}</version>
24        </dependency>
25    </dependencies>
26</project>

2 实现扩展功能

2.1 扩展自定义后端

2.1.1 实现接口 BackendStoreProvider

• 可实现接口：org.apache.hugegraph.backend.store.BackendStoreProvider
• 或者继承抽象类：org.apache.hugegraph.backend.store.AbstractBackendStoreProvider

以 RocksDB 后端 RocksDBStoreProvider 为例：

 1public class RocksDBStoreProvider extends AbstractBackendStoreProvider {
 2
 3    protected String database() {
 4        return this.graph().toLowerCase();
 5    }
 6
 7    @Override
 8    protected BackendStore newSchemaStore(HugeConfig config, String store) {
 9        return new RocksDBStore.RocksDBSchemaStore(this, this.database(), store);
10    }
11
12    @Override
13    protected BackendStore newGraphStore(HugeConfig config, String store) {
14        return new RocksDBStore.RocksDBGraphStore(this, this.database(), store);
15    }
16
17    @Override
18    protected BackendStore newSystemStore(HugeConfig config, String store) {
19        return new RocksDBStore.RocksDBSystemStore(this, this.database(), store);
20    }
21
22    @Override
23    public String type() {
24        return "rocksdb";
25    }
26
27    @Override
28    public String driverVersion() {
29        return "1.11";
30    }
31}

2.1.2 实现接口 BackendStore

BackendStore 的核心抽象方法如下（接口默认辅助方法略）：

 1public interface BackendStore {
 2    // Store name
 3    String store();
 4
 5    // Stored version
 6    String storedVersion();
 7
 8    // Database name
 9    String database();
10
11    // Get the parent provider
12    BackendStoreProvider provider();
13
14    // Get the system schema store
15    SystemSchemaStore systemSchemaStore();
16
17    // Whether it is the storage of schema
18    boolean isSchemaStore();
19
20    // Open/close database
21    void open(HugeConfig config);
22    void close();
23    boolean opened();
24
25    // Initialize/clear database
26    void init();
27    void clear(boolean clearSpace);
28    boolean initialized();
29
30    // Delete all data of database (keep table structure)
31    void truncate();
32
33    // Add/delete data
34    void mutate(BackendMutation mutation);
35
36    // Query data
37    Iterator<BackendEntry> query(Query query);
38    Iterator<Iterator<BackendEntry>> query(Iterator<Query> queries,
39                                           Function<Query, Query> queryWriter,
40                                           HugeGraph hugeGraph);
41    Number queryNumber(Query query);
42
43    // Transaction
44    void beginTx();
45    void commitTx();
46    void rollbackTx();
47
48    // Get metadata by key
49    <R> R metadata(HugeType type, String meta, Object[] args);
50
51    // Backend features
52    BackendFeatures features();
53
54    // Increase next id for specific type
55    void increaseCounter(HugeType type, long increment);
56
57    // Get current counter for a specific type
58    long getCounter(HugeType type);
59}

2.1.3 扩展自定义序列化器

序列化器必须继承抽象类：org.apache.hugegraph.backend.serializer.AbstractSerializer(implements GraphSerializer, SchemaSerializer) 主要接口的定义如下：

 1public interface GraphSerializer {
 2    BackendEntry writeVertex(HugeVertex vertex);
 3    BackendEntry writeOlapVertex(HugeVertex vertex);
 4    BackendEntry writeVertexProperty(HugeVertexProperty<?> prop);
 5    HugeVertex readVertex(HugeGraph graph, BackendEntry entry);
 6    BackendEntry writeEdge(HugeEdge edge);
 7    BackendEntry writeEdgeProperty(HugeEdgeProperty<?> prop);
 8    HugeEdge readEdge(HugeGraph graph, BackendEntry entry);
 9    CIter<Edge> readEdges(HugeGraph graph, BackendEntry bytesEntry);
10    BackendEntry writeIndex(HugeIndex index);
11    HugeIndex readIndex(HugeGraph graph, ConditionQuery query, BackendEntry entry);
12    BackendEntry writeId(HugeType type, Id id);
13    Query writeQuery(Query query);
14}
15
16public interface SchemaSerializer {
17    BackendEntry writeVertexLabel(VertexLabel vertexLabel);
18    VertexLabel readVertexLabel(HugeGraph graph, BackendEntry entry);
19    BackendEntry writeEdgeLabel(EdgeLabel edgeLabel);
20    EdgeLabel readEdgeLabel(HugeGraph graph, BackendEntry entry);
21    BackendEntry writePropertyKey(PropertyKey propertyKey);
22    PropertyKey readPropertyKey(HugeGraph graph, BackendEntry entry);
23    BackendEntry writeIndexLabel(IndexLabel indexLabel);
24    IndexLabel readIndexLabel(HugeGraph graph, BackendEntry entry);
25}

2.1.4 扩展自定义配置项

增加自定义后端时，可能需要增加新的配置项，实现流程主要包括：

• 增加配置项容器类，并实现接口org.apache.hugegraph.config.OptionHolder
• 提供单例方法public static OptionHolder instance()，并在对象初始化时调用方法OptionHolder.registerOptions()
• 增加配置项声明，单值配置项类型为ConfigOption、多值配置项类型为ConfigListOption

以 RocksDB 配置项定义为例：

 1public class RocksDBOptions extends OptionHolder {
 2
 3    private RocksDBOptions() {
 4        super();
 5    }
 6
 7    private static volatile RocksDBOptions instance;
 8
 9    public static synchronized RocksDBOptions instance() {
10        if (instance == null) {
11            instance = new RocksDBOptions();
12            instance.registerOptions();
13        }
14        return instance;
15    }
16
17    public static final ConfigOption<String> DATA_PATH =
18            new ConfigOption<>(
19                    "rocksdb.data_path",
20                    "The path for storing data of RocksDB.",
21                    disallowEmpty(),
22                    "rocksdb-data/data"
23            );
24
25    public static final ConfigOption<String> WAL_PATH =
26            new ConfigOption<>(
27                    "rocksdb.wal_path",
28                    "The path for storing WAL of RocksDB.",
29                    disallowEmpty(),
30                    "rocksdb-data/wal"
31            );
32
33    public static final ConfigListOption<String> DATA_DISKS =
34            new ConfigListOption<>(
35                    "rocksdb.data_disks",
36                    false,
37                    "The optimized disks for storing data of RocksDB. " +
38                    "The format of each element: `STORE/TABLE: /path/disk`." +
39                    "Allowed keys are [g/vertex, g/edge_out, g/edge_in, " +
40                    "g/vertex_label_index, g/edge_label_index, " +
41                    "g/range_int_index, g/range_float_index, " +
42                    "g/range_long_index, g/range_double_index, " +
43                    "g/secondary_index, g/search_index, g/shard_index, " +
44                    "g/unique_index, g/olap]",
45                    null,
46                    String.class,
47                    ImmutableList.of()
48            );
49}

2.2 扩展自定义分词器

分词器需要实现接口org.apache.hugegraph.analyzer.Analyzer，以实现一个 SpaceAnalyzer 空格分词器为例。

 1package org.apache.hugegraph.plugin;
 2
 3import java.util.Arrays;
 4import java.util.HashSet;
 5import java.util.Set;
 6
 7import org.apache.hugegraph.analyzer.Analyzer;
 8
 9public class SpaceAnalyzer implements Analyzer {
10
11    @Override
12    public Set<String> segment(String text) {
13        return new HashSet<>(Arrays.asList(text.split(" ")));
14    }
15}

3. 实现插件接口，并进行注册

插件注册入口为HugeGraphPlugin.register()，自定义插件必须实现该接口方法，在其内部注册上述定义好的扩展项。接口org.apache.hugegraph.plugin.HugeGraphPlugin定义如下：

 1public interface HugeGraphPlugin {
 2
 3    String name();
 4
 5    void register();
 6
 7    String supportsMinVersion();
 8
 9    String supportsMaxVersion();
10}

并且 HugeGraphPlugin 提供了 4 个静态方法用于注册扩展项：

• registerOptions(String name, String classPath)：注册配置项
• registerBackend(String name, String classPath)：注册后端（BackendStoreProvider）
• registerSerializer(String name, String classPath)：注册序列化器
• registerAnalyzer(String name, String classPath)：注册分词器

下面以注册 SpaceAnalyzer 分词器为例：

 1package org.apache.hugegraph.plugin;
 2
 3public class DemoPlugin implements HugeGraphPlugin {
 4
 5    @Override
 6    public String name() {
 7        return "demo";
 8    }
 9
10    @Override
11    public void register() {
12        HugeGraphPlugin.registerAnalyzer("demo", SpaceAnalyzer.class.getName());
13    }
14
15    @Override
16    public String supportsMinVersion() {
17        return "1.7.0";
18    }
19
20    @Override
21    public String supportsMaxVersion() {
22        return "1.8.0";
23    }
24}

4. 配置 SPI 入口

1. 确保 services 目录存在：hugegraph-plugin-demo/resources/META-INF/services
2. 在 services 目录下建立文本文件：org.apache.hugegraph.plugin.HugeGraphPlugin
3. 文件内容如下：org.apache.hugegraph.plugin.DemoPlugin

5. 打 Jar 包

通过 maven 打包，在项目目录下执行命令mvn package，在 target 目录下会生成 Jar 包文件。使用时将该 Jar 包拷到plugins目录，重启服务即可生效。

4 - HugeGraph工具链本地测试指南

本指南帮助开发者在本地运行 HugeGraph 工具链测试。

1. 核心概念

1.1 核心依赖：HugeGraph Server

工具链的集成测试和功能测试都依赖 HugeGraph Server，包括 Client、Loader、Hubble、Spark Connector、Tools 等组件。

1.2 测试类型

• 单元测试 (Unit Tests)：测试单个函数/方法，不依赖外部服务
• API 测试 (ApiTestSuite)：测试 API 接口，需要运行中的 HugeGraph Server
• 功能测试 (FuncTestSuite)：端到端测试，需要完整的系统环境

2. 环境准备

2.1 系统要求

• 操作系统：Linux / macOS（Windows 使用 WSL2）
• JDK：>= 11，配置好 JAVA_HOME
• Maven：>= 3.6
• Python：>= 3.11（仅 Hubble 测试需要）

2.2 克隆代码

1git clone https://github.com/apache/hugegraph-toolchain.git
2cd hugegraph-toolchain

3. 部署测试环境

方式选择

• 脚本部署：指定 Server Commit，可复现 CI 使用的服务端版本
• Docker 部署：适合快速检查；测试失败时应先核对镜像与 Toolchain 的兼容性

详细安装说明参考 社区文档

3.1 脚本部署

参数说明

• $COMMIT_ID：指定 Server 源码的 Git Commit ID
• $DB_DATABASE / $DB_PASS：Loader JDBC 测试用的 MySQL 数据库名和密码

部署步骤

1. 安装 HugeGraph Server

1# 设置 Server 基线；需要可复现结果时请使用完整 commit SHA
2export COMMIT_ID="master"
3
4# 执行安装（脚本位于 /assembly/travis/ 目录）
5hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID

• 脚本会启动 HTTP 8080 和 HTTPS 8443 两个实例，并配置 admin/pa 认证。
• 执行前确认两个端口未被占用。

2. 安装可选依赖

1# Hadoop (仅 Loader HDFS 测试需要)
2hugegraph-loader/assembly/travis/install-hadoop.sh
3
4# MySQL (仅 Loader JDBC 测试需要)
5hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS

3. 健康检查

1curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs
2# 返回 {"graphs":["hugegraph"]} 表示成功

3.2 Docker 部署

注意：Docker 镜像可能版本滞后，如遇兼容性问题请使用脚本部署

快速启动

1docker network create hugegraph-net
2docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest

docker-compose 配置（可选）

完整配置示例，包含 Server、MySQL、Hadoop 服务（需要 Docker Compose V2）：

 1version: '3.8'
 2
 3services:
 4  hugegraph-server:
 5    image: hugegraph/hugegraph:latest  # 可以替换为特定版本，或构建自己的镜像
 6    container_name: hugegraph-server
 7    ports:
 8      - "8080:8080"  # HugeGraph Server HTTP 端口
 9    environment:
10      # 根据需要配置HugeGraph Server的参数，例如后端存储
11      - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb"
12    volumes:
13      # 如果需要持久化数据或挂载配置文件，可以在这里添加卷
14      # - ./hugegraph-data:/opt/hugegraph/data
15    healthcheck:
16      test: ["CMD-SHELL", "curl -f http://localhost:8080/graphspaces/DEFAULT/graphs || exit 1"]
17      interval: 5s
18      timeout: 3s
19      retries: 5
20    networks:
21      - hugegraph-net
22  
23  # 如果需要hugegraph-loader的JDBC测试，可以添加以下服务
24  #   mysql:
25  #     image: mysql:5.7
26  #     container_name: mysql-db
27  #     environment:
28  #       MYSQL_ROOT_PASSWORD: ${DB_PASS:-your_mysql_root_password} # 从环境变量读取，或使用默认值
29  #       MYSQL_DATABASE: ${DB_DATABASE:-hugegraph_test_db} # 从环境变量读取，或使用默认值
30  #     ports:
31  #       - "3306:3306"
32  #     volumes:
33  #       - ./mysql-data:/var/lib/mysql # 数据持久化
34  #     healthcheck:
35  #       test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${DB_PASS:-your_mysql_root_password}"]
36  #       interval: 5s
37  #       timeout: 3s
38  #       retries: 5
39  #     networks:
40  #       - hugegraph-net
41
42  # 如果需要hugegraph-loader的Hadoop/HDFS测试，可以添加以下服务
43  #   namenode:
44  #     image: johannestang/hadoop-namenode:2.0.0-hadoop2.8.5-java8
45  #     container_name: namenode
46  #     ports:
47  #       - "0.0.0.0:9870:9870"
48  #       - "0.0.0.0:8020:8020"
49  #     environment:
50  #       - CLUSTER_NAME=test-cluster
51  #       - HDFS_NAMENODE_USER=root
52  #       - HADOOP_CONF_DIR=/hadoop/etc/hadoop
53  #     volumes:
54  #       - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml
55  #       - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml
56  #       - namenode_data:/hadoop/dfs/name
57  #     command: bash -c "if [ ! -d /hadoop/dfs/name/current ]; then hdfs namenode -format; fi && /entrypoint.sh"
58  #     healthcheck:
59  #       test: ["CMD", "hdfs", "dfsadmin", "-report"]
60  #       interval: 5s
61  #       timeout: 3s
62  #       retries: 5
63  #     networks:
64  #       - hugegraph-net
65
66  #   datanode:
67  #     image: johannestang/hadoop-datanode:2.0.0-hadoop2.8.5-java8
68  #     container_name: datanode
69  #     depends_on:
70  #       - namenode
71  #     environment:
72  #       - CLUSTER_NAME=test-cluster
73  #       - HDFS_DATANODE_USER=root
74  #       - HADOOP_CONF_DIR=/hadoop/etc/hadoop
75  #     volumes:
76  #       - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml
77  #       - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml
78  #       - datanode_data:/hadoop/dfs/data
79  #     healthcheck:
80  #       test: ["CMD", "hdfs", "dfsadmin", "-report"]
81  #       interval: 5s
82  #       timeout: 3s
83  #       retries: 5
84  #     networks:
85  #       - hugegraph-net
86
87networks:
88  hugegraph-net:
89    driver: bridge
90volumes:
91  namenode_data:
92  datanode_data:

Hadoop 配置挂载

在与 docker-compose.yml 相同的目录下创建 ./config 文件夹用于挂载 Hadoop 配置文件。如果不需要 HDFS 测试，可以跳过此步骤。

📁 ./config/core-site.xml 内容：

1<configuration>
2    <property>
3        <name>fs.defaultFS</name>
4        <value>hdfs://namenode:8020</value>
5    </property>
6</configuration>

📁 ./config/hdfs-site.xml 内容：

 1<configuration>
 2    <property>
 3        <name>dfs.namenode.name.dir</name>
 4        <value>/hadoop/hdfs/name</value>
 5    </property>
 6    <property>
 7        <name>dfs.datanode.data.dir</name>
 8        <value>/hadoop/hdfs/data</value>
 9    </property>
10    <property>
11        <name>dfs.permissions.superusergroup</name>
12        <value>hadoop</value>
13    </property>
14    <property>
15        <name>dfs.support.append</name>
16        <value>true</value>
17    </property>
18</configuration>

Docker 操作

 1# 启动服务
 2docker compose up -d
 3
 4# 检查状态
 5docker compose ps
 6lsof -i:8080  # Server
 7lsof -i:8020  # Hadoop
 8lsof -i:3306  # MySQL
 9
10# 停止服务
11docker compose down

4. 运行测试

各工具的测试流程：

4.1 hugegraph-client

编译

1mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp

依赖服务

启动 HugeGraph Server（参考 第3节）

Server 鉴权配置

ApiTest 需要认证。使用 3.1 节的脚本安装时无需重复配置；自行部署 Server 时，认证配置和测试凭证必须与测试代码一致。

 1# 1. 修改鉴权模式
 2cp conf/rest-server.properties conf/rest-server.properties.backup
 3sed -i 's|#auth.authenticator=.*|auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator|' conf/rest-server.properties
 4grep auth.authenticator conf/rest-server.properties
 5sed -i 's|gremlin.graph=org.apache.hugegraph.HugeFactory|gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy|' conf/graphs/hugegraph.properties
 6
 7# 2. 设置密码
 8# 注：测试代码中默认使用 "pa" 作为密码，设置时需与测试保持一致
 9bin/stop-hugegraph.sh
10export PASSWORD="pa"  # 设置为测试默认密码
11echo -e "${PASSWORD}" | bin/init-store.sh
12bin/start-hugegraph.sh

运行测试

1# 检查环境
2curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs
3
4# 运行测试
5cd hugegraph-client
6mvn test -Dtest=UnitTestSuite -ntp      # 单元测试
7mvn test -Dtest=ApiTestSuite -ntp       # API测试（需 Server）
8mvn test -Dtest=FuncTestSuite -ntp      # 功能测试（需 Server）

测试失败时检查 Server 日志：logs/hugegraph-server.log

4.2 hugegraph-loader

编译

1mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp

依赖服务

• 必需：HugeGraph Server
• 可选：Hadoop (HDFS 测试)、MySQL (JDBC 测试)；Kafka 测试通过 Testcontainers 启动 Kafka 容器，因此还需要可用的 Docker daemon

运行测试

1cd hugegraph-loader
2mvn test -P unit -ntp   # 单元测试
3mvn test -P file -ntp   # 文件测试（需 Server）
4mvn test -P hdfs -ntp   # HDFS测试（需 Server + Hadoop）
5mvn test -P jdbc -ntp   # JDBC测试（需 Server + MySQL）
6mvn test -P kafka -ntp  # Kafka 测试（需 Server + Docker daemon；测试会启动 Kafka 容器）

4.3 hugegraph-hubble

编译

1mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp
2cd hugegraph-hubble
3mvn -e compile -Dmaven.javadoc.skip=true -ntp

依赖服务

1. 启动 Server（参考 第3节）

2. Python 环境

1python -m venv venv
2source venv/bin/activate  # Windows: venv\Scripts\activate
3python -m pip install -r hubble-dist/assembly/travis/requirements.txt

3. 构建并验证

1mvn package -Dmaven.test.skip=true
2# 可选：启动验证
3cd apache-hugegraph-hubble*/bin
4./start-hubble.sh -d && sleep 10
5curl http://localhost:8088/actuator/health
6./stop-hubble.sh

运行测试

 1# 单元测试
 2mvn test -P unit-test -pl hugegraph-hubble/hubble-be -ntp
 3
 4# 旧版 Python API 测试（需 Server；脚本会安装并启动 Hubble）
 5curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs  # 检查 Server
 6cd hugegraph-hubble
 7./hubble-dist/assembly/travis/run-api-test.sh
 8
 9# 当前 CI 的完整验收入口（需先生成 Hubble tar 包）
10HUBBLE_TARBALL="$(ls target/apache-hugegraph-hubble-*.tar.gz | head -n 1)"
11hubble-dist/assembly/travis/verify-hubble-issue-694.sh \
12  "$HUBBLE_TARBALL" http://127.0.0.1:8080

4.4 hugegraph-spark-connector

编译

1mvn install -pl hugegraph-client,hugegraph-spark-connector -am -Dmaven.javadoc.skip=true -DskipTests -ntp

运行测试

1cd hugegraph-spark-connector
2mvn test -ntp  # 需 Server 运行

4.5 hugegraph-tools

编译

1mvn install -pl hugegraph-client,hugegraph-tools -am -Dmaven.javadoc.skip=true -DskipTests -ntp

运行测试

1cd hugegraph-tools
2mvn test -Dtest=FuncTestSuite -ntp  # 需 Server 运行

5. 常见问题

服务连接问题

无法连接 Server、MySQL 或 Hadoop 时：

• 确认服务已启动（Server 必须在 8080 端口）
• 检查端口占用：lsof -i:8080
• Docker 检查：docker compose ps 和 docker compose logs

配置问题

找不到文件或参数错误时：

• 检查环境变量：echo $COMMIT_ID
• 脚本权限：chmod +x hugegraph-*/assembly/travis/*.sh

HDFS 测试失败

• 确认 NameNode/DataNode 运行正常
• 检查 Hadoop 日志
• 验证 HDFS 连接：hdfs dfsadmin -report

JDBC 测试失败

• 确认 MySQL 运行正常
• 验证数据库连接：mysql -u root -p$DB_PASS
• 检查 MySQL 日志

6. 参考资料

• HugeGraph GitHub 仓库：https://github.com/apache/hugegraph
• HugeGraph 工具链 GitHub 仓库：https://github.com/apache/hugegraph-toolchain
• HugeGraph Server 文档：https://hugegraph.apache.org/cn/docs/quickstart/hugegraph/hugegraph-server/
• CI 配置：.github/workflows/*-ci.yml
• 依赖服务安装脚本：hugegraph-*/assembly/travis/

5 - Backup Restore

描述

Backup 和 Restore 是备份图和恢复图的功能。备份和恢复的数据包括元数据（schema）和图数据（vertex 和 edge）。

Backup

将 HugeGraph 系统中的一张图的元数据和图数据以 JSON 格式导出。

Restore

将 Backup 导出的JSON格式的数据，重新导入到 HugeGraph 系统中的一个图中。

Restore 有两种模式：

• Restoring 模式，将 Backup 导出的元数据和图数据原封不动的恢复到 HugeGraph 系统中。可用于图的备份和恢复，一般目标图是新图（没有元数据和图数据）。比如：
  • 系统升级，先备份图，然后升级系统，最后将图恢复到新的系统中
  • 图迁移，从一个 HugeGraph 系统中，使用 Backup 功能将图导出，然后使用 Restore 功能将图导入另一个 HugeGraph 系统中
• Merging 模式，将 Backup 导出的元数据和图数据导入到另一个已经存在元数据或者图数据的图中，过程中元数据的 ID 可能发生改变，顶点和边的 ID 也会发生相应变化。
  • 可用于合并图

使用方法

可以使用hugegraph-tools进行图的备份和恢复。

Backup

1bin/hugegraph backup -t all -d data

该命令将 http://127.0.0.1:8080（默认 –url）的 hugegraph 图的全部元数据和图数据备份到data目录下。

Backup 在任意图模式下都可以正常工作，它不会检查图模式

Restore

Restore 有两种模式： RESTORING 和 MERGING，恢复之前首先要根据需要设置图模式，图处于其他模式时 restore 命令会失败。

步骤1：查看并设置图模式

1bin/hugegraph graph-mode-get

该命令用于查看当前图模式，包括：NONE、RESTORING、MERGING、LOADING。

1bin/hugegraph graph-mode-set -m RESTORING

该命令用于设置图模式，Restore 之前可以设置成 RESTORING 或者 MERGING 模式，例子中设置成 RESTORING。

步骤2：Restore 数据

1bin/hugegraph restore -t all -d data

该命令将data目录下的全部元数据和图数据重新导入到 http://127.0.0.1:8080 的 hugegraph 图中。

步骤3：恢复图模式

1bin/hugegraph graph-mode-set -m NONE

该命令用于恢复图模式为 NONE。

至此，一次完整的图备份和图恢复流程结束。

帮助

备份和恢复命令的详细使用方式可以参考hugegraph-tools文档。

Backup/Restore使用和实现的API说明

Backup

Backup 使用元数据和图数据的相应的 list(GET) API 导出，并未增加新的 API。

Restore

Restore 使用元数据和图数据的相应的 create(POST) API 导入，并未增加新的 API。

Restore 时存在两种不同的模式： Restoring 和 Merging，另外，还有常规模式 NONE(默认)，区别如下：

• None 模式，元数据和图数据的写入属于正常状态，可参见功能说明。特别的：
  • 元数据（schema）创建时不允许指定 ID
  • 图数据（vertex）在 id strategy 为 Automatic 时，不允许指定 ID
• Restoring 模式，恢复到一个新图中，特别的：
  • 元数据（schema）创建时允许指定 ID
  • 图数据（vertex）在 id strategy 为 Automatic 时，允许指定 ID
• Merging 模式，合并到一个已存在元数据和图数据的图中，特别的：
  • 元数据（schema）创建时不允许指定 ID
  • 图数据（vertex）在 id strategy 为 Automatic 时，允许指定 ID

正常情况下，图模式为 None，当需要 Restore 图时，需要根据需要临时修改图模式为 Restoring 模式或者 Merging 模式，并在完成 Restore 时，恢复图模式为 None。

实现的设置图模式的 RESTful API 如下：

查看某个图的模式

启用鉴权时需要图读取权限（space_member 或该图的所有者）。

Method & Url

1GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode

Response Status

1200

Response Body

1{
2    "mode": "NONE"
3}

合法的图模式包括：NONE，RESTORING，MERGING，LOADING

设置某个图的模式

启用鉴权时需要图空间管理权限（space）；管理员可按权限继承规则满足。

Method & Url

1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode

Request Body

1"RESTORING"

合法的图模式包括：NONE，RESTORING，MERGING，LOADING

Response Status

1200

Response Body

1{
2    "mode": "RESTORING"
3}

6 - HugeGraph Docker 集群部署指南

概述

HugeGraph 通过 Docker-Compose 可快速运行完整的分布式集群版（PD + Store + Server）。该方式适用于 Linux 和 Mac。

前置条件

• Docker Engine 20.10+ 或 Docker Desktop 4.x+
• Docker Compose v2
• Mac 运行 3 节点集群时，建议分配至少 12 GB 内存（设置 → 资源 → 内存）。[其他平台根据实际情况调整]

已测试环境：Linux（原生 Docker）和 macOS（Docker Desktop with ARM M4）

Compose 文件

在 HugeGraph 主仓库 docker/ 目录下提供了四个 compose 文件：

单机拓扑使用 hugegraph/hugegraph:${HUGEGRAPH_VERSION:-latest}；HStore 拓扑使用对应的 hugegraph/pd、hugegraph/store 和 hugegraph/server tag。Hubble 由 ${HUBBLE_IMAGE:-hugegraph/hubble:latest} 单独选择。

注: 后续步骤皆为假设你本地已拉取 hugegraph 主仓库代码 (至少是 docker 目录)

本页的 HStore 与 HA Compose 操作按当前主线文件编写，必须使用从同一主线源码构建的 PD、Store 和 Server 镜像；不要把这些 Compose 文件与 1.7.0 标签的 HStore 组件镜像混用。单机示例单独固定 hugegraph/hugegraph:1.7.0 镜像标签。

鉴权环境

以下 .env 模板对应当前主线 Compose。尖括号内容和 replace-with-your-password 都是占位，必须替换为真实值后才能载入或启动；可参考主线 docker/README.md 的鉴权环境步骤生成 .env，并先替换其中的管理员密码占位：

1HUGEGRAPH_ADMIN_PASSWORD='replace-with-your-password'
2HUGEGRAPH_AUTH_TOKEN_SECRET='<32 字节随机值，例如 openssl rand -hex 32>'
3HG_PD_AUTH_SECRET_KEY='<24 字节随机值，例如 openssl rand -hex 24>'

在主线 HStore 和 HA 拓扑中，HG_PD_AUTH_SECRET_KEY 是 PD REST Basic 鉴权密码，所有 PD 节点、Server 和 Hubble 都必须使用同一个值。当前主线 PD Docker 镜像要求设置该密钥。Hubble 不会直接读取 .env，启动前还要用该值生成拓扑对应的本地配置文件，见下文。不要提交 .env 或生成的 .local.properties。

HUGEGRAPH_ADMIN_PASSWORD 非空时会以 PASSWORD 启用 Server 鉴权，Hubble 通过 Server API 自动识别该模式；该密码只在首次初始化内置 admin 账号。不设置或设为空值则关闭鉴权，这只适用于可信的本地环境。

当前主线 Compose 会把 HUGEGRAPH_AUTH_TOKEN_SECRET 传给 HG_SERVER_AUTH_TOKEN_SECRET。同一密钥可让主线多 Server 副本验证相同 token，并在容器重建后继续验证已签发 token；HA Compose 还要求显式提供该密钥。hugegraph/hugegraph:1.7.0 单机镜像的 Docker 入口脚本只根据 PASSWORD 开启鉴权，不读取 HG_SERVER_AUTH_TOKEN_SECRET，因此不要把 .env 中该变量视为该镜像的固定 JWT 配置。若在 1.7.0 中需要固定 JWT secret，请在其认证图配置 conf/graphs/hugegraph.properties 中显式设置 auth.token_secret，并确保该配置随容器替换保留；认证图路径及密钥生成说明见鉴权配置指南。

之后修改 HUGEGRAPH_ADMIN_PASSWORD 不会轮换已有密码，请使用用户 API 修改。

单节点快速启动

本节固定使用 hugegraph/hugegraph:1.7.0 单机镜像标签；HStore/HA 示例使用当前主线构建镜像，不能照搬本节的版本号。

1cd "$(git rev-parse --show-toplevel)/docker"
2# 单机 RocksDB Server 镜像示例
3HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose.yml up -d --wait

验证：

1curl -fsS http://localhost:8080/versions
2curl -fsS http://localhost:8088/about        # Hubble

Hubble 默认只发布在宿主机回环地址（127.0.0.1:8088）。只有在 HTTPS 反向代理和可信网络管控之后才应设置 HUBBLE_PUBLISH_HOST。

最小 HStore 快速启动（当前主线镜像）

从 HugeGraph Server 主线仓库根目录构建 PD、Store 和 HStore Server 镜像：

1cd "$(git rev-parse --show-toplevel)"
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .
3docker build -f hugegraph-store/Dockerfile -t hugegraph/store:local .
4docker build -f hugegraph-server/Dockerfile-hstore -t hugegraph/server:local .

从仓库根目录执行以下命令进入 docker/，载入 .env 并生成最小拓扑所需的 Hubble 配置。缺少 hstore.local.properties 时，Compose 不会为只读 bind mount 自动创建有效配置；先生成文件再启动：

1cd "$(git rev-parse --show-toplevel)/docker"
2set -a; . ./.env; set +a
3./set-hubble-pd-password.sh hstore
4HUGEGRAPH_VERSION=local HUGEGRAPH_PULL_POLICY=never \
5  docker compose -f docker-compose-hstore.yml up -d --wait

验证：

1set -a; . ./.env; set +a
2curl -fsS http://localhost:8620/v1/health    # PD
3curl -fsS http://localhost:8520/v1/health    # Store
4curl -fsS http://localhost:8080/versions     # Server
5curl -fsS http://localhost:8088/about        # Hubble
6curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?请先载入 .env}" \
7  http://localhost:8620/v1/stores       # PD REST 认证后查看 Store 注册状态

若要从本地源码构建该拓扑而不是拉取镜像，可加上开发覆盖文件，并在后续所有生命周期命令中同时带上这两个文件：

1cd "$(git rev-parse --show-toplevel)/docker"
2set -a; . ./.env; set +a
3./set-hubble-pd-password.sh hstore
4docker compose -f docker-compose-hstore.yml -f docker-compose.dev.yml up -d --build --wait

覆盖文件为本地构建生成 dev 标签的镜像；如果已经按上文构建 local 标签镜像，则使用基础 Compose 文件和 HUGEGRAPH_VERSION=local 启动，不要同时混用两个版本标签。

3 节点集群快速启动（当前主线镜像）

HA Compose 文件不包含源码构建覆盖层。先按最小 HStore 一节从同一主线源码构建 hugegraph/pd:local、hugegraph/store:local 和 hugegraph/server:local，然后在 docker/ 目录载入 .env，生成 HA Hubble 配置并启动：

1cd "$(git rev-parse --show-toplevel)/docker"
2set -a; . ./.env; set +a
3./set-hubble-pd-password.sh hstore-ha
4HUGEGRAPH_VERSION=local \
5  docker compose -f docker-compose-3pd-3store-3server.yml up -d --wait

HA Hubble bind-mount conf/hubble/hstore-ha.local.properties；必须在启动前生成。该文件与最小 HStore 使用的 hstore.local.properties 分开生成，但两者从同一 .env 读取同一个 HG_PD_AUTH_SECRET_KEY。

默认内置的启动顺序：

1. PD (节点)最先启动，且必须通过 /v1/health 健康检查
2. Store (节点)在所有 PD 健康后再启动
3. Server (节点)在所有 Store + PD 健康后最后启动

验证集群正常：PD 的 /v1/health 和 /v1/ready 是无需认证的探针；查询 Store 注册和分区数据属于受保护的 PD REST 管理接口，需用用户名 hg 和 .env 中的 HG_PD_AUTH_SECRET_KEY 进行 Basic 认证。

 1set -a; . ./.env; set +a
 2curl -fsS http://localhost:8620/v1/health      # PD 健康检查
 3curl -fsS http://localhost:8520/v1/health      # Store 健康检查
 4curl -fsS http://localhost:8080/versions        # Server
 5for port in 8620 8621 8622; do
 6  curl -fsS "http://localhost:${port}/v1/ready" | grep -q '"ready":true' || exit 1
 7done
 8curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?请先载入 .env}" \
 9  http://localhost:8620/v1/stores          # 认证后查看已注册的 Store
10curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?请先载入 .env}" \
11  http://localhost:8620/v1/partitions      # 认证后查看分区分配
12curl -fsS http://localhost:8088/about           # Hubble

开启鉴权后，图列表接口应拒绝匿名请求并接受管理员：

1set -a; . ./.env; set +a
2curl -o /dev/null -w '%{http_code}\n' \
3  http://localhost:8080/graphspaces/DEFAULT/graphs                      # 期望 401
4curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \
5  http://localhost:8080/graphspaces/DEFAULT/graphs                      # 期望 200

另外两个 Server 分别在 8081 和 8082 上提供服务，其余 PD 和 Store 节点分别在 8621/8622 和 8521/8522。

环境变量参考

以下 PD、Store、Server 和 Compose 变量表描述当前主线镜像入口及 Compose 文件，不是 hugegraph/hugegraph:1.7.0 单机镜像的环境变量契约。PD 和 Store 的入口脚本会把各自的变量拼成 SPRING_APPLICATION_JSON，并在启动时打印部分非敏感配置摘要；PD 密钥不会打印在该摘要中。docker logs 可用于核对日志列出的配置项，但不要以日志中未显示密钥来判断是否生效。Server 的入口脚本则直接改写 conf/graphs/hugegraph.properties 和 conf/rest-server.properties 中的键。

PD 变量

已弃用的别名：GRPC_HOST → HG_PD_GRPC_HOST、RAFT_ADDRESS → HG_PD_RAFT_ADDRESS、RAFT_PEERS → HG_PD_RAFT_PEERS_LIST、PD_INITIAL_STORE_LIST → HG_PD_INITIAL_STORE_LIST。只有当新名称未设置时才会把旧名称映射过去，并打印一条警告日志。任一必填变量缺失时，入口脚本以退出码 2 退出。

Store 变量

已弃用的别名：PD_ADDRESS → HG_STORE_PD_ADDRESS、GRPC_HOST → HG_STORE_GRPC_HOST、RAFT_ADDRESS → HG_STORE_RAFT_ADDRESS

Server 变量

与 PD、Store 不同，Server 入口脚本没有必填变量：只有实际设置了的变量才会被写入配置文件。但分布式部署至少需要 HG_SERVER_BACKEND 和 HG_SERVER_PD_PEERS。

已弃用的别名：BACKEND → HG_SERVER_BACKEND、PD_PEERS → HG_SERVER_PD_PEERS

wait-storage.sh 最多等待 300 秒直到出现状态为 Up 的 Store。该时长写死在脚本中，无法通过环境变量调整。

HG_SERVER_INIT_STORE_ENABLED 只接受 HugeConfig 能识别的写法（忽略大小写）：y、t、yes、on、true、n、f、no、off、false。其他取值（包括 0 和 1）都会让入口脚本终止。

入口脚本在初始化成功后写入 docker/init_complete，后续启动会跳过重新初始化，但仍会再执行一次 bin/init-store.sh，以便关闭状态下每次启动都重新校验配置。

Compose 变量

以下变量由 Compose 文件读取，而非入口脚本：

端口参考

3 节点集群发布的端口：

单机拓扑只发布 8080 和 8088；最小 HStore 拓扑发布 8620（PD REST）、8520（Store REST）、8080 和 8088。PD Raft 使用网络内的 8610，所有拓扑都不对外发布。

故障排查

1. 容器 OOM 退出（exit code 137）：将 Docker Desktop 内存增加到 12 GB 以上 (或调整被 kill 的启动 jvm 内存设置)

2. Raft 选举超时：检查所有 PD 节点的 HG_PD_RAFT_PEERS_LIST 是否一致。验证连通性：docker exec hg-pd0 ping pd1

3. 分区分配未完成：在 docker/ 目录先载入 .env，再用 PD REST Basic 认证检查 Store：

   1set -a; . ./.env; set +a
   2curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?请先载入 .env}" http://localhost:8620/v1/stores

   3 个 Store 都显示 "state":"Up" 后，PD 才能为集群完成分区分配。

4. 连接被拒：确保 HG_* 环境变量使用容器主机名（pd0、store0），而非 127.0.0.1

5. 数据在意料之外地保留了下来：docker compose down 会保留命名卷。要同时删除该拓扑的数据，请使用 docker compose down -v

查看运行时日志：使用 docker logs <container-name>（如 docker logs hg-pd0）可直接查看日志，无需进入容器。单机镜像 hugegraph/hugegraph 设置了 STDOUT_MODE=true，其服务日志会输出到容器 stdout。hugegraph/server（HStore）镜像没有设置该变量，因此对 HStore 拓扑的 Server 执行 docker logs 只能看到入口脚本的输出，其余内容需在容器内查看 logs/hugegraph-server.log。

容器监控与健康检查

版本说明：本节描述当前主线 Docker 镜像的行为，不包含在 1.7.0 镜像中。可使用上文从主线构建并标记为 local 的镜像，或包含这些改动的 latest 镜像。

进程监控模型

此前，三个 Docker 入口脚本均以 tail -f /dev/null 结尾，即使 Java 进程崩溃，容器仍会保持运行状态。由于容器从未退出，Docker 的 restart: unless-stopped 策略也不会触发。

现在，入口脚本直接监控 Java 进程：

• PD 和 Store 容器：入口脚本向启动脚本传入 -d false 参数，启动脚本通过 exec 直接替换为 Java 进程。容器进程即为 Java 进程，当 Java 退出（崩溃或正常关闭）时，容器立即退出，Docker 的重启策略随即触发。
• Server 容器：入口脚本使用 tail --pid=$PID -f /dev/null 阻塞，直到 Java 退出。SIGTERM/SIGINT 信号陷阱会将 docker stop 信号转发给 Java 并等待其正常关闭（退出码 0）。若 Java 崩溃，入口脚本以退出码 1 退出，从而触发重启策略。
• 所有镜像中的 PID 1 均为 dumb-init，负责将 Docker 信号转发给入口脚本进程。

Server 启动等待超时

HG_SERVER_STARTUP_TIMEOUT_S 控制 Server 启动脚本等待 REST 服务响应的时长，未设置时默认 120 秒。取值必须是不带前导零的十进制整数，范围为 1–86400 秒。空字符串、0、负数、小数和超出范围的值都会使入口脚本记录错误并以退出码 1 退出。

入口脚本通过 bin/start-hugegraph.sh -t 传入该值。如果 Server 在等待期限内未就绪，或进程提前退出，启动失败，容器以退出码 1 退出；配置的重启策略可能会重新启动容器。此时长不包括此前的存储初始化或等待后端就绪的时间。

例如，在 HugeGraph 仓库的 docker/ 目录下，将单机 Server 的启动等待时间增加到 300 秒（Compose 文件会将该变量传入容器）：

1HG_SERVER_STARTUP_TIMEOUT_S=300 HUGEGRAPH_VERSION=latest \
2  docker compose -f docker-compose.yml up -d --wait

该设置与 Docker 健康检查的 start_period、interval、timeout 和 retries 相互独立。健康检查参数决定何时将容器标记为 unhealthy；仅增加健康检查的等待时间，不会延长 Server 启动脚本的等待期限。调整此变量也不会自动修改健康检查参数，启动较慢时应分别检查这两组设置。

健康检查端点

所有四个 Docker 镜像现已内置 HEALTHCHECK 指令。docker ps 将显示真实的健康状态。在 90 秒的启动期内，检查失败不计入统计；此后，连续三次失败将把容器标记为 unhealthy。

Compose 文件在此之上还定义了自己的健康检查，因此 --wait 和 depends_on: condition: service_healthy 不依赖镜像内置的检查。Compose 中的检查使用更短的启动期（视服务和拓扑为 30 到 120 秒）和更多的重试次数。

注意：start-hugegraph.sh 中的 -m true 标志（基于 cron 的监控）仅适用于虚拟机/裸机部署，Docker 镜像中未安装也不使用该功能。Docker 用户应依赖内置的 HEALTHCHECK 和 Docker 重启策略。

7 - FAQ

• 如何选择后端存储? 选 RocksDB 还是分布式存储?

  HugeGraph 支持多种部署模式，根据数据规模和场景选择：

  • 单机模式：Server + RocksDB，适合开发测试、Graph AI 和中小规模生产环境（≤ 2 TB）
  • 分布式模式：HugeGraph-PD + HugeGraph-Store（HStore），用于需要水平扩展和多副本的部署，支持 ≤ 1 PB 的数据规模

  1.7.0 支持 RocksDB、HStore、HBase 和 Memory。Cassandra、ScyllaDB、MySQL、PostgreSQL 等旧后端需使用 1.5.x 或更早版本。

• 启动服务时提示：xxx (core dumped) xxx

  请先确认 JDK 版本不低于 Java 11。HugeGraph 1.7.0 不再支持 Java 8。

• 启动服务成功了，但是操作图时有类似于"无法连接到后端或连接未打开"的提示

  RocksDB、HBase 等本地持久化后端首次启动前需要使用 init-store 初始化。HStore 由 PD、Store 管理，不执行该脚本。

• 所有的后端在使用前都需要执行init-store吗，序列化的选择可以随意填写么?

  Memory 和 HStore 不执行 init-store；RocksDB、HBase 等本地持久化后端首次使用前需要初始化。序列化器必须与后端匹配，例如 RocksDB 使用 binary。

• 执行init-store报错：Exception in thread "main" java.lang.UnsatisfiedLinkError: /tmp/librocksdbjni3226083071221514754.so: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.10' not found (required by /tmp/librocksdbjni3226083071221514754.so)

  RocksDB需要 gcc 4.3.0 (GLIBCXX_3.4.10) 及以上版本

• bin目录下包含start-hugegraph.sh、start-restserver.sh和start-gremlinserver.sh三个似乎与启动有关的脚本，到底该使用哪个

  当前发布包只保留 start-hugegraph.sh 作为 Server 启动脚本。GremlinServer 和 REST Server 由同一进程启动。

• 配置了两个图，名字是hugegraph和hugegraph1，而启动服务的命令是start-hugegraph.sh，是只打开了hugegraph这个图吗

  脚本名称与图名无关。Server 默认从 conf/graphs 扫描并加载本地图配置，目录可在 conf/rest-server.properties 的 graphs 配置项中修改。graph.load_from_local_config 的默认值是 false，只控制图管理器构造阶段的预加载及 reload() 重扫，不能用于禁止启动时加载；需要加载多个本地图时，为每个图准备独立配置文件。详见服务端配置说明。

• 服务启动成功后，使用curl查询所有顶点时返回乱码

  服务端返回的批量顶点/边是压缩（gzip）过的，可以使用管道重定向至 gunzip 进行解压（curl http://example | gunzip），也可以用Firefox的postman或者Chrome浏览器的restlet插件发请求，会自动解压缩响应数据。

• 使用顶点Id通过RESTful API查询顶点时返回空，但是顶点确实是存在的

  检查顶点Id的类型，如果是字符串类型，API的url中的id部分需要加上双引号，数字类型则不用加。

• 已经根据需要给顶点Id加上了双引号，但是通过RESTful API查询顶点时仍然返回空

  检查顶点id中是否包含+、空格、/、?、%、&和=这些URL的保留字符，如果存在则需要进行编码。下表给出了编码值：

   1特殊字符 | 编码值
   2--------| ----
   3+       | %2B
   4空格     | %20
   5/       | %2F
   6?       | %3F
   7%       | %25
   8#       | %23
   9&       | %26
  10=       | %3D

• 查询某一类别的顶点或边（query by label）时提示超时

  由于属于某一label的数据量可能比较多，请加上limit限制。

• 通过RESTful API操作图是可以的，但是发送Gremlin语句就报错：Request Failed(500)

  可能是GremlinServer的配置有误，检查gremlin-server.yaml的host、port是否与rest-server.properties的gremlinserver.url匹配，如不匹配则修改，然后重启服务。

• 使用Loader导数据出现Socket Timeout异常，然后导致Loader中断

  持续地导入数据会使Server的压力过大，然后导致有些请求超时。可以通过调整Loader的参数来适当缓解Server压力（如：重试次数，重试间隔，错误容忍数等），降低该问题出现频率。

• 如何删除图中的全部数据

  管理员可调用 DELETE /graphspaces/{graphspace}/graphs/{graph}/clear?confirm_message=I'm sure to delete all data。confirm_message 查询参数必须与该值完全一致，否则请求会被拒绝，详见 Graph API。该操作会清除 schema、顶点、边和索引。

• 清空了数据库，并且执行了init-store，但是添加schema时提示"xxx has existed"

  HugeGraphServer内是有缓存的，清空数据库的同时是需要重启Server的，否则残留的缓存会产生不一致。

• 插入顶点或边的过程中报错：The max length of vertex id is 16384, but got xxx {yyy} 或 The max length of edge id is 65536, but got xxx {yyy}

  为了保证查询性能，目前的后端存储对id列的长度做了限制，顶点id不能超过16384字节，边id长度不能超过65536字节；索引id超过32字节时会转为哈希存储，而不是报错。

• 是否支持嵌套属性，如果不支持，是否有什么替代方案

  嵌套属性目前暂不支持。替代方案：可以把嵌套属性作为单独的顶点拿出来，然后用边连接起来。

• 一个EdgeLabel是否可以连接多对VertexLabel，比如"投资"关系，可以是"个人"投资"企业"，也可以是"企业"投资"企业"

  可以。创建EdgeLabel时对每一对顶点标签各调用一次link(sourceLabel, targetLabel)，所有配对都会被保留，因此同一个"投资"标签可以同时覆盖"个人"投资"企业"和"企业"投资"企业"。旧的sourceLabel()和targetLabel()构建方法已废弃，且只支持单一配对。

• 通过RestAPI发送请求时提示HTTP 415 Unsupported Media Type

  请求头中需要指定Content-Type:application/json

其他问题可以在对应项目的 issue 区搜索，例如 Server-Issues / Loader Issues

8 - 报告安全问题

报告 Apache HugeGraph 的安全问题

遵循 ASF 的规范，HugeGraph 社区对解决修复项目中的安全问题保持非常积极和开放的态度。

我们强烈建议用户首先向我们的独立安全邮件列表报告此类问题，相关详细的流程规范请参考 ASF SEC 守则。

请注意，安全邮件组适用于报告未公开的安全漏洞并跟进漏洞处理的过程。常规的软件 Bug/Error 报告应该使用 Github Issue/Discussion 或是 HugeGraph-Dev 邮箱组。发送到安全邮件组但与安全问题无关的邮件将被忽略。

独立的安全邮件 (组) 地址为： security@hugegraph.apache.org

安全漏洞处理大体流程如下：

• 报告人私下向 Apache HugeGraph SEC 邮件组报告漏洞 (尽可能包括复现的版本/相关说明/复现方式/影响范围等)
• HugeGraph 项目安全团队与报告人私下合作/商讨漏洞解决方案 (初步确认后可申请 CVE 编号予以登记)
• 项目创建一个新版本的受漏洞影响的软件包，以提供修复程序
• 合适的时间可公开漏洞的大体问题 & 描述如何应用修复程序 (遵循 ASF 规范，公告中不应携带复现细节等敏感信息)
• 正式的 CVE 发布及相关流程同 ASF-SEC 页面

已发现的安全漏洞 (CVEs)

HugeGraph 主仓库 (Server/PD/Store)

• CVE-2024-27348: HugeGraph-Server - Command execution in gremlin
• CVE-2024-27349: HugeGraph-Server - Bypass whitelist in Auth mode
• CVE-2024-43441: HugeGraph-Server - Fixed JWT Token (Secret)
• CVE-2025-26866: HugeGraph-Server - RAFT and deserialization vulnerability

HugeGraph-Toolchain 仓库 (Hubble/Loader/Client/Tools/..)

• CVE-2024-27347: HugeGraph-Hubble - SSRF in Hubble connection page