Ubuntu 22.04 安装 Apache HugeGraph 1.7.0 指南

在 Ubuntu 22.04.5 上以 Apache 官方 tar.gz 发行包安装 HugeGraph 1.7.0 分布式图数据库，完成 JDK 17 前置、下载解压、store 初始化、启动与 8080 端口验证，并实测 REST API 建 schema/插入顶点/查询，JVM 堆内存限定为 256-512MB。安装与验证在 Ubuntu 22.04.5 真实服务器实测通过。

Apache HugeGraphApache HugeGraph安装部署数据库ApacheUbuntu 22.04图数据库2026/10/11

Ubuntu 22.04 安装 Apache HugeGraph 1.7.0 指南

目标：在 Ubuntu 22.04.5 上以 Apache 官方 tar.gz 发行包从零安装 Apache HugeGraph 1.7.0（分布式图数据库，兼容 Apache TinkerPop3 与 Gremlin 查询语言），完成 JDK 前置、下载解压、store 初始化、启动、8080 健康与版本 API 验证，并用 REST API 实测建 schema/插入顶点/查询，JVM 堆内存限为 256–512MB。安装与验证流程已在 Ubuntu 22.04.5 真实服务器实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • 运行时环境：OpenJDK 17（17.0.20.1，任务要求 JDK 17；详见「四、4.2」与「九、常见问题」关于 Gremlin 引擎的说明）
  • 组件版本：Apache HugeGraph 1.7.0（server 发行包 apache-hugegraph-server-incubating-1.7.0）
  • 下载源与大小：apache-hugegraph-incubating-1.7.0.tar.gz，约 892 MB（934,977,316 字节）
  • 安装目录：/opt/hugegraph/hugegraph-server-1.7.0
  • 默认端口：REST 服务 8080、Gremlin Server 8182
  • 默认数据后端：RocksDB（存储路径 rocksdb-data/，位于安装目录下）
  • 示例管理账号：admin（启用认证后生效，见「八、认证与访问控制」）
  • 数据目录示例：本文以 /opt/hugegraph/hugegraph-server-1.7.0 为安装根目录

二、前置条件

  • 拥有 root 权限，已配置可访问 archive.apache.org 的网络
  • 已安装 wget、curl、tar、unzip、lsof、procps（start-hugegraph.sh 会用 lsof 探测端口）
  • 已安装 JDK，本文采用 OpenJDK 17，并确认 java -version 为 17

三、版本选型说明

Apache HugeGraph 在 archive.apache.org 的版本对照：

版本说明后端能力（store）建议
1.7.0当前归档最新稳定版（实测对象）仅支持 hstore / rocksdb / hbase / memory推荐，本文按此版安装
1.5.0 / 1.3.01.x 历史版本除上述外还支持 mysql / postgresql / cassandra如需 MySQL/PG/Cassandra 后端请选用 < 1.7.0
1.2.0 / 1.0.0早期版本同上一般不建议新装

⚠️ 重要：HugeGraph 1.7.0 起（源码注释说明 since 1.7.0）后端仅保留 hstore/rocksdb/hbase/memory，移除了 Cassandra/MySQL/PG。若你的业务依赖 MySQL、PostgreSQL 或 Cassandra 作为后端存储，应选择 1.6.0 及更早版本；本文按最新 1.7.0 + 默认 RocksDB 部署。

另外，1.7.0 是新的「PD + Store + Server」分层架构：发行包内同时包含 apache-hugegraph-pd-incubating-1.7.0、apache-hugegraph-store-incubating-1.7.0、apache-hugegraph-server-incubating-1.7.0 三个子包。本文部署的 Server 为 Http/REST + Gremlin 服务层，默认使用内嵌 RocksDB store。

Apache HugeGraph-Hubble 图可视化工具属于 apache-hugegraph-toolchain-incubating-1.7.0.tar.gz 发行包，为可选组件（见「七、可选：HugeGraph-Hubble 图可视化工具」）。

四、官方 tar.gz 在线安装方案（推荐）

4.1 安装 JDK 17 前置

apt-get update
apt-get install -y openjdk-17-jdk-headless

验证版本：

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

JDK 17 安装路径为 /usr/lib/jvm/java-17-openjdk-amd64。若同时装有 JDK 11，可用 update-alternatives 切换默认版本，或启动时通过 JAVA_HOME 指定（见「四、4.5」）。

安装 lsof（启动脚本 start-hugegraph.sh 端口检查依赖它）：

apt-get install -y lsof procps

4.2 下载 Apache 官方发行包

mkdir -p /opt/hugegraph
cd /opt/hugegraph
wget https://archive.apache.org/dist/incubator/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz

4.3 解压并整理目录

