apache · bitflicker64 · Mar 7, 2026 · Mar 7, 2026
diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md 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
@@ -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=<pd-ip>:8686 \
+  -e HG_STORE_GRPC_HOST=<your-ip> \
+  -e HG_STORE_RAFT_ADDRESS=<your-ip>:8510 \
+  -v /path/to/storage:/hugegraph-store/storage \
+  --name hugegraph-store \
+  hugegraph/store: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
@@ -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=<your-ip> \
+  -e HG_PD_RAFT_ADDRESS=<your-ip>:8610 \
+  -e HG_PD_RAFT_PEERS_LIST=<your-ip>:8610 \
+  -e HG_PD_INITIAL_STORE_LIST=<store-ip>:8500 \
+  -v /path/to/data:/hugegraph-pd/pd_data \
+  --name hugegraph-pd \
+  hugegraph/pd: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
@@ -39,7 +39,7 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存
 #### 3.1 使用 Docker 容器 (便于**测试**)
 <!-- 3.1 is linked by another place. if change 3.1's title, please check -->
 
-可参考 [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,23 @@ Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存
 </div>
 
 
-另外，如果我们希望能够在一个文件中管理除了 `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
 ```
 
+如需开启鉴权，可在 compose 文件的环境变量中添加 `PASSWORD=xxx`，或在 `docker run` 命令中传入 `-e PASSWORD=xxx`。
+
+完整的部署指南请参阅 [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 +307,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)。
 </details>
 
 ##### 5.1.2 RocksDB / ToplingDB