HugeGraph (OLTP)

• 1: HugeGraph Server 快速开始
• 2: HugeGraph-PD Quick Start
• 3: HugeGraph-Store Quick Start

1 - HugeGraph Server 快速开始

1 HugeGraph Server 概述

apache/hugegraph 是 HugeGraph 图数据库的主仓库，包含 hugegraph-server、hugegraph-pd、hugegraph-store 等一级模块。本页介绍其中的 hugegraph-server 模块及其运行服务。

hugegraph-server 模块包含 hugegraph-core、hugegraph-api、hugegraph-dist 和存储适配等子模块。Core 实现属性图模型、事务与 TinkerPop 接口，API 提供 HTTP 服务并将客户端请求交给 Core 处理。图数据由 RocksDB（单机默认）、HStore（分布式）或 HBase 后端保存。

⚠️ 版本说明：本文以 HugeGraph 1.7.0 至 master 分支的代码为参考，仅介绍 RocksDB、HStore 和 HBase。其他旧后端的使用与配置请参考 HugeGraph 1.5.x 文档。

名称说明：HugeGraph 表示整个项目或主仓库，hugegraph-server 表示仓库中的 Server 模块，HugeGraphServer 是服务进程的 Java 类名。下文的 Server 服务指运行中的图数据库服务。

2 依赖

2.1 安装 Java 11 (JDK 11)

HugeGraph 1.7.0 中的 hugegraph-server 模块使用 Java 11 编译，运行和源码构建均需使用 Java 11 或更高版本。

在继续阅读前，请先执行 java -version 命令确认 JDK 版本。

1.7.0 起不再支持 Java 8。bin/hugegraph-server.sh 在低于 Java 11 的环境下会直接拒绝启动。

安全检查默认开启，会安装 HugeSecurityManager，它要求 Java 11 到 23。JDK 24 移除了 Security Manager（JEP 486），因此在 Java 24 及更高版本上必须关闭该检查后再启动服务：bin/start-hugegraph.sh -s false。

源码构建还需要 Maven 3.5.0 或更高版本。

3 部署

有四种方式可以部署 Server 服务：

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

不要把 Gremlin、Cypher 等查询接口直接暴露到公网。生产环境应启用认证与授权，限制网络访问并保留审计日志；部署建议见安全指南。

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

可参考 Docker 部署方式。

可以使用 docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0 快速启动一个使用 RocksDB 后端的 Server 实例。

可选项：

1. 可以使用 docker exec -it server bash 进入容器执行运维或调试操作。
2. 可以使用 docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0 在启动时预加载一个内置样例图。可通过 RESTful API 进行验证，具体步骤可参考 5.1.4。
3. 可以使用 -e PASSWORD=xxx 开启鉴权模式并设置 admin 密码，具体步骤可参考 Config Authentication。

如果使用 Docker Desktop，则可以按如下方式设置相关选项：

注意：Docker Compose 文件使用桥接网络（hg-net），适用于 Linux 和 Mac（Docker Desktop）。如需运行 3 节点分布式集群，请为 Docker Desktop 分配至少 12 GB 内存（设置 → 资源 → 内存）。Linux 上 Docker 直接使用宿主机内存。

如果希望通过一个配置文件统一管理 HugeGraph 的多个服务实例，则可以使用 docker compose。 docker/ 目录下提供了四个 compose 文件：

cd hugegraph/docker
# 注意版本号请随时保持更新 → 1.x.0
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose.yml up -d --wait

单机拓扑将 Server 暴露在 8080 端口，Hubble 暴露在 127.0.0.1:8088。HUGEGRAPH_VERSION 决定 Server、PD 和 Store 的镜像 tag，Hubble 由 HUBBLE_IMAGE 单独选择。

compose 文件从 HUGEGRAPH_ADMIN_PASSWORD 读取管理员密码，从 HUGEGRAPH_AUTH_TOKEN_SECRET 读取 JWT 密钥，通常放在 docker/.env 文件中。HUGEGRAPH_ADMIN_PASSWORD 非空即开启鉴权，Hubble 会自动识别该模式。若直接使用 docker run，则改为传入 -e PASSWORD=xxx。

完整的部署指南请参阅 docker/README.md。

注意：

1. HugeGraph 的 Docker 镜像主要用于便捷地快速启动 HugeGraph，并不是 ASF 官方发布物料包。你可以从 ASF Release Distribution Policy 中了解更多细节。

2. 推荐使用 release tag (如 1.7.0/1.x.0) 以获取稳定版。使用 latest tag 可以使用开发中的最新功能。

3.2 下载 tar 包

# 1.7.0 是项目孵化期发布的历史版本，因此文件名仍带 incubating
wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
tar zxf apache-hugegraph-incubating-1.7.0.tar.gz

3.3 源码编译

源码编译前请确保本机有安装 wget/curl 命令

下载 HugeGraph 源代码

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

编译打包生成 tar 包

cd hugegraph
# (Optional) use "-P stage" param if you build failed with the latest code(during pre-release period)
mvn package -DskipTests

构建成功时日志中会出现：

[INFO] BUILD SUCCESS

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

默认构建会打包 rocksdb、hbase 和 hstore 三个后端模块，并把它们记录在 hugegraph-dist jar 内的 backend.properties 资源的 backends 配置项中。若只需要包含 RocksDB 的精简发布包，可加上 -Drocksdb-only：