发行包解压后得到 apache-hugegraph-incubating-1.7.0/，内含 apache-hugegraph-server-incubating-1.7.0 等子包。将 Server 子包移动为独立安装目录：

cd /opt/hugegraph
tar xzf apache-hugegraph-incubating-1.7.0.tar.gz
mv apache-hugegraph-incubating-1.7.0/apache-hugegraph-server-incubating-1.7.0 /opt/hugegraph/hugegraph-server-1.7.0

查看安装目录结构：

ls /opt/hugegraph/hugegraph-server-1.7.0

实测回显：

bin
conf
ext
lib
scripts
swagger-ui

其中：bin/ 存放启动/运维脚本（start-hugegraph.sh、stop-hugegraph.sh、init-store.sh、gremlin-console.sh 等），conf/ 存放全部配置文件，lib/ 为运行 jar，ext/ 为可选扩展插件目录。

4.4 初始化 Store（首次启动前必须执行）

HugeGraph 1.7.0 虽然默认内嵌 RocksDB，但首次启动前必须先初始化后端元数据，否则启动会报 The backend store of 'DEFAULT-hugegraph' has not been initialized。

cd /opt/hugegraph/hugegraph-server-1.7.0/bin
bash init-store.sh

实测回显（关键部分）：

Initializing HugeGraph Store...
2026-10-11 05:53:48 [main] [INFO] o.a.h.c.InitStore - Init graph with config file: /opt/hugegraph/hugegraph-server-1.7.0/conf/graphs/hugegraph.properties
2026-10-11 05:53:52 [main] [INFO] o.a.h.b.s.r.RocksDBStore - Write down the backend version: 1.11
2026-10-11 05:53:52 [main] [INFO] o.a.h.StandardHugeGraph - Graph 'DEFAULT-hugegraph' has been initialized
Initialization finished.
exit=0

4.5 配置 JVM 堆并启动

HugeGraph-Server 的 JVM 堆参数默认在启动脚本 bin/hugegraph-server.sh 中通过 MIN_MEM/MAX_MEM 计算（默认 -Xms512m 起）。为把堆限制在 256–512MB，本文用 JAVA_OPTIONS 环境变量覆盖（详见《Apache HugeGraph 配置参数详解》之 JVM 内存段）。

启动：

cd /opt/hugegraph/hugegraph-server-1.7.0/bin
export JAVA_OPTIONS="-Xms256m -Xmx512m"
bash start-hugegraph.sh

实测回显：

Starting HugeGraphServer in daemon mode...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
Started [pid 2072]
exit=0

💡 说明：也可不 export，直接修改 bin/hugegraph-server.sh 中 MIN_MEM（对应 -Xms）与 MAX_MEM（决定 -Xmx 上界），详见配置详解篇。

验证 JVM 生效值（jps -v）与端口监听：

jps -v | grep -i HugeGraphServer
ss -ltnp | grep -E "8080|8182"

实测回显（JVM 已生效 -Xms256m -Xmx512m）：

2072 HugeGraphServer -Dname=HugeGraphServer -Dlog4j.configurationFile=/opt/hugegraph/hugegraph-server-1.7.0/conf/log4j2.xml -Djava.security.manager=org.apache.hugegraph.security.HugeSecurityManager -Xms256m -Xmx512m --add-exports=java.base/jdk.internal.reflect=ALL-UNNAMED --add-modules=jdk.unsupported --add-exports=java.base/sun.nio.ch=ALL-UNNAMED -XX:+ParallelRefProcEnabled -XX:InitiatingHeapOccupancyPercent=50 -XX:G1RSetUpdatingPauseTimePercent=5
tcp6       0      0 127.0.0.1:8080   :::*   LISTEN  2072/java
tcp6       0      0 127.0.0.1:8182   :::*   LISTEN  2072/java

💡 说明：start-hugegraph.sh 默认以 daemon 模式后台启动并把 pid 写入 bin/pid；-XX:+HeapDumpOnOutOfMemoryError 与 -XX:HeapDumpPath 也在脚本中生成。

4.6 停止服务

cd /opt/hugegraph/hugegraph-server-1.7.0/bin
bash stop-hugegraph.sh

五、REST API 实测：建 schema / 插入数据 / 查询

启动成功后，HugeGraph 默认图名为 hugegraph，REST 基址为 http://127.0.0.1:8080/graphs/hugegraph。下面用 curl 从零建 schema、插入顶点并查询（所有回显均为实测输出）。

5.1 健康与 API 检查

查看可用图列表：

curl -s http://localhost:8080/graphs

实测回显：

{"graphs":["hugegraph"]}

查看全部 REST API 元数据（/apis 返回非常长的 API 清单）：

