Documentation

• 1: Apache HugeGraph 介绍
• 2: 下载 Apache HugeGraph
• 3: 快速上手
  • 3.1: HugeGraph (OLTP)
    • 3.1.1: HugeGraph Server 快速上手
    • 3.1.2: HugeGraph-PD 快速上手
    • 3.1.3: HugeGraph-Store 快速上手
    • 3.1.4: 使用 Helm 部署 HugeGraph
    • 3.1.5: HugeGraph Kubernetes 运维
  • 3.2: HugeGraph ToolChain
    • 3.2.1: 使用 Hubble 实现图可视化：单机快速上手
    • 3.2.2: 图可视化
      • 3.2.2.1: 使用 Hubble 管理 HStore 分布式集群
    • 3.2.3: HugeGraph-Loader 快速上手
    • 3.2.4: 图导入
      • 3.2.4.1: 使用 SeaTunnel Sink 导入图数据
    • 3.2.5: Tools 快速上手
    • 3.2.6: 图导出/迁移
      • 3.2.6.1: 使用 SeaTunnel Source 导出与迁移图数据
    • 3.2.7: HugeGraph-Spark-Connector 快速上手
  • 3.3: HugeGraph-AI
    • 3.3.1: HugeGraph-LLM
    • 3.3.2: HugeGraph-ML
    • 3.3.3: HugeGraph-LLM 使用流程
    • 3.3.4: 配置参考
    • 3.3.5: HugeGraph-LLM REST API
    • 3.3.6: Vermeer Python 客户端
    • 3.3.7: HugeGraph-MCP
    • 3.3.8: HugeGraph-LLM SDK 快速上手
  • 3.4: HugeGraph 图计算（OLAP）
    • 3.4.1: HugeGraph-Vermeer 快速上手
    • 3.4.2: HugeGraph-Computer 快速上手
    • 3.4.3: HugeGraph-Computer 配置参考
• 4: HugeGraph-Server 配置
  • 4.1: Server 启动指南
  • 4.2: Server 完整配置手册
  • 4.3: HugeGraph 内置用户权限与扩展权限配置及使用
  • 4.4: 配置 HugeGraphServer 使用 https 协议
  • 4.5: 配置 RocksDB 后端
  • 4.6: 配置 HStore 分布式后端
  • 4.7: 配置 HBase 后端
• 5: 客户端与 API
  • 5.1: HugeGraph RESTful API
    • 5.1.1: Graphspace API
    • 5.1.2: Schema API
    • 5.1.3: PropertyKey API
    • 5.1.4: VertexLabel API
    • 5.1.5: EdgeLabel API
    • 5.1.6: IndexLabel API
    • 5.1.7: Rebuild API
    • 5.1.8: Vertex API
    • 5.1.9: Edge API
    • 5.1.10: Traverser API
    • 5.1.11: Rank API
    • 5.1.12: Variable API
    • 5.1.13: Graphs API
    • 5.1.14: Task API
    • 5.1.15: Gremlin API
    • 5.1.16: Cypher API
    • 5.1.17: Authentication API
    • 5.1.18: Metrics API
    • 5.1.19: Other API
  • 5.2: 客户端/SDK
    • 5.2.1: HugeGraph Java Client
    • 5.2.2: HugeGraph Python 客户端快速上手
    • 5.2.3: HugeGraph Go 客户端快速入门
  • 5.3: Gremlin-Console
• 6: 使用指南
  • 6.1: HugeGraph 架构概览
    • 6.1.1: HugeGraph Plugin 机制及插件扩展流程
    • 6.1.2: HugeGraph 设计理念
  • 6.2: 开发测试
    • 6.2.1: HugeGraph工具链本地测试指南
    • 6.2.2: ToplingDB 开发版集成
  • 6.3: 备份与恢复
  • 6.4: HugeGraph Docker 集群部署指南
  • 6.5: FAQ
  • 6.6: 报告安全问题
  • 6.7: 1.8.0 共享基础模块迁移指南
  • 6.8: HugeGraph 1.8.0 Gremlin 迁移与兼容性指南
• 7: 图查询语言
  • 7.1: HugeGraph Gremlin
  • 7.2: HugeGraph Cypher
  • 7.3: Cypher 兼容性
  • 7.4: 从 Neo4j 迁移
  • 7.5: HugeGraph Examples
• 8: PERFORMANCE
  • 8.1: HugeGraph BenchMark Performance
  • 8.2: HugeGraph-API Performance
    • 8.2.1: v0.5.6 Stand-alone(RocksDB)
    • 8.2.2: v0.5.6 Cluster(Cassandra)
  • 8.3: HugeGraph-Loader Performance
  • 8.4: HugeGraph 0.4.4 性能测试
• 9: 贡献指南
  • 9.1: 参与 HugeGraph 社区
  • 9.2: 订阅社区邮件列表
  • 9.3: 验证 Apache 发版
  • 9.4: 在 IDEA 中配置 Server 开发环境
  • 9.5: Apache HugeGraph Committer 指南
• 10: CHANGELOGS
  • 10.1: HugeGraph 1.8.0 Release Notes
  • 10.2: HugeGraph 1.7.0 Release Notes
  • 10.3: HugeGraph 1.5.0 Release Notes
  • 10.4: HugeGraph 1.3.0 Release Notes
  • 10.5: HugeGraph 1.2.0 Release Notes
  • 10.6: HugeGraph 1.0.0 Release Notes
  • 10.7: HugeGraph 0.12 Release Notes
• 11: Apache 贡献者协议

 1+-----------------------------------------------------------------+
 2|                   Apache HugeGraph Ecosystem                    |
 3+-----------------------------------------------------------------+
 4|  +-------------+  +-------------+  +-------------------------+  |
 5|  | HugeGraph   |  | Vermeer*    |  | HugeGraph-AI            |  |
 6|  | Core Engine |  | Computer    |  | (GraphRAG/ML/Python)    |  |
 7|  | (OLTP)      |  | (Java BSP)  |  |                         |  |
 8|  +------+------+  +------+------+  +------------+------------+  |
 9|         |                |                      |               |
10|  +------+----------------+----------------------+------------+  |
11|  | HugeGraph Toolchain                                       |  |
12|  | Hubble (UI) | Loader | Client (Java/Go/Py) | Tools        |  |
13|  +-----------------------------------------------------------+  |
14+-----------------------------------------------------------------+

1 - Apache HugeGraph 介绍

什么是 Apache HugeGraph？

Apache HugeGraph 是一套易用、高效、通用的开源全栈图系统（GitHub），覆盖图数据库（OLTP 实时查询）、图计算（OLAP 大规模分析）与图 AI（GraphRAG / 图机器学习）三大领域。

HugeGraph 支持百亿以上的顶点和边的快速存储与查询，具备出色的 OLTP 性能。其图引擎兼容 Apache TinkerPop 3 框架，同时支持 Gremlin 和 Cypher（OpenCypher 标准）查询语言。

典型应用场景： 深度关系探索、关联分析、路径搜索、特征抽取、社区检测、知识图谱等。
适用领域： 网络安全、电信反欺诈、金融风控、广告推荐、社交网络、智能问答等。

生态系统全景

 1+----------------------------------------------------------------------+
 2|              Apache HugeGraph - Full-Stack Graph System              |
 3+------------------+--------------------+------------------------------+
 4| Graph DB (OLTP)  | Graph Compute      | Graph AI                     |
 5| HugeGraph        | Vermeer (Memory)   | HugeGraph-AI                 |
 6| Server           | Computer (Dist.)   | GraphRAG / GNN / Py          |
 7+------------------+--------------------+------------------------------+
 8|                         HugeGraph Toolchain                          |
 9| Hubble | Loader | Client (Java/Go/Python; Rust WIP) | Spark | Tools  |
10| SeaTunnel 3.0+: Source + Sink                                        |
11+----------------------------------------------------------------------+

HugeGraph Server（OLTP 图引擎）

HugeGraph Server 是图数据库的 OLTP 引擎和服务入口，负责属性图建模、事务处理、查询执行和 API 接入。图数据实际保存在配置的 RocksDB、HStore 或 HBase 后端中。

• 属性图与 Schema：支持 VertexLabel、EdgeLabel、PropertyKey 和 IndexLabel 管理
• 查询语言：支持 Gremlin（TinkerPop 3）和 Cypher（OpenCypher）
• REST API：提供 Schema、图数据、查询、任务和运维接口
• 索引与查询：支持精确查询、范围查询和复合条件查询
• 存储后端：支持 RocksDB（单机推荐）、HStore（分布式推荐）和 HBase（Cassandra、MySQL、PostgreSQL 等历史后端已在 1.7.0 禁用并在 1.8.0 彻底移除）

主要模块包括 hugegraph-core、存储后端模块和 hugegraph-api。Core 实现图模型、事务和查询逻辑，后端模块负责连接具体存储系统，API 模块负责 HTTP 接入。当前 REST 资源路径包含图空间与图名称，例如：

1/graphspaces/{graphspace}/graphs/{graph}

