这是本节的多页打印视图。 .

开发测试

HugeGraph 开发者测试与环境集成指南，包含 Toolchain 本地测试与开发版存储引擎集成。

1: HugeGraph工具链本地测试指南
2: ToplingDB 开发版集成

本节汇总 HugeGraph 开发者在本地进行测试与环境集成的操作指南。

模块指引

Toolchain 本地测试
指导开发者在本地搭建 HugeGraph Server 并运行 Toolchain 全量组件的单元测试与功能测试。
ToplingDB (开发版)
介绍从开发源码构建并启用可选 ToplingDB 运行时的配置与测试方法。

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

2 - ToplingDB 开发版集成

从开发源码构建可选 ToplingDB 运行时，隔离数据目录，并了解启动与恢复边界。

开发版接口：本文适用于开启可选 ToplingDB 运行时的开发构建版本。已有发行版和镜像标签不代表支持本文接口，采用前须完成运行时验证。

确认数据库所属组件

HugeGraph 默认使用标准 RocksDB。对持有本地存储的每个进程分别启用 Topling：

组件	业务 provider 配置	启动命令
独立 RocksDB Server	每个选用的 graph properties 文件中设置 `rocksdb.provider=topling`	`bin/start-hugegraph.sh`
PD	`conf/application.yml` 的 `rocksdb` 下设置 `provider: topling`	`bin/start-hugegraph-pd.sh`
Store	`conf/application-pd.yml` 的 `rocksdb` 下设置 `provider: topling`	`bin/start-hugegraph-store.sh`

独立 Server 保持 backend=rocksdb；HStore Server 使用 backend=hstore，不需要本地 Topling 运行时。同一 Server 进程中的本地 RocksDB 图必须使用相同 provider。业务配置必须与启动脚本选择的运行时一致。

构建并准备标准发行包

在源码仓库根目录，使用 Java 17 和 Maven 3.6.3 或更新版本构建普通发行包：

1mvn clean package -Dmaven.test.skip=true -Dmaven.javadoc.skip=true

从可信制品渠道取得 Topling Easy Migrate JNI JAR 及其 SHA-256。准备环境需要 Java 17 JDK、Linux x86_64、sha256sum、unzip、od、ldd 和 GNU mv。还须满足所选 JAR 的 native 依赖，包括其要求的 glibc 和 libaio。

先停止组件，解压一份新的标准发行包，再从该组件目录执行：

1export TOPLING_JNI_JAR=/absolute/path/to/rocksdbjni-topling.jar
2export TOPLING_JNI_SHA256='<trusted-64-character-sha256>'
3bash bin/prepare-topling.sh

脚本校验复制后的 JAR 哈希、Topling Java 标识、唯一的 Linux x86_64 JNI 条目、ELF 架构及 native 依赖。安装前还会用所选 JNI 打开临时数据库，确认 EasyMigrate 配置实际改变了持久化的写缓冲区大小；类标识和哈希匹配但不支持该配置入口的构建会被拒绝。此探针不代表已有数据兼容性或所有生产配置均已验证。校验记录绑定已测试的 JAR 和 native 库，启动时拒绝缺失或失效的记录；从旧准备脚本升级时请重新准备一份新发行包。默认/标准模式启动时会拒绝继承的 RocksDB JNI 预载库，Topling 模式则拒绝与所选 JNI 竞争的预载库；其他预载库继续保留。它将 topling/rocksdbjni.jar、对应 native 库和可选网页资源放在 lib 之外。已有 topling 目录时会拒绝准备；更换运行时请使用另一份已停止的新发行包。按实际部署需要，为 Server、PD 和 Store 分别执行准备步骤。

将持久数据放在发行包之外

更换 provider 不会转换已有数据库。为 Topling 使用独立、初始为空的目录，并保留标准 provider 的数据。预先创建服务账号可写的持久目录，将其放在源码检出、构建输出和解压后的发行包目录之外。注意：每个图必须使用互不相同的独立数据与 WAL 目录，避免目录冲突：

组件	配置文件及配置项	持久路径示例
Server 数据	Graph properties：`rocksdb.data_path`	`/srv/hugegraph/topling/server/<graph>/data`
Server WAL	Graph properties：`rocksdb.wal_path`	`/srv/hugegraph/topling/server/<graph>/wal`
PD	`conf/application.yml`：`pd.data-path`	`/srv/hugegraph/topling/pd`
Store 数据	`conf/application.yml`：`app.data-path`	`/srv/hugegraph/topling/store/data`
Store Raft	`conf/application.yml`：`app.raft-path`	`/srv/hugegraph/topling/store/raft`