mvn package -DskipTests -ntp -Drocksdb-only

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

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

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 分布式存储 (HStore)

backend=hstore
serializer=binary

# PD 服务地址，多个 PD 地址用逗号分割，配置 PD 的 RPC 端口
pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688

# 简单示例（带鉴权）
gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy

# 指定存储 hstore（必须）
backend=hstore
serializer=binary
store=hugegraph

# pd config
pd.peers=127.0.0.1:8686

usePD=true
# 从 graphs 目录加载上面的 hugegraph.properties；源码默认值为 false
graph.load_from_local_config=true
# 注意，1.7.0 必须在 rest-server.properties 配置 pd.peers
pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688

# 若需要 auth 
# auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator

usePD=true
restserver.url=http://127.0.0.1:8081
gremlinserver.url=http://127.0.0.1:8181
pd.peers=127.0.0.1:8686

rpc.server_host=127.0.0.1
rpc.server_port=8091

server.id=server-1
server.role=master

usePD=true
restserver.url=http://127.0.0.1:8082
gremlinserver.url=http://127.0.0.1:8182
pd.peers=127.0.0.1:8686

rpc.server_host=127.0.0.1
rpc.server_port=8092

server.id=server-2
server.role=worker

host: 127.0.0.1
port: 8181

host: 127.0.0.1
port: 8182

bin/start-hugegraph.sh

curl http://localhost:8081/graphspaces/DEFAULT/graphs
# 应返回：{"graphs":["hugegraph"]}

bin/stop-hugegraph.sh

cd hugegraph/docker
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d --wait

# Server 配置，server0、server1、server2 共用
HG_SERVER_BACKEND: hstore
HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686
HG_SERVER_CLUSTER: hg
HG_SERVER_USE_PD: "true"
HG_SERVER_MIN_FREE_MEMORY: "0"
HG_SERVER_INIT_STORE_ENABLED: "false"
HG_SERVER_REQUIRE_AUTH_TOKEN_SECRET: "true"
STORE_REST: store0:8520
# 每个节点单独设置，例如 server0
HG_SERVER_REST_URL: http://server0:8080

curl http://localhost:8080/versions
curl http://localhost:8620/v1/stores

5.1.2 RocksDB / ToplingDB

以下从本地 properties 文件启动图的示例要求在 conf/rest-server.properties 中设置：

graph.load_from_local_config=true

当前源码默认值是 false，上游发布模板尚未写出该选项。

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

cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-server-incubating-1.7.0
bin/init-store.sh

bin/start-hugegraph.sh
Starting HugeGraphServer in daemon mode...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
Started [pid 21614]

5.1.3 HBase

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

cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-server-incubating-1.7.0
bin/init-store.sh

bin/start-hugegraph.sh
Starting HugeGraphServer in daemon mode...
Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
Started [pid 21614]

5.1.4 启动 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/graphspaces/DEFAULT/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.1.5 启动脚本的参数

bin/start-hugegraph.sh 支持以下参数。每个参数都需要带值，即写作 -d false，不能只写 -d。

bin/stop-hugegraph.sh 支持 -m true|false（默认 true），用于控制停止服务时是否同时移除 crontab 监控任务。

5.2 使用 Docker

在 3.1 使用 Docker 容器 中，我们已经介绍了如何使用 docker 部署 Server 服务。还可以通过切换后端存储或设置参数，在 Server 启动时加载样例图。

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

在 Docker 启动时设置环境变量 PRELOAD=true，即可在启动脚本执行过程中加载样例数据。

1. 使用docker run

   使用 docker run -itd --name=server -p 8080:8080 -e PRELOAD=true hugegraph/hugegraph:1.7.0

2. 使用docker-compose

   创建docker-compose.yml，具体文件如下，在环境变量中设置 PRELOAD=true。其中，example.groovy 是一个预定义的脚本，用于预加载样例数据。如果有需要，可以通过挂载新的 example.groovy 脚本改变预加载的数据。

   version: '3'
   services:
     server:
       image: hugegraph/hugegraph:1.7.0
       container_name: server
       environment:
         - PRELOAD=true
         - PASSWORD=xxx
       volumes:
         - /path/to/yourscript:/hugegraph-server/scripts/example.groovy
       ports:
         - 8080:8080

   使用命令 docker compose up -d 启动容器

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

> curl "http://localhost:8080/graphspaces/DEFAULT/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/graphspaces/DEFAULT/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/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices

说明

1. 由于图的点和边很多，对于 list 型的请求，比如获取所有顶点，获取所有边等，Server 会将数据压缩再返回，所以使用 curl 时得到一堆乱码，可以重定向至 gunzip 进行解压。推荐使用 Chrome 浏览器 + Restlet 插件发送 HTTP 请求进行测试。

   curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices" | gunzip

2. 当前 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 apache-hugegraph-incubating-1.7.0/apache-hugegraph-server-incubating-1.7.0
bin/stop-hugegraph.sh

8 使用 IntelliJ IDEA 调试 Server

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

2 - HugeGraph-PD Quick Start

1 HugeGraph-PD 概述

HugeGraph-PD（Placement Driver）是 HugeGraph 分布式版本的元数据管理组件，负责管理图数据的分布和存储节点的协调。它在分布式 HugeGraph 中扮演着核心角色，维护集群状态并协调 HugeGraph-Store 存储节点。