单机部署通常使用 RocksDB。分布式部署使用 HStore，由 PD 管理集群元数据和分区调度，Store 保存图数据及其副本。HBase 可作为独立的后端存储。

• Server 快速上手
• PD 快速上手
• HStore 快速上手
• REST API

HugeGraph Toolchain

HugeGraph Toolchain 提供客户端、数据导入、可视化管理、Spark 集成和命令行运维工具，覆盖图应用从接入数据到日常管理的主要环节。

图计算引擎（OLAP）

HugeGraph-Computer 仓库提供两种互补的 OLAP 图计算引擎。通用图算法任务默认建议从 Vermeer 开始；需要 Java BSP/Pregel 计算模型时，可使用 Computer：

• Vermeer（默认入口）：使用 Go 编写，采用 master-worker 架构，以内存计算为主，提供 REST API、gRPC 和 Web UI，适合快速执行中小规模图分析任务。
• Computer：使用 Java 编写，实现 BSP/Pregel 分布式计算模型，可运行在 Kubernetes、YARN 或本地进程中。数据超过内存阈值时可以落盘，适合更大规模的图计算任务。

两者都可以读取 HugeGraph 数据，但运行架构、资源需求、配置和算法接口不同。

• Vermeer 快速上手
• Computer 快速上手

HugeGraph-AI（Graph + AI）

HugeGraph-AI 连接图技术与大语言模型、图机器学习框架。仓库使用 Python 3.10 或更高版本，并通过 uv 管理工作区，主要包含以下模块：

• hugegraph-llm：提供 GraphRAG、知识图谱构建、自然语言查询和 Text2Gremlin
• hugegraph-ml：提供节点分类、图分类、图嵌入、链接预测和欺诈检测等模型
• hugegraph-python-client：通过 Python 管理 Schema、图数据和 Gremlin 查询
• vermeer-python-client：通过 Python 调用 Vermeer 图计算服务

HugeGraph-AI 快速上手

部署模式

图计算属于 OLAP 任务，容量和资源需求取决于所选引擎、图结构与算法，不沿用上表的 OLTP 存储容量口径。

选择入口

社区

• GitHub Issues
• 开发者邮件列表：dev@hugegraph.apache.org
• 邮件列表订阅方法
• 安全问题：security@hugegraph.apache.org
• 微信公众号：Apache HugeGraph

2 - 下载 Apache HugeGraph

指南:

• 推荐使用已发布的软件包。Server 1.7.0 建议使用 Java 11，其他 JDK 的支持范围见 Server 启动指南；Toolchain、AI、Vermeer 等组件的运行环境请按各自版本的快速入门核对。
• 验证下载版本, 请使用相应的哈希 (SHA512)、签名和 项目签名验证 KEYS
• 检查哈希 (SHA512)、签名的说明在 版本验证 页面, 也可参考 ASF 验证说明
• 注: HugeGraph 所有组件版本号已保持一致, client/loader/hubble/common 等 maven 仓库版本号同理, 依赖引用可参考 maven 示例
• 兼容说明: HugeGraph 于 2026 年 1 月毕业后，下载路径已从 /incubator/hugegraph 迁移到 /hugegraph。历史版本的发布文件名可能仍包含 -incubating-。
• 从源码构建请参考 编译构建说明

文件名中的 src 表示源码包，需要按对应组件的指南编译，不能直接按二进制包的目录执行启动脚本。源码主线可能包含尚未发布的配置和接口；使用下表中的发布包或指定版本的容器镜像时，应核对文档里的适用版本说明。

最新版本

源码归档是 Apache 软件基金会的正式发布物；二进制软件包是基于源码构建的便利用品。所有文件均通过 ASF 镜像分发，签名与校验和托管在 downloads.apache.org。GitHub 自动生成的源码归档不是 ASF 正式发布版本。

归档版本

注:

1. 请大家尽早迁移到最新 Release 版本上, 社区将不再维护 1.0.0 前的旧版本 (非 ASF 版本)
2. 1.3.0 是最后一个兼容 Java8 的主版本, 请尽早使用/迁移运行时为 Java11 (低版本 Java 有潜在更多的 SEC 风险和性能影响)
3. 从版本 1.5.0 开始，需要 Java11 运行时环境

3 - 快速上手

根据需要选择 Server、Toolchain、图计算或 HugeGraph-AI 的快速上手文档。各组件独立发布，安装前请核对对应仓库的运行环境和版本。

3.1 - HugeGraph (OLTP)

本目录包含 HugeGraph Server 单机快速上手，以及分布式部署所需的 PD 和 Store 入门文档。

DeepWiki 项目概览；涉及安装、配置和运行行为时，请以对应版本的 HugeGraph 文档及代码为准。

首次使用可从 Server 单机快速上手 开始。该页将 ASF 已发布的 1.7.0 下载包与 master 源码构建分开说明。若使用 HStore 分布式存储，还需配置 PD 和 Store。

GitHub 访问： https://github.com/apache/hugegraph

3.1.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 表示整个项目或主仓库，hugegraph-server 表示仓库中的 Server 模块，HugeGraphServer 是服务进程的 Java 类名。下文的 Server 服务指运行中的图数据库服务。

flowchart TD
    A{选择安装来源}
    A -->|已发布版本| R["HugeGraph 1.7.0 tar 包"]
    R --> V[SHA-512 校验]
    V --> X[解压并使用随包配置]
    A -->|开发主线| M["master 源码"]
    M --> B["mvn package -DskipTests"]
    B --> C[确认 conf/graphs 中的 RocksDB 配置]
    C --> I[bin/init-store.sh]
    I --> S["bin/start-hugegraph.sh -p true"]
    S --> Q["请求 /versions 和图顶点接口"]

主仓库模块概览使用短名称；server、core、api、dist、pd 和 store 对应带 hugegraph- 前缀的模块。上方保留功能说明，dist 负责发行打包。

---
markmap:
  spacingHorizontal: 40
---
# HugeGraph
## server
- core
- api
- dist
## pd
## store

2 依赖

2.1 安装 Java 17 (JDK 17)

从 HugeGraph 1.8.0 开始使用 Java 17；1.7.0 是最后一个支持 Java 11 的版本。 所有模块的源码构建要求 JDK 17 和 Maven 3.6.3 或更高版本，Server、PD 和 Store 的运行环境统一使用 JDK 17。 Server 安全检查（-s true）要求 Java 17 到 23 以及可读的 conf/java-security.properties；在 Java 24 或更高版本上，需以 -s false 启动 Server（JDK 24 通过 JEP 486 移除了 Security Manager）。

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

1# 随包 Driver 与 Console 默认采用 GraphBinary V1
2# - Schema 结果为标准 Map
3# - Blob 值以二进制格式传输（包含在返回图元素内的 Blob）
4serializer:
5  className: org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1
6  config:
7    builder: org.apache.hugegraph.io.HugeGraphTypeSerializerRegistryBuilder
8    ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]

1# 默认 HTTP JSON 采用 untyped GraphSON V1
2# - 保留 Tree 的旧 key/value 数组结构
3# - Typed GraphSON V1 因安全原因已禁用（typed V2/V3 仅适用于受支持的简单标量与 ID）
4# - graph.schema() 返回包含各类 label 的 Map

3 部署

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

• Docker 容器 用于测试或开发，快速启动 Server 服务。
• ASF 发布包 下载已发布的 tar 包，校验后安装。
• master 源码 构建开发主线，产物不等同于 ASF 发布包。
• 旧版一键部署工具（已过时） 仅供了解旧版部署方式。

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

完整容器部署指引请参考 Docker 部署方式。

快速启动使用 RocksDB 单机后端的 Server 容器：

1docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph:1.7.0

1# 启动时自动预加载内置样例图（marko / lop 等数据）
2docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0

1# 开启鉴权模式并设置内置 admin 初始密码
2docker run -itd --name=server -p 8080:8080 -e PASSWORD="replace-with-your-password" hugegraph/hugegraph:1.7.0

常用容器操作：

• 进入容器终端：docker exec -it server bash
• 查看启动日志：docker logs -f server
• 验证服务可用性：curl -fsS http://127.0.0.1:8080/versions

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

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

1cd hugegraph/docker
2# 注意版本号请随时保持更新 → 1.x.0
3HUGEGRAPH_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 单独选择。

单机 docker-compose.yml 示例使用 HugeGraph 1.7.0 版本镜像 hugegraph/hugegraph:1.7.0；该文件引用的 docker/conf/hubble/standalone.properties 已随源码提供。Compose 文件从 HUGEGRAPH_ADMIN_PASSWORD 读取管理员密码，从 HUGEGRAPH_AUTH_TOKEN_SECRET 读取 JWT 密钥，通常放在 docker/.env 文件中。HUGEGRAPH_ADMIN_PASSWORD 非空即开启鉴权，Hubble 会自动识别该模式。若直接使用 docker run，则改为传入 -e PASSWORD=xxx。HStore Compose 文件属于当前主线，不能与 1.7.0 的 PD/Store/Server 发布镜像混用，见下文。