独立 Server 的每个选用图配置都需修改，例如 conf/graphs/hugegraph.properties（若配置多个图，请将路径中的 hugegraph 替换为对应图名）：

1backend=rocksdb
2rocksdb.provider=topling
3rocksdb.data_path=/srv/hugegraph/topling/server/hugegraph/data
4rocksdb.wal_path=/srv/hugegraph/topling/server/hugegraph/wal

Server 的数据和 WAL 路径都要设置，且不同图之间不能共享同一路径。若 WAL 仍使用发行包内的默认路径，重新构建或替换发行包时可能丢失该目录。运行时或发行包更新时，保留外部数据、WAL 和 Raft 根目录。

PD 和 Store 应在上表对应的 provider 配置文件中修改已有 rocksdb 映射，保留其余选项：

1rocksdb:
2  provider: topling

持久路径另在 conf/application.yml 中配置，同时保留正常的网络地址和集群配置。

准备完成后的 runtime 目录权限为 0755，普通资源文件为 0644，因此使用另一个服务账号也能读取 JNI。该账号还需要组件上级目录的遍历权限；prepare 不会修改上级目录权限。

选择运行时并启动验证

在每个持有 Topling 数据库的组件启动终端中，显式选择运行时：

1export TOPLINGDB_ROCKSDB_PROVIDER=topling
2# 执行第一张表中该组件对应的启动命令。

启动脚本默认使用该组件的 conf/toplingdb.yaml，也可用 TOPLINGDB_EASY_MIGRATE_CONF=/absolute/path/config.yaml 显式覆盖。发行包中的 native 配置关闭 HTTP 服务，并保留 Java 写入路径要求的 memtable_as_log_index=false。请按机器条件调整该文件；它与业务 provider、数据目录配置分别生效。

独立 Server 使用全新图时，首次启动前先初始化一次存储：

1bash bin/init-store.sh
2bash bin/start-hugegraph.sh

bin/init-store.sh、bin/dump-store.sh 与 bin/start-hugegraph.sh 使用同一显式运行时选择。 HStore 按 PD、Store、Server 的顺序启动。在同一 shell 中启动 HStore Server 前，执行 unset TOPLINGDB_ROCKSDB_PROVIDER （或 export TOPLINGDB_ROCKSDB_PROVIDER=rocksdb）；不要在该 Server 上启用本地 Topling。业务 provider 与实际运行时不一致时，组件会在开库前拒绝启动。

采用前须确认实际 RocksDB Java 类和进程加载的 JNI 库来自准备好的运行时。在专用数据目录中验证真实写入、读取、正常停止和重启； HStore 还需通过 Server 执行图操作，覆盖 PD 和 Store 链路。仅构建成功、启动成功或通过标准 JNI 单元测试，不能证明 Topling 运行时已验收。

停止或切回标准 RocksDB

先停止新业务，再使用正常停止脚本。HStore 依次执行 Server 的 bin/stop-hugegraph.sh、Store 的 bin/stop-hugegraph-store.sh、 PD 的 bin/stop-hugegraph-pd.sh，等待前一个进程退出后再停止其依赖。强制终止进程不能作为正常 native 资源清理的证明。

切回标准 RocksDB 前先停止组件，取消 TOPLINGDB_ROCKSDB_PROVIDER，并把业务 provider 改回 rocksdb。使用对应的标准 provider 数据和 WAL 路径，不要指向已被 Topling 修改的数据库。

专用 Topling 发行包、Docker/Compose 打包、通用生命周期改造及可重试快照恢复分别后续交付。本文覆盖普通发行包的启动脚本；自定义 IDE 和嵌入式入口需要自行准备运行时并完成验证。

开发测试

模块指引

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

1. 核心概念

1.1 核心依赖：HugeGraph Server

1.2 测试类型

2. 环境准备

2.1 系统要求

2.2 克隆代码

3. 部署测试环境

方式选择

3.1 脚本部署

参数说明

部署步骤

3.2 Docker 部署

快速启动

docker-compose 配置（可选）

Hadoop 配置挂载

Docker 操作

4. 运行测试

4.1 hugegraph-client

编译

依赖服务

Server 鉴权配置

运行测试

4.2 hugegraph-loader

编译

依赖服务

运行测试

4.3 hugegraph-hubble

编译

依赖服务

运行测试

4.4 hugegraph-spark-connector

编译

运行测试

4.5 hugegraph-tools

编译

运行测试

5. 常见问题

服务连接问题

配置问题

HDFS 测试失败

JDBC 测试失败

6. 参考资料

2 - ToplingDB 开发版集成

确认数据库所属组件

构建并准备标准发行包

将持久数据放在发行包之外

选择运行时并启动验证

停止或切回标准 RocksDB

询问 AI