PD 将集群元数据保存在 pd.data-path 下的内嵌 RocksDB 中，并通过 Raft 在各 PD 节点之间复制，因此 3 节点或 5 节点的 PD 集群在少数节点宕机时仍可继续提供服务。在此基础上，PD 还负责注册和激活 Store 节点、分配与再平衡分区、跟踪 Store 心跳，并响应来自 Store 和 Server 的服务发现请求。

PD 监听三个端口：

2 依赖

2.1 前置条件

• 操作系统：Linux 或 macOS（Windows 尚未经过完整测试）
• Java 版本：≥ 11
• Maven 版本：≥ 3.5.0

3 部署

有两种方式可以部署 HugeGraph-PD 组件：

• 方式 1：下载 tar 包
• 方式 2：源码编译

3.1 下载 tar 包

从 Apache HugeGraph 官方下载页面下载最新版本的 HugeGraph-PD：

# 1.7.0 是项目孵化期发布的历史版本，因此文件名和目录名仍带 incubating
wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
tar zxf apache-hugegraph-incubating-1.7.0.tar.gz
cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-pd-incubating-1.7.0

3.2 源码编译

# 1. 克隆源代码
git clone https://github.com/apache/hugegraph.git

# 2. 编译项目
cd hugegraph
mvn clean install -DskipTests=true

# 3. 编译成功后，PD 目录和发布包分别位于
#    hugegraph-pd/apache-hugegraph-pd-{version}          （解压后的 PD 发布目录）
#    hugegraph-pd/apache-hugegraph-pd-{version}.tar.gz   （仅含 PD 的发布包，只在 Linux 构建机上生成）
#    target/apache-hugegraph-{version}.tar.gz            （PD + Store + Server 的完整发布包）

只编译 PD 发布包及其依赖模块：

mvn clean package -pl hugegraph-pd/hg-pd-dist -am -DskipTests

解压后的发布目录只包含三个子目录：bin（启停脚本）、conf（application.yml、application.yml.template、log4j2.xml、verify-license.json）和 lib（hg-pd-service jar 包）。

3.3 Docker 部署

HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 hugegraph/pd。

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

使用 docker-compose 模式部署完整的 3 节点集群（PD + Store + Server）：

cd hugegraph/docker
# 注意版本号请随时保持更新 → 1.x.0
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d

单 PD、单 Store、单 Server 的最小拓扑对应 docker-compose-hstore.yml。

通过 docker run 运行单个 PD 节点时，通过环境变量提供配置：

docker run -d \
  -p 8620:8620 \
  -p 8686:8686 \
  -p 8610:8610 \
  -e HG_PD_GRPC_HOST=<your-ip> \
  -e HG_PD_RAFT_ADDRESS=<your-ip>:8610 \
  -e HG_PD_RAFT_PEERS_LIST=<your-ip>:8610 \
  -e HG_PD_INITIAL_STORE_LIST=<store-ip>:8500 \
  -v /path/to/data:/hugegraph-pd/pd_data \
  --name hugegraph-pd \
  hugegraph/pd:1.7.0

环境变量参考：

缺少上述四个必填变量中的任意一个时，entrypoint 会拒绝启动。它把这些值转换成 SPRING_APPLICATION_JSON 覆盖项，因此无需修改镜像内的 conf/application.yml；未被 HG_PD_* 变量覆盖的配置项仍沿用该文件中的值。JAVA_OPTS 会透传给 JVM。

注意：在 Docker 桥接网络中，HG_PD_GRPC_HOST 和 HG_PD_RAFT_ADDRESS 应使用容器主机名（如 pd0）而非 IP 地址。

已弃用的别名：GRPC_HOST、RAFT_ADDRESS、RAFT_PEERS、PD_INITIAL_STORE_LIST 仍可使用，但会输出弃用警告。新部署请使用 HG_PD_* 名称。

镜像内置 HEALTHCHECK，每 15 秒探测 8620 端口上的 GET /v1/health，启动宽限期 90 秒、重试 3 次，因此 docker ps 能反映真实的 PD 健康状态。entrypoint 以 -d false 调用启动脚本，容器进程就是 Java 进程本身，Java 退出时容器随之退出并触发 Docker 的重启策略。镜像还设置了 STDOUT_MODE=true，因此运行时日志可通过 docker logs <container-name>（如 docker logs hg-pd0）直接查看，无需进入容器。

完整的集群部署指南请参阅 docker/README.md。

4 配置

PD 的主要配置文件为 conf/application.yml，以下是发布包中自带的内容：

spring:
  application:
    name: hugegraph-pd

management:
  metrics:
    export:
      prometheus:
        enabled: true
  endpoints:
    web:
      exposure:
        include: "*"

logging:
  config: 'file:./conf/log4j2.xml'

license:
  verify-path: ./conf/verify-license.json
  license-path: ./conf/hugegraph.license

grpc:
  # 集群模式下的 gRPC 端口
  port: 8686
  # 部署时需改为本机实际的 IPv4 地址
  host: 127.0.0.1

server:
  # REST 服务端口号
  port: 8620

pd:
  # 存储路径
  data-path: ./pd_data
  # 自动扩容的检查周期（秒）
  patrol-interval: 1800
  # 集群可用所需的最小 Store 数量
  initial-store-count: 1
  # store 的配置信息，格式为 IP:gRPC端口
  initial-store-list: 127.0.0.1:8500