curl -s http://localhost:8080/apis

5.2 创建 PropertyKey（属性键）

HugeGraph 1.7.0 中，schema 的 properties 字段是属性键名数组，属性类型需单独用 PropertyKey API 定义：

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"name":"name","data_type":"TEXT","cardinality":"SINGLE"}' \
  http://localhost:8080/graphs/hugegraph/schema/propertykeys

实测回显：

{"property_key": {"id":1,"name":"name","data_type":"TEXT","cardinality":"SINGLE","aggregate_type":"NONE","write_type":"OLTP","properties":[],"status":"CREATED","user_data":{"~create_time":"2026-10-11 05:54:52.332"}}, "task_id": 0}

同理创建 age（INT）与 since（INT）两个属性键，命令如下：

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"name":"age","data_type":"INT","cardinality":"SINGLE"}' \
  http://localhost:8080/graphs/hugegraph/schema/propertykeys

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"name":"since","data_type":"INT","cardinality":"SINGLE"}' \
  http://localhost:8080/graphs/hugegraph/schema/propertykeys

5.3 创建 VertexLabel（顶点类型）与 EdgeLabel（边类型）

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"name":"person","id_strategy":"DEFAULT","properties":["name","age"]}' \
  http://localhost:8080/graphs/hugegraph/schema/vertexlabels

实测回显：

{"id":1,"name":"person","id_strategy":"AUTOMATIC","primary_keys":[],"nullable_keys":[],"index_labels":[],"properties":["name","age"],"status":"CREATED","ttl":0,"enable_label_index":true,"user_data":{"~create_time":"2026-10-11 05:54:58.395"}}

创建边类型 knows（person → person）：

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"name":"knows","source_label":"person","target_label":"person","frequency":"SINGLE","properties":["since"]}' \
  http://localhost:8080/graphs/hugegraph/schema/edgelabels

实测回显：

{"id":1,"name":"knows","edgelabel_type":"NORMAL","source_label":"person","target_label":"person","links":[{"person":"person"}],"frequency":"SINGLE","sort_keys":[],"nullable_keys":[],"index_labels":[],"properties":["since"],"status":"CREATED","ttl":0,"enable_label_index":true,"user_data":{"~create_time":"2026-10-11 05:54:58.421"}}

5.4 插入顶点

注意 1.7.0 里点属性需包在 properties 对象内，而非平铺：

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"label":"person","properties":{"name":"marko","age":29}}' \
  http://localhost:8080/graphs/hugegraph/graph/vertices

实测回显：

{"id":1173863628936314880,"label":"person","type":"vertex","properties":{"name":"marko","age":29}}

再插入 vadas(age 27)：

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"label":"person","properties":{"name":"vadas","age":27}}' \
  http://localhost:8080/graphs/hugegraph/graph/vertices

实测回显：

{"id":1173863629078921216,"label":"person","type":"vertex","properties":{"name":"vadas","age":27}}

5.5 查询

按 id 查询单个顶点（即 Gremlin g.V('id') 的 REST 等价）：

curl -s http://localhost:8080/graphs/hugegraph/graph/vertices/1173863628936314880

实测回显：

{"id":1173863628936314880,"label":"person","type":"vertex","properties":{"name":"marko","age":29}}

查看已建的顶点类型（schema 查询）：

curl -s http://localhost:8080/graphs/hugegraph/schema/vertexlabels

实测回显：

{"vertexlabels": [{"id":1,"name":"person","id_strategy":"AUTOMATIC","primary_keys":[],"nullable_keys":[],"index_labels":[],"properties":["name","age"],"status":"CREATED","ttl":0,"enable_label_index":true,"user_data":{"~create_time":"2026-10-11 05:54:58.395"}}]}

💡 说明：REST 全图遍历接口（如 GET /graphs/hugegraph/graph/vertices）默认返回 HugeGraph GraphSON 二进制序列化结果，命令行直接查看是二进制乱码，故查询建议用「按 id 单点 GET」或 Gremlin 语句；若要读图遍历结果，使用 Gremlin Console 或在 REST 请求中显式声明 GraphSON 序列化器。

六、配置说明

HugeGraph-Server 的核心配置文件集中在安装目录 conf/ 下：

文件作用
conf/rest-server.propertiesREST 服务与全局配置（restserver.url、server.id、server.role、认证开关等）
conf/graphs/hugegraph.properties图配置：后端 backend=rocksdb、store=hugegraph、缓存、存储路径等
conf/gremlin-server.yamlGremlin Server（8182）配置：host/port、channelizer、脚本插件、序列化器
conf/remote.yamlGremlin Console 连接远端（8182）使用的客户端配置
conf/log4j2.xml日志配置

