From 25a7086ceefab7379625d4383fcc9d06eafb1b46 Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Sat, 7 Mar 2026 18:30:06 +0530 Subject: [PATCH 01/16] doc: add Docker bridge networking guide and update deployment docs --- .../docs/guides/hugegraph-docker-cluster.md | 135 ++++++++++++++++++ .../quickstart/hugegraph/hugegraph-hstore.md | 70 +++++++++ .../docs/quickstart/hugegraph/hugegraph-pd.md | 47 ++++++ .../quickstart/hugegraph/hugegraph-server.md | 56 ++++++-- .../docs/guides/hugegraph-docker-cluster.md | 135 ++++++++++++++++++ .../quickstart/hugegraph/hugegraph-hstore.md | 70 +++++++++ .../docs/quickstart/hugegraph/hugegraph-pd.md | 47 ++++++ .../quickstart/hugegraph/hugegraph-server.md | 56 ++++++-- 8 files changed, 586 insertions(+), 30 deletions(-) create mode 100644 content/cn/docs/guides/hugegraph-docker-cluster.md create mode 100644 content/en/docs/guides/hugegraph-docker-cluster.md diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md new file mode 100644 index 000000000..a73e2208d --- /dev/null +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -0,0 +1,135 @@ +--- +title: "HugeGraph Docker 集群部署指南" +linkTitle: "Docker 集群" +weight: 5 +--- + +## 概述 + +HugeGraph 支持通过 Docker 桥接网络运行完整的分布式集群（PD + Store + Server）。该方式适用于 Linux 和 Mac（Docker Desktop）。 + +早期版本使用 `network_mode: host`，仅在 Linux 上可用。集群现在使用 Docker 桥接网络（`hg-net`），服务通过容器主机名而非 `127.0.0.1` 进行通信。 + +## 前置条件 + +- Docker Engine 20.10+ 或 Docker Desktop 4.x+ +- Docker Compose v2 +- 3 节点集群需为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存） +- 本地克隆仓库（在更新后的镜像发布到 Docker Hub 之前的临时要求） + +> **已测试平台**：Linux（原生 Docker）和 macOS（Docker Desktop，已在 Apple M4 上测试）。Windows Docker Desktop 未经测试。 + +## Compose 文件 + +[`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了三个 compose 文件： + +| 文件 | 描述 | +|------|------| +| `docker-compose.yml` | 使用预构建镜像的单节点快速启动 | +| `docker-compose-dev.yml` | 从源码构建的单节点开发模式 | +| `docker-compose-3pd-3store-3server.yml` | 3 节点分布式集群 | + +## 单节点快速启动 + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose up -d +``` + +验证： +```bash +curl http://localhost:8080/versions +``` + +## 3 节点集群快速启动 + +```bash +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +启动顺序自动强制执行： +1. PD 节点首先启动，必须通过 `/v1/health` 健康检查 +2. Store 节点在所有 PD 节点健康后启动 +3. Server 节点在所有 Store 节点健康后启动 + +验证集群： +```bash +curl http://localhost:8620/v1/health # PD 健康检查 +curl http://localhost:8520/v1/health # Store 健康检查 +curl http://localhost:8080/versions # Server +curl http://localhost:8620/v1/stores # 已注册的 Store +curl http://localhost:8620/v1/partitions # 分区分配 +``` + +## 环境变量参考 + +### PD 变量 + +| 变量 | 必填 | 默认值 | 映射配置 | +|------|------|--------|----------| +| `HG_PD_GRPC_HOST` | 是 | — | `grpc.host` | +| `HG_PD_RAFT_ADDRESS` | 是 | — | `raft.address` | +| `HG_PD_RAFT_PEERS_LIST` | 是 | — | `raft.peers-list` | +| `HG_PD_INITIAL_STORE_LIST` | 是 | — | `pd.initial-store-list` | +| `HG_PD_GRPC_PORT` | 否 | `8686` | `grpc.port` | +| `HG_PD_REST_PORT` | 否 | `8620` | `server.port` | +| `HG_PD_DATA_PATH` | 否 | `/hugegraph-pd/pd_data` | `pd.data-path` | +| `HG_PD_INITIAL_STORE_COUNT` | 否 | `1` | `pd.initial-store-count` | + +**已弃用的别名**：`GRPC_HOST` → `HG_PD_GRPC_HOST`、`RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`、`RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` + +### Store 变量 + +| 变量 | 必填 | 默认值 | 映射配置 | +|------|------|--------|----------| +| `HG_STORE_PD_ADDRESS` | 是 | — | `pdserver.address` | +| `HG_STORE_GRPC_HOST` | 是 | — | `grpc.host` | +| `HG_STORE_RAFT_ADDRESS` | 是 | — | `raft.address` | +| `HG_STORE_GRPC_PORT` | 否 | `8500` | `grpc.port` | +| `HG_STORE_REST_PORT` | 否 | `8520` | `server.port` | +| `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | `app.data-path` | + +**已弃用的别名**：`PD_ADDRESS` → `HG_STORE_PD_ADDRESS`、`GRPC_HOST` → `HG_STORE_GRPC_HOST`、`RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` + +### Server 变量 + +| 变量 | 必填 | 默认值 | 映射配置 | +|------|------|--------|----------| +| `HG_SERVER_BACKEND` | 是 | — | `hugegraph.properties` 中的 `backend` | +| `HG_SERVER_PD_PEERS` | 是 | — | `pd.peers` | +| `STORE_REST` | 否 | — | `wait-partition.sh` 使用 | +| `PASSWORD` | 否 | — | 启用鉴权模式 | + +**已弃用的别名**：`BACKEND` → `HG_SERVER_BACKEND`、`PD_PEERS` → `HG_SERVER_PD_PEERS` + +## 端口参考 + +| 服务 | 宿主机端口 | 用途 | +|------|-----------|------| +| pd0 | 8620 | REST API | +| pd0 | 8686 | gRPC | +| pd1 | 8621 | REST API | +| pd1 | 8687 | gRPC | +| pd2 | 8622 | REST API | +| pd2 | 8688 | gRPC | +| store0 | 8500 | gRPC | +| store0 | 8520 | REST API | +| store1 | 8501 | gRPC | +| store1 | 8521 | REST API | +| store2 | 8502 | gRPC | +| store2 | 8522 | REST API | +| server0 | 8080 | Graph API | +| server1 | 8081 | Graph API | +| server2 | 8082 | Graph API | + +## 故障排查 + +**容器 OOM 被杀（退出码 137）**：将 Docker Desktop 内存增加到 12 GB 以上。 + +**Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1` + +**分区分配未完成**：检查 `curl http://localhost:8620/v1/stores` — 所有 3 个 Store 必须显示 `"state":"Up"` 才能完成分区分配。 + +**连接被拒**：确保 `HG_*` 环境变量使用容器主机名（`pd0`、`store0`），而非 `127.0.0.1`。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 50d28d579..0447fadc3 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -50,6 +50,48 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker 部署 + +HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/store:latest`。 + +使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +通过 `docker run` 运行单个 Store 节点： + +```bash +docker run -d \ + -p 8520:8520 \ + -p 8500:8500 \ + -p 8510:8510 \ + -e HG_STORE_PD_ADDRESS=:8686 \ + -e HG_STORE_GRPC_HOST= \ + -e HG_STORE_RAFT_ADDRESS=:8510 \ + -v /path/to/storage:/hugegraph-store/storage \ + --name hugegraph-store \ + hugegraph/store:latest +``` + +**环境变量参考：** + +| 变量 | 必填 | 默认值 | 描述 | +|------|------|--------|------| +| `HG_STORE_PD_ADDRESS` | 是 | — | PD gRPC 地址（如 `pd0:8686,pd1:8686,pd2:8686`） | +| `HG_STORE_GRPC_HOST` | 是 | — | 本节点的 gRPC 主机名/IP（如 `store0`） | +| `HG_STORE_RAFT_ADDRESS` | 是 | — | 本节点的 Raft 地址（如 `store0:8510`） | +| `HG_STORE_GRPC_PORT` | 否 | `8500` | gRPC 服务端口 | +| `HG_STORE_REST_PORT` | 否 | `8520` | REST API 端口 | +| `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | 数据存储路径 | + +> **注意**：在 Docker 桥接网络中，`HG_STORE_GRPC_HOST` 应使用容器主机名（如 `store0`）而非 IP 地址。 + +> **已弃用的别名**：`PD_ADDRESS`、`GRPC_HOST`、`RAFT_ADDRESS` 仍可使用，但会输出弃用警告。新部署请使用 `HG_STORE_*` 名称。 + ### 4 配置 Store 的主要配置文件为 `conf/application.yml`，以下是关键配置项： @@ -188,6 +230,34 @@ pdserver: address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688 ``` +#### 6.3 Docker 集群快速启动 + +3 节点 Store 集群包含在 `docker/docker-compose-3pd-3store-3server.yml` 中。每个 Store 节点拥有独立的主机名和环境变量： + +```yaml +# store0 +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 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store1 +HG_STORE_RAFT_ADDRESS: store1:8510 + +# store2 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store2 +HG_STORE_RAFT_ADDRESS: store2:8510 +``` + +Store 节点仅在所有 PD 节点通过健康检查（`/v1/health`）后启动，通过 `depends_on: condition: service_healthy` 强制执行。 + +完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 + ### 7 验证 Store 服务 确认 Store 服务是否正常运行： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 46d70c32f..5beba9065 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -49,6 +49,53 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker 部署 + +HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd:latest`。 + +使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +通过 `docker run` 运行单个 PD 节点时，通过环境变量提供配置： + +```bash +docker run -d \ + -p 8620:8620 \ + -p 8686:8686 \ + -p 8610:8610 \ + -e HG_PD_GRPC_HOST= \ + -e HG_PD_RAFT_ADDRESS=:8610 \ + -e HG_PD_RAFT_PEERS_LIST=:8610 \ + -e HG_PD_INITIAL_STORE_LIST=:8500 \ + -v /path/to/data:/hugegraph-pd/pd_data \ + --name hugegraph-pd \ + hugegraph/pd:latest +``` + +**环境变量参考：** + +| 变量 | 必填 | 默认值 | 描述 | +|------|------|--------|------| +| `HG_PD_GRPC_HOST` | 是 | — | 本节点的 gRPC 主机名/IP（Docker 中使用 `pd0`，裸机使用 `192.168.1.10`） | +| `HG_PD_RAFT_ADDRESS` | 是 | — | 本节点的 Raft 地址（如 `pd0:8610`） | +| `HG_PD_RAFT_PEERS_LIST` | 是 | — | 所有 PD 节点的 Raft 地址（如 `pd0:8610,pd1:8610,pd2:8610`） | +| `HG_PD_INITIAL_STORE_LIST` | 是 | — | 预期的 Store gRPC 地址（如 `store0:8500,store1:8500,store2:8500`） | +| `HG_PD_GRPC_PORT` | 否 | `8686` | gRPC 服务端口 | +| `HG_PD_REST_PORT` | 否 | `8620` | REST API 端口 | +| `HG_PD_DATA_PATH` | 否 | `/hugegraph-pd/pd_data` | 元数据存储路径 | +| `HG_PD_INITIAL_STORE_COUNT` | 否 | `1` | 集群可用所需的最小 Store 数量 | + +> **注意**：在 Docker 桥接网络中，`HG_PD_GRPC_HOST` 和 `HG_PD_RAFT_ADDRESS` 应使用容器主机名（如 `pd0`）而非 IP 地址。 + +> **已弃用的别名**：`GRPC_HOST`、`RAFT_ADDRESS`、`RAFT_PEERS`、`PD_INITIAL_STORE_LIST` 仍可使用，但会输出弃用警告。新部署请使用 `HG_PD_*` 名称。 + +完整的集群部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 + ### 4 配置 PD 的主要配置文件为 `conf/application.yml`，以下是关键配置项： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 5b0610e16..bc86abd9f 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -39,7 +39,7 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 #### 3.1 使用 Docker 容器 (便于**测试**) -可参考 [Docker 部署方式](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/README.md)。 +可参考 [Docker 部署方式](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 我们可以使用 `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` 去快速启动一个内置了 `RocksDB` 的 `Hugegraph server`. @@ -55,23 +55,21 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 -另外，如果我们希望能够在一个文件中管理除了 `server` 之外的其他 Hugegraph 相关的实例，我们也可以使用 `docker-compose`完成部署，使用命令 `docker-compose up -d`，（当然只配置 `server` 也是可以的）以下是一个样例的 `docker-compose.yml`: +> **注意**：Docker compose 文件使用桥接网络（`hg-net`），适用于 Linux 和 Mac（Docker Desktop）。如需运行 3 节点分布式集群，请为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。 -```yaml -version: '3' -services: - server: - image: hugegraph/hugegraph:1.7.0 - container_name: server - environment: - - PASSWORD=xxx - # - PASSWORD=xxx 为可选参数，设置的时候可以开启鉴权模式，并设置密码 - # - PRELOAD=true - # - PRELOAD=true 为可选参数，为 True 时可以在启动的时候预加载一个内置的样例图 - ports: - - 8080:8080 +另外，如果我们希望能够在一个文件中管理 HugeGraph 相关的实例，可以使用 `docker compose` 完成部署。 +[`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了两个 compose 文件： + +- **单节点快速启动**（预构建镜像）：`docker/docker-compose.yml` +- **单节点开发构建**（从源码构建）：`docker/docker-compose-dev.yml` + +```bash +cd docker +docker compose up -d ``` +完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 + > 注意： > > 1. hugegraph 的 docker 镜像是一个便捷版本，用于快速启动 hugegraph，并不是**官方发布物料包方式**。你可以从 [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) 中得到更多细节。 @@ -307,6 +305,34 @@ curl http://localhost:8081/graphs ```bash bin/stop-hugegraph.sh ``` + +#### Docker 集群快速启动 + +通过 Docker 运行完整的分布式集群（3 PD + 3 Store + 3 Server）： + +> **前置条件**：为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。需要克隆仓库（在更新后的镜像发布之前的临时要求）。 + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +服务通过 `hg-net` 桥接网络上的容器主机名进行通信。配置通过环境变量注入： + +```yaml +# Server 配置 +HG_SERVER_BACKEND: hstore +HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686 +``` + +验证集群： +```bash +curl http://localhost:8080/versions +curl http://localhost:8620/v1/stores +``` + +完整的环境变量参考、端口表和故障排查指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 ##### 5.1.2 RocksDB / ToplingDB diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md new file mode 100644 index 000000000..32edf2263 --- /dev/null +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -0,0 +1,135 @@ +--- +title: "HugeGraph Docker Cluster Guide" +linkTitle: "Docker Cluster" +weight: 5 +--- + +## Overview + +HugeGraph supports running a full distributed cluster (PD + Store + Server) via Docker using bridge networking. This works on Linux and Mac (Docker Desktop). + +Previous versions used `network_mode: host` which only worked on Linux. The cluster now uses a Docker bridge network (`hg-net`) where services communicate via container hostnames instead of `127.0.0.1`. + +## Prerequisites + +- Docker Engine 20.10+ or Docker Desktop 4.x+ +- Docker Compose v2 +- For the 3-node cluster: at least **12 GB** memory allocated to Docker Desktop (Settings → Resources → Memory) +- Repository cloned locally (temporary requirement until updated images are published to Docker Hub) + +> **Tested platforms**: Linux (native Docker) and macOS (Docker Desktop, tested on Apple M4). Windows Docker Desktop is untested. + +## Compose Files + +Three compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: + +| File | Description | +|------|-------------| +| `docker-compose.yml` | Single-node quickstart using pre-built images | +| `docker-compose-dev.yml` | Single-node dev build from source | +| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster | + +## Single-Node Quickstart + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose up -d +``` + +Verify: +```bash +curl http://localhost:8080/versions +``` + +## 3-Node Cluster Quickstart + +```bash +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +Startup ordering is enforced automatically: +1. PD nodes start first and must pass `/v1/health` +2. Store nodes start after all PD nodes are healthy +3. Server nodes start after all Store nodes are healthy + +Verify the cluster: +```bash +curl http://localhost:8620/v1/health # PD health +curl http://localhost:8520/v1/health # Store health +curl http://localhost:8080/versions # Server +curl http://localhost:8620/v1/stores # Registered stores +curl http://localhost:8620/v1/partitions # Partition assignment +``` + +## Environment Variable Reference + +### PD Variables + +| Variable | Required | Default | Maps To | +|----------|----------|---------|---------| +| `HG_PD_GRPC_HOST` | Yes | — | `grpc.host` | +| `HG_PD_RAFT_ADDRESS` | Yes | — | `raft.address` | +| `HG_PD_RAFT_PEERS_LIST` | Yes | — | `raft.peers-list` | +| `HG_PD_INITIAL_STORE_LIST` | Yes | — | `pd.initial-store-list` | +| `HG_PD_GRPC_PORT` | No | `8686` | `grpc.port` | +| `HG_PD_REST_PORT` | No | `8620` | `server.port` | +| `HG_PD_DATA_PATH` | No | `/hugegraph-pd/pd_data` | `pd.data-path` | +| `HG_PD_INITIAL_STORE_COUNT` | No | `1` | `pd.initial-store-count` | + +**Deprecated aliases**: `GRPC_HOST` → `HG_PD_GRPC_HOST`, `RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`, `RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` + +### Store Variables + +| Variable | Required | Default | Maps To | +|----------|----------|---------|---------| +| `HG_STORE_PD_ADDRESS` | Yes | — | `pdserver.address` | +| `HG_STORE_GRPC_HOST` | Yes | — | `grpc.host` | +| `HG_STORE_RAFT_ADDRESS` | Yes | — | `raft.address` | +| `HG_STORE_GRPC_PORT` | No | `8500` | `grpc.port` | +| `HG_STORE_REST_PORT` | No | `8520` | `server.port` | +| `HG_STORE_DATA_PATH` | No | `/hugegraph-store/storage` | `app.data-path` | + +**Deprecated aliases**: `PD_ADDRESS` → `HG_STORE_PD_ADDRESS`, `GRPC_HOST` → `HG_STORE_GRPC_HOST`, `RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` + +### Server Variables + +| Variable | Required | Default | Maps To | +|----------|----------|---------|---------| +| `HG_SERVER_BACKEND` | Yes | — | `backend` in `hugegraph.properties` | +| `HG_SERVER_PD_PEERS` | Yes | — | `pd.peers` | +| `STORE_REST` | No | — | used by `wait-partition.sh` | +| `PASSWORD` | No | — | enables auth mode | + +**Deprecated aliases**: `BACKEND` → `HG_SERVER_BACKEND`, `PD_PEERS` → `HG_SERVER_PD_PEERS` + +## Port Reference + +| Service | Host Port | Purpose | +|---------|-----------|---------| +| pd0 | 8620 | REST API | +| pd0 | 8686 | gRPC | +| pd1 | 8621 | REST API | +| pd1 | 8687 | gRPC | +| pd2 | 8622 | REST API | +| pd2 | 8688 | gRPC | +| store0 | 8500 | gRPC | +| store0 | 8520 | REST API | +| store1 | 8501 | gRPC | +| store1 | 8521 | REST API | +| store2 | 8502 | gRPC | +| store2 | 8522 | REST API | +| server0 | 8080 | Graph API | +| server1 | 8081 | Graph API | +| server2 | 8082 | Graph API | + +## Troubleshooting + +**Containers OOM killed (exit code 137)**: Increase Docker Desktop memory to 12 GB+. + +**Raft leader election timeout**: Check `HG_PD_RAFT_PEERS_LIST` is identical on all PD nodes. Verify connectivity: `docker exec hg-pd0 ping pd1` + +**Partition assignment not completing**: Check `curl http://localhost:8620/v1/stores` — all 3 stores must show `"state":"Up"` before partitions are assigned. + +**Connection refused**: Ensure `HG_*` env vars use container hostnames (`pd0`, `store0`), not `127.0.0.1`. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 2d82a48d5..fc75d8d26 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -50,6 +50,48 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker Deployment + +The HugeGraph-Store Docker image is available on Docker Hub as `hugegraph/store:latest`. + +For a complete 3-node cluster with PD, Store, and Server, use the compose file: + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +To run a single Store node via `docker run`: + +```bash +docker run -d \ + -p 8520:8520 \ + -p 8500:8500 \ + -p 8510:8510 \ + -e HG_STORE_PD_ADDRESS=:8686 \ + -e HG_STORE_GRPC_HOST= \ + -e HG_STORE_RAFT_ADDRESS=:8510 \ + -v /path/to/storage:/hugegraph-store/storage \ + --name hugegraph-store \ + hugegraph/store:latest +``` + +**Environment variable reference:** + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `HG_STORE_PD_ADDRESS` | Yes | — | PD gRPC addresses (e.g. `pd0:8686,pd1:8686,pd2:8686`) | +| `HG_STORE_GRPC_HOST` | Yes | — | This node's hostname/IP for gRPC (e.g. `store0`) | +| `HG_STORE_RAFT_ADDRESS` | Yes | — | This node's Raft address (e.g. `store0:8510`) | +| `HG_STORE_GRPC_PORT` | No | `8500` | gRPC server port | +| `HG_STORE_REST_PORT` | No | `8520` | REST API port | +| `HG_STORE_DATA_PATH` | No | `/hugegraph-store/storage` | Data storage path | + +> **Note**: In Docker bridge networking, use container hostnames (e.g. `store0`) for `HG_STORE_GRPC_HOST` instead of IP addresses. + +> **Deprecated aliases**: `PD_ADDRESS`, `GRPC_HOST`, `RAFT_ADDRESS` still work but log a deprecation warning. Use the `HG_STORE_*` names for new deployments. + ### 4 Configuration The main configuration file for Store is `conf/application.yml`. Here are the key configuration items: @@ -188,6 +230,34 @@ pdserver: address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688 ``` +#### 6.3 Docker Cluster Quickstart + +The 3-node Store cluster is included in `docker/docker-compose-3pd-3store-3server.yml`. Each Store node gets its own hostname and env vars: + +```yaml +# store0 +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 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store1 +HG_STORE_RAFT_ADDRESS: store1:8510 + +# store2 +HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686 +HG_STORE_GRPC_HOST: store2 +HG_STORE_RAFT_ADDRESS: store2:8510 +``` + +Store nodes start only after all PD nodes pass healthchecks (`/v1/health`), enforced via `depends_on: condition: service_healthy`. + +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full setup guide. + ### 7 Verify Store Service Confirm that the Store service is running properly: diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index c8b6cf401..e76330ef8 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -49,6 +49,53 @@ mvn clean install -DskipTests=true # target/apache-hugegraph-incubating-{version}.tar.gz ``` +#### 3.3 Docker Deployment + +The HugeGraph-PD Docker image is available on Docker Hub as `hugegraph/pd:latest`. + +For a complete 3-node cluster with PD, Store, and Server, use the compose file: + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +To run a single PD node via `docker run`, configuration is provided via environment variables: + +```bash +docker run -d \ + -p 8620:8620 \ + -p 8686:8686 \ + -p 8610:8610 \ + -e HG_PD_GRPC_HOST= \ + -e HG_PD_RAFT_ADDRESS=:8610 \ + -e HG_PD_RAFT_PEERS_LIST=:8610 \ + -e HG_PD_INITIAL_STORE_LIST=:8500 \ + -v /path/to/data:/hugegraph-pd/pd_data \ + --name hugegraph-pd \ + hugegraph/pd:latest +``` + +**Environment variable reference:** + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `HG_PD_GRPC_HOST` | Yes | — | This node's hostname/IP for gRPC (e.g. `pd0` in Docker, `192.168.1.10` on bare metal) | +| `HG_PD_RAFT_ADDRESS` | Yes | — | This node's Raft address (e.g. `pd0:8610`) | +| `HG_PD_RAFT_PEERS_LIST` | Yes | — | All PD peers (e.g. `pd0:8610,pd1:8610,pd2:8610`) | +| `HG_PD_INITIAL_STORE_LIST` | Yes | — | Expected store gRPC addresses (e.g. `store0:8500,store1:8500,store2:8500`) | +| `HG_PD_GRPC_PORT` | No | `8686` | gRPC server port | +| `HG_PD_REST_PORT` | No | `8620` | REST API port | +| `HG_PD_DATA_PATH` | No | `/hugegraph-pd/pd_data` | Metadata storage path | +| `HG_PD_INITIAL_STORE_COUNT` | No | `1` | Minimum stores required for cluster availability | + +> **Note**: In Docker bridge networking, use container hostnames (e.g. `pd0`) for `HG_PD_GRPC_HOST` and `HG_PD_RAFT_ADDRESS` instead of IP addresses. + +> **Deprecated aliases**: `GRPC_HOST`, `RAFT_ADDRESS`, `RAFT_PEERS`, `PD_INITIAL_STORE_LIST` still work but log a deprecation warning. Use the `HG_PD_*` names for new deployments. + +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full cluster setup guide. + ### 4 Configuration The main configuration file for PD is `conf/application.yml`. Here are the key configuration items: diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index ee70e6d2d..9aa08ebca 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -42,7 +42,7 @@ There are four ways to deploy HugeGraph-Server components: #### 3.1 Use Docker container (Convenient for Test/Dev) -You can refer to the [Docker deployment guide](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/README.md). +You can refer to the [Docker deployment guide](https://github.com/apache/hugegraph/blob/master/docker/README.md). We can use `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` to quickly start a `HugeGraph Server` with a built-in `RocksDB` backend. @@ -56,23 +56,21 @@ If you use docker desktop, you can set the option like: image -Also, if we want to manage the other Hugegraph related instances in one file, we can use `docker-compose` to deploy, with the command `docker-compose up -d` (you can config only `server`). Here is an example `docker-compose.yml`: +> **Note**: The Docker compose files use bridge networking (`hg-net`) and work on Linux and Mac (Docker Desktop). For the 3-node distributed cluster, allocate at least **12 GB** memory to Docker Desktop (Settings → Resources → Memory). -```yaml -version: '3' -services: - server: - image: hugegraph/hugegraph:1.7.0 - container_name: server - environment: - - PASSWORD=xxx - # PASSWORD is an option to enable auth mode with the password you set. - # - PRELOAD=true - # PRELOAD is a option to preload a build-in sample graph when initializing. - ports: - - 8080:8080 +Also, if we want to manage HugeGraph-related instances in one file, we can use `docker compose` to deploy. +Two compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: + +- **Single-node quickstart** (pre-built images): `docker/docker-compose.yml` +- **Single-node dev build** (build from source): `docker/docker-compose-dev.yml` + +```bash +cd docker +docker compose up -d ``` +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full setup guide. + > Note: > > 1. The docker image of the hugegraph is a convenient release to start it quickly, but not **official distribution** artifacts. You can find more details from [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub). @@ -323,6 +321,34 @@ The sequence to stop the services should be the reverse of the startup sequence: ```bash bin/stop-hugegraph.sh ``` + +#### Docker Cluster Quickstart + +For running the full distributed cluster (3 PD + 3 Store + 3 Server) via Docker: + +> **Prerequisites**: Allocate at least **12 GB** memory to Docker Desktop (Settings → Resources → Memory). Requires a cloned repository (temporary requirement until updated images are published). + +```bash +git clone https://github.com/apache/hugegraph.git +cd hugegraph/docker +docker compose -f docker-compose-3pd-3store-3server.yml up -d +``` + +Services communicate via container hostnames on the `hg-net` bridge network. Configuration is injected via environment variables: + +```yaml +# Server configuration +HG_SERVER_BACKEND: hstore +HG_SERVER_PD_PEERS: pd0:8686,pd1:8686,pd2:8686 +``` + +Verify the cluster: +```bash +curl http://localhost:8080/versions +curl http://localhost:8620/v1/stores +``` + +See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full environment variable reference, port table, and troubleshooting guide. ##### 5.1.2 Memory From 6b074315055e5048035b56230b540896fbe24641 Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Sat, 7 Mar 2026 18:34:16 +0530 Subject: [PATCH 02/16] doc: add PASSWORD auth note to Docker quickstart section --- content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 2 ++ content/en/docs/quickstart/hugegraph/hugegraph-server.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index bc86abd9f..7dbdc9c77 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -68,6 +68,8 @@ cd docker docker compose up -d ``` +如需开启鉴权，可在 compose 文件的环境变量中添加 `PASSWORD=xxx`，或在 `docker run` 命令中传入 `-e PASSWORD=xxx`。 + 完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 > 注意： diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 9aa08ebca..e3c2e8b7f 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -69,6 +69,8 @@ cd docker docker compose up -d ``` +To enable authentication, add `PASSWORD=xxx` to the service environment in the compose file or pass `-e PASSWORD=xxx` to `docker run`. + See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full setup guide. > Note: From 445988e0b6addebd2838c7abaccf0a2a0d765faa Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Mon, 23 Mar 2026 15:44:13 +0530 Subject: [PATCH 03/16] docs: pin HUGEGRAPH_VERSION, fix image tags, remove stale clone workaround --- content/en/docs/guides/hugegraph-docker-cluster.md | 8 +++----- .../en/docs/quickstart/hugegraph/hugegraph-hstore.md | 8 +++----- content/en/docs/quickstart/hugegraph/hugegraph-pd.md | 8 +++----- .../en/docs/quickstart/hugegraph/hugegraph-server.md | 12 ++++-------- 4 files changed, 13 insertions(+), 23 deletions(-) diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 32edf2263..f6a985bea 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -1,4 +1,4 @@ ---- +cl--- title: "HugeGraph Docker Cluster Guide" linkTitle: "Docker Cluster" weight: 5 @@ -15,7 +15,6 @@ Previous versions used `network_mode: host` which only worked on Linux. The clus - Docker Engine 20.10+ or Docker Desktop 4.x+ - Docker Compose v2 - For the 3-node cluster: at least **12 GB** memory allocated to Docker Desktop (Settings → Resources → Memory) -- Repository cloned locally (temporary requirement until updated images are published to Docker Hub) > **Tested platforms**: Linux (native Docker) and macOS (Docker Desktop, tested on Apple M4). Windows Docker Desktop is untested. @@ -32,9 +31,8 @@ Three compose files are available in the [`docker/`](https://github.com/apache/h ## Single-Node Quickstart ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose up -d +HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` Verify: @@ -46,7 +44,7 @@ curl http://localhost:8080/versions ```bash cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` Startup ordering is enforced automatically: diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index fc75d8d26..1489e33f9 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -39,7 +39,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-hstore-incubating-{ver ```bash # 1. Clone the source code -git clone https://github.com/apache/hugegraph.git # 2. Build the project cd hugegraph @@ -52,14 +51,13 @@ mvn clean install -DskipTests=true #### 3.3 Docker Deployment -The HugeGraph-Store Docker image is available on Docker Hub as `hugegraph/store:latest`. +The HugeGraph-Store Docker image is available on Docker Hub as `hugegraph/store:1.7.0`. For a complete 3-node cluster with PD, Store, and Server, use the compose file: ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` To run a single Store node via `docker run`: @@ -74,7 +72,7 @@ docker run -d \ -e HG_STORE_RAFT_ADDRESS=:8510 \ -v /path/to/storage:/hugegraph-store/storage \ --name hugegraph-store \ - hugegraph/store:latest + hugegraph/store:1.7.0 ``` **Environment variable reference:** diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index e76330ef8..8e70aa4e5 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -38,7 +38,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-pd-incubating-{version ```bash # 1. Clone the source code -git clone https://github.com/apache/hugegraph.git # 2. Build the project cd hugegraph @@ -51,14 +50,13 @@ mvn clean install -DskipTests=true #### 3.3 Docker Deployment -The HugeGraph-PD Docker image is available on Docker Hub as `hugegraph/pd:latest`. +The HugeGraph-PD Docker image is available on Docker Hub as `hugegraph/pd:1.7.0`. For a complete 3-node cluster with PD, Store, and Server, use the compose file: ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` To run a single PD node via `docker run`, configuration is provided via environment variables: @@ -74,7 +72,7 @@ docker run -d \ -e HG_PD_INITIAL_STORE_LIST=:8500 \ -v /path/to/data:/hugegraph-pd/pd_data \ --name hugegraph-pd \ - hugegraph/pd:latest + hugegraph/pd:1.7.0 ``` **Environment variable reference:** diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index e3c2e8b7f..3208c3ec9 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -66,7 +66,7 @@ Two compose files are available in the [`docker/`](https://github.com/apache/hug ```bash cd docker -docker compose up -d +HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` To enable authentication, add `PASSWORD=xxx` to the service environment in the compose file or pass `-e PASSWORD=xxx` to `docker run`. @@ -110,7 +110,6 @@ shasum -a 512 apache-hugegraph-incubating-src-{version}.tar.gz curl https://downloads.apache.org/hugegraph/{version}/apache-hugegraph-incubating-{version}-src.tar.gz.sha512 # Way2 : clone the latest code by git way (e.g GitHub) -git clone https://github.com/apache/hugegraph.git ``` Compile and generate tarball @@ -328,12 +327,9 @@ bin/stop-hugegraph.sh For running the full distributed cluster (3 PD + 3 Store + 3 Server) via Docker: -> **Prerequisites**: Allocate at least **12 GB** memory to Docker Desktop (Settings → Resources → Memory). Requires a cloned repository (temporary requirement until updated images are published). - ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` Services communicate via container hostnames on the `hg-net` bridge network. Configuration is injected via environment variables: @@ -645,7 +641,7 @@ In [3.1 Use Docker container](#31-use-docker-container-convenient-for-testdev), When using Docker, we can use Cassandra as the backend storage. We highly recommend using docker-compose directly to manage both the server and Cassandra. -The sample `docker-compose.yml` can be obtained on [GitHub](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/example/docker-compose-cassandra.yml), and you can start it with `docker-compose up -d`. (If using Cassandra 4.0 as the backend storage, it takes approximately two minutes to initialize. Please be patient.) +The sample `docker-compose.yml` can be obtained on [GitHub](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/example/docker-compose-cassandra.yml), and you can start it with `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d`. (If using Cassandra 4.0 as the backend storage, it takes approximately two minutes to initialize. Please be patient.) ```yaml version: "3" @@ -727,7 +723,7 @@ Set the environment variable `PRELOAD=true` when starting Docker to load data du - 8080:8080 ``` - Use `docker-compose up -d` to start the container + Use `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d` to start the container And use the RESTful API to request `HugeGraphServer` and get the following result: From 42f74761c846abb47ec77a175d5ee6161bbdd842 Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Mon, 23 Mar 2026 20:47:20 +0530 Subject: [PATCH 04/16] docs: fix front matter typo, restore Way2 clone command --- content/en/docs/guides/hugegraph-docker-cluster.md | 2 +- content/en/docs/quickstart/hugegraph/hugegraph-server.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index f6a985bea..12c95ff76 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -1,4 +1,4 @@ -cl--- +--- title: "HugeGraph Docker Cluster Guide" linkTitle: "Docker Cluster" weight: 5 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 3208c3ec9..391456528 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -110,6 +110,8 @@ shasum -a 512 apache-hugegraph-incubating-src-{version}.tar.gz curl https://downloads.apache.org/hugegraph/{version}/apache-hugegraph-incubating-{version}-src.tar.gz.sha512 # Way2 : clone the latest code by git way (e.g GitHub) +git clone https://github.com/apache/hugegraph.git + ``` Compile and generate tarball From 8d30efad508bcc0e63e02d9fbd0eabc7826ff299 Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Thu, 26 Mar 2026 12:40:12 +0530 Subject: [PATCH 05/16] docs: fix compose filename typo, restore git clone in source build sections, fix front matter typo --- content/en/docs/guides/hugegraph-docker-cluster.md | 2 +- content/en/docs/quickstart/hugegraph/hugegraph-hstore.md | 1 + content/en/docs/quickstart/hugegraph/hugegraph-pd.md | 1 + content/en/docs/quickstart/hugegraph/hugegraph-server.md | 2 +- 4 files changed, 4 insertions(+), 2 deletions(-) diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 12c95ff76..50d86a413 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -25,7 +25,7 @@ Three compose files are available in the [`docker/`](https://github.com/apache/h | File | Description | |------|-------------| | `docker-compose.yml` | Single-node quickstart using pre-built images | -| `docker-compose-dev.yml` | Single-node dev build from source | +| `docker-compose.dev.yml` | Single-node dev build from source | | `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster | ## Single-Node Quickstart diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 1489e33f9..6152f75ad 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -39,6 +39,7 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-hstore-incubating-{ver ```bash # 1. Clone the source code +git clone https://github.com/apache/hugegraph.git # 2. Build the project cd hugegraph diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index 8e70aa4e5..a0c5b6d3d 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -38,6 +38,7 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-pd-incubating-{version ```bash # 1. Clone the source code +git clone https://github.com/apache/hugegraph.git # 2. Build the project cd hugegraph diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 391456528..14688d348 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -62,7 +62,7 @@ Also, if we want to manage HugeGraph-related instances in one file, we can use ` Two compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: - **Single-node quickstart** (pre-built images): `docker/docker-compose.yml` -- **Single-node dev build** (build from source): `docker/docker-compose-dev.yml` +- **Single-node dev build** (build from source): `docker/docker-compose.dev.yml` ```bash cd docker From bf9de46e9d1ddc7360fe558cf16f5e8e5eac060b Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Thu, 26 Mar 2026 12:48:58 +0530 Subject: [PATCH 06/16] docs: sync CN files - pin HUGEGRAPH_VERSION, fix image tags, restore git clone in source build --- content/cn/docs/guides/hugegraph-docker-cluster.md | 8 +++----- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 8 +++----- content/cn/docs/quickstart/hugegraph/hugegraph-pd.md | 8 +++----- content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 9 +++------ 4 files changed, 12 insertions(+), 21 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index a73e2208d..fc9cc62f0 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -15,7 +15,6 @@ HugeGraph 支持通过 Docker 桥接网络运行完整的分布式集群（PD + - Docker Engine 20.10+ 或 Docker Desktop 4.x+ - Docker Compose v2 - 3 节点集群需为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存） -- 本地克隆仓库（在更新后的镜像发布到 Docker Hub 之前的临时要求） > **已测试平台**：Linux（原生 Docker）和 macOS（Docker Desktop，已在 Apple M4 上测试）。Windows Docker Desktop 未经测试。 @@ -26,15 +25,14 @@ HugeGraph 支持通过 Docker 桥接网络运行完整的分布式集群（PD + | 文件 | 描述 | |------|------| | `docker-compose.yml` | 使用预构建镜像的单节点快速启动 | -| `docker-compose-dev.yml` | 从源码构建的单节点开发模式 | +| `docker-compose.dev.yml` | 从源码构建的单节点开发模式 | | `docker-compose-3pd-3store-3server.yml` | 3 节点分布式集群 | ## 单节点快速启动 ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose up -d +HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` 验证： @@ -46,7 +44,7 @@ curl http://localhost:8080/versions ```bash cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` 启动顺序自动强制执行： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 0447fadc3..e5d212f3b 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -39,7 +39,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-hstore-incubating-{ver ```bash # 1. 克隆源代码 -git clone https://github.com/apache/hugegraph.git # 2. 编译项目 cd hugegraph @@ -52,14 +51,13 @@ mvn clean install -DskipTests=true #### 3.3 Docker 部署 -HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/store:latest`。 +HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/store:1.7.0`。 使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` 通过 `docker run` 运行单个 Store 节点： @@ -74,7 +72,7 @@ docker run -d \ -e HG_STORE_RAFT_ADDRESS=:8510 \ -v /path/to/storage:/hugegraph-store/storage \ --name hugegraph-store \ - hugegraph/store:latest + hugegraph/store:1.7.0 ``` **环境变量参考：** diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 5beba9065..bfd56fdab 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -38,7 +38,6 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-pd-incubating-{version ```bash # 1. 克隆源代码 -git clone https://github.com/apache/hugegraph.git # 2. 编译项目 cd hugegraph @@ -51,14 +50,13 @@ mvn clean install -DskipTests=true #### 3.3 Docker 部署 -HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd:latest`。 +HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd:1.7.0`。 使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` 通过 `docker run` 运行单个 PD 节点时，通过环境变量提供配置： @@ -74,7 +72,7 @@ docker run -d \ -e HG_PD_INITIAL_STORE_LIST=:8500 \ -v /path/to/data:/hugegraph-pd/pd_data \ --name hugegraph-pd \ - hugegraph/pd:latest + hugegraph/pd:1.7.0 ``` **环境变量参考：** diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 7dbdc9c77..08e32b048 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -61,11 +61,11 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了两个 compose 文件： - **单节点快速启动**（预构建镜像）：`docker/docker-compose.yml` -- **单节点开发构建**（从源码构建）：`docker/docker-compose-dev.yml` +- **单节点开发构建**（从源码构建）：`docker/docker-compose.dev.yml` ```bash cd docker -docker compose up -d +HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` 如需开启鉴权，可在 compose 文件的环境变量中添加 `PASSWORD=xxx`，或在 `docker run` 命令中传入 `-e PASSWORD=xxx`。 @@ -93,7 +93,6 @@ tar zxf *hugegraph*.tar.gz 下载 HugeGraph 源代码 ```bash -git clone https://github.com/apache/hugegraph.git ``` 编译打包生成 tar 包 @@ -312,12 +311,10 @@ bin/stop-hugegraph.sh 通过 Docker 运行完整的分布式集群（3 PD + 3 Store + 3 Server）： -> **前置条件**：为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。需要克隆仓库（在更新后的镜像发布之前的临时要求）。 ```bash -git clone https://github.com/apache/hugegraph.git cd hugegraph/docker -docker compose -f docker-compose-3pd-3store-3server.yml up -d +HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` 服务通过 `hg-net` 桥接网络上的容器主机名进行通信。配置通过环境变量注入： From e970bbcdea4683e389aff4e323bd1a303c973750 Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Thu, 26 Mar 2026 12:54:40 +0530 Subject: [PATCH 07/16] docs: restore git clone in CN source build sections --- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 1 + content/cn/docs/quickstart/hugegraph/hugegraph-pd.md | 1 + content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 1 + 3 files changed, 3 insertions(+) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index e5d212f3b..732602fd3 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -39,6 +39,7 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-hstore-incubating-{ver ```bash # 1. 克隆源代码 +git clone https://github.com/apache/hugegraph.git # 2. 编译项目 cd hugegraph diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index bfd56fdab..df069df0c 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -38,6 +38,7 @@ cd apache-hugegraph-incubating-{version}/apache-hugegraph-pd-incubating-{version ```bash # 1. 克隆源代码 +git clone https://github.com/apache/hugegraph.git # 2. 编译项目 cd hugegraph diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 08e32b048..2fb9dba6e 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -93,6 +93,7 @@ tar zxf *hugegraph*.tar.gz 下载 HugeGraph 源代码 ```bash +git clone https://github.com/apache/hugegraph.git ``` 编译打包生成 tar 包 From 989b63938a1739728ccada3871142972ebfaea15 Mon Sep 17 00:00:00 2001 From: bitflicker64 Date: Thu, 26 Mar 2026 13:45:18 +0530 Subject: [PATCH 08/16] docs: revert HUGEGRAPH_VERSION prefix from deprecated Cassandra section --- content/en/docs/quickstart/hugegraph/hugegraph-server.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 14688d348..c84ff8b18 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -643,7 +643,7 @@ In [3.1 Use Docker container](#31-use-docker-container-convenient-for-testdev), When using Docker, we can use Cassandra as the backend storage. We highly recommend using docker-compose directly to manage both the server and Cassandra. -The sample `docker-compose.yml` can be obtained on [GitHub](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/example/docker-compose-cassandra.yml), and you can start it with `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d`. (If using Cassandra 4.0 as the backend storage, it takes approximately two minutes to initialize. Please be patient.) +The sample `docker-compose.yml` can be obtained on [GitHub](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/docker/example/docker-compose-cassandra.yml), and you can start it with `docker-compose up -d`. (If using Cassandra 4.0 as the backend storage, it takes approximately two minutes to initialize. Please be patient.) ```yaml version: "3" @@ -725,7 +725,7 @@ Set the environment variable `PRELOAD=true` when starting Docker to load data du - 8080:8080 ``` - Use `HUGEGRAPH_VERSION=1.7.0 docker-compose up -d` to start the container + Use `docker-compose up -d` to start the container And use the RESTful API to request `HugeGraphServer` and get the following result: From ae63fce46c585fe543dcfabbfa016bd2886b0da1 Mon Sep 17 00:00:00 2001 From: Himanshu Verma Date: Sun, 5 Apr 2026 13:04:21 +0530 Subject: [PATCH 09/16] docs: add docker logs tip to Docker deployment sections --- content/en/docs/guides/hugegraph-docker-cluster.md | 4 +++- content/en/docs/quickstart/hugegraph/hugegraph-hstore.md | 2 ++ content/en/docs/quickstart/hugegraph/hugegraph-pd.md | 2 ++ content/en/docs/quickstart/hugegraph/hugegraph-server.md | 3 ++- 4 files changed, 9 insertions(+), 2 deletions(-) diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 50d86a413..f300b6cc6 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -14,7 +14,7 @@ Previous versions used `network_mode: host` which only worked on Linux. The clus - Docker Engine 20.10+ or Docker Desktop 4.x+ - Docker Compose v2 -- For the 3-node cluster: at least **12 GB** memory allocated to Docker Desktop (Settings → Resources → Memory) +- For the 3-node cluster on Mac (Docker Desktop): allocate at least **12 GB** memory (Settings → Resources → Memory) > **Tested platforms**: Linux (native Docker) and macOS (Docker Desktop, tested on Apple M4). Windows Docker Desktop is untested. @@ -131,3 +131,5 @@ curl http://localhost:8620/v1/partitions # Partition assignment **Partition assignment not completing**: Check `curl http://localhost:8620/v1/stores` — all 3 stores must show `"state":"Up"` before partitions are assigned. **Connection refused**: Ensure `HG_*` env vars use container hostnames (`pd0`, `store0`), not `127.0.0.1`. + +**Viewing runtime logs**: Use `docker logs ` (e.g. `docker logs hg-pd0`) to view logs directly without exec-ing into the container. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 6152f75ad..d08ef1319 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -255,6 +255,8 @@ HG_STORE_RAFT_ADDRESS: store2:8510 Store nodes start only after all PD nodes pass healthchecks (`/v1/health`), enforced via `depends_on: condition: service_healthy`. +To view runtime logs for a running Store container use `docker logs ` (e.g. `docker logs hg-store0`). + See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full setup guide. ### 7 Verify Store Service diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index a0c5b6d3d..e3b0086df 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -93,6 +93,8 @@ docker run -d \ > **Deprecated aliases**: `GRPC_HOST`, `RAFT_ADDRESS`, `RAFT_PEERS`, `PD_INITIAL_STORE_LIST` still work but log a deprecation warning. Use the `HG_PD_*` names for new deployments. +To view runtime logs for a running PD container use `docker logs ` (e.g. `docker logs hg-pd0`). + See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full cluster setup guide. ### 4 Configuration diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index c84ff8b18..139e05907 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -56,7 +56,7 @@ If you use docker desktop, you can set the option like: image -> **Note**: The Docker compose files use bridge networking (`hg-net`) and work on Linux and Mac (Docker Desktop). For the 3-node distributed cluster, allocate at least **12 GB** memory to Docker Desktop (Settings → Resources → Memory). +> **Note**: The Docker compose files use bridge networking (`hg-net`) and work on Linux and Mac (Docker Desktop). For the 3-node distributed cluster on Mac (Docker Desktop), allocate at least **12 GB** memory (Settings → Resources → Memory). On Linux, Docker uses host memory directly. Also, if we want to manage HugeGraph-related instances in one file, we can use `docker compose` to deploy. Two compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: @@ -347,6 +347,7 @@ Verify the cluster: curl http://localhost:8080/versions curl http://localhost:8620/v1/stores ``` +To view runtime logs for any container use `docker logs ` (e.g. `docker logs hg-pd0`). See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full environment variable reference, port table, and troubleshooting guide. From d1fbee8a24fad8b9da3c09b424a843196ceba14e Mon Sep 17 00:00:00 2001 From: Himanshu Verma Date: Sun, 5 Apr 2026 13:13:15 +0530 Subject: [PATCH 10/16] docs: unify compose cd path to hugegraph/docker across all EN docs --- content/en/docs/quickstart/hugegraph/hugegraph-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 139e05907..0244ab557 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -65,7 +65,7 @@ Two compose files are available in the [`docker/`](https://github.com/apache/hug - **Single-node dev build** (build from source): `docker/docker-compose.dev.yml` ```bash -cd docker +cd hugegraph/docker HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` From d04a00139a31e84214dbe4e1411684d58b8630c0 Mon Sep 17 00:00:00 2001 From: Himanshu Verma Date: Sun, 5 Apr 2026 13:23:52 +0530 Subject: [PATCH 11/16] docs: sync CN files with EN updates --- content/cn/docs/guides/hugegraph-docker-cluster.md | 2 +- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 2 ++ content/cn/docs/quickstart/hugegraph/hugegraph-pd.md | 2 ++ content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 4 +++- 4 files changed, 8 insertions(+), 2 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index fc9cc62f0..03b7cdafa 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -14,7 +14,7 @@ HugeGraph 支持通过 Docker 桥接网络运行完整的分布式集群（PD + - Docker Engine 20.10+ 或 Docker Desktop 4.x+ - Docker Compose v2 -- 3 节点集群需为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存） +- Mac（Docker Desktop）运行 3 节点集群时，需分配至少 **12 GB** 内存（设置 → 资源 → 内存）。Linux 上 Docker 直接使用宿主机内存，无需额外分配 > **已测试平台**：Linux（原生 Docker）和 macOS（Docker Desktop，已在 Apple M4 上测试）。Windows Docker Desktop 未经测试。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 732602fd3..ffe53f19c 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -255,6 +255,8 @@ HG_STORE_RAFT_ADDRESS: store2:8510 Store 节点仅在所有 PD 节点通过健康检查（`/v1/health`）后启动，通过 `depends_on: condition: service_healthy` 强制执行。 +运行时日志可通过 `docker logs `（如 `docker logs hg-store0`）直接查看，无需进入容器。 + 完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 ### 7 验证 Store 服务 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index df069df0c..05411044a 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -93,6 +93,8 @@ docker run -d \ > **已弃用的别名**：`GRPC_HOST`、`RAFT_ADDRESS`、`RAFT_PEERS`、`PD_INITIAL_STORE_LIST` 仍可使用，但会输出弃用警告。新部署请使用 `HG_PD_*` 名称。 +运行时日志可通过 `docker logs `（如 `docker logs hg-pd0`）直接查看，无需进入容器。 + 完整的集群部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 ### 4 配置 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 2fb9dba6e..5b048ed2a 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -64,7 +64,7 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 - **单节点开发构建**（从源码构建）：`docker/docker-compose.dev.yml` ```bash -cd docker +cd hugegraph/docker HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` @@ -332,6 +332,8 @@ curl http://localhost:8080/versions curl http://localhost:8620/v1/stores ``` +运行时日志可通过 `docker logs `（如 `docker logs hg-pd0`）直接查看，无需进入容器。 + 完整的环境变量参考、端口表和故障排查指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 From f454c8c4173c7e0b0532b413d80fa92cd54a09a3 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 7 Apr 2026 19:35:05 +0800 Subject: [PATCH 12/16] docs: update Docker Compose cluster guidance Revise Chinese and English docs for HugeGraph Docker deployment to standardize on Docker Compose wording and usage. Add notes that users should clone/pull the HugeGraph repo (or at least the docker/ directory), include a reminder to keep the HUGEGRAPH_VERSION aligned with releases, and adjust memory recommendations for Mac (3-node cluster ~12 GB) with platform guidance. Clarify compose file descriptions, emphasize container hostnames for HG_* env vars, change some example log years to 2026, reformat deprecated-alias lines, and number/troubleshooting items for clarity. Minor phrasing and section-title tweaks across hugegraph-docker-cluster.md, hugegraph-hstore.md, hugegraph-pd.md, and hugegraph-server.md (EN & CN). Signed-off-by: imbajin --- .../docs/guides/hugegraph-docker-cluster.md | 43 ++++++++++--------- .../quickstart/hugegraph/hugegraph-hstore.md | 12 ++++-- .../docs/quickstart/hugegraph/hugegraph-pd.md | 8 ++-- .../quickstart/hugegraph/hugegraph-server.md | 7 +-- .../docs/guides/hugegraph-docker-cluster.md | 43 ++++++++++--------- .../quickstart/hugegraph/hugegraph-hstore.md | 13 +++--- .../docs/quickstart/hugegraph/hugegraph-pd.md | 9 ++-- .../quickstart/hugegraph/hugegraph-server.md | 7 +-- 8 files changed, 79 insertions(+), 63 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 03b7cdafa..ab3e9fd25 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -6,32 +6,33 @@ weight: 5 ## 概述 -HugeGraph 支持通过 Docker 桥接网络运行完整的分布式集群（PD + Store + Server）。该方式适用于 Linux 和 Mac（Docker Desktop）。 - -早期版本使用 `network_mode: host`，仅在 Linux 上可用。集群现在使用 Docker 桥接网络（`hg-net`），服务通过容器主机名而非 `127.0.0.1` 进行通信。 +HugeGraph 通过 Docker-Compose 可快速运行完整的分布式集群版（PD + Store + Server）。该方式适用于 Linux 和 Mac。 ## 前置条件 - Docker Engine 20.10+ 或 Docker Desktop 4.x+ - Docker Compose v2 -- Mac（Docker Desktop）运行 3 节点集群时，需分配至少 **12 GB** 内存（设置 → 资源 → 内存）。Linux 上 Docker 直接使用宿主机内存，无需额外分配 +- Mac 运行 3 节点集群时，建议分配至少 **12 GB** 内存（设置 → 资源 → 内存）。[其他平台根据实际情况调整] -> **已测试平台**：Linux（原生 Docker）和 macOS（Docker Desktop，已在 Apple M4 上测试）。Windows Docker Desktop 未经测试。 +> **已测试环境**：Linux（原生 Docker）和 macOS（Docker Desktop with ARM M4） ## Compose 文件 -[`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了三个 compose 文件： +在 HugeGraph 主仓库 [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了三个 compose 文件： | 文件 | 描述 | |------|------| -| `docker-compose.yml` | 使用预构建镜像的单节点快速启动 | -| `docker-compose.dev.yml` | 从源码构建的单节点开发模式 | -| `docker-compose-3pd-3store-3server.yml` | 3 节点分布式集群 | +| `docker-compose.yml` | 使用预构建镜像的** 1x3 单进程(节点)**快速启动 | +| `docker-compose.dev.yml` | 从源码构建的单节点**开发模式** | +| `docker-compose-3pd-3store-3server.yml` | ** 3x3 进程**(模拟节点)分布式集群 | + +> 注: 后续步骤皆为假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录) ## 单节点快速启动 ```bash cd hugegraph/docker + # 注意版本号请随时保持更新 → 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` @@ -47,12 +48,12 @@ cd hugegraph/docker HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` -启动顺序自动强制执行： -1. PD 节点首先启动，必须通过 `/v1/health` 健康检查 -2. Store 节点在所有 PD 节点健康后启动 -3. Server 节点在所有 Store 节点健康后启动 +默认内置的启动顺序： +1. PD (节点)最先启动，且必须通过 `/v1/health` 健康检查 +2. Store (节点)在所有 PD 健康后再启动 +3. Server (节点)在所有 Store + PD 健康后最后启动 -验证集群： +验证集群正常：(重要) ```bash curl http://localhost:8620/v1/health # PD 健康检查 curl http://localhost:8520/v1/health # Store 健康检查 @@ -76,7 +77,7 @@ curl http://localhost:8620/v1/partitions # 分区分配 | `HG_PD_DATA_PATH` | 否 | `/hugegraph-pd/pd_data` | `pd.data-path` | | `HG_PD_INITIAL_STORE_COUNT` | 否 | `1` | `pd.initial-store-count` | -**已弃用的别名**：`GRPC_HOST` → `HG_PD_GRPC_HOST`、`RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`、`RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` +> **已弃用的别名**：`GRPC_HOST` → `HG_PD_GRPC_HOST`、`RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`、`RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` ### Store 变量 @@ -89,7 +90,7 @@ curl http://localhost:8620/v1/partitions # 分区分配 | `HG_STORE_REST_PORT` | 否 | `8520` | `server.port` | | `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | `app.data-path` | -**已弃用的别名**：`PD_ADDRESS` → `HG_STORE_PD_ADDRESS`、`GRPC_HOST` → `HG_STORE_GRPC_HOST`、`RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` +> **已弃用的别名**：`PD_ADDRESS` → `HG_STORE_PD_ADDRESS`、`GRPC_HOST` → `HG_STORE_GRPC_HOST`、`RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` ### Server 变量 @@ -100,7 +101,7 @@ curl http://localhost:8620/v1/partitions # 分区分配 | `STORE_REST` | 否 | — | `wait-partition.sh` 使用 | | `PASSWORD` | 否 | — | 启用鉴权模式 | -**已弃用的别名**：`BACKEND` → `HG_SERVER_BACKEND`、`PD_PEERS` → `HG_SERVER_PD_PEERS` +> **已弃用的别名**：`BACKEND` → `HG_SERVER_BACKEND`、`PD_PEERS` → `HG_SERVER_PD_PEERS` ## 端口参考 @@ -124,10 +125,10 @@ curl http://localhost:8620/v1/partitions # 分区分配 ## 故障排查 -**容器 OOM 被杀（退出码 137）**：将 Docker Desktop 内存增加到 12 GB 以上。 +1. **容器 OOM 退出（exit code 137）**：将 Docker Desktop 内存增加到 12 GB 以上 (或调整被 kill 的启动 jvm 内存设置) -**Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1` +2. **Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1` -**分区分配未完成**：检查 `curl http://localhost:8620/v1/stores` — 所有 3 个 Store 必须显示 `"state":"Up"` 才能完成分区分配。 +3. **分区分配未完成**：检查 `curl http://localhost:8620/v1/stores` — 3 个 Store 必须都显示 `"state":"Up"` 才能完成分区分配 -**连接被拒**：确保 `HG_*` 环境变量使用容器主机名（`pd0`、`store0`），而非 `127.0.0.1`。 +4. **连接被拒**：确保 `HG_*` 环境变量使用容器主机名（`pd0`、`store0`），而非 `127.0.0.1` diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index ffe53f19c..00b085569 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -1,3 +1,4 @@ + --- title: "HugeGraph-Store Quick Start" linkTitle: "安装/构建 HugeGraph-Store" @@ -52,12 +53,15 @@ mvn clean install -DskipTests=true #### 3.3 Docker 部署 -HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/store:1.7.0`。 +HugeGraph-Store Docker 镜像已发布在 DockerHub，镜像名是 `hugegraph/store`。 + +> 注: 后续步骤皆假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录) -使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： +使用 docker-compose 文件部署完整的 3 节点集群（PD + Store + Server）： ```bash cd hugegraph/docker +# 注意版本号请随时保持更新 → 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` @@ -157,7 +161,7 @@ logging: 启动成功后，可以在 `logs/hugegraph-store-server.log` 中看到类似以下的日志： ``` -2024-xx-xx xx:xx:xx [main] [INFO] o.a.h.s.n.StoreNodeApplication - Started StoreNodeApplication in x.xxx seconds (JVM running for x.xxx) +2026-xx-xx 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 @@ -229,7 +233,7 @@ pdserver: address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688 ``` -#### 6.3 Docker 集群快速启动 +#### 6.3 Docker 分布式集群配置 3 节点 Store 集群包含在 `docker/docker-compose-3pd-3store-3server.yml` 中。每个 Store 节点拥有独立的主机名和环境变量： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 05411044a..bee3b147a 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -51,12 +51,14 @@ mvn clean install -DskipTests=true #### 3.3 Docker 部署 -HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd:1.7.0`。 +HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd`。 +> 注: 后续步骤皆假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录) -使用 compose 文件部署完整的 3 节点集群（PD + Store + Server）： +使用 docker-compose 模式部署完整的 3 节点集群（PD + Store + Server）： ```bash cd hugegraph/docker +# 注意版本号请随时保持更新 → 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` @@ -164,7 +166,7 @@ partition: 启动成功后，可以在 `logs/hugegraph-pd-stdout.log` 中看到类似以下的日志： ``` -2024-xx-xx xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx) +2026-xx-xx xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx) ``` #### 5.2 停止 PD diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 5b048ed2a..72b8ab281 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -57,7 +57,7 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 > **注意**：Docker compose 文件使用桥接网络（`hg-net`），适用于 Linux 和 Mac（Docker Desktop）。如需运行 3 节点分布式集群，请为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。 -另外，如果我们希望能够在一个文件中管理 HugeGraph 相关的实例，可以使用 `docker compose` 完成部署。 +另外，如果我们希望能够一体化管理 HugeGraph 多模块实例，则可以使用 `docker compose` 方式。 [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了两个 compose 文件： - **单节点快速启动**（预构建镜像）：`docker/docker-compose.yml` @@ -65,6 +65,7 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 ```bash cd hugegraph/docker +# 注意版本号请随时保持更新 → 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` @@ -308,9 +309,9 @@ curl http://localhost:8081/graphs bin/stop-hugegraph.sh ``` -#### Docker 集群快速启动 +#### Docker 分布式集群 -通过 Docker 运行完整的分布式集群（3 PD + 3 Store + 3 Server）： +通过 Docker-Compose 运行完整的分布式集群（3 PD + 3 Store + 3 Server）： ```bash diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index f300b6cc6..1992a358c 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -6,32 +6,33 @@ weight: 5 ## Overview -HugeGraph supports running a full distributed cluster (PD + Store + Server) via Docker using bridge networking. This works on Linux and Mac (Docker Desktop). - -Previous versions used `network_mode: host` which only worked on Linux. The cluster now uses a Docker bridge network (`hg-net`) where services communicate via container hostnames instead of `127.0.0.1`. +HugeGraph can quickly run a full distributed deployment (PD + Store + Server) with Docker Compose. This works on Linux and Mac. ## Prerequisites - Docker Engine 20.10+ or Docker Desktop 4.x+ - Docker Compose v2 -- For the 3-node cluster on Mac (Docker Desktop): allocate at least **12 GB** memory (Settings → Resources → Memory) +- For a 3-node cluster on Mac: allocate at least **12 GB** memory (Settings → Resources → Memory). Adjust this on other platforms as needed. -> **Tested platforms**: Linux (native Docker) and macOS (Docker Desktop, tested on Apple M4). Windows Docker Desktop is untested. +> **Tested environments**: Linux (native Docker) and macOS (Docker Desktop with ARM M4). ## Compose Files -Three compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: +Three compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory of the HugeGraph main repository: | File | Description | |------|-------------| -| `docker-compose.yml` | Single-node quickstart using pre-built images | -| `docker-compose.dev.yml` | Single-node dev build from source | -| `docker-compose-3pd-3store-3server.yml` | 3-node distributed cluster | +| `docker-compose.yml` | Quickstart for a single-host deployment using pre-built images | +| `docker-compose.dev.yml` | Development mode for a single-host deployment built from source | +| `docker-compose-3pd-3store-3server.yml` | Distributed cluster with 3 PD, 3 Store, and 3 Server processes | + +> **Note**: The following steps assume you have already cloned or pulled the HugeGraph main repository locally, or at least have its `docker/` directory available. ## Single-Node Quickstart ```bash cd hugegraph/docker +# Keep the version aligned with the latest release, for example 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` @@ -47,12 +48,12 @@ cd hugegraph/docker HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` -Startup ordering is enforced automatically: -1. PD nodes start first and must pass `/v1/health` -2. Store nodes start after all PD nodes are healthy -3. Server nodes start after all Store nodes are healthy +Built-in startup ordering: +1. PD nodes start first and must pass the `/v1/health` check +2. Store nodes start only after all PD nodes are healthy +3. Server nodes start last, after all PD and Store nodes are healthy -Verify the cluster: +Verify that the cluster is healthy: ```bash curl http://localhost:8620/v1/health # PD health curl http://localhost:8520/v1/health # Store health @@ -76,7 +77,7 @@ curl http://localhost:8620/v1/partitions # Partition assignment | `HG_PD_DATA_PATH` | No | `/hugegraph-pd/pd_data` | `pd.data-path` | | `HG_PD_INITIAL_STORE_COUNT` | No | `1` | `pd.initial-store-count` | -**Deprecated aliases**: `GRPC_HOST` → `HG_PD_GRPC_HOST`, `RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`, `RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` +> **Deprecated aliases**: `GRPC_HOST` → `HG_PD_GRPC_HOST`, `RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`, `RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST` ### Store Variables @@ -89,7 +90,7 @@ curl http://localhost:8620/v1/partitions # Partition assignment | `HG_STORE_REST_PORT` | No | `8520` | `server.port` | | `HG_STORE_DATA_PATH` | No | `/hugegraph-store/storage` | `app.data-path` | -**Deprecated aliases**: `PD_ADDRESS` → `HG_STORE_PD_ADDRESS`, `GRPC_HOST` → `HG_STORE_GRPC_HOST`, `RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` +> **Deprecated aliases**: `PD_ADDRESS` → `HG_STORE_PD_ADDRESS`, `GRPC_HOST` → `HG_STORE_GRPC_HOST`, `RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS` ### Server Variables @@ -100,7 +101,7 @@ curl http://localhost:8620/v1/partitions # Partition assignment | `STORE_REST` | No | — | used by `wait-partition.sh` | | `PASSWORD` | No | — | enables auth mode | -**Deprecated aliases**: `BACKEND` → `HG_SERVER_BACKEND`, `PD_PEERS` → `HG_SERVER_PD_PEERS` +> **Deprecated aliases**: `BACKEND` → `HG_SERVER_BACKEND`, `PD_PEERS` → `HG_SERVER_PD_PEERS` ## Port Reference @@ -124,12 +125,12 @@ curl http://localhost:8620/v1/partitions # Partition assignment ## Troubleshooting -**Containers OOM killed (exit code 137)**: Increase Docker Desktop memory to 12 GB+. +1. **Containers exit due to OOM (`exit code 137`)**: Increase Docker Desktop memory to at least 12 GB, or reduce the JVM heap settings for the process that is being killed. -**Raft leader election timeout**: Check `HG_PD_RAFT_PEERS_LIST` is identical on all PD nodes. Verify connectivity: `docker exec hg-pd0 ping pd1` +2. **Raft leader election timeout**: Check that `HG_PD_RAFT_PEERS_LIST` is identical on all PD nodes. Verify connectivity with `docker exec hg-pd0 ping pd1`. -**Partition assignment not completing**: Check `curl http://localhost:8620/v1/stores` — all 3 stores must show `"state":"Up"` before partitions are assigned. +3. **Partition assignment does not complete**: Check `curl http://localhost:8620/v1/stores` and confirm that all 3 stores show `"state":"Up"` before partition assignment can finish. -**Connection refused**: Ensure `HG_*` env vars use container hostnames (`pd0`, `store0`), not `127.0.0.1`. +4. **Connection refused**: Ensure `HG_*` environment variables use container hostnames (`pd0`, `store0`) instead of `127.0.0.1`. **Viewing runtime logs**: Use `docker logs ` (e.g. `docker logs hg-pd0`) to view logs directly without exec-ing into the container. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index d08ef1319..dac7745ef 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -52,12 +52,15 @@ mvn clean install -DskipTests=true #### 3.3 Docker Deployment -The HugeGraph-Store Docker image is available on Docker Hub as `hugegraph/store:1.7.0`. +The HugeGraph-Store Docker image is available on Docker Hub as `hugegraph/store`. -For a complete 3-node cluster with PD, Store, and Server, use the compose file: +> **Note**: The following steps assume you have already cloned or pulled the HugeGraph main repository locally, or at least have its `docker/` directory available. + +Use the compose file to deploy the complete 3-node cluster (PD + Store + Server): ```bash cd hugegraph/docker +# Keep the version aligned with the latest release, for example 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` @@ -157,7 +160,7 @@ Ensure that the PD service is already started, then in the Store installation di After successful startup, you can see logs similar to the following in `logs/hugegraph-store-server.log`: ``` -2024-xx-xx xx:xx:xx [main] [INFO] o.a.h.s.n.StoreNodeApplication - Started StoreNodeApplication in x.xxx seconds (JVM running for x.xxx) +2026-xx-xx xx:xx:xx [main] [INFO] o.a.h.s.n.StoreNodeApplication - Started StoreNodeApplication in x.xxx seconds (JVM running for x.xxx) ``` #### 5.2 Stop Store @@ -229,9 +232,9 @@ pdserver: address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688 ``` -#### 6.3 Docker Cluster Quickstart +#### 6.3 Docker Distributed Cluster Configuration -The 3-node Store cluster is included in `docker/docker-compose-3pd-3store-3server.yml`. Each Store node gets its own hostname and env vars: +The distributed Store cluster definition is included in `docker/docker-compose-3pd-3store-3server.yml`. Each Store node gets its own hostname and environment variables: ```yaml # store0 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index e3b0086df..f0e04055b 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -51,12 +51,15 @@ mvn clean install -DskipTests=true #### 3.3 Docker Deployment -The HugeGraph-PD Docker image is available on Docker Hub as `hugegraph/pd:1.7.0`. +The HugeGraph-PD Docker image is available on Docker Hub as `hugegraph/pd`. -For a complete 3-node cluster with PD, Store, and Server, use the compose file: +> **Note**: The following steps assume you have already cloned or pulled the HugeGraph main repository locally, or at least have its `docker/` directory available. + +Use the `docker compose` setup to deploy the complete 3-node cluster (PD + Store + Server): ```bash cd hugegraph/docker +# Keep the version aligned with the latest release, for example 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d ``` @@ -164,7 +167,7 @@ In the PD installation directory, execute: After successful startup, you can see logs similar to the following in `logs/hugegraph-pd-stdout.log`: ``` -2024-xx-xx xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx) +2026-xx-xx xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx) ``` #### 5.2 Stop PD diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 0244ab557..4bafc9955 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -58,7 +58,7 @@ If you use docker desktop, you can set the option like: > **Note**: The Docker compose files use bridge networking (`hg-net`) and work on Linux and Mac (Docker Desktop). For the 3-node distributed cluster on Mac (Docker Desktop), allocate at least **12 GB** memory (Settings → Resources → Memory). On Linux, Docker uses host memory directly. -Also, if we want to manage HugeGraph-related instances in one file, we can use `docker compose` to deploy. +If you want a single, unified setup for multiple HugeGraph services, you can use `docker compose`. Two compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: - **Single-node quickstart** (pre-built images): `docker/docker-compose.yml` @@ -66,6 +66,7 @@ Two compose files are available in the [`docker/`](https://github.com/apache/hug ```bash cd hugegraph/docker +# Keep the version aligned with the latest release, for example 1.x.0 HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` @@ -325,9 +326,9 @@ The sequence to stop the services should be the reverse of the startup sequence: bin/stop-hugegraph.sh ``` -#### Docker Cluster Quickstart +#### Docker Distributed Cluster -For running the full distributed cluster (3 PD + 3 Store + 3 Server) via Docker: +Run the full distributed cluster (3 PD + 3 Store + 3 Server) with Docker Compose: ```bash cd hugegraph/docker From 40a818e233bac50d11c9c6e4358e342f63248990 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 7 Apr 2026 19:56:22 +0800 Subject: [PATCH 13/16] docs: polish HugeGraph quickstart pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cleanup and wording/formatting improvements across HugeGraph quickstart docs (CN/EN) for hugegraph-hstore, hugegraph-pd and hugegraph-server. Changes include: normalize “macOS” and Docker/Docker Hub terminology; clarify Java 11/JDK guidance and authentication requirements; rephrase HugeGraph-Server naming and startup/preload descriptions for clarity; update PD config comment for initial-store-count; add/standardize PD API curl example and expanded Store JSON example; improve Docker/Docker Compose examples (including mounting example.groovy and notes about Docker Desktop memory); fix punctuation, grammar and minor layout issues. Signed-off-by: imbajin --- .../quickstart/hugegraph/hugegraph-hstore.md | 13 +-- .../docs/quickstart/hugegraph/hugegraph-pd.md | 12 ++- .../quickstart/hugegraph/hugegraph-server.md | 43 +++++----- .../quickstart/hugegraph/hugegraph-hstore.md | 48 ++++++++++- .../docs/quickstart/hugegraph/hugegraph-pd.md | 8 +- .../quickstart/hugegraph/hugegraph-server.md | 82 +++++++++---------- 6 files changed, 127 insertions(+), 79 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 00b085569..5769c859d 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -1,4 +1,3 @@ - --- title: "HugeGraph-Store Quick Start" linkTitle: "安装/构建 HugeGraph-Store" @@ -13,10 +12,10 @@ HugeGraph-Store 是 HugeGraph 分布式版本的存储节点组件，负责实 #### 2.1 前置条件 -- 操作系统：Linux 或 MacOS（Windows 尚未经过完整测试） +- 操作系统：Linux 或 macOS（Windows 尚未经过完整测试） - Java 版本：≥ 11 - Maven 版本：≥ 3.5.0 -- 已部署的 HugeGraph-PD（如果是多节点部署） +- 如需进行多节点部署，请先部署 HugeGraph-PD ### 3 部署 @@ -53,7 +52,7 @@ mvn clean install -DskipTests=true #### 3.3 Docker 部署 -HugeGraph-Store Docker 镜像已发布在 DockerHub，镜像名是 `hugegraph/store`。 +HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名是 `hugegraph/store`。 > 注: 后续步骤皆假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录) @@ -279,7 +278,9 @@ curl http://localhost:8520/actuator/health curl http://localhost:8620/v1/stores ``` -如果Store配置成功，上述接口的响应中应该包含当前节点的状态信息，状态为Up表示节点正常运行，这里只展示了一个节点配置成功的响应，如果三个节点都配置成功并正在运行，响应中`storeId`列表应该包含三个id，并且`stateCountMap`中`Up`、`numOfService`、`numOfNormalService`三个字段应该为3。 +如果 Store 配置成功，上述接口响应中应包含当前节点的状态信息，其中 `state` 为 `Up` 表示节点运行正常。 + +下方示例仅展示 1 个 Store 节点的返回结果。如果 3 个节点都已正确配置并正在运行，则响应中的 `storeId` 列表应包含 3 个 ID，且 `stateCountMap.Up`、`numOfService` 和 `numOfNormalService` 都应为 `3`。 ```javascript { "message": "OK", @@ -316,4 +317,4 @@ curl http://localhost:8620/v1/stores }, "status": 0 } -``` \ No newline at end of file +``` diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index bee3b147a..91f65f13e 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -12,7 +12,7 @@ HugeGraph-PD (Placement Driver) 是 HugeGraph 分布式版本的元数据管理 #### 2.1 前置条件 -- 操作系统：Linux 或 MacOS（Windows 尚未经过完整测试） +- 操作系统：Linux 或 macOS（Windows 尚未经过完整测试） - Java 版本：≥ 11 - Maven 版本：≥ 3.5.0 @@ -122,7 +122,7 @@ pd: data-path: ./pd_data # 自动扩容的检查周期（秒） patrol-interval: 1800 - # 初始 store 列表，在列表内的 store 自动激活 + # 集群可用所需的最小 Store 数量 initial-store-count: 1 # store 的配置信息，格式为 IP:gRPC端口 initial-store-list: 127.0.0.1:8500 @@ -186,3 +186,11 @@ curl http://localhost:8620/actuator/health ``` 如果返回 `{"status":"UP"}`，则表示 PD 服务已成功启动。 + +此外，也可以通过 PD API 查看 Store 节点状态： + +```bash +curl http://localhost:8620/v1/stores +``` + +如果响应中 `state` 为 `Up`，说明对应的 Store 节点运行正常。在一个健康的 3 节点部署中，`storeId` 列表应包含 3 个 ID，且 `stateCountMap.Up`、`numOfService` 和 `numOfNormalService` 都应为 `3`。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 72b8ab281..0e6167ebf 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -12,18 +12,18 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 > ⚠️ **重要变更**: 从 1.7.0 版本开始，MySQL、PostgreSQL、Cassandra、ScyllaDB 等遗留后端已被移除。如需使用这些后端，请使用 1.5.x 或更早版本。 -> 文档中会出现 `HugeGraph-Server` 及 `HugeGraphServer` 这两种写法，其他组件也类似。 -> 这两种写法含义上并明显差异，可以这么区分：`HugeGraph-Server` 表示服务端相关组件代码，`HugeGraphServer` 表示服务进程。 +> 文档中会出现 `HugeGraph-Server` 与 `HugeGraphServer` 两种写法，其他组件也类似。 +> 两者在含义上并无明显差异，可简单区分为：`HugeGraph-Server` 表示服务端相关组件代码，`HugeGraphServer` 表示服务进程。 ### 2 依赖 #### 2.1 安装 Java 11 (JDK 11) -请考虑在 Java 11 的环境上启动 `HugeGraph-Server`(在 1.5.0 版前，会保留对 Java 8 的基本兼容) +建议在 Java 11 环境中运行 `HugeGraph-Server`（1.5.0 之前的版本仍保留对 Java 8 的基本兼容）。 -**在往下阅读之前先执行 `java -version` 命令确认 jdk 版本** +**在继续阅读前，请先执行 `java -version` 命令确认 JDK 版本。** -> 注：使用 Java 8 启动 HugeGraph-Server 会失去一些**安全性**的保障，也会降低性能相关指标 (请尽早升级/迁移，1.7.0 不再支持) +> 注：使用 Java 8 启动 HugeGraph-Server 会失去部分**安全性**保障，也会影响性能表现。请尽早升级或迁移，1.7.0 起已不再支持 Java 8。 ### 3 部署 @@ -34,30 +34,30 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存 - 方式 3：源码编译 - 方式 4：使用 tools 工具部署 (Outdated) -**注意** 生产或对外网暴露访问的环境必须使用 Java 11 并开启 [Auth 权限认证](/cn/docs/config/config-authentication/), 否则会有安全隐患。 +**注意**：生产环境或对公网暴露的环境必须使用 Java 11，并开启 [Auth 权限认证](/cn/docs/config/config-authentication/)，否则存在安全风险。 #### 3.1 使用 Docker 容器 (便于**测试**) 可参考 [Docker 部署方式](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 -我们可以使用 `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` 去快速启动一个内置了 `RocksDB` 的 `Hugegraph server`. +可以使用 `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` 快速启动一个内置 `RocksDB` 后端的 `HugeGraph-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.9](#519-%E5%90%AF%E5%8A%A8-server-%E7%9A%84%E6%97%B6%E5%80%99%E5%88%9B%E5%BB%BA%E7%A4%BA%E4%BE%8B%E5%9B%BE) -3. 可以使用 `-e PASSWORD=xxx` 设置是否开启鉴权模式以及 admin 的密码，具体步骤可以参考 [Config Authentication](/cn/docs/config/config-authentication#使用-docker-时开启鉴权模式) +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.8](#518-%E5%90%AF%E5%8A%A8-server-%E7%9A%84%E6%97%B6%E5%80%99%E5%88%9B%E5%BB%BA%E7%A4%BA%E4%BE%8B%E5%9B%BE)。 +3. 可以使用 `-e PASSWORD=xxx` 开启鉴权模式并设置 admin 密码，具体步骤可参考 [Config Authentication](/cn/docs/config/config-authentication#使用-docker-时开启鉴权模式)。 -如果使用 docker desktop，则可以按照如下的方式设置可选项： +如果使用 Docker Desktop，则可以按如下方式设置相关选项：
image
-> **注意**：Docker compose 文件使用桥接网络（`hg-net`），适用于 Linux 和 Mac（Docker Desktop）。如需运行 3 节点分布式集群，请为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。 +> **注意**：Docker Compose 文件使用桥接网络（`hg-net`），适用于 Linux 和 Mac（Docker Desktop）。如需运行 3 节点分布式集群，请为 Docker Desktop 分配至少 **12 GB** 内存（设置 → 资源 → 内存）。Linux 上 Docker 直接使用宿主机内存。 -另外，如果我们希望能够一体化管理 HugeGraph 多模块实例，则可以使用 `docker compose` 方式。 +如果希望通过一个配置文件统一管理 HugeGraph 的多个服务实例，则可以使用 `docker compose`。 [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了两个 compose 文件： - **单节点快速启动**（预构建镜像）：`docker/docker-compose.yml` @@ -75,7 +75,7 @@ HUGEGRAPH_VERSION=1.7.0 docker compose up -d > 注意： > -> 1. hugegraph 的 docker 镜像是一个便捷版本，用于快速启动 hugegraph，并不是**官方发布物料包方式**。你可以从 [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) 中得到更多细节。 +> 1. HugeGraph 的 Docker 镜像主要用于便捷地快速启动 HugeGraph，并不是 **ASF 官方发布物料包**。你可以从 [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) 中了解更多细节。 > > 2. 推荐使用 `release tag` (如 `1.7.0/1.x.0`) 以获取稳定版。使用 `latest` tag 可以使用开发中的最新功能。 @@ -135,7 +135,6 @@ mvn package -DskipTests
过时的 tools 工具安装 -```bash #### 3.4 使用 tools 工具部署 (Outdated) HugeGraph-Tools 提供了一键部署的命令行工具，用户可以使用该工具快速地一键下载、解压、配置并启动 HugeGraph-Server 和 HugeGraph-Hubble，最新的 HugeGraph-Toolchain 中已经包含所有的这些工具，直接下载它解压就有工具包集合了 @@ -169,11 +168,11 @@ bin/hugegraph deploy -v {hugegraph-version} -p {install-path} [-u {download-path #### 5.1 使用启动脚本启动 -启动分为"首次启动"和"非首次启动"，这么区分是因为在第一次启动前需要初始化后端数据库，然后启动服务。 +启动流程分为“首次启动”和“非首次启动”。首次启动前需要先初始化后端数据库，然后再启动服务。 -而在人为停掉服务后，或者其他原因需要再次启动服务时，因为后端数据库是持久化存在的，直接启动服务即可。 +如果服务曾被手动停止，或因其他原因需要再次启动，由于后端数据库已持久化存在，通常可以直接启动服务。 -HugeGraphServer 启动时会连接后端存储并尝试检查后端存储版本号，如果未初始化后端或者后端已初始化但版本不匹配时（旧版本数据），HugeGraphServer 会启动失败，并给出错误信息。 +HugeGraphServer 启动时会连接后端存储并检查其版本信息。如果后端尚未初始化，或者已初始化但版本不匹配（例如存在旧版本数据），HugeGraphServer 会启动失败并给出错误信息。 如果需要外部访问 HugeGraphServer，请修改 `rest-server.properties` 的 `restserver.url` 配置项（默认为 `http://127.0.0.1:8080`），修改成机器名或 IP 地址。 @@ -599,7 +598,7 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK ##### 5.1.8 启动 server 的时候创建示例图 -在脚本启动时候携带 `-p true`参数，表示 preload, 即创建示例图图 +在启动脚本时携带 `-p true` 参数，表示开启 preload，即创建示例图。 ``` bin/start-hugegraph.sh -p true @@ -619,7 +618,7 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK #### 5.2 使用 Docker -在 [3.1 使用 Docker 容器](#31-使用-docker-容器-便于测试)中，我们已经介绍了如何使用 `docker` 部署 `hugegraph-server`, 我们还可以使用其他的后端存储或者设置参数在 sever 启动的时候加载样例图 +在 [3.1 使用 Docker 容器](#31-使用-docker-容器-便于测试) 中，我们已经介绍了如何使用 `docker` 部署 `hugegraph-server`。此外，也可以通过切换后端存储或设置参数，在 Server 启动时加载样例图。 ##### 5.2.1 使用 Cassandra 作为后端 @@ -681,7 +680,7 @@ volumes: 在这个 yaml 中，需要在环境变量中以 `hugegraph.`的形式进行参数传递，配置 Cassandra 相关的参数。 -具体来说，在 `hugegraph.properties` 配置文件中，提供了 `backend=xxx`, `cassandra.host=xxx` 等配置项，为了配置这些配置项，在传递环境变量的过程之中，我们需要在这些配置项前加上 `hugegrpah.`，即 `hugegraph.backend` 和 `hugegraph.cassandra.host`。 +具体来说，在 `hugegraph.properties` 配置文件中，提供了 `backend=xxx`、`cassandra.host=xxx` 等配置项。为了通过环境变量传递这些配置，需要在配置项前加上 `hugegraph.`，例如 `hugegraph.backend` 和 `hugegraph.cassandra.host`。 其他配置可以参照 [4 配置](#4-配置) @@ -689,7 +688,7 @@ volumes: ##### 5.2.2 启动 server 的时候创建示例图 -在 docker 启动的时候设置环境变量 `PRELOAD=true`, 从而实现启动脚本的时候加载数据。 +在 Docker 启动时设置环境变量 `PRELOAD=true`，即可在启动脚本执行过程中加载样例数据。 1. 使用`docker run` diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index dac7745ef..f48f3fc20 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -12,10 +12,10 @@ HugeGraph-Store is the storage node component of HugeGraph's distributed version #### 2.1 Requirements -- Operating System: Linux or MacOS (Windows has not been fully tested) +- Operating System: Linux or macOS (Windows has not been fully tested) - Java version: ≥ 11 - Maven version: ≥ 3.5.0 -- Deployed HugeGraph-PD (for multi-node deployment) +- Deploy HugeGraph-PD first for multi-node deployment ### 3 Deployment @@ -275,5 +275,47 @@ If it returns `{"status":"UP"}`, it indicates that the Store service has been su Additionally, you can check the status of Store nodes in the cluster through the PD API: ```bash -curl http://localhost:8620/pd/api/v1/stores +curl http://localhost:8620/v1/stores +``` + +If Store is configured successfully, the response should include status information for the current node, and `state: "Up"` means the node is running normally. + +The example below shows a single Store node. If all three nodes are configured correctly and running, the `storeId` list should contain three IDs, and `stateCountMap.Up`, `numOfService`, and `numOfNormalService` should all be `3`. + +```javascript +{ + "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.5.0/apache-hugegraph-store-incubating-1.5.0/lib/hg-store-node-1.5.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 +} ``` diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index f0e04055b..fe21c9156 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -12,7 +12,7 @@ HugeGraph-PD (Placement Driver) is the metadata management component of HugeGrap #### 2.1 Requirements -- Operating System: Linux or MacOS (Windows has not been fully tested) +- Operating System: Linux or macOS (Windows has not been fully tested) - Java version: ≥ 11 - Maven version: ≥ 3.5.0 @@ -123,7 +123,7 @@ pd: data-path: ./pd_data # Auto-expansion check cycle (seconds) patrol-interval: 1800 - # Initial store list, stores in the list are automatically activated + # Minimum number of Store nodes required for cluster availability initial-store-count: 1 # Store configuration information, format is IP:gRPC port initial-store-list: 127.0.0.1:8500 @@ -188,13 +188,13 @@ curl http://localhost:8620/actuator/health If it returns `{"status":"UP"}`, it indicates that the PD service has been successfully started. -Additionally, you can verify the status of the Store node by querying the PD API: +Additionally, you can verify Store node status through the PD API: ```bash curl http://localhost:8620/v1/stores ``` -If the Store is configured successfully, the response of the above interface should contain the status information of the current node. The status "Up" indicates that the node is running normally. Only the response of one node configuration is shown here. If all three nodes are configured successfully and are running, the `storeId` list in the response should contain three IDs, and the `Up`, `numOfService`, and `numOfNormalService` fields in `stateCountMap` should be 3. +If the response shows `state` as `Up`, the corresponding Store node is running normally. The example below shows a single Store node. In a healthy 3-node deployment, the `storeId` list should contain three IDs, and `stateCountMap.Up`, `numOfService`, and `numOfNormalService` should all be `3`. ```javascript { diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 4bafc9955..990774cfd 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -6,27 +6,23 @@ weight: 1 ### 1 HugeGraph-Server Overview -`HugeGraph-Server` is the core part of the HugeGraph Project, contains submodules such as graph-core, backend, API. +`HugeGraph-Server` is the core server component of the HugeGraph project. It includes submodules such as graph-core, backend, and API. -The Core Module is an implementation of the Tinkerpop interface; The Backend module is used to save the graph data to the data store. For version 1.7.0+, supported backends include: RocksDB (standalone default), HStore (distributed), HBase, and Memory. The API Module provides HTTP Server, which converts Client's HTTP request into a call to Core Module. +The Core module implements the TinkerPop interfaces. The Backend module manages data storage. Starting from 1.7.0, supported backends include RocksDB (the default standalone backend), HStore (distributed), HBase, and Memory. The API module provides an HTTP server that converts client requests into calls to the Core module. > ⚠️ **Important Change**: Starting from version 1.7.0, legacy backends such as MySQL, PostgreSQL, Cassandra, and ScyllaDB have been removed. If you need to use these backends, please use version 1.5.x or earlier. -> There will be two spellings HugeGraph-Server and HugeGraphServer in the document, and other -> modules are similar. There is no big difference in the meaning of these two ways, -> which can be distinguished as follows: `HugeGraph-Server` represents the code of server-related -> components, `HugeGraphServer` represents the service process. +> The documentation uses both `HugeGraph-Server` and `HugeGraphServer`, and the same pattern applies to other components. The two names are nearly interchangeable: `HugeGraph-Server` usually refers to the server-side codebase, while `HugeGraphServer` refers to the running service process. ### 2 Dependency for Building/Running #### 2.1 Install Java 11 (JDK 11) -You need to use Java 11 to run `HugeGraph-Server` (compatible with Java 8 before 1.5.0, but not recommended to use), -and configure by yourself. +Use Java 11 to run `HugeGraph-Server`. Versions earlier than 1.5.0 kept basic compatibility with Java 8, but Java 11 is recommended. -**Be sure to execute the `java -version` command to check the jdk version before reading** +**Before continuing, run `java -version` to confirm your JDK version.** -> Note: Using Java8 will lose some security guarantees, we recommend using Java11 in production +> Note: Running HugeGraph-Server on Java 8 loses some security protections and may reduce performance. Please upgrade as soon as possible. Java 8 is no longer supported starting from 1.7.0. ### 3 Deploy @@ -37,26 +33,26 @@ There are four ways to deploy HugeGraph-Server components: - Method 3: Source code compilation - Method 4: One-click deployment -**Note:** If it's exposed to the public network, **must enable** [Auth authentication](/docs/config/config-authentication/) to ensure safety (so as the legacy version). +**Note:** For production environments or environments exposed to the public network, you must use Java 11 and enable [Auth authentication](/docs/config/config-authentication/) to avoid security risks. #### 3.1 Use Docker container (Convenient for Test/Dev) You can refer to the [Docker deployment guide](https://github.com/apache/hugegraph/blob/master/docker/README.md). -We can use `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` to quickly start a `HugeGraph Server` with a built-in `RocksDB` backend. +You can use `docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0` to quickly start a `HugeGraph-Server` instance with a built-in `RocksDB` backend. Optional: -1. use `docker exec -it graph bash` to enter the container to do some operations. -2. use `docker run -itd --name=graph -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0` to start with a **built-in** example graph. We can use `RESTful API` to verify the result. The detailed step can refer to [5.1.8](#518-create-an-example-graph-when-startup) -3. use `-e PASSWORD=xxx` to enable auth mode and set the password for admin. You can find more details from [Config Authentication](/docs/config/config-authentication#use-docker-to-enable-authentication-mode) +1. You can use `docker exec -it server bash` to enter the container for troubleshooting or other maintenance operations. +2. You can use `docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0` to preload a **built-in** sample graph at startup. You can verify it through the `RESTful API`. See [5.1.8](#518-create-an-example-graph-when-startup) for details. +3. You can use `-e PASSWORD=xxx` to enable authentication mode and set the admin password. See [Config Authentication](/docs/config/config-authentication#use-docker-to-enable-authentication-mode) for details. -If you use docker desktop, you can set the option like: +If you use Docker Desktop, you can set the options as follows:
image
-> **Note**: The Docker compose files use bridge networking (`hg-net`) and work on Linux and Mac (Docker Desktop). For the 3-node distributed cluster on Mac (Docker Desktop), allocate at least **12 GB** memory (Settings → Resources → Memory). On Linux, Docker uses host memory directly. +> **Note**: The Docker Compose files use bridge networking (`hg-net`) and work on Linux and Mac (Docker Desktop). For the 3-node distributed cluster on Mac (Docker Desktop), allocate at least **12 GB** of memory (Settings → Resources → Memory). On Linux, Docker uses host memory directly. If you want a single, unified setup for multiple HugeGraph services, you can use `docker compose`. Two compose files are available in the [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) directory: @@ -76,11 +72,11 @@ See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/RE > Note: > -> 1. The docker image of the hugegraph is a convenient release to start it quickly, but not **official distribution** artifacts. You can find more details from [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub). +> 1. HugeGraph Docker images are provided as a convenient way to start HugeGraph quickly, but they are not official ASF distribution artifacts. You can find more details in the [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub). > -> 2. Recommend to use `release tag` (like `1.7.0`/`1.x.0`) for the stable version. Use `latest` tag to experience the newest functions in development. +> 2. We recommend using a release tag (such as `1.7.0` or `1.x.0`) for stable deployments. Use the `latest` tag only if you want the newest features still under development. -#### 3.2 Download the binary tar tarball +#### 3.2 Download the binary tarball You could download the binary tarball from the download page of the ASF site like this: ```bash @@ -188,13 +184,13 @@ For detailed configuration introduction, please refer to [configuration document #### 5.1 Use a startup script to startup -The startup is divided into "first startup" and "non-first startup." This distinction is because the back-end database needs to be initialized before the first startup, and then the service is started. -after the service is stopped artificially, or when the service needs to be started again for other reasons, because the backend database is persistent, you can start the service directly. +Startup is divided into "first startup" and "non-first startup". On the first startup, you need to initialize the backend database before starting the service. -When HugeGraphServer starts, it will connect to the backend storage and try to check the version number of the backend storage. If the backend is not initialized or the backend has been initialized but the version does not match (old version data), HugeGraphServer will fail to start and give an error message. +If the service was stopped manually, or needs to be started again for any other reason, you can usually start it directly because the backend database is persistent. -If you need to access HugeGraphServer externally, please modify the `restserver.url` configuration item of `rest-server.properties` -（default is `http://127.0.0.1:8080`）, change to machine name or IP address. +When HugeGraphServer starts, it connects to the backend storage and checks its version information. If the backend has not been initialized, or if it was initialized with an incompatible version (for example, old-version data), HugeGraphServer will fail to start and report an error. + +If you need to access HugeGraphServer externally, modify the `restserver.url` configuration item in `rest-server.properties` (the default is `http://127.0.0.1:8080`) and change it to the machine name or IP address. Since the configuration (hugegraph.properties) and startup steps required by various backends are slightly different, the following will introduce the configuration and startup of each backend one by one. @@ -613,7 +609,7 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK ##### 5.1.8 Create an example graph when startup -Carry the `-p true` arguments when starting the script, which indicates `preload`, to create a sample graph. +Pass the `-p true` argument when starting the script to enable `preload`, which creates a sample graph. ``` bin/start-hugegraph.sh -p true @@ -634,7 +630,7 @@ This indicates the successful creation of the sample graph. #### 5.2 Use Docker to startup -In [3.1 Use Docker container](#31-use-docker-container-convenient-for-testdev), we have introduced how to use docker to deploy `hugegraph-server`. `server` can also preload an example graph by setting the parameter. +In [3.1 Use Docker container](#31-use-docker-container-convenient-for-testdev), we introduced how to deploy `hugegraph-server` with Docker. You can also switch storage backends or preload a sample graph by setting the corresponding parameters. ##### 5.2.1 Uses Cassandra as storage @@ -696,15 +692,15 @@ volumes: In this YAML file, configuration parameters related to Cassandra need to be passed as environment variables in the format of `hugegraph.`. -Specifically, in the configuration file `hugegraph.properties` , there are settings like `backend=xxx` and `cassandra.host=xxx`. To configure these settings during the process of passing environment variables, we need to prepend `hugegraph.` to these configurations, like `hugegraph.backend` and `hugegraph.cassandra.host`. +Specifically, the `hugegraph.properties` file contains settings such as `backend=xxx` and `cassandra.host=xxx`. To pass these settings through environment variables, prepend `hugegraph.` to the configuration keys, for example `hugegraph.backend` and `hugegraph.cassandra.host`. -The rest of the configurations can be referenced under [4 config](#4-config) +Refer to [4 Config](#4-config) for the remaining settings.
##### 5.2.2 Create an example graph when starting a server -Set the environment variable `PRELOAD=true` when starting Docker to load data during the execution of the startup script. +Set the environment variable `PRELOAD=true` when starting Docker so that sample data is loaded during startup. 1. Use `docker run` @@ -712,22 +708,24 @@ Set the environment variable `PRELOAD=true` when starting Docker to load data du 2. Use `docker-compose` - Create `docker-compose.yml` as following. We should set the environment variable `PRELOAD=true`. [`example.groovy`](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/scripts/example.groovy) is a predefined script to preload the sample data. If needed, we can mount a new `example.groovy` to change the preload data. + Create a `docker-compose.yml` file like the following and set `PRELOAD=true` in the environment. [`example.groovy`](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/scripts/example.groovy) is a predefined script used to preload sample data. If needed, you can mount a new `example.groovy` script to change the preload data. ```yaml version: '3' - services: - server: - image: hugegraph/hugegraph:1.7.0 - container_name: server - environment: - - PRELOAD=true - - PASSWORD=xxx - ports: - - 8080:8080 + services: + server: + image: hugegraph/hugegraph:1.7.0 + container_name: server + environment: + - PRELOAD=true + - PASSWORD=xxx + volumes: + - /path/to/yourscript:/hugegraph/scripts/example.groovy + ports: + - 8080:8080 ``` - Use `docker-compose up -d` to start the container + Use `docker-compose up -d` to start the container. And use the RESTful API to request `HugeGraphServer` and get the following result: @@ -737,7 +735,7 @@ And use the RESTful API to request `HugeGraphServer` and get the following resul {"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}}]} ``` -This indicates the successful creation of the sample graph. +This indicates that the sample graph was created successfully. ### 6. Access server From fa53ee278dd31452ed98580cee1476e10af20241 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 7 Apr 2026 20:02:58 +0800 Subject: [PATCH 14/16] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- content/cn/docs/guides/hugegraph-docker-cluster.md | 2 +- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 2 +- content/en/docs/guides/hugegraph-docker-cluster.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index ab3e9fd25..a3f6578b6 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -1,7 +1,7 @@ --- title: "HugeGraph Docker 集群部署指南" linkTitle: "Docker 集群" -weight: 5 +weight: 6 --- ## 概述 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 5769c859d..b92576bc4 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -256,7 +256,7 @@ HG_STORE_GRPC_HOST: store2 HG_STORE_RAFT_ADDRESS: store2:8510 ``` -Store 节点仅在所有 PD 节点通过健康检查（`/v1/health`）后启动，通过 `depends_on: condition: service_healthy` 强制执行。 +Store 节点仅在所有 PD 节点通过健康检查后才会启动，其中 docker-compose 中的 healthcheck 实际访问的是 PD 的 REST 接口 `/v1/health`（也可以通过 Actuator 暴露的 `/actuator/health` 进行手动检查），并通过 `depends_on: condition: service_healthy` 强制执行依赖关系。 运行时日志可通过 `docker logs `（如 `docker logs hg-store0`）直接查看，无需进入容器。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 1992a358c..6b742f6ae 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -1,7 +1,7 @@ --- title: "HugeGraph Docker Cluster Guide" linkTitle: "Docker Cluster" -weight: 5 +weight: 6 --- ## Overview From 353877c1b0d65c0f04c546c657c1f779658cb2be Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 7 Apr 2026 20:17:12 +0800 Subject: [PATCH 15/16] Lower heading level Demote the "Docker Distributed Cluster" section heading from H4 to H6 in both English and Chinese quickstart pages to correct the document hierarchy and formatting (files updated: content/en/docs/quickstart/hugegraph/hugegraph-server.md and content/cn/docs/quickstart/hugegraph/hugegraph-server.md). Signed-off-by: imbajin --- content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 2 +- content/en/docs/quickstart/hugegraph/hugegraph-server.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 0e6167ebf..8ecc4a08f 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -308,7 +308,7 @@ curl http://localhost:8081/graphs bin/stop-hugegraph.sh ``` -#### Docker 分布式集群 +###### Docker 分布式集群 通过 Docker-Compose 运行完整的分布式集群（3 PD + 3 Store + 3 Server）： diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 990774cfd..84469f08e 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -322,7 +322,7 @@ The sequence to stop the services should be the reverse of the startup sequence: bin/stop-hugegraph.sh ``` -#### Docker Distributed Cluster +###### Docker Distributed Cluster Run the full distributed cluster (3 PD + 3 Store + 3 Server) with Docker Compose: From 9f455103397abb1894243985289f10d6763c2358 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 7 Apr 2026 20:33:44 +0800 Subject: [PATCH 16/16] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 2 +- content/cn/docs/quickstart/hugegraph/hugegraph-pd.md | 2 +- content/en/docs/quickstart/hugegraph/hugegraph-hstore.md | 2 +- content/en/docs/quickstart/hugegraph/hugegraph-pd.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index b92576bc4..d07fdfe2a 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -160,7 +160,7 @@ logging: 启动成功后，可以在 `logs/hugegraph-store-server.log` 中看到类似以下的日志： ``` -2026-xx-xx xx:xx:xx [main] [INFO] o.a.h.s.n.StoreNodeApplication - Started StoreNodeApplication in x.xxx seconds (JVM running for x.xxx) +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 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 91f65f13e..6602cbd94 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -166,7 +166,7 @@ partition: 启动成功后，可以在 `logs/hugegraph-pd-stdout.log` 中看到类似以下的日志： ``` -2026-xx-xx xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx) +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) ``` #### 5.2 停止 PD diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index f48f3fc20..9c357de63 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -160,7 +160,7 @@ Ensure that the PD service is already started, then in the Store installation di After successful startup, you can see logs similar to the following in `logs/hugegraph-store-server.log`: ``` -2026-xx-xx xx:xx:xx [main] [INFO] o.a.h.s.n.StoreNodeApplication - Started StoreNodeApplication in x.xxx seconds (JVM running for x.xxx) +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 Stop Store diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index fe21c9156..9f30bd794 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -167,7 +167,7 @@ In the PD installation directory, execute: After successful startup, you can see logs similar to the following in `logs/hugegraph-pd-stdout.log`: ``` -2026-xx-xx xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx) +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) ``` #### 5.2 Stop PD