raft:
  # 本节点的 raft 地址
  address: 127.0.0.1:8610
  # 集群中所有 PD 节点的 raft 地址
  peers-list: 127.0.0.1:8610

store:
  # store 下线时间（秒）。超过该时间，认为 store 永久不可用，分配副本到其他机器
  max-down-time: 172800
  # 是否开启 store 监控数据存储
  monitor_data_enabled: true
  # 监控数据的间隔
  monitor_data_interval: 1 minute
  # 监控数据的保留时间
  monitor_data_retention: 1 day

partition:
  # 默认每个分区副本数
  default-shard-count: 1
  # 默认每机器最大副本数
  store-max-shard-count: 12

conf/application.yml.template 是另一份带占位符（$GRPC_PORT$、$RAFT_ADDRESS$ 等）的副本，供自动生成配置的部署工具使用，PD 本身不读取它。启动脚本通过 -Dspring.config.location 指定的始终是 conf/application.yml。

4.1 配置项参考

conf/application.yml 中未出现的配置项会回退到下表的内置默认值；没有内置默认值的配置项必须存在，否则 PD 无法启动。

gRPC 与 REST

application.yml.template 中还有 grpc.netty-server.max-inbound-message-size: 100MB，但 PD 在代码中把 gRPC 服务端的入站消息上限固定为 1 GB，该配置项实际不生效。

Raft

PD 核心

Store 管理

分区

初始分区数由这两个配置项和 pd.initial-store-list 的长度推导得出：

初始分区数 = Store 数量 * partition.store-max-shard-count / partition.default-shard-count

服务发现、License 与监控

线程池

4.2 单节点配置

发布包自带的 conf/application.yml 本身就是一份可用的单节点配置，适用于开发和测试：单节点 PD 不存在 Raft 多数派可失，partition.default-shard-count: 1 表示每个分区只有一个副本。

grpc:
  host: 127.0.0.1
  port: 8686
server:
  port: 8620
raft:
  address: 127.0.0.1:8610
  peers-list: 127.0.0.1:8610
pd:
  data-path: ./pd_data
  initial-store-count: 1
  initial-store-list: 127.0.0.1:8500
partition:
  default-shard-count: 1

4.3 三节点集群配置

生产环境请部署 3 个或 5 个 PD 节点，节点数取奇数以保证 Raft 总能形成多数派。3 节点集群可容忍 1 个节点故障。raft.peers-list 必须列出全部节点，并且在所有节点上逐字节一致；grpc.host 和 raft.address 每个节点各不相同。

节点 1（192.168.1.10）：

grpc:
  host: 192.168.1.10
  port: 8686
server:
  port: 8620
raft:
  address: 192.168.1.10:8610
  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
pd:
  data-path: /data/pd
  initial-store-count: 3
  initial-store-list: 192.168.1.20:8500,192.168.1.21:8500,192.168.1.22:8500
partition:
  default-shard-count: 3

节点 2（192.168.1.11）和节点 3（192.168.1.12）使用同一份配置，只把 grpc.host 和 raft.address 换成自己的地址：

# 节点 2
grpc:
  host: 192.168.1.11
raft:
  address: 192.168.1.11:8610
  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610

# 节点 3
grpc:
  host: 192.168.1.12
raft:
  address: 192.168.1.12:8610
  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610

若要在同一台机器上启动 3 个 PD 节点做测试，需为每个节点分别指定 pd.data-path 和各自的端口，例如 raft 端口 8610/8611/8612、gRPC 端口 8686/8687/8688、REST 端口 8620/8621/8622。

在 Docker 桥接网络中，同样的配置来自环境变量，并使用容器主机名而非 IP 地址：

# pd0
HG_PD_GRPC_HOST: pd0
HG_PD_RAFT_ADDRESS: pd0:8610
HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
HG_PD_INITIAL_STORE_COUNT: 3

# pd1
HG_PD_GRPC_HOST: pd1
HG_PD_RAFT_ADDRESS: pd1:8610
HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610

# pd2
HG_PD_GRPC_HOST: pd2
HG_PD_RAFT_ADDRESS: pd2:8610
HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610

5 启动与停止

5.1 启动 PD

在 PD 安装目录下执行：

./bin/start-hugegraph-pd.sh

脚本要求 PATH 或 JAVA_HOME 中有 11 及以上版本的 JDK；如果发现已有 Java 进程在使用本安装目录的 conf 目录，脚本会直接退出，不做任何事。

支持的参数：

-d 参数控制守护进程模式：

• -d true（默认）：以后台守护进程方式运行，脚本立即返回。
• -d false：以前台模式运行，脚本通过 exec 替换为 Java 进程，容器/进程管理器的进程即为 Java 本身。在 Docker 或进程管理器（systemd、supervisord）下运行时请使用此参数，以便在崩溃时自动检测并重启服务。

每个参数都有对应的环境变量：DAEMON、GC_OPTION、USER_OPTION 和 OPEN_TELEMETRY。设置 JAVA_OPTIONS 会完全替换脚本计算出的堆参数，否则脚本会根据可用内存在 512 MB 到 32 GB 之间选择堆大小。设置 STDOUT_MODE=true 时 JVM 输出保留在 stdout，不再重定向到 logs/hugegraph-pd-stdout.log，Docker 镜像正是这样做的。

启动成功后，可以在 logs/hugegraph-pd-stdout.log 中看到类似以下的日志：