默认数据后端为 RocksDB，后端切换在 conf/graphs/hugegraph.properties 中的 backend= 一行实现（详见《Apache HugeGraph 配置参数详解》）。默认不需要、不启用认证——若需启用并设置管理员账号 admin，见「八」。

七、可选：HugeGraph-Hubble 图可视化工具

HugeGraph-Hubble 是官方的可视化图分析工具（Web UI），属于 toolchain 发行包：

cd /opt/hugegraph
wget https://archive.apache.org/dist/incubator/hugegraph/1.7.0/apache-hugegraph-toolchain-incubating-1.7.0.tar.gz
tar xzf apache-hugegraph-toolchain-incubating-1.7.0.tar.gz

Toolchain 目录内含 hugegraph-hubble 子目录，启动脚本在 hugegraph-hubble/bin/hubble.sh（start 参数启动），默认端口 8088。本组件为可选，不影响 Server 的安装与使用；本次部署未启用 Hubble，仅列出获取方式。

八、认证与访问控制（admin 账号）

默认安装不启用认证，REST/Gremlin 均可直接访问。若需启用认证并设置管理员账号：

  1. 编辑 conf/rest-server.properties，追加/修改：
auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator
auth.graph_store=hugegraph
auth.admin_pa=q1w2e3r4

⚠️ 注意：HugeGraph 1.7.0 中管理员初始密码默认是 pa（配置项 auth.admin_pa），首次启动生效。示例管理账号为 admin，本文演示口令固定为 q1w2e3r4。请在真实生产环境改为你自己的高强度口令。

  1. 重启 Server 后，使用 admin + 配置的口令登录获取 token，后续请求在 Authorization: Bearer <token> 头中携带。也可用发行包自带脚本快速开启认证：
cd /opt/hugegraph/hugegraph-server-1.7.0/bin
bash enable-auth.sh

九、常见问题（FAQ）

Q1：启动报 The backend store of 'DEFAULT-hugegraph' has not been initialized 未执行 store 初始化。首次启动前先执行 cd /opt/hugegraph/hugegraph-server-1.7.0/bin && bash init-store.sh，再执行 start-hugegraph.sh。

Q2：启动后 8000 端口未监听 / 8080 健康检查失败 start-hugegraph.sh 依赖 lsof 探测端口，缺少时会报 Required lsof but it is unavailable。安装依赖后重试：

apt-get install -y lsof procps

Q3：JDK 17 下调用 Gremlin（/gremlin 或 Gremlin Console）报 gremlin-groovy is not an available GremlinScriptEngine 这是 Apache HugeGraph 1.7.0 内置 groovy-2.5.14-indy.jar 的 ASM 仅支持到 class file major version 61 之前的版本所致：在 JDK 17 上 Groovy 引擎初始化时抛 Unsupported class file major version 61，导致 Gremlin 脚本引擎无法创建。此时 8080 的 REST API 完全正常，只是 Gremlin 脚本不可用。解决方案（推荐生产切到 JDK 11）：

# 切换到 JDK 11（1.7.0 对 Gremlin/Groovy 兼容性更稳）
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
bash start-hugegraph.sh

Q4：Gremlin 语句报 No such property: graph（或 g / hugegraph） HugeGraph 1.7.0 单机部署默认 conf/gremlin-server.yaml 中 graphs: {} 为空，不会把默认图自动绑定为脚本变量。需在配置/请求（如 graphspace）中显式绑定后，才能用 g.V() 形式执行。若你一定要在单机上用 g，需按官方文档为 Gremlin Server 注入 hugegraph 图（注意：直接往 graphs 注入 hugegraph 可能与动态图管理冲突，实测会导致 8182 Gremlin Server 无法绑定端口，请谨慎并保留原文件备份）。

Q5：如何确认 JDK 与堆内存生效 用 jps -v | grep HugeGraphServer 查看进程参数，应能看到 -Xms256m -Xmx512m；用 ss -ltnp 确认 8080/8182 处于 LISTEN。

十、卸载方式

停止服务并删除安装目录、数据目录与下载的安装包：

cd /opt/hugegraph/hugegraph-server-1.7.0/bin
bash stop-hugegraph.sh
rm -rf /opt/hugegraph/hugegraph-server-1.7.0
rm -rf /opt/hugegraph/apache-hugegraph-incubating-1.7.0
rm -f /opt/hugegraph/apache-hugegraph-incubating-1.7.0.tar.gz

如需同时移除 JDK 17：apt-get remove -y openjdk-17-jdk-headless。

⚠️ 注意：删除安装目录会连同 RocksDB 数据目录（rocksdb-data/）一并删除，请提前备份。

十一、参考链接