JWT 密钥的版本差异：当前主线构建的 Server 镜像会把 HUGEGRAPH_AUTH_TOKEN_SECRET 映射到 HG_SERVER_AUTH_TOKEN_SECRET，并写入 Server 启动配置；跨重建时应在 .env 中保留同一密钥。1.7.0 镜像的 Docker 入口脚本只处理 PASSWORD 等旧变量，不会读取 HG_SERVER_AUTH_TOKEN_SECRET。如需在 1.7.0 中固定 JWT 密钥，须将 auth.token_secret 持久写入该版本的 conf/graphs/hugegraph.properties；若保留默认随机密钥，不应假定已有 JWT 在 Server 重启后仍有效。

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

使用 PD 的 Server 服务标识

对于使用 PD 的 Server，Helm chart 提供 server.serviceId 和 server.graphSpace 配置项。 二者默认为 DEFAULT，此时保留 conf/rest-server.properties 中已有的 server.service_id 和 server.graphspace。 非默认值会向 Server 容器注入 HG_SERVER_SERVICE_ID 或 HG_SERVER_GRAPHSPACE。 注意：这些服务身份相关的 Chart 配置项（server.serviceId、server.graphSpace 和 server.testGraphAlias）适用于开发中的 1.8.0+ 版本镜像与 Chart； 目前尚无已发布的 Chart 或镜像支持这些选项。不要将本示例与未支持该特性的旧版本搭配使用。 通过 HG_SERVER_SERVICE_ID、SERVICE_ID 或 server.serviceId 传入的非空服务 ID 仅支持可打印 ASCII，包含空格和反斜杠； 部署校验会拒绝非 ASCII 和控制字符。此限制仅针对这些配置入口，不改变 Core Service 名称协议和已有的手工 properties 配置。 Helm 会将 server.serviceId 中的美元符号（包括 $(POD_IP)）按字面量保留，不展开 Kubernetes 环境变量引用。 重读服务元数据或清理图空间时，会保留完整的服务 ID，包括其中的 / 和 -。 使用上述 chart values 设置身份；Server 的 extraEnv 会保留对应的新旧身份变量名，禁止重复覆盖。 HG_SERVER_GRAPHSPACE、生效的旧变量 GRAPH_SPACE 和 server.graphSpace 遵循同一规则： 接受 DEFAULT，或以小写字母开头、最多 48 位的小写字母、数字和下划线组成的已有空间名称：

1helm upgrade --install hg ./helm/hugegraph \
2  --set-string server.serviceId=analytics \
3  --set-string server.graphSpace=team_a

部署分配到 team_a 的 Server 前，先通过现有 DEFAULT 空间的 Server，用具有创建图空间权限的账号创建该空间。 chart 和这些环境变量不会自动创建图空间；同一个 Server Deployment 的所有副本使用相同服务标识。

用 helm test 检查该空间中的图前，先创建目标图，再将 --set-string server.testGraphAlias=team_a-demo 设置为它实际的 Gremlin 绑定。 创建图空间不会自动创建 hugegraph 图。

容器部署中的 HG_SERVER_SERVICE_ID 和 HG_SERVER_GRAPHSPACE 写入上述两个配置项。 旧名称 SERVICE_ID 和 GRAPH_SPACE 仍可使用；非空的新变量优先于对应旧变量。 同一配置项的新旧变量均未设置或为空时，保留已有值。Compose 不会自动传入宿主机上的这些变量， 需要在 Compose override 的 Server environment: 中显式添加。详见 Helm chart 配置说明。

这些设置选择 Server 在 PD 中的服务元数据，不会搬迁已有图，也不会修改未指定图空间的 REST 路径所用的 server.path_graphspace。 请求使用 /graphspaces/team_a/... 路径，并在 Hubble 中选择匹配的图空间和服务；开启鉴权时，显式指定路径仍须获得授权。

server.testGraphAlias 默认为 DEFAULT-hugegraph。hook 会逐个 Server Pod 检查这一已有本地图绑定，不会从 server.graphSpace 自动派生别名。 别名的大小写须与实际绑定一致：本地 Demo.properties 可以绑定为 DEFAULT-Demo；通过 REST 创建的图使用小写名称。 本地图绑定可以独立于 Server 在 PD 中分配的图空间存在，因此默认 hook 成功不能证明 team_a 中的图可查询。 出现 Could not rebind 时，先确认目标图存在且别名正确；重启 Pod 不能创建缺失的图或纠正别名。

配置渲染和入口脚本检查不能单独证明 Linux 上的非默认服务发现、鉴权或跨图空间隔离已通过验收。

3.2 下载已发布的 tar 包

以下示例针对 HugeGraph 1.7.0。使用其他版本时，请先在 ASF 下载目录 确认该版本及对应文件名；不要把 master 源码构建包当作已发布的二进制包。

1cd /path/to/downloads
2wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz.sha512
4sha512sum -c apache-hugegraph-incubating-1.7.0.tar.gz.sha512
5tar zxf apache-hugegraph-incubating-1.7.0.tar.gz

SHA-512 校验通过后再解压。也可按 Apache 发布流程验证 PGP 签名：

1wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz.asc
2wget https://downloads.apache.org/hugegraph/KEYS
3gpg --import KEYS
4gpg --verify apache-hugegraph-incubating-1.7.0.tar.gz.asc apache-hugegraph-incubating-1.7.0.tar.gz

只应信任通过 Apache 项目渠道核实的发布者密钥；签名验证可与 SHA-512 校验一起使用。

3.3 从 master 源码构建

下面的命令构建的是开发主线，不是 1.7.0 发布包。

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

下载 HugeGraph 源代码

1git clone --branch master https://github.com/apache/hugegraph.git

编译打包生成 tar 包

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

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

1[INFO] BUILD SUCCESS

执行成功后，根目录 target/ 下会生成主线聚合包（当前仓库版本属性为 1.8.0）：

1target/apache-hugegraph-1.8.0.tar.gz

该文件名中的版本号来自源码的 revision 属性；它不会把主线构建变成 ASF 发布物料。构建过程还会在仓库根目录生成 apache-hugegraph-1.8.0/ 聚合目录，其中的 Server 子目录名由 Server 模块的 final.name 决定，例如当前为 apache-hugegraph-server-1.8.0。若只保留了 tar 包，则先执行 tar zxf target/apache-hugegraph-1.8.0.tar.gz 再进入该目录。

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

1mvn package -DskipTests -ntp -Drocksdb-only

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

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

4 配置

Server 的 tar 包随包提供 conf/rest-server.properties、conf/gremlin-server.yaml 和 conf/graphs/hugegraph.properties；源码构建包从 hugegraph-server/hugegraph-dist/src/assembly/static/conf/ 装配这些文件。解压后在 Server 安装目录内编辑配置，无需另行生成。发行包版本之间可能有默认值差异，下面涉及的默认值和启动行为按 master 主线说明。

单机 RocksDB 快速上手只需确认 conf/graphs/hugegraph.properties 使用 backend=rocksdb、serializer=binary。正常 Server 初始化会扫描 conf/graphs/ 并加载本地图配置，无需额外设置 graph.load_from_local_config=true。该选项默认 false，控制构造阶段的提前加载。图配置变化通过重启 Server 应用，不使用热重载进行维护。

详细的配置介绍请参考配置文档及配置项介绍。

5 启动

5.1 使用启动脚本启动

启动流程分为首次启动和非首次启动两种情况。首次启动前需要先初始化后端数据库，然后再启动服务。

如果服务曾被手动停止，或因其他原因需要再次启动，由于后端数据库已持久化存在，通常可以直接启动服务。

HugeGraphServer 启动时会连接后端存储并检查其版本信息。如果后端尚未初始化，或者已初始化但版本不匹配（例如存在旧版本数据），HugeGraphServer 会启动失败并给出错误信息。

如果需要外部访问 HugeGraphServer，请修改 rest-server.properties 的 restserver.url 配置项（默认为 http://127.0.0.1:8080），修改成机器名或 IP 地址。

由于各种后端所需的配置（hugegraph.properties）及启动步骤略有不同，下面逐一对各后端的配置及启动做介绍。

5.1.1 分布式存储 (HStore)

要使用分布式存储引擎，需要先部署 HugeGraph-PD 和 HugeGraph-Store，详见 HugeGraph-PD 快速入门 和 HugeGraph-Store 快速入门。

1backend=hstore
2serializer=binary
3
4# PD 服务地址，多个 PD 地址用逗号分割，配置 PD 的 RPC 端口
5pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688
6pd.cluster=hg

 1# 简单示例（带鉴权）
 2gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy
 3
 4# 指定存储 hstore（必须）
 5backend=hstore
 6serializer=binary
 7store=hugegraph
 8
 9# pd config
10pd.peers=127.0.0.1:8686
11pd.cluster=hg

1usePD=true
2# 本例与图配置的 pd.cluster 共用集群名 hg
3cluster=hg
4# 配置 Server 进程连接的 PD 地址；替换为实际 PD RPC 地址
5pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688
6
7# 本地测试可按需启用；生产环境必须启用鉴权
8# auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator

 1usePD=true
 2restserver.url=http://127.0.0.1:8081
 3gremlinserver.url=http://127.0.0.1:8181
 4pd.peers=127.0.0.1:8686
 5
 6rpc.server_host=127.0.0.1
 7rpc.server_port=8091
 8
 9server.id=server-1
