Apache HugeGraph 常用 CLI 命令与工具详解

详解 Apache HugeGraph 1.7.0 Server 自带的 CLI 脚本（bin/）与常用工具（REST API、Gremlin Console、init-store、enable-auth、jps 等）的用法、参数与真实回显，覆盖启动停止、store 初始化、系统检查与数据运维。

Apache HugeGraphApache HugeGraph数据库Apache运维图数据库2026/10/11

Apache HugeGraph 常用 CLI 命令与工具详解

目标：详解 Apache HugeGraph 1.7.0 Server 自带的 CLI 脚本（位于 bin/）与常用工具的使用方法、参数与真实回显，覆盖启停、store 初始化、认证启用、系统检查、JVM 查看，以及基于 REST API 的数据运维与 Gremlin Console 连接。所有回显来自真实服务器实测。

一、环境信息

  • 组件版本：Apache HugeGraph 1.7.0（安装于 /opt/hugegraph/hugegraph-server-1.7.0）
  • 脚本目录：bin/
  • 进程信息：RestServer(hugegraph) 8080 端口、Gremlin Server 8182 端口
  • 相关命令工具：jps、ss、curl（用于验证）

二、工具概览

bin/ 目录下的常用脚本一览：

脚本作用
start-hugegraph.sh启动 HugeGraphServer（daemon 模式）
stop-hugegraph.sh停止 HugeGraphServer
init-store.sh初始化后端 store（首次必跑）
enable-auth.sh一键启用认证
gremlin-console.sh启动 Gremlin Console（连接 8182）
hugegraph-server.sh实际拉起 JVM 的执行脚本（JVM 参数所在）
hugegraph.servicesystemd 单元模板
checksocket.sh / util.sh / dump-conf.sh / dump-store.sh运维辅助脚本
raft-tools.sh / monitor-hugegraph.sh / start-monitor.sh / stop-monitor.sh集群/监控相关（多节点场景）

三、前置条件

  • 已完成安装（见《Ubuntu 22.04 安装 Apache HugeGraph 1.7.0 指南》）
  • 已安装 lsof、procps、curl
  • 目录权限：以能读写安装目录的用户（root）执行

四、工具详解

4.1 start-hugegraph.sh —— 启动服务

用法与常用参数：

bash start-hugegraph.sh
bash start-hugegraph.sh -p true        # preload 示例脚本模式（生成 gremlin-server-preload.yaml）
bash start-hugegraph.sh -s false       # 关闭安全启动检查
bash start-hugegraph.sh -m true        # 同时开启监控

默认以 daemon 方式后台启动，并把进程 pid 写入 bin/pid。配合 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

⚠️ 注意：缺少 lsof 时该脚本报 Required lsof but it is unavailable，先 apt-get install -y lsof procps。

4.2 stop-hugegraph.sh —— 停止服务

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

实测回显：

The HugeGraphServer monitor has been closed
Killing HugeGraphServer(pid 2072)......HugeGraphServer shutdown timeout(exceeded 10 seconds)

💡 说明：默认有约 10 秒优雅停止窗口，进程未退会强行终止。

4.3 init-store.sh —— 初始化后端 store（首次启动前必跑）

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.4 enable-auth.sh —— 一键启用认证

cd /opt/hugegraph/hugegraph-server-1.7.0/bin
bash enable-auth.sh

该脚本备份 gremlin-server.yaml、rest-server.properties、graphs/hugegraph.properties 到 conf-bak/，随后自动向 gremlin-server.yaml 追加 authentication 段（使用 StandardAuthenticator 与 WsAndHttpBasicAuthHandler），向 rest-server.properties 追加 auth.authenticator/auth.graph_store，并把 gremlin.graph 改为 org.apache.hugegraph.auth.HugeFactoryAuthProxy。修改后需重启生效。

4.5 gremlin-console.sh —— Gremlin Console

启动控制台：

cd /opt/hugegraph/hugegraph-server-1.7.0/bin
bash gremlin-console.sh

客户端连接配置在 conf/remote.yaml（hosts: [localhost]，port: 8182）。进入 Console 后通过 TinkerPop 远程命令连接：

:plugin use tinkerpop.server
:remote connect tinkerpop.server conf/remote.yaml

⚠️ 注意：1.7.0 单机默认 graphs: {} 不会把图自动绑定为脚本变量，直接用 g.V() 可能报 No such property: g；请在配置好 graphspace 后使用对应图遍历变量。JDK 17 下 Gremlin/Groovy 引擎兼容问题见《Apache HugeGraph 配置参数详解》常见问题。

4.6 REST API 运维命令（curl）

通过 REST API 完成 schema 与数据运维，更稳定：

# 查看图列表
curl -s http://localhost:8080/graphs

# 查看已建顶点类型
curl -s http://localhost:8080/graphs/hugegraph/schema/vertexlabels

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

# 创建顶点类型
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

# 插入顶点
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 查询顶点
curl -s http://localhost:8080/graphs/hugegraph/graph/vertices/1173863628936314880

实测回显（摘录）：

{"graphs":["hugegraph"]}
{"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"}}]}
{"id":1173863628936314880,"label":"person","type":"vertex","properties":{"name":"marko","age":29}}

创建边类型（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

4.7 jps / ss —— JVM 与端口验证

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

实测回显：

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 ...
tcp6       0      0 127.0.0.1:8080   :::*   LISTEN  2072/java
tcp6       0      0 127.0.0.1:8182   :::*   LISTEN  2072/java

4.8 日志查看

服务日志默认写 logs/hugegraph-server.log：

tail -f /opt/hugegraph/hugegraph-server-1.7.0/logs/hugegraph-server.log

五、注意事项

  • 首次部署必须先 init-store.sh 再 start-hugegraph.sh，否则启动报 store 未初始化。
  • 启用认证（enable-auth.sh）后会改变 gremlin.graph，所有客户端需携带 token。
  • 修改 bin/hugegraph-server.sh 的 MIN_MEM/MAX_MEM 或使用 JAVA_OPTIONS 覆盖堆大小后，务必用 jps -v 确认生效。
  • Compose 部署时对应命令映射为 docker compose up -d / docker compose ps / docker compose logs（见 Compose 部署指南）。

六、常见问题（FAQ）

Q1：start-hugegraph.sh 报 lsof 不可用 apt-get install -y lsof 后重试。

Q2：8080 curl 不通 jps -v 与 ss -ltnp 确认进程与端口；若 store 未初始化会启动失败，先跑 init-store.sh。

Q3：Gremlin 语句如 g.V() 报 No such property 1.7.0 单机默认未绑定图遍历变量，需在 graphspace 场景下使用或先注入默认图（见配置详解篇）；另外 JDK 17 下 Groovy 引擎可能不可用，切 JDK 11 更稳。

Q4：如何查看管理账号 默认不启用认证；启用后管理员为 admin，口令由 auth.admin_pa 配置决定（演示口令 q1w2e3r4）。

七、参考链接