hugegraph/store

HugeGraph Store

![License]([***]

注意：从1.5.0版本开始，HugeGraph-Store代码已迁移至此位置。

概述

HugeGraph Store是HugeGraph的分布式存储后端，为生产环境中的图数据库部署提供高可用性、水平扩展性和强一致性。它构建在RocksDB和Apache JRaft之上，作为需要企业级可靠性的大规模图工作负载的数据平面。

核心功能

• 分布式存储：基于哈希的分区方式，数据自动分布在多个Store节点
• 高可用性：使用Raft共识算法实现多副本数据复制，容忍节点故障而不丢失数据
• 水平扩展性：动态分区分配和重新平衡，实现无缝集群扩展
• 查询优化：高级查询下推（过滤、聚合、索引）和多分区并行执行
• 元数据协调：与HugeGraph PD紧密集成，实现集群管理和服务发现
• 高性能：基于gRPC的通信，支持流式处理大型结果集

技术栈

• 存储引擎：RocksDB 7.7.3（针对图工作负载优化）
• 共识协议：Apache JRaft（蚂蚁金服的Raft实现）
• RPC框架：gRPC + Protocol Buffers
• 部署环境：Java 11+，支持Docker/Kubernetes

适用场景

适合使用Store的场景：

• 需要高可用性的生产环境部署（99.9%+ 正常运行时间）
• 超过单节点存储容量的工作负载（100GB+）
• 多租户或高并发场景（1000+ QPS）
• 需要水平扩展和容错能力的环境

适合使用RocksDB后端的场景：

• 开发和测试环境
• 中等数据量的单节点部署（<100GB）
• 优先考虑简单性而非分布式的嵌入式场景

---

架构

HugeGraph Store是一个Maven多模块项目，包含9个模块：

三层架构

客户端层 (hugegraph-server)
    ↓ (通过hg-store-client连接gRPC)
Store节点层 (hg-store-node)
    ├─ gRPC服务 (会话、查询、状态)
    ├─ 分区引擎 (每个分区 = 一个Raft组)
    └─ PD集成 (心跳、分区分配)
         ↓
存储引擎层 (hg-store-core + hg-store-rocksdb)
    ├─ HgStoreEngine (管理所有分区引擎)
    ├─ PartitionEngine (每个分区的Raft状态机)
    └─ RocksDB (持久化存储)

关键架构特性

• 基于分区的分布：数据被分割为多个分区（默认：基于哈希）并分布在Store节点上
• 每个分区的Raft共识：每个分区是一个独立的Raft组，有1-3个副本（生产环境通常为3个）
• PD协调：Store节点向PD注册，用于分区分配、元数据同步和健康监控
• 查询下推：过滤器、聚合和索引扫描被下推到Store节点进行并行执行

有关详细架构、Raft共识机制和分区管理，请参见分布式架构。

---

快速开始

先决条件

• Java：11或更高版本
• Maven：3.5或更高版本
• HugeGraph PD集群：Store需要运行中的PD集群进行元数据协调（参见PD README）
• 磁盘空间：每个Store节点至少10GB，用于数据和Raft日志
• 网络：Store节点之间的低延迟网络（<5ms），用于Raft共识

构建

重要：首先构建hugegraph-struct，因为它是必需的依赖项。

从项目根目录：

bash
# 构建struct模块
mvn install -pl hugegraph-struct -am -DskipTests

# 构建Store及所有依赖
mvn clean package -pl hugegraph-store/hg-store-dist -am -DskipTests

组装好的发行版将位于：

hugegraph-store/apache-hugegraph-store-<version>/lib/hg-store-node-<version>.jar

配置

解压发行包并编辑conf/application.yml：

核心设置

单节点开发示例（使用fake-pd）

yaml
pdserver:
  address: localhost:8686  # 当fake-pd为true时忽略

grpc:
  host: 127.0.0.1
  port: 8500

raft:
  address: 127.0.0.1:8510
  snapshotInterval: 1800

server:
  port: 8520

app:
  data-path: ./storage
  fake-pd: true  # 内置PD模式（仅开发使用）

3节点集群示例（生产环境）

先决条件：运行中的3节点PD集群，地址为192.168.1.10:8686，192.168.1.11:8686，192.168.1.12:8686

Store节点1（192.168.1.20）：

yaml
pdserver:
  address: 192.168.1.10:8686,192.168.1.11:8686,192.168.1.12:8686

grpc:
  host: 192.168.1.20
  port: 8500

raft:
  address: 192.168.1.20:8510

app:
  data-path: ./storage
  fake-pd: false

Store节点2（192.168.1.21）：

yaml
pdserver:
  address: 192.168.1.10:8686,192.168.1.11:8686,192.168.1.12:8686

grpc:
  host: 192.168.1.21
  port: 8500

raft:
  address: 192.168.1.21:8510

app:
  data-path: ./storage
  fake-pd: false

Store节点3（192.168.1.22）：

yaml
pdserver:
  address: 192.168.1.10:8686,192.168.1.11:8686,192.168.1.12:8686

grpc:
  host: 192.168.1.22
  port: 8500

raft:
  address: 192.168.1.22:8510

app:
  data-path: ./storage
  fake-pd: false

有关详细配置选项、RocksDB调优和部署拓扑，请参见部署指南。

运行

启动Store服务器：

bash
# 替换{version}为您的hugegraph版本
# 对于历史版本1.7.0及更早版本，使用
# apache-hugegraph-store-incubating-{version}
cd apache-hugegraph-store-{version}

# 启动Store节点
bin/start-hugegraph-store.sh

# 停止Store节点
bin/stop-hugegraph-store.sh

# 重启Store节点
bin/restart-hugegraph-store.sh

启动选项

bash
bin/start-hugegraph-store.sh [-g GC_TYPE] [-j "JVM_OPTIONS"]

• -g：GC类型（g1或ZGC，默认：g1）
• -j：自定义JVM选项（例如：-j "-Xmx16g -Xms8g"）

默认JVM内存设置（在start-hugegraph-store.sh中定义）：

• 最大堆：32GB
• 最小堆：512MB

验证部署

检查Store是否运行并已注册到PD：

bash
# 检查进程
ps aux | grep hugegraph-store

# 测试gRPC端点（需要grpcurl）
grpcurl -plaintext localhost:8500 list

# 检查REST API健康状态
curl http://localhost:8520/v1/health

# 查看日志
tail -f logs/hugegraph-store.log

# 验证是否已注册到PD（从PD节点执行）
curl http://localhost:8620/v1/stores

对于生产环境部署，请参见部署指南和最佳实践。

---

与HugeGraph Server集成

HugeGraph Store作为HugeGraph Server的可插拔后端。要使用Store作为后端：

1. 配置HugeGraph Server后端

编辑hugegraph-server/conf/graphs/<graph-name>.properties：

properties
# 后端配置
backend=hstore
serializer=binary

# Store连接（PD地址）
store.provider=org.apache.hugegraph.backend.store.hstore.HstoreProvider
store.pd_peers=192.168.1.10:8686,192.168.1.11:8686,192.168.1.12:8686

# 连接池设置
store.max_sessions=4
store.session_timeout=30000

2. 启动HugeGraph Server

确保PD和Store集群正在运行，然后启动HugeGraph Server：

bash
cd hugegraph-server
bin/init-store.sh  # 初始化模式
bin/start-hugegraph.sh

3. 验证后端

bash
# 通过REST API检查后端
curl --location --request GET 'http://localhost:8080/metrics/backend' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
# 响应应显示：
# {"backend": "hstore", "nodes": [...]}

---

测试

运行Store测试：

bash
# 所有测试（从hugegraph根目录）
mvn test -pl hugegraph-store/hg-store-test -am

# 特定测试模块
mvn test -pl hugegraph-store/hg-store-test -am -Dtest=HgStoreEngineTest

# 从hugegraph-store目录
cd hugegraph-store
mvn test

测试配置文件

Store测试分为6个配置文件（默认全部激活）：

• store-client-test：客户端库测试
• store-core-test：核心存储和分区管理测试
• store-common-test：通用工具和查询抽象测试
• store-rocksdb-test：RocksDB抽象层测试
• store-server-test：Store节点服务器和gRPC服务测试
• store-raftcore-test：Raft共识集成测试

有关开发工作流和调试，请参见开发指南。

---

Docker

构建Docker镜像

从项目根目录：

bash
docker build -f hugegraph-store/Dockerfile -t hugegraph-store:latest .

运行容器

bash
docker run -d \
  -p 8520:8520 \
  -p 8500:8500 \
  -p 8510:8510 \
  -v /path/to/conf:/hugegraph-store/conf \
  -v /path/to/storage:/hugegraph-store/storage \
  -e PD_ADDRESS=192.168.1.10:8686,192.168.1.11:8686 \
  --name hugegraph-store \
  hugegraph-store:latest

暴露端口：

• 8520：REST API（管理、指标）
• 8500：gRPC（客户端连接）
• 8510：Raft共识

Docker Compose示例

完整的HugeGraph分布式部署（PD + Store + Server）示例，请参见：

hugegraph-server/hugegraph-dist/docker/example/

有关Docker和Kubernetes部署详情，请参见部署指南。

---

文档

HugeGraph Store的综合文档：

---

生产部署注意事项

集群拓扑

最小集群（开发/测试）：

• 3个PD节点
• 3个Store节点
• 1-3个Server节点

推荐生产集群：

• 3-5个PD节点（Raft仲裁需要奇数）
• 6-12个Store节点（取决于数据大小和吞吐量）
• 3-6个Server节点（取决于查询负载）

大规模集群：

• 5个PD节点
• 12+个Store节点（水平扩展）
• 6+个Server节点（负载均衡）

高可用性

• Store使用Raft共识进行领导者选举和数据复制
• 每个分区有1-3个副本（默认：生产环境3个）
• 集群可容忍每个分区最多(N-1)/2个Store节点故障（例如，3副本设置可容忍1个故障）
• 自动故障转移和领导者重选（通常<10秒）
• PD提供集群范围的协调和元数据一致性

分区策略