YYYY-mm-dd xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx)

进程号会写入 bin/pid。

5.2 停止 PD

在 PD 安装目录下执行：

./bin/stop-hugegraph-pd.sh

脚本读取 bin/pid，向该进程发送终止信号，最多等待 30 秒直到进程退出，然后删除 pid 文件。如果 bin/pid 不存在，脚本会提示并正常退出。

6 分布式集群的启动顺序

请按以下顺序启动各组件：

1. 全部 PD 节点。它们组成 Raft 组并选出 leader。等到每个节点都能响应 GET /v1/health 再继续。
2. 全部 Store 节点。每个 Store 通过 gRPC 向 PD 注册，PD 会自动激活 pd.initial-store-list 中列出的 Store。等到 GET /v1/stores 中每个 Store 的 state 都是 Up 再继续。
3. 全部 Server 节点。Server 读取 pd.peers，并依赖 PD 报告至少有一个存活的 Store 才能完成分区分配。

Docker Compose 的各个拓扑正是这样编排的：Store 容器通过 depends_on 加 condition: service_healthy 等待 PD 的 /v1/health 健康检查，Server 容器以同样方式等待 Store 的健康检查，Server 的 entrypoint 还会轮询 PD 的 /v1/stores，直到有 Store 报告 Up 才启动 HugeGraph。

停止时顺序相反：先停 Server，再停 Store，最后停 PD。

7 验证

7.1 REST API 认证