10server.role=master

 1usePD=true
 2restserver.url=http://127.0.0.1:8082
 3gremlinserver.url=http://127.0.0.1:8182
 4pd.peers=127.0.0.1:8686
 5
 6rpc.server_host=127.0.0.1
 7rpc.server_port=8092
 8
 9server.id=server-2
10server.role=worker

1host: 127.0.0.1
2port: 8181

1host: 127.0.0.1
2port: 8182

1bin/start-hugegraph.sh

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

1bin/stop-hugegraph.sh

1# 在 hugegraph 仓库根目录执行
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 .
5
6cd docker

 1(
 2  set -eu
 3  command -v openssl >/dev/null
 4  jwt_secret="$(openssl rand -hex 32)"
 5  pd_secret="$(openssl rand -hex 24)"
 6  umask 077
 7  test ! -e .env || {
 8    echo ".env already exists; edit it instead of overwriting it" >&2
 9    exit 1
10  }
11  printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\nHUGEGRAPH_AUTH_TOKEN_SECRET='%s'\nHG_PD_AUTH_SECRET_KEY='%s'\n" \
12    'replace-with-your-password' "${jwt_secret}" "${pd_secret}" > .env
13  HG_PD_AUTH_SECRET_KEY="${pd_secret}" ./set-hubble-pd-password.sh hstore
14  HG_PD_AUTH_SECRET_KEY="${pd_secret}" ./set-hubble-pd-password.sh hstore-ha
15)

1set -a
2. ./.env
3set +a
4HUGEGRAPH_VERSION=local docker compose \
5  -f docker-compose-3pd-3store-3server.yml \
6  up -d --wait pd0 pd1 pd2 store0 store1 store2 server0 server1 server2 hubble

1curl -fsS http://localhost:8080/versions
2curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?请先加载 .env}" \
3  http://localhost:8620/v1/stores

5.1.2 RocksDB / ToplingDB

从 master 构建的单机最小流程如下。此例启用内置样例数据，以便后续请求能验证图数据读写路径。

1. 检查 Java 环境，确认满足主线构建要求。
2. 构建 master 源码；下方命令使用该构建包中的 Server 子目录。
3. 确认 RocksDB 配置，再进入构建产物中的 Server 子目录。
4. 初始化存储，然后启动服务并加载样例图，命令见下方。
5. 请求 /versions 和样例图顶点接口，检查实际返回内容。

主线包内的 conf/graphs/hugegraph.properties 默认已设置 backend=rocksdb 和 serializer=binary。使用默认数据目录时无需修改；若改过后端或数据路径，先确认配置，再初始化存储。

初始化数据库（首次启动，或在 conf/graphs/ 下添加了新图配置后）：

1# 进入解压或构建出的 Server 根目录
2cd apache-hugegraph-*/apache-hugegraph-server-*
3bin/init-store.sh

启动 Server 并加载内置样例图：

1bin/start-hugegraph.sh -p true

启动脚本会按 rest-server.properties 中的 restserver.url 轮询 /graphs，超时或进程失败时以非零状态退出。随后先检查服务版本，再读取样例顶点：

1curl -fsS http://127.0.0.1:8080/versions
2curl --compressed -fsS \
3  http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices

第一条请求应返回包含 versions 的 JSON；第二条应返回包含 vertices 的 JSON，且样例数据中可见 marko、lop 等顶点。仅检查进程存在或 HTTP 状态码，不足以证明图后端和业务请求正常。

ToplingDB (Beta): 作为 RocksDB 的高性能替代方案，配置方式请参考: ToplingDB 快速上手

5.1.3 HBase

 1backend=hbase
 2serializer=hbase
 3
 4# hbase backend config
 5hbase.hosts=localhost
 6hbase.port=2181
 7# Note: recommend to modify the HBase partition number by the actual/env data amount & RS amount before init store
 8# it may influence the loading speed a lot
 9#hbase.enable_partition=true
10#hbase.vertex_partitions=10
11#hbase.edge_partitions=30

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

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

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

在启动脚本时携带 -p true 参数，表示开启 preload，即创建示例图。

1bin/start-hugegraph.sh -p true
2Starting HugeGraphServer in daemon mode...
3Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK

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

1> curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices" | gunzip
2
3{"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 监控任务。

bin/hugegraph-server.sh 会把 -XX:+HeapDumpOnOutOfMemoryError、-XX:HeapDumpPath 和 -XX:ErrorFile 放在 JAVA_TOOL_OPTIONS 的最前面。因此无论是否设置了 JAVA_OPTIONS（下文所述的例外情况除外），内存溢出时的堆转储（heapdump_<主机名>_<启动时间>/java_pid<pid>.hprof）和 JVM 崩溃日志（hs_err_pid<pid>_<主机名>_<启动时间>.log）都会写入 logs/，其中 <启动时间> 为本地时间，格式是 YYYYMMDD-HHMMSS。每次启动都有自己的 heapdump_* 目录，因此服务及其启动的 JVM（例如 computer 任务）会分别写入各自的转储（HotSpot 按 JVM 的 PID 命名转储文件和崩溃日志，因此同一次启动中复用了先前 PID 的 JVM 无法写入它的转储，它的崩溃日志也会覆盖先前那个 JVM 的）。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（<启动时间>-1、-2……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为尽力写入 logs/ 本身；磁盘已满时可能也没有空间写入转储。堆转储可能和堆一样大。启动脚本从不删除转储或 heapdump_* 目录：每次启动到 Java 阶段都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM 都已退出后，可以移走或删除旧目录，但不要动正在运行的服务最新的那个目录；没有它，下一次转储会被写成一个同名文件。JVM 会在这些默认值之后读取你自己的 JAVA_TOOL_OPTIONS、JDK_JAVA_OPTIONS（包括 @argfile）、命令行（JAVA_OPTIONS；未设置或为空时为 -j）和 _JAVA_OPTIONS，因此在其中任意一处为上述参数指定的值都会覆盖默认值。只有环境变量会传给服务启动的 JVM：要对所有 JVM 关闭堆转储，请设置 JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError；通过 -j 或 JAVA_OPTIONS 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动到 Java 阶段仍会创建空的 heapdump_* 目录，除非创建失败而改为写入 logs/。如果日志路径中包含双引号或 %，启动脚本会给出警告，堆转储直接写入 logs/，不使用每次启动的目录，也不设置崩溃日志的默认值；通过 JAVA_TOOL_OPTIONS 关闭堆转储的方式仍然有效。同时包含两种引号的路径则完全不设置堆转储默认值。由于设置了这些默认值，JVM 启动时会在 stderr 输出 Picked up JAVA_TOOL_OPTIONS: ...。

版本范围：以上行为适用于当前开发分支/master 分支。1.7.0 只在未设置 JAVA_OPTIONS 时添加堆转储参数，堆转储直接写入 logs/java_pid<pid>.hprof，JVM 崩溃日志写入安装目录。

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 脚本改变预加载的数据。

    1version: '3'
    2services:
    3  server:
    4    image: hugegraph/hugegraph:1.7.0
    5    container_name: server
    6    environment:
    7      - PRELOAD=true
    8      - PASSWORD=xxx
    9    volumes:
   10      - /path/to/yourscript:/hugegraph-server/scripts/example.groovy
   11    ports:
   12      - 8080:8080

   基于当前 master 构建的 Server 镜像以非 root 的 UID 10001 运行，挂载的脚本必须对该用户可读。

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

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

1> curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices" | gunzip
2
3{"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 查看服务进程

1jps
26475 HugeGraphServer

curl 请求 RESTful API

1curl -fsS http://127.0.0.1:8080/versions

返回包含 versions 的 JSON（HTTP 2xx）可确认 REST API 已响应。jps 中出现 HugeGraphServer 只表示进程存在；要确认图后端可用，请按单机流程加载样例图后请求顶点接口。

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 的顶点及相关属性

1curl http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices

说明

1. 对于顶点、边等列表请求，Server 可以压缩响应。使用 curl --compressed 可自动解压：

   1curl --compressed -fsS "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices"

2. 默认监听地址为 127.0.0.1，其他机器无法直接访问。

1vim conf/rest-server.properties
2
3restserver.url=http://0.0.0.0:8080

响应体如下：

 1{
 2    "vertices": [
 3        {
 4            "id": "2lop",
 5            "label": "software",
 6            "type": "vertex",
 7            "properties": {
 8                "price": [
 9                    {
10                        "id": "price",
11                        "value": 328
12                    }
13                ],
14                "name": [
15                    {
16                        "id": "name",
17                        "value": "lop"
18                    }
19                ],
20                "lang": [
21                    {
22                        "id": "lang",
23                        "value": "java"
24                    }
25                ]
26            }
27        },
28        {
29            "id": "1josh",
30            "label": "person",
31            "type": "vertex",
32            "properties": {
33                "name": [
34                    {
35                        "id": "name",
36                        "value": "josh"
37                    }
38                ],
39                "age": [
40                    {
41                        "id": "age",
42                        "value": 32
43                    }
44                ]
45            }
46        },
47        ...
48    ]
49}

详细的 API 请参考 RESTful-API 文档。

另外也可以通过访问 localhost:8080/swagger-ui/index.html 查看 API。

在使用 Swagger UI 调试 HugeGraph 提供的 API 时，如果 HugeGraph Server 开启了鉴权模式，可以在 Swagger 页面输入鉴权信息。

当前 HugeGraph 支持基于 Basic 和 Bearer 两种形式设置鉴权信息。

7 停止 Server

1# 在 Server 根目录下执行
2bin/stop-hugegraph.sh

8 使用 IntelliJ IDEA 调试 Server

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

3.1.2 - HugeGraph-PD 快速上手

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 版本：HugeGraph 1.8.0+ 使用 Java 17（Maven 源码构建仅接受 JDK 17；启动脚本拒绝低于 17 的运行时；1.7.0 是最后一个支持 Java 11 的版本）
• Maven 版本：≥ 3.6.3（从源码编译时）

3 部署

HugeGraph-PD 组件主要支持以下部署与运行方式：

• 下载发布包 — 下载并解压官方发布的完整二进制安装包。
• 源码编译 — 基于 master 主线代码使用 Maven 与 Java 17 编译 PD 模块。
• Docker 部署 — 使用容器快速体验或搭建分布式集群。

3.1 下载 tar 包

Apache 下载页目前提供 1.7.0 的完整二进制包，其中包含 PD、Store 和 Server；没有单独列出 PD 二进制包。下载前请在 官方 Apache HugeGraph 下载页核对版本、签名和 SHA512。1.7.0 是孵化期发布的历史版本，归档文件和解压目录仍带 incubating：

1# 1.7.0 是项目孵化期发布的历史版本，因此文件名和目录名仍带 incubating
2curl -fLO --connect-timeout 10 --max-time 1800 https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3tar zxf apache-hugegraph-incubating-1.7.0.tar.gz
4cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-pd-incubating-1.7.0

3.2 源码编译

1. 克隆源代码仓库：

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

2. 编译 PD 模块：

   1# 仅编译 PD 发行包及其依赖模块
   2mvn clean package -pl hugegraph-pd/hg-pd-dist -am -DskipTests

3. 检查编译产物：

   1cd hugegraph-pd/apache-hugegraph-pd-*/
   2ls -la bin conf lib

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

3.3 Docker 部署

HG_PD_* 环境变量和 /v1/ready 是当前主线源码提供的功能；server 的 1.7.0 发布源码标签尚无这些 Docker 环境变量映射或 readiness API。本文下面的 Docker 示例仅适用于从当前主线源码构建并标记为 local 的镜像；使用 1.7.0 发布资产时，应以该版本随包配置和说明为准：

1# 在 hugegraph 仓库根目录执行
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .

单独运行当前主线构建的 PD 时，先设置部署专用密钥，并把示例地址替换为容器可达的真实地址：

下面的 mkdir -p 和非递归 chown 仅适用于新建空目录。复用旧 root 镜像写入的数据时，先停止 PD， 执行一次 sudo chown -R 10001:10001 /path/to/data，再启动 UID 10001 镜像。

 1export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
 2# master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写
 3mkdir -p /path/to/data && sudo chown 10001:10001 /path/to/data
 4docker run -d \
 5  -p 8620:8620 -p 8686:8686 -p 8610:8610 \
 6  -e HG_PD_GRPC_HOST=192.168.1.10 \
 7  -e HG_PD_RAFT_ADDRESS=192.168.1.10:8610 \
 8  -e HG_PD_RAFT_PEERS_LIST=192.168.1.10:8610 \
 9  -e HG_PD_INITIAL_STORE_LIST=192.168.1.20:8500 \
10  -e HG_PD_AUTH_SECRET_KEY="$HG_PD_AUTH_SECRET_KEY" \
11  -v /path/to/data:/hugegraph-pd/pd_data \
12  --name hugegraph-pd \
13  hugegraph/pd:local

当前主线 entrypoint 要求以上五个必填变量，生成 SPRING_APPLICATION_JSON 覆盖项后再启动 PD；其他配置继续从镜像内的 conf/application.yml 读取。JAVA_OPTS 会透传给 JVM。旧变量 GRPC_HOST、RAFT_ADDRESS、RAFT_PEERS、PD_INITIAL_STORE_LIST 仍可用，但会输出弃用警告。

PD 镜像的 Docker HEALTHCHECK 每 15 秒检查 /v1/health，它只表示 REST 监听器有响应，不代表 Raft 已形成多数派。Compose 示例中的健康检查也使用这个存活接口；需要在启动 Store 前另行检查 /v1/ready。容器以前台方式运行，Java 退出会让容器退出；只有配置了 Docker 重启策略时容器才会自动重启。Docker 日志可通过 docker logs <container-name> 查看。

当前主线 Compose 的完整启动和最小拓扑见 Store 页面及 docker/README.md。Compose 文件的服务配置来自主线源码；若启动包含 Hubble 的完整拓扑，先按 docker/README.md 生成未跟踪的 Hubble 配置文件。

4 配置

PD 启动脚本读取安装目录中的 conf/application.yml。请使用与安装包版本相同的源文件，不要把发布版和主线配置混用： 1.7.0 发布标签配置；当前主线配置。主线 application.yml 将 auth.secret-key 留空，REST 受保护接口在未设置密钥时会拒绝请求；application.yml.template 不由 PD 启动脚本读取。

4.1 配置项参考

以下表格列出主线配置及代码默认值，Raft 超时设置可参阅 PDConfig 实现。1.7.0 二进制包请使用对应标签的原始配置；主线源码构建包则以 主线配置文件 为准。下文会单独说明与 1.7.0 的差异。

gRPC 与 REST

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

Raft

raft.rpc-connect-timeout 和 raft.rpc-install-snapshot-timeout 仅在 1.7.0 之后的版本中提供。1.7.0 中 raft.rpc-timeout 同时也是连接超时和安装快照超时，id 分配也不等待 ReadIndex。

PD 核心

Store 管理

分区

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

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

服务发现、License 与监控

线程池

4.2 单节点配置

在主线源码构建的发布目录中，以 conf/application.yml 为基础，只需按节点改写 gRPC/Raft 地址和数据路径，并设置 auth.secret-key。以下值仅适用于开发测试；单节点 PD 不提供多数派容错，partition.default-shard-count: 1 表示每个分区只有一个副本。

 1grpc:
 2  host: 127.0.0.1
 3  port: 8686
 4server:
 5  port: 8620
 6raft:
 7  address: 127.0.0.1:8610
 8  peers-list: 127.0.0.1:8610
 9pd:
10  data-path: ./pd_data
11  initial-store-count: 1
12  initial-store-list: 127.0.0.1:8500
13partition:
14  default-shard-count: 1
15auth:
16  secret-key: 替换为部署专用密钥

可以用 openssl rand -hex 24 生成部署密钥；使用 Docker 时通过 HG_PD_AUTH_SECRET_KEY 传入。1.7.0 发布标签的认证行为不同，详见“REST API 认证”。

4.3 三节点集群配置

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

节点 1（192.168.1.10）：

 1grpc:
 2  host: 192.168.1.10
 3  port: 8686
 4server:
 5  port: 8620
 6raft:
 7  address: 192.168.1.10:8610
 8  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
 9pd:
10  data-path: /data/pd
11  initial-store-count: 3
12  initial-store-list: 192.168.1.20:8500,192.168.1.21:8500,192.168.1.22:8500
13partition:
14  default-shard-count: 3

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

 1# 节点 2
 2grpc:
 3  host: 192.168.1.11
 4raft:
 5  address: 192.168.1.11:8610
 6  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
 7
 8# 节点 3
 9grpc:
10  host: 192.168.1.12
11raft:
12  address: 192.168.1.12:8610
13  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 地址：

 1# 所有 PD 节点共用同一个密钥，实际部署从私密环境变量注入
 2HG_PD_AUTH_SECRET_KEY: ${HG_PD_AUTH_SECRET_KEY:?set HG_PD_AUTH_SECRET_KEY}
 3
 4# pd0
 5HG_PD_GRPC_HOST: pd0
 6HG_PD_RAFT_ADDRESS: pd0:8610
 7HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
 8HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
 9HG_PD_INITIAL_STORE_COUNT: 3
10
11# pd1
12HG_PD_GRPC_HOST: pd1
13HG_PD_RAFT_ADDRESS: pd1:8610
14HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
15
16# pd2
17HG_PD_GRPC_HOST: pd2
18HG_PD_RAFT_ADDRESS: pd2:8610
19HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610

5 启动与停止

5.1 启动 PD

在 PD 安装目录下执行：

1./bin/start-hugegraph-pd.sh

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

下文的生命周期说明适用于当前主线构建；上文下载的 1.7.0 启动脚本不包含这些修复。 支持的参数如下，GC 的版本限制见下文：

master 构建接受 g1、G1、zgc 和 ZGC。 上文下载的 1.7.0 启动脚本仅接受显式指定 zgc 或 ZGC；-g g1、-g G1 和其他参数会中止启动。 默认路径请省略 -g；参数被拒绝时，查看 logs/hugegraph-pd-stdout.log。

-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 中看到类似以下的日志：

1YYYY-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 安装目录下执行：

1./bin/stop-hugegraph-pd.sh

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

6 分布式集群的启动顺序

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

1. 全部 PD 节点。它们组成 Raft 组并选出 leader。对每个节点检查 GET /v1/ready；仅当 HTTP 状态为 200 且响应中的 ready 为 true 时，再启动 Store。GET /v1/health 只检查 REST 监听器是否存活。
2. 全部 Store 节点。每个 Store 通过 gRPC 向 PD 注册，PD 会自动激活 pd.initial-store-list 中列出的 Store。等到 GET /v1/stores 中每个 Store 的 state 都是 Up 再继续。
3. 全部 Server 节点。Server 读取 pd.peers，并依赖 PD 报告至少有一个存活的 Store 才能完成分区分配。

sequenceDiagram
    participant 运维者
    participant PD
    participant Store
    participant Server
    运维者->>PD: GET /v1/ready（逐个检查 PD）
    PD-->>运维者: 200 且 ready=true
    运维者->>Store: 启动 Store
    Store->>PD: gRPC 注册与心跳
    运维者->>PD: GET /v1/stores（Basic 认证）
    PD-->>运维者: 每个目标 Store 状态为 Up
    运维者->>Server: 启动 Server
    Server->>PD: gRPC 查询分区与服务发现
    Server->>Store: gRPC 访问图数据

主线 Compose 中 Store 的 depends_on: condition: service_healthy 只等待 PD /v1/health 存活检查，Server 同样只等待 Store REST 存活检查；Server entrypoint 还会轮询 PD /v1/stores，直到有 Store 报告 Up 才启动 HugeGraph。docker compose up --wait 因而不能替代 PD Raft 就绪与 Store 注册状态检查。

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

7 验证

7.1 REST API 认证

当前主线除 /actuator/*、/v1/health、/v1/ready 和 /v1/prom/targets/* 之外，所有 PD REST 路径都要求 HTTP Basic Authorization。用户名必须是内部服务名 hg、store、hubble、vermeer 之一，密码必须等于 auth.secret-key；无密钥或密码不匹配时会返回 HTTP 401。用启动 PD 时的同一密钥检查 Store 列表：

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

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?请先设置 PD 部署密钥}" \
2  http://localhost:8620/v1/stores

bin/wait-storage.sh 通过 PD_AUTH_USER、PD_AUTH_PASSWORD 配置同一凭据。1.7.0 发布标签的认证实现只检查用户名是否属于内部服务名，不比较密码；不要把该旧版行为套用到当前主线源码构建包。

7.2 健康检查

GET /v1/health 不需要凭据，返回 200 且响应体为空，只表示 PD REST 监听器已启动：

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

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

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

/actuator/health 的 {"status":"UP"} 也不代表 PD Raft 集群已有可用 leader。主线新增的 GET /v1/ready 会在 PD Raft 节点已激活并能看到 leader 时返回 HTTP 200 和 ready:true；尚未就绪时返回 HTTP 503 和 ready:false：

1curl -i http://localhost:8620/v1/ready

7.3 集群与成员状态

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

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?请先设置 PD 部署密钥}" \
2  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 节点状态：

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?请先设置 PD 部署密钥}" \
2  http://localhost:8620/v1/stores

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

 1{
 2  "message": "OK",
 3  "data": {
 4    "stores": [
 5      {
 6        "storeId": 8319292642220586694,
 7        "address": "127.0.0.1:8500",
 8        "raftAddress": "127.0.0.1:8510",
 9        "version": "",
10        "state": "Up",
11        "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",
12        "dataPath": "./storage",
13        "startTimeStamp": 1754027127969,
14        "registedTimeStamp": 1754027127969,
15        "lastHeartBeat": 1754027909444,
16        "capacity": 494384795648,
17        "available": 346535829504,
18        "partitionCount": 0,
19        "graphSize": 0,
20        "keyCount": 0,
21        "leaderCount": 0,
22        "serviceName": "127.0.0.1:8500-store",
23        "serviceVersion": "",
24        "serviceCreatedTimeStamp": 1754027127000,
25        "partitions": []
26      }
27    ],
28    "stateCountMap": {
29      "Up": 1
30    },
31    "numOfService": 1,
32    "numOfNormalService": 1
33  },
34  "status": 0
35}

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，在存在图之后还会有按图统计的分区和大小指标。

同时暴露用于监控 Raft 法定人数（Quorum）状态及告警的成员指标：

• hg_raft_leader：当前 PD 节点若为选出的 Raft Leader 则为 1，Follower 节点为 0。
• hg_raft_has_leader：当前 PD 节点若能看到活跃的 Raft Leader（即属于法定多数 Quorum 一部分）则为 1，失去 Quorum 时为 0。
• hg_raft_alive_peers：Leader 节点在租约超时时间内收到心跳的活跃 Raft 节点总数（包含自身）；非 Leader 节点上返回 NaN。

在 1.7.0 之后的版本中，PD 还会为每个已注册的 Store 导出 hg_store_state{store="<id>",state="<state>"}：Store 当前状态（Unknown、Pending、Up、Offline、Exiting 或 Tombstone）对应的序列为 1，其余为 0；以及 hg_store_leader_count{store="<id>"}，即 leader 位于该 Store 上的分片组数量。重建后的 Store 在 leader 迁回之前会报告 0。所有 PD 成员读取的是同一份复制的元数据，因此聚合这些序列前请先只选取一个实例。

7.6 Store 下线与排空生命周期

下线或下架 Store 节点遵循严谨的状态机流转，以确保在不中断业务的前提下安全排空分片副本：

1. 状态机流转过程：

   • Up：Store 在线且健康，正常参与副本分配和 leader 选举。
   • Exiting：Store 处于排空状态。处于 Exiting 时，该节点继续正常续租心跳，但 PD 会将其排除在新的副本分配和迁移目标之外。
   • 分区迁移：PD 自动调度后台迁移任务，将该节点上的所有分片副本逐步迁至其他健康的活跃 Store 上。
   • Tombstone：Store 永久下线退出。一旦标记为 Tombstone，管理接口不再允许将其恢复为活跃状态。

2. 发起排空操作： 通过管理接口将目标 Store 状态置为 Exiting：

   1curl -X POST http://<pd-host>:8620/v1/store/{storeId} \
   2  -H "Authorization: Basic <credentials>" \
   3  -H "Content-Type: application/json" \
   4  -d '{"storeState": "Exiting"}'

3. 容量约束与下线检查：

   • 容量校验：排空会校验集群剩余可用 Store 节点数是否满足 minStoreCount（pd.min-store-count）。若剩余容量不足， PD 将直接拦截并在状态持久化前拒绝请求；此时需扩容足够的活跃 Store 后重新发起下线请求。
   • 退出完成判定：PD 会持续保持 Exiting 状态，直到 Store 最新心跳上报本地分区引擎数为 0 且 PD 元数据中无任何分片组引用该 Store ID。
   • 销毁前核验：在删除 Store Pod 或持久化存储卷前，运维人员必须确认其余分片组已具备完整的 Raft 成员、全额副本以及最新的健康心跳。
   • 重新注册意图保留：处于 Exiting 状态的 Store 重启重新注册时，即使其地址在 pd.initial-store-list 中，PD 仍会保留其 Exiting 排空意图。

3.1.3 - HugeGraph-Store 快速上手

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 版本：HugeGraph 1.8.0+ 使用 Java 17（Maven 源码构建仅接受 JDK 17；启动脚本拒绝低于 17 的运行时；1.7.0 是最后一个支持 Java 11 的版本）
• Maven 版本：≥ 3.6.3（从源码编译时）
• 如需进行多节点部署，请先部署 HugeGraph-PD

3 部署

3 部署

HugeGraph-Store 组件主要支持以下部署与运行方式：

• 下载发布包 — 下载并解压官方发布的完整二进制安装包。
• 源码编译 — 基于 master 主线代码使用 Maven 与 Java 17 编译 Store 模块。
• Docker 部署 — 使用容器运行 Store 节点并组建分布式集群。

3.1 下载 tar 包

Apache 下载页目前提供 1.7.0 的完整二进制包，其中包含 PD、Store 和 Server；没有单独列出 Store 二进制包。下载前请在 官方 Apache HugeGraph 下载页核对版本、签名和 SHA512。1.7.0 是孵化期发布的历史版本，归档文件和解压目录仍带 incubating：

1# 1.7.0 是项目孵化期发布的历史版本，因此文件名和目录名仍带 incubating
2curl -fLO --connect-timeout 10 --max-time 1800 https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3tar zxf apache-hugegraph-incubating-1.7.0.tar.gz
4cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-store-incubating-1.7.0

3.2 源码编译

1. 克隆源代码仓库：

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

2. 编译依赖及 Store 模块：

   1# 单独编译 Store 前需先编译其依赖的 hugegraph-struct 模块
   2mvn install -pl hugegraph-struct -am -DskipTests
   3mvn clean package -pl hugegraph-store/hg-store-dist -am -DskipTests

3. 检查编译产物：

   1cd hugegraph-store/apache-hugegraph-store-*
   2ls -la bin conf lib

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

3.3 Docker 部署

HG_STORE_* 环境变量映射是当前主线源码提供的功能；server 的 1.7.0 发布源码标签尚无这些映射。本文下面的 Docker 示例仅适用于从当前主线源码构建并使用同一个本地标签的 PD、Store 和 HStore Server 镜像：

1# 在 hugegraph 仓库根目录执行
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/README.md 的认证环境步骤 在 docker/ 创建 .env。 该步骤使用 umask 077 并拒绝覆盖已有文件；若 .env 已存在，应保留原文件并编辑补全缺少的项。不要为已初始化的数据目录重新生成 HG_PD_AUTH_SECRET_KEY。此文件由仓库 .gitignore 忽略，仍不要提交。 每次在新 shell 执行 Compose 或 PD REST 命令前，都从 docker/ 目录加载同一文件：

1# 在 hugegraph 仓库根目录执行
2cd docker
3set -a; . ./.env; set +a
4: "${HG_PD_AUTH_SECRET_KEY:?请在 .env 中设置 HG_PD_AUTH_SECRET_KEY}"
5# 只启动 PD、Store、Server，不启动可选 Hubble 服务
6HUGEGRAPH_VERSION=local HUGEGRAPH_PULL_POLICY=never \
7  docker compose -f docker-compose-hstore.yml \
8  up -d --wait pd store server

后续重启或调用 PD REST 时，先按上面的方式加载同一个密钥；不要为已初始化的数据目录重新生成新值。HUGEGRAPH_VERSION=local 和 HUGEGRAPH_PULL_POLICY=never 是此 Compose 命令的参数，每次运行 Compose 生命周期命令时都要显式带上。

若要启动 Compose 文件中的 Hubble 服务，需使用拓扑对应的未跟踪配置文件。最小拓扑 docker-compose-hstore.yml 使用 conf/hubble/hstore.local.properties； HA 拓扑 docker-compose-3pd-3store-3server.yml 使用 conf/hubble/hstore-ha.local.properties。 上述 README 初始化步骤会用共享 PD 密钥生成两份文件。若文件缺失或需更新，先从 docker/ 目录载入已有 .env，再执行对应命令：

1set -a; . ./.env; set +a
2./set-hubble-pd-password.sh hstore      # 最小拓扑
3./set-hubble-pd-password.sh hstore-ha  # HA 拓扑

多节点拓扑中的服务名是 pd0–pd2、store0–store2 和 server0–server2。该主线 Compose 文件也应使用上述本地构建的同标签镜像，不能将 HUGEGRAPH_VERSION=1.7.0 发布镜像与主线 Compose 文件混用。

单独运行当前主线构建的 Store 时，将示例地址换成 Store 与 PD 均可路由的实际地址：

下面的 mkdir -p 和非递归 chown 仅适用于新建空目录。复用旧 root 镜像写入的数据时，先停止 Store， 执行一次 sudo chown -R 10001:10001 /path/to/storage，再启动 UID 10001 镜像。

 1# master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写
 2mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage
 3docker run -d \
 4  -p 8520:8520 -p 8500:8500 -p 8510:8510 \
 5  -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \
 6  -e HG_STORE_GRPC_HOST=192.168.1.20 \
 7  -e HG_STORE_RAFT_ADDRESS=192.168.1.20:8510 \
 8  -v /path/to/storage:/hugegraph-store/storage \
 9  --name hugegraph-store \
10  hugegraph/store:local

当前主线 Docker 环境变量：

当前主线 entrypoint 将这些变量写入 SPRING_APPLICATION_JSON，覆盖镜像内 conf/application.yml；其余配置仍从该文件和 application-pd.yml 读取，然后以前台方式启动 Java。旧变量 PD_ADDRESS、GRPC_HOST、RAFT_ADDRESS 仍可用，但会输出弃用警告。

PD 和 Store 的 Docker HEALTHCHECK 都检查 /v1/health，只说明本地 REST 监听器有响应。Compose 的 depends_on 也以此作为启动门槛，因此还需单独检查 PD /v1/ready 与 PD /v1/stores 中的 Store Up 状态。Store 镜像默认设置 STDOUT_MODE=true；其 Dockerfile 只声明 EXPOSE 8520，从 Docker 网络外访问 gRPC 8500 或 Raft 8510 时需另行发布端口。

4 配置

Store 从 conf/ 读取两个配置文件。1.7.0 发布标签的源文件见 application.yml 和 application-pd.yml；当前主线文件见 application.yml 和 application-pd.yml。主线默认配置把 spring.profiles.include: pd 加载的 RocksDB 设置放在第二个文件中；启动脚本指定 application.yml。

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

4.1 application.yml

以下配置参考表核对的是 Server 主线提交的发行目录值和 Java 默认注入值；1.7.0 发布包请使用其版本标签对应的配置文件，不要跨版本覆盖。

4.2 application-pd.yml

此文件只保存 rocksdb 参数和 Actuator 暴露设置。

4.3 配置项参考

下表中「当前主线目录值」来自前述两个主线配置文件，「代码默认值」是配置项缺失时节点使用的回退值；目录中未列出的配置项应以代码默认值为准。

核心

Raft

存储与标签

RocksDB

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。

线程池

gRPC 回调队列（1.8.0）

Store 使用无界队列处理 gRPC 回调，避免队列满时丢弃取消或完成通知，导致请求无法正常结束。thread.pool.grpc.queue 仍可写在配置中，但不再限制这个队列的容量。

thread.pool.grpc.core 和 thread.pool.grpc.max 仍用于配置线程池。由于回调可以继续排队，积压通常不会触发线程数从 core 增长到 max；只增大 max 无法提高回调处理能力。

持续过载仍会使队列积压并增加内存占用。应限制客户端并发，并根据节点资源调整扫描和查询工作线程池；不要依赖 thread.pool.grpc.queue 限流。1.7.0 仍使用配置的 gRPC 队列容量。

查询下推

后台任务

内置 PD 模式

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

诊断

自 HugeGraph 1.8.0 起，Store 的 HTTP 激活接口 GET /v1/arthasstart 已禁用（直接返回 403），旧 Arthas 配置字段仅为兼容保留。 推荐直接以服务进程属主身份运行发行包内置的脚本诊断正在运行的 JVM （官方容器镜像内置 JDK 17，可直接使用 docker exec 执行）：

1bin/arthas.sh

同机多进程时可指定 --pid <PID> --telnet-port 3659。 更多参数、认证配置及安全实践参见 Arthas 诊断代理。

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 安装目录下执行：

1./bin/start-hugegraph-store.sh

下文的生命周期与下载时限说明适用于包含启动脚本修复的 master 构建；上文下载的 1.7.0 启动脚本不包含这些修复。 启动脚本支持四个参数，GC 的版本限制见下文：

master 构建接受 g1、G1、zgc 和 ZGC。 上文下载的 1.7.0 启动脚本仅接受显式指定 zgc 或 ZGC；-g g1、-g G1 和其他参数会中止启动。 默认路径请省略 -g；参数被拒绝时，查看 logs/hugegraph-store-server.log。

守护进程模式：

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

JVM 内存方面，如果没有自行设置 JAVA_OPTIONS：-Xms512m，-Xmx 取空闲内存的一半并限制在 512 MB 到 2048 MB 之间。 脚本还会加上与该堆大小相同的 -XX:MaxDirectMemorySize、-XX:MetaspaceSize=256M、OOM 时把堆转储写入 logs/，以及滚动的 GC 日志 logs/gc.log。 生产节点通常需要大得多的堆，请显式指定，并同时设置直接内存上限，例如 -j "-Xmx32g -Xms32g -XX:MaxDirectMemorySize=2g"。 不设上限时，JVM 允许的直接内存与 32 GB 的堆相同，RocksDB 预算会把它计算在内，在内存不足约 66 GB 的主机上会降到 256 MiB 的下限。

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

主线构建中，每次可选 jemalloc 下载的连接时限为 5 秒，总时限为 30 秒。 1.7.0 的下载 helper 没有连接或总时限。超时或校验失败时沿用已有回退路径，不预加载下载库并继续启动。 校验有效的缓存库仍可复用，失败下载的临时文件会被清理。

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

1YYYY-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 安装目录下执行：

1./bin/stop-hugegraph-store.sh

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

5.3 重启 Store

1./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，分区分配也就无法完成。当前主线应先对每个 PD 检查 /v1/ready 返回 HTTP 200 且 ready:true；/v1/health 只是存活检查。
2. 再启动 Store。Store 早于 PD 启动并不致命：心跳线程会持续重试注册，并在 PD 可用之前打印 store heartbeat error: PD UNREACHABLE。
3. 最后启动 HugeGraph-Server，此时所有 Store 节点都应上报 state: "Up"。Server 需要分区就绪之后才能初始化或打开图。

主线 Compose 用 depends_on: condition: service_healthy 等待本地健康检查，但 PD 和 Store 的 Docker 健康检查都只访问 /v1/health，不能证明 Raft 多数派或 Store 注册已就绪。Server entrypoint 会等待 PD 至少报告一个 Up 的 Store；运维时仍应检查 PD /v1/ready 和 /v1/stores。

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：

1grpc:
2  port: 8500
3raft:
4  address: 127.0.0.1:8510
5server:
6  port: 8520
7app:
8  data-path: ./storage-a

节点 B：

1grpc:
2  port: 8501
3raft:
4  address: 127.0.0.1:8511
5server:
6  port: 8521
7app:
8  data-path: ./storage-b

节点 C：

1grpc:
2  port: 8502
3raft:
4  address: 127.0.0.1:8512
5server:
6  port: 8522
7app:
8  data-path: ./storage-c

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

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

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

1pd:
2  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 节点拥有独立的主机名和环境变量：

 1# store0，宿主机端口 8500（gRPC）、8510（Raft）、8520（REST）
 2HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
 3HG_STORE_GRPC_HOST: store0
 4HG_STORE_GRPC_PORT: "8500"
 5HG_STORE_REST_PORT: "8520"
 6HG_STORE_RAFT_ADDRESS: store0:8510
 7HG_STORE_DATA_PATH: /hugegraph-store/storage
 8
 9# store1，宿主机端口 8501、8511、8521
10HG_STORE_GRPC_HOST: store1
11HG_STORE_RAFT_ADDRESS: store1:8510
12
13# store2，宿主机端口 8502、8512、8522
14HG_STORE_GRPC_HOST: store2
15HG_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 服务是否正常运行：

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

如果返回 {"status":"UP"}，表示 Store 本地应用健康检查通过；它本身不证明已在 PD 注册为 Up。

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

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

7.1 Store REST 接口

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

GET /-/lifecycle 返回 JSON 格式的进程生命周期状态，形如 {"status":0,"text":"STARTED"}。其中 text 包含四种状态：

• STARTING：Spring 上下文或 gRPC 服务仍在启动中；
• STARTED：Spring 应用已就绪（ApplicationReadyEvent）且 gRPC 服务已启动运行；
• STOPPING：进程已进入关闭流程（ContextClosedEvent，优先级最高）；
• UNAVAILABLE：gRPC 服务已提前停止或已终止。

主线发行目录的 Store 配置将 management.endpoints.web.exposure.include 设为 "*"，并启用 Prometheus；Actuator 端点没有 PD REST Basic 认证保护，请限制 Store REST 端口的网络可达范围。

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

7.2 通过 PD 检查注册结果

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

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?请先设置 PD 部署密钥}" \
2  http://localhost:8620/v1/stores

对于当前主线源码构建包，PD REST 用户名必须是 hg、store、hubble、vermeer 之一，密码必须与 PD 的 auth.secret-key 相同；HG_PD_AUTH_SECRET_KEY 会同时配置 Compose 中的 PD 和 Server。/v1/health、/v1/ready、/actuator/* 和 /v1/prom/targets/* 不需要认证。1.7.0 发布标签的实现只校验用户名，不比较密码；不要把这一旧行为用于主线源码构建包。

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

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

 1{
 2  "message": "OK",
 3  "data": {
 4    "stores": [
 5      {
 6        "storeId": 8319292642220586694,
 7        "address": "127.0.0.1:8500",
 8        "raftAddress": "127.0.0.1:8510",
 9        "version": "",
10        "state": "Up",
11        "deployPath": "/Users/{your_user_name}/hugegraph/hugegraph-store/apache-hugegraph-store-{version}/lib/hg-store-node-{version}.jar",
12        "dataPath": "./storage",
13        "startTimeStamp": 1754027127969,
14        "registedTimeStamp": 1754027127969,
15        "lastHeartBeat": 1754027909444,
16        "capacity": 494384795648,
17        "available": 346535829504,
18        "partitionCount": 0,
19        "graphSize": 0,
20        "keyCount": 0,
21        "leaderCount": 0,
22        "serviceName": "127.0.0.1:8500-store",
23        "serviceVersion": "",
24        "serviceCreatedTimeStamp": 1754027127000,
25        "partitions": []
26      }
27    ],
28    "stateCountMap": {
29      "Up": 1
30    },
31    "numOfService": 1,
32    "numOfNormalService": 1
33  },
34  "status": 0
35}

7.3 最小图读写验证

确认 Store 已在 PD 中显示为 Up 后，再启动配置为 HStore 后端、连接同一 PD 集群的 Server。Server 配置步骤见 Server 快速上手。确认 GET /versions 可访问且默认图 hugegraph 已加载后，可以创建一个属性键、顶点标签和顶点，再读取该顶点：

 1SERVER_URL=http://localhost:8080
 2GRAPH_URL="$SERVER_URL/graphspaces/DEFAULT/graphs/hugegraph"
 3
 4# 这些名称在当前图空间中必须唯一；已存在时换一组名称再执行
 5curl -fsS -X POST "$GRAPH_URL/schema/propertykeys" \
 6  -H 'Content-Type: application/json' \
 7  -d '{"name":"pd_store_demo_name","data_type":"TEXT","cardinality":"SINGLE","properties":[]}'
 8
 9curl -fsS -X POST "$GRAPH_URL/schema/vertexlabels" \
10  -H 'Content-Type: application/json' \
11  -d '{"name":"pd_store_demo_vertex","id_strategy":"CUSTOMIZE_STRING","properties":["pd_store_demo_name"],"primary_keys":[],"nullable_keys":[]}'
12
13curl -fsS -X POST "$GRAPH_URL/graph/vertices" \
14  -H 'Content-Type: application/json' \
15  -d '{"id":"pd-store-demo-1","label":"pd_store_demo_vertex","properties":{"pd_store_demo_name":"stored in HStore"}}'
16
17curl -fsS "$GRAPH_URL/graph/vertices/%22pd-store-demo-1%22"

最后一个响应应包含顶点 ID pd-store-demo-1 和属性 pd_store_demo_name。若 Server 开启了认证，以上请求还需按其认证配置增加凭据。

3.1.4 - 使用 Helm 部署 HugeGraph

本文适用于 HugeGraph 1.8.0 及以后版本，需要支持 OCI 的 Helm 3.10+ 和 Kubernetes (K8s) 1.23+。 可从 GHCR 或 Docker Hub 安装 hugegraph-helm。Chart 与 HugeGraph 服务分别维护版本，例如 0.4.x 的 Chart 可以部署 1.8.x 的服务。

Artifact Hub 方便查找 Chart、查看版本和安装说明，实际安装包仍从 GHCR 或 Docker Hub 下载。 参数和源码开发方式见 chart README， 生命周期操作见 运维参考。

1 安装

选择一个下载源即可，公共 CI 推荐 GHCR。本地轻量测试可直接使用单节点预设。

1CHART=oci://ghcr.io/hugegraph/hugegraph-helm
2kubectl config current-context
3kubectl get nodes
4kubectl get storageclass
5helm install hugegraph "$CHART" --devel -n hugegraph \
6  --create-namespace --wait --timeout 15m

1CHART=oci://registry-1.docker.io/hugegraph/hugegraph-helm
2kubectl config current-context
3kubectl get nodes
4kubectl get storageclass
5helm install hugegraph "$CHART" --devel -n hugegraph \
6  --create-namespace --wait --timeout 15m

1# 适合本地 Minikube/Kind 等轻量测试；直接安装本次下载的 Chart
2CHART=oci://ghcr.io/hugegraph/hugegraph-helm
3helm pull "$CHART" --devel --untar
4helm install hugegraph ./hugegraph-helm -n hugegraph \
5  -f ./hugegraph-helm/values-single.yaml \
6  --create-namespace --wait --timeout 10m

单节点试用预设使用 HStore 的 1 PD + 1 Store + 1 Server 与 Hubble，放宽调度限制，适合资源受限环境。 SeaTunnel 和 Vermeer 仍保持关闭。

2 模式和访问入口

解压后目录为 hugegraph-helm/，源码目录仍为 helm/hugegraph/。

默认 mode: easy，Server 和 Hubble 自动分配 NodePort，PD 保持 ClusterIP。可以直接使用 HTTP，无需域名、证书或额外确认参数。 mode: strict 默认将 Server/Hubble 设为 ClusterIP，并开启完整 NetworkPolicy 隔离。 SeaTunnel 和 Vermeer 启用后的原生 HTTP/UI 在 easy 模式下默认使用 NodePort，strict 模式下默认使用 ClusterIP，两种模式均需登录。 内部 RPC、Worker HTTP 与 SeaTunnel 成员端口仍保持私有。两个模式都保留鉴权和持久化。 优先级是组件显式参数高于全局参数，全局参数高于模式默认值，显式 false 也会生效。 全局参数包括 persistence.enabled 和 global.imageRegistry，严格预设为 values-strict.yaml。

1kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble
2kubectl get nodes -o wide
3kubectl -n hugegraph get secret hugegraph-admin \
4  -o jsonpath='{.data.password}' | base64 --decode