doc: add docker-compose guide and update deployment docs

content/cn/docs/guides/hugegraph-docker-cluster.md

@@ -0,0 +1,134 @@
+---
+title: "HugeGraph Docker 集群部署指南"
+linkTitle: "Docker 集群"
+weight: 6
+---
+
+## 概述
+
+HugeGraph 通过 Docker-Compose 可快速运行完整的分布式集群版（PD + Store + Server）。该方式适用于 Linux 和 Mac。
+
+## 前置条件
+
+- Docker Engine 20.10+ 或 Docker Desktop 4.x+
+- Docker Compose v2
+- Mac 运行 3 节点集群时，建议分配至少 **12 GB** 内存（设置 → 资源 → 内存）。[其他平台根据实际情况调整]
+
+> **已测试环境**：Linux（原生 Docker）和 macOS（Docker Desktop with ARM M4）
+
+## Compose 文件
+
+在 HugeGraph 主仓库 [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了三个 compose 文件：
+
+| 文件 | 描述 |
+|------|------|
+| `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
+```
+
+验证：
+```bash
+curl http://localhost:8080/versions
+```
+
+## 3 节点集群快速启动
+
+```bash
+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 + PD 健康后最后启动
+
+验证集群正常：(重要)
+```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 |
+
+## 故障排查
+
+1. **容器 OOM 退出（exit code 137）**：将 Docker Desktop 内存增加到 12 GB 以上 (或调整被 kill 的启动 jvm 内存设置)
+
+2. **Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1`
+
+3. **分区分配未完成**：检查 `curl http://localhost:8620/v1/stores` — 3 个 Store 必须都显示 `"state":"Up"` 才能完成分区分配
+
+4. **连接被拒**：确保 `HG_*` 环境变量使用容器主机名（`pd0`、`store0`），而非 `127.0.0.1`

content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md

@@ -12,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 部署
 
@@ -50,6 +50,50 @@ mvn clean install -DskipTests=true
 #    target/apache-hugegraph-incubating-{version}.tar.gz
 ```
 
+#### 3.3 Docker 部署
+
+HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名是 `hugegraph/store`。
+
+> 注: 后续步骤皆假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录)
+
+使用 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
+```
+
+通过 `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:1.7.0
+```
+
+**环境变量参考：**
+
+| 变量 | 必填 | 默认值 | 描述 |
+|------|------|--------|------|
+| `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`，以下是关键配置项：
@@ -116,7 +160,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)
+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
@@ -188,6 +232,36 @@ 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 节点通过健康检查后才会启动，其中 docker-compose 中的 healthcheck 实际访问的是 PD 的 REST 接口 `/v1/health`（也可以通过 Actuator 暴露的 `/actuator/health` 进行手动检查），并通过 `depends_on: condition: service_healthy` 强制执行依赖关系。
+
+运行时日志可通过 `docker logs <container-name>`（如 `docker logs hg-store0`）直接查看，无需进入容器。
+
+完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。
+
 ### 7 验证 Store 服务
 
 确认 Store 服务是否正常运行：
@@ -204,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",
@@ -241,4 +317,4 @@ curl http://localhost:8620/v1/stores
   },
   "status": 0
 }
-```
+```

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
 
@@ -49,6 +49,56 @@ mvn clean install -DskipTests=true
 #    target/apache-hugegraph-incubating-{version}.tar.gz
 ```
 
+#### 3.3 Docker 部署
+
+HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd`。
+> 注: 后续步骤皆假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录)
+
+使用 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
+```
+
+通过 `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:1.7.0
+```
+
+**环境变量参考：**
+
+| 变量 | 必填 | 默认值 | 描述 |
+|------|------|--------|------|
+| `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 logs <container-name>`（如 `docker logs hg-pd0`）直接查看，无需进入容器。
+
+完整的集群部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。
+
 ### 4 配置
 
 PD 的主要配置文件为 `conf/application.yml`，以下是关键配置项：
@@ -72,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
@@ -116,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)
+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
@@ -136,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`。