除 /actuator/*、/v1/health 和 /v1/prom/targets/* 之外，PD 的所有 REST 路径都要求带 HTTP Basic Authorization 头，且用户名必须是内部服务名 hg、store、hubble、vermeer 之一。不带该头的请求会得到：

{"status": -1, "error": "Unauthorized!"}

目前不校验密码，任意值均可。Server 自带的 bin/wait-storage.sh 使用 store:admin，并支持用 PD_AUTH_USER 和 PD_AUTH_PASSWORD 覆盖，因此下面的示例使用同样的凭据：

curl -u store:admin http://localhost:8620/v1/stores

警告：该校验只用于区分 HugeGraph 自身组件与其他流量。请勿把 PD 的 REST 或 gRPC 端口暴露到不可信网络，应通过防火墙规则或安全组加以限制，并保持 raft.ip-whitelist.enabled 开启，使 Raft 端口只接受配置中的 peer。

7.2 健康检查

GET /v1/health 不需要凭据，Docker 健康检查用的就是它。它返回 200 且响应体为空：

curl -i http://localhost:8620/v1/health

Spring Boot actuator 端点同样可用，输出更直观：

curl http://localhost:8620/actuator/health

如果返回 {"status":"UP"}，则表示 PD 服务已成功启动。

7.3 集群与成员状态

查看 PD 成员以及当前的 Raft leader：

curl -u store:admin http://localhost:8620/v1/members

响应中包含 pdList、选出的 pdLeader、numOfService、numOfNormalService 和 stateCountMap。健康的 3 节点 PD 集群中，numOfService 和 numOfNormalService 都应为 3，且恰好有一个成员的 role 为 Leader。

GET /v1/cluster 在成员列表之外还返回 Store 列表、图列表和集群整体状态；GET / 返回一份简要汇总（leader 地址、集群状态、成员数、Store 数、图数量、分区数）。

7.4 Store 状态

也可以通过 PD API 查看 Store 节点状态：

curl -u store:admin http://localhost:8620/v1/stores

如果响应中 state 为 Up，说明对应的 Store 节点运行正常。下面的示例只有一个 Store 节点。在一个健康的 3 节点部署中，storeId 列表应包含 3 个 ID，且 stateCountMap.Up、numOfService 和 numOfNormalService 都应为 3。

{
  "message": "OK",
  "data": {
    "stores": [
      {
        "storeId": 8319292642220586694,
        "address": "127.0.0.1:8500",
        "raftAddress": "127.0.0.1:8510",
        "version": "",
        "state": "Up",
        "deployPath": "/Users/{your_user_name}/hugegraph/apache-hugegraph-incubating-1.7.0/apache-hugegraph-store-incubating-1.7.0/lib/hg-store-node-1.7.0.jar",
        "dataPath": "./storage",
        "startTimeStamp": 1754027127969,
        "registedTimeStamp": 1754027127969,
        "lastHeartBeat": 1754027909444,
        "capacity": 494384795648,
        "available": 346535829504,
        "partitionCount": 0,
        "graphSize": 0,
        "keyCount": 0,
        "leaderCount": 0,
        "serviceName": "127.0.0.1:8500-store",
        "serviceVersion": "",
        "serviceCreatedTimeStamp": 1754027127000,
        "partitions": []
      }
    ],
    "stateCountMap": {
      "Up": 1
    },
    "numOfService": 1,
    "numOfNormalService": 1
  },
  "status": 0
}

7.5 其他 REST 接口

下表中的路径均相对于 http://<pd-host>:8620，除注明外都需要 7.1 中的 Basic 认证头。

两个 log 接口接受形如 {"startTime": "...", "endTime": "..."} 的时间范围，yyyy-MM-dd HH:mm:ss 和 yyyy-MM-dd 都是可接受的格式。

PD 以 hg 前缀注册自己的指标，因此 /actuator/prometheus 除标准 JVM 指标外还会暴露 hg_up、hg_graphs、hg_stores 和 hg_terms，在存在图之后还会有按图统计的分区和大小指标。

3 - HugeGraph-Store Quick Start

1 HugeGraph-Store 概述

HugeGraph-Store 是 HugeGraph 分布式版本的存储节点组件，负责实际存储和管理图数据。它与 HugeGraph-PD 协同工作，共同构成 HugeGraph 的分布式存储引擎，提供高可用性和水平扩展能力。

每个 Store 节点使用 RocksDB 保存图数据，并通过 Raft（JRaft）进行复制：每个分区是一个独立的 Raft 组，因此分区在丢失少数副本时仍可继续工作。Store 节点之间并不直接感知彼此，它们向 PD 注册，由 PD 下发分区分配，并通过心跳上报状态。HugeGraph-Server 先从 PD 查询分区位置，再通过 gRPC 访问 Store。

2 依赖

2.1 前置条件

• 操作系统：Linux 或 macOS（Windows 尚未经过完整测试）
• Java 版本：≥ 11（编译期强制校验，bin/start-hugegraph-store.sh 启动时会再次检查）
• Maven 版本：≥ 3.5.0
• 如需进行多节点部署，请先部署 HugeGraph-PD

3 部署

有两种方式可以部署 HugeGraph-Store 组件：

• 方式 1：下载 tar 包
• 方式 2：源码编译

3.1 下载 tar 包

从 Apache HugeGraph 官方下载页面下载最新版本的 HugeGraph-Store：

# 1.7.0 是项目孵化期发布的历史版本，因此文件名和目录名仍带 incubating
wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
tar zxf apache-hugegraph-incubating-1.7.0.tar.gz
cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-store-incubating-1.7.0

3.2 源码编译

# 1. 克隆源代码
git clone https://github.com/apache/hugegraph.git

# 2. 编译项目
cd hugegraph
mvn clean install -DskipTests=true

# 3. 编译成功后，Store 目录和完整发布包分别位于
#    hugegraph-store/apache-hugegraph-store-{version}
#    target/apache-hugegraph-{version}.tar.gz

如果只想单独编译 Store 而不是整个仓库，需要先编译 hugegraph-struct，因为 Store 依赖它：

mvn install -pl hugegraph-struct -am -DskipTests
mvn clean package -pl hugegraph-store/hg-store-dist -am -DskipTests

生成的目录只包含 bin/、conf/ 和 lib/hg-store-node-{version}.jar。

3.3 Docker 部署

HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名是 hugegraph/store。

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

有两个 compose 文件包含 Store：

cd hugegraph/docker
# 注意版本号请随时保持更新 → 1.x.0

# 最小分布式部署
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-hstore.yml up -d --wait

# 或者多节点集群
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d

通过 docker run 运行单个 Store 节点：

docker run -d \
  -p 8520:8520 \
  -p 8500:8500 \
  -p 8510:8510 \
  -e HG_STORE_PD_ADDRESS=<pd-ip>:8686 \
  -e HG_STORE_GRPC_HOST=<your-ip> \
  -e HG_STORE_RAFT_ADDRESS=<your-ip>:8510 \
  -v /path/to/storage:/hugegraph-store/storage \
  --name hugegraph-store \
  hugegraph/store:1.7.0

环境变量参考：

入口脚本会把这些变量转换为 SPRING_APPLICATION_JSON，覆盖在 conf/application.yml 之上，然后执行 bin/start-hugegraph-store.sh -d false -j "$JAVA_OPTS"。上表未覆盖的配置项仍需要修改 conf/application.yml，或者自行提供 SPRING_APPLICATION_JSON。

镜像细节：

• JAVA_OPTS 默认值为 -XX:+UnlockExperimentalVMOptions -XX:+UseContainerSupport -XX:MaxRAMPercentage=50 -XshowSettings:vm
• STDOUT_MODE=true，因此 Java 日志输出到容器 stdout，而不是 logs/hugegraph-store-server.log
• HEALTHCHECK 在 90 秒启动期后每 15 秒访问一次 GET http://localhost:8520/v1/health
• 镜像只声明了 EXPOSE 8520；如果需要从 Docker 网络之外访问 8500 和 8510，请自行发布这两个端口

注意：在 Docker 桥接网络中，HG_STORE_GRPC_HOST 应使用容器主机名（如 store0）而非 IP 地址。

已弃用的别名：PD_ADDRESS、GRPC_HOST、RAFT_ADDRESS 仍可使用，但会输出弃用警告。新部署请使用 HG_STORE_* 名称。

4 配置

Store 从 conf/ 读取两个配置文件：

• application.yml，主配置文件（PD 地址、各端口、Raft、数据路径）
• application-pd.yml，由 application.yml 中的 spring.profiles.include: pd 引入，包含 RocksDB 内存设置和 Actuator 暴露配置

4.1 application.yml

发布包中自带的文件内容如下：

pdserver:
  # PD service address, multiple PD addresses separated by commas
  address: localhost:8686

management:
  metrics:
    export:
      prometheus:
        enabled: true
  endpoints:
    web:
      exposure:
        include: "*"

grpc:
  # grpc service address
  host: 127.0.0.1
  port: 8500
  netty-server:
    max-inbound-message-size: 1000MB
raft:
  # raft cache queue size
  disruptorBufferSize: 1024
  address: 127.0.0.1:8510
  max-log-file-size: 600000000000
  # Snapshot generation interval, in seconds
  snapshotInterval: 1800
server:
  # rest service address
  port: 8520

app:
  # Storage path, support multiple paths, separated by commas
  data-path: ./storage
  #raft-path: ./storage

spring:
  application:
    name: store-node-grpc-server
  profiles:
    active: default
    include: pd

logging:
  config: 'file:./conf/log4j2.xml'
  level:
    root: info

4.2 application-pd.yml

management:
  metrics:
    export:
      prometheus:
        enabled: true
  endpoints:
    web:
      exposure:
        include: "*"

rocksdb:
  # rocksdb total memory usage, force flush to disk when reaching this value
  total_memory_size: 32000000000
  # memtable size used by rocksdb
  write_buffer_size: 32000000
  # For each rocksdb, the number of memtables reaches this value for writing to disk.
  min_write_buffer_number_to_merge: 16

4.3 配置项参考

下表中「模板值」是上面两个文件中的取值，「代码默认值」是配置项缺失时节点使用的回退值；模板未列出的配置项应以代码默认值为准。

核心

Raft

存储与标签

RocksDB

org/apache/hugegraph/rocksdb/access/RocksDBOptions.java 中定义的其他选项都可以加在同一个 rocksdb: 块下，例如 rocksdb.max_background_jobs、rocksdb.level0_file_num_compaction_trigger 或 rocksdb.bloom_filter_bits_per_key。

线程池

查询下推

后台任务

内置 PD 模式

仅用于单机开发调试，通过 app.fake-pd: true 开启。此时节点自行扮演 PD 角色，并忽略 pdserver.address。

诊断

4.4 各节点需要区分的配置

对于多节点部署，需要为每个 Store 节点修改以下配置：

1. grpc.host 和 grpc.port（其他组件访问本节点的地址）
2. raft.address（Raft 协议地址）
3. server.port（REST 端口）
4. app.data-path（数据存储路径）

pdserver.address 在所有节点上保持一致，它列出的是整个 PD 集群。

5 启动与停止

5.1 启动 Store

确保 PD 服务已经启动，然后在 Store 安装目录下执行：

./bin/start-hugegraph-store.sh

启动脚本支持四个参数：

守护进程模式：

• -d true（默认）：以后台守护进程方式运行，脚本立即返回，并把 Java 进程号写入 bin/pid。
• -d false：以前台模式运行，脚本通过 exec 替换为 Java 进程，容器或进程管理器的进程即为 Java 本身。在 Docker 或进程管理器（systemd、supervisord）下运行时请使用此参数，以便在崩溃时自动检测并重启服务。

JVM 内存方面，如果没有自行设置 JAVA_OPTIONS：-Xms512m，-Xmx 取空闲内存的一半并限制在 512 MB 到 2048 MB 之间。脚本还会加上 -XX:MetaspaceSize=256M、OOM 时把堆转储写入 logs/，以及滚动的 GC 日志 logs/gc.log。生产节点通常需要大得多的堆，请显式指定，例如 -j "-Xmx32g -Xms32g"。

当 ulimit -n 或 ulimit -u 低于 1024 时脚本会拒绝启动；在 x86_64 和 arm64 上，如果能成功下载并校验对应的动态库，脚本会预加载 jemalloc。

启动成功后，可以在 logs/hugegraph-store-server.log 中看到类似以下的日志：

YYYY-mm-dd xx:xx:xx [main] [INFO] o.a.h.s.n.StoreNodeApplication - Started StoreNodeApplication in x.xxx seconds (JVM running for x.xxx)

5.2 停止 Store

在 Store 安装目录下执行：

./bin/stop-hugegraph-store.sh

脚本读取 bin/pid，向该进程发送信号，最多等待 30 秒直至进程退出，然后删除 pid 文件。如果 bin/pid 不存在，脚本直接退出且不做任何操作。

5.3 重启 Store

./bin/restart-hugegraph-store.sh

该脚本依次 source 停止脚本和启动脚本，并转发 5.1 中的参数。

5.4 启动顺序

1. 先启动 PD。每个 Store 的 grpc.host:grpc.port 都应出现在 PD 的 pd.initial-store-list 中，否则 PD 只会把该节点登记为 Pending 而不会置为 Up，分区分配也就无法完成。
2. 再启动 Store。Store 早于 PD 启动并不致命：心跳线程会持续重试注册，并在 PD 可用之前打印 store heartbeat error: PD UNREACHABLE。
3. 最后启动 HugeGraph-Server，此时所有 Store 节点都应上报 state: "Up"。Server 需要分区就绪之后才能初始化或打开图。

compose 文件用 depends_on: condition: service_healthy 表达同样的顺序：Store 等待所有 PD 健康检查通过，Server 等待所有 Store 健康检查通过。

6 多节点部署示例

以下是一个三节点部署的配置示例：

6.1 三节点配置参考

• 3 PD 节点
  • raft 端口：8610, 8611, 8612
  • rpc 端口：8686, 8687, 8688
  • rest 端口：8620, 8621, 8622
• 3 Store 节点
  • raft 端口：8510, 8511, 8512
  • rpc 端口：8500, 8501, 8502
  • rest 端口：8520, 8521, 8522

6.2 Store 节点配置

对于三个 Store 节点，每个节点的主要配置差异如下：

节点 A：

grpc:
  port: 8500
raft:
  address: 127.0.0.1:8510
server:
  port: 8520
app:
  data-path: ./storage-a

节点 B：

grpc:
  port: 8501
raft:
  address: 127.0.0.1:8511
server:
  port: 8521
app:
  data-path: ./storage-b

节点 C：

grpc:
  port: 8502
raft:
  address: 127.0.0.1:8512
server:
  port: 8522
app:
  data-path: ./storage-c

所有节点都应该指向相同的 PD 集群：

pdserver:
  address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688

同时每个 PD 节点都应列出三个 Store 的 gRPC 地址：

pd:
  initial-store-list: 127.0.0.1:8500,127.0.0.1:8501,127.0.0.1:8502

6.3 Docker 分布式集群配置

3 节点 Store 集群包含在 docker/docker-compose-3pd-3store-3server.yml 中。每个 Store 节点拥有独立的主机名和环境变量：

# store0，宿主机端口 8500（gRPC）、8510（Raft）、8520（REST）
HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
HG_STORE_GRPC_HOST: store0
HG_STORE_GRPC_PORT: "8500"
HG_STORE_REST_PORT: "8520"
HG_STORE_RAFT_ADDRESS: store0:8510
HG_STORE_DATA_PATH: /hugegraph-store/storage

# store1，宿主机端口 8501、8511、8521
HG_STORE_GRPC_HOST: store1
HG_STORE_RAFT_ADDRESS: store1:8510

# store2，宿主机端口 8502、8512、8522
HG_STORE_GRPC_HOST: store2
HG_STORE_RAFT_ADDRESS: store2:8510

每个节点的容器内端口都是 8500/8510/8520，只有映射到宿主机的端口不同。PD 节点相应地设置 HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500。

Store 节点仅在所有 PD 节点通过健康检查后才会启动，其中 docker-compose 中的 healthcheck 实际访问的是 PD 的 REST 接口 /v1/health（也可以通过 Actuator 暴露的 /actuator/health 进行手动检查），并通过 depends_on: condition: service_healthy 强制执行依赖关系。

运行时日志可通过 docker logs <container-name>（如 docker logs hg-store0）直接查看，无需进入容器。

完整的部署指南请参阅 docker/README.md。

7 验证 Store 服务

确认 Store 服务是否正常运行：

curl http://localhost:8520/actuator/health

如果返回 {"status":"UP"}，则表示 Store 服务已成功启动。

GET /v1/health 是 Docker 镜像和 compose 文件使用的轻量检查接口，它返回 HTTP 200 且响应体为空，因此应使用 curl -fsS 并检查退出码，而不是检查输出内容：

curl -fsS http://localhost:8520/v1/health && echo OK

7.1 Store REST 接口

Store 节点在 server.port 上提供以下只读接口：

Actuator 和 Prometheus 之所以可访问，是因为自带配置设置了 management.endpoints.web.exposure.include: "*" 和 management.metrics.export.prometheus.enabled: true。

节点还提供一批会修改状态或执行重负载操作的运维接口：PUT /-/state、GET /-/cleaner、GET /v1/partition/dump/{id}、GET /v1/partition/clean/{id}、POST /v1/compat?id=<partition>、GET /v1/arthasstart、POST /raft/options，以及 /fix/* 和 /test/* 两组接口。请仅在排查问题时使用，并且不要把 REST 端口暴露到不可信网络。

7.2 通过 PD 检查注册结果

也可以通过 PD API 查看集群中的 Store 节点状态：

curl -u store:admin http://localhost:8620/v1/stores

PD 的 REST 端口默认开启 basic 认证：用户名必须是 hg、store、hubble、vermeer 之一，密码目前还不校验。不带凭据的请求会返回 {"status":-1,"error":"Unauthorized!"}。只有 /v1/health、/actuator/* 和 /v1/prom/targets/* 不需要认证。

如果 Store 配置成功，上述接口响应中应包含当前节点的状态信息，其中 state 为 Up 表示节点运行正常。如果节点长期停留在 Pending，通常是因为它没有出现在 PD 的 pd.initial-store-list 中。

下方示例仅展示 1 个 Store 节点的返回结果。如果 3 个节点都已正确配置并正在运行，则响应中的 storeId 列表应包含 3 个 ID，且 stateCountMap.Up、numOfService 和 numOfNormalService 都应为 3。

{
  "message": "OK",
  "data": {
    "stores": [
      {
        "storeId": 8319292642220586694,
        "address": "127.0.0.1:8500",
        "raftAddress": "127.0.0.1:8510",
        "version": "",
        "state": "Up",
        "deployPath": "/Users/{your_user_name}/hugegraph/hugegraph-store/apache-hugegraph-store-{version}/lib/hg-store-node-{version}.jar",
        "dataPath": "./storage",
        "startTimeStamp": 1754027127969,
        "registedTimeStamp": 1754027127969,
        "lastHeartBeat": 1754027909444,
        "capacity": 494384795648,
        "available": 346535829504,
        "partitionCount": 0,
        "graphSize": 0,
        "keyCount": 0,
        "leaderCount": 0,
        "serviceName": "127.0.0.1:8500-store",
        "serviceVersion": "",
        "serviceCreatedTimeStamp": 1754027127000,
        "partitions": []
      }
    ],
    "stateCountMap": {
      "Up": 1
    },
    "numOfService": 1,
    "numOfNormalService": 1
  },
  "status": 0
}