Skip to content

Commit 1fda07c

Browse files
bitflicker64imbajinCopilot
authored
doc: add docker-compose guide and update deployment docs (#455)
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 <jin@apache.org> Co-authored-by: imbajin <jin@apache.org> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 5a3027b commit 1fda07c

File tree

8 files changed

+733
-108
lines changed

8 files changed

+733
-108
lines changed

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

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: "HugeGraph Docker 集群部署指南"
3+
linkTitle: "Docker 集群"
4+
weight: 6
5+
---
6+
7+
## 概述
8+
9+
HugeGraph 通过 Docker-Compose 可快速运行完整的分布式集群版（PD + Store + Server）。该方式适用于 Linux 和 Mac。
10+
11+
## 前置条件
12+
13+
- Docker Engine 20.10+ 或 Docker Desktop 4.x+
14+
- Docker Compose v2
15+
- Mac 运行 3 节点集群时，建议分配至少 **12 GB** 内存（设置 → 资源 → 内存）。[其他平台根据实际情况调整]
16+
17+
> **已测试环境**：Linux（原生 Docker）和 macOS（Docker Desktop with ARM M4）
18+
19+
## Compose 文件
20+
21+
在 HugeGraph 主仓库 [`docker/`](https://github.com/apache/hugegraph/tree/master/docker) 目录下提供了三个 compose 文件：
22+
23+
| 文件 | 描述 |
24+
|------|------|
25+
| `docker-compose.yml` | 使用预构建镜像的** 1x3 单进程(节点)**快速启动 |
26+
| `docker-compose.dev.yml` | 从源码构建的单节点**开发模式** |
27+
| `docker-compose-3pd-3store-3server.yml` | ** 3x3 进程**(模拟节点)分布式集群 |
28+
29+
> 注: 后续步骤皆为假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录)
30+
31+
## 单节点快速启动
32+
33+
```bash
34+
cd hugegraph/docker
35+
# 注意版本号请随时保持更新 → 1.x.0
36+
HUGEGRAPH_VERSION=1.7.0 docker compose up -d
37+
```
38+
39+
验证：
40+
```bash
41+
curl http://localhost:8080/versions
42+
```
43+
44+
## 3 节点集群快速启动
45+
46+
```bash
47+
cd hugegraph/docker
48+
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d
49+
```
50+
51+
默认内置的启动顺序：
52+
1. PD (节点)最先启动，且必须通过 `/v1/health` 健康检查
53+
2. Store (节点)在所有 PD 健康后再启动
54+
3. Server (节点)在所有 Store + PD 健康后最后启动
55+
56+
验证集群正常：(重要)
57+
```bash
58+
curl http://localhost:8620/v1/health # PD 健康检查
59+
curl http://localhost:8520/v1/health # Store 健康检查
60+
curl http://localhost:8080/versions # Server
61+
curl http://localhost:8620/v1/stores # 已注册的 Store
62+
curl http://localhost:8620/v1/partitions # 分区分配
63+
```
64+
65+
## 环境变量参考
66+
67+
### PD 变量
68+
69+
| 变量 | 必填 | 默认值 | 映射配置 |
70+
|------|------|--------|----------|
71+
| `HG_PD_GRPC_HOST` | 是 | — | `grpc.host` |
72+
| `HG_PD_RAFT_ADDRESS` | 是 | — | `raft.address` |
73+
| `HG_PD_RAFT_PEERS_LIST` | 是 | — | `raft.peers-list` |
74+
| `HG_PD_INITIAL_STORE_LIST` | 是 | — | `pd.initial-store-list` |
75+
| `HG_PD_GRPC_PORT` | 否 | `8686` | `grpc.port` |
76+
| `HG_PD_REST_PORT` | 否 | `8620` | `server.port` |
77+
| `HG_PD_DATA_PATH` | 否 | `/hugegraph-pd/pd_data` | `pd.data-path` |
78+
| `HG_PD_INITIAL_STORE_COUNT` | 否 | `1` | `pd.initial-store-count` |
79+
80+
> **已弃用的别名**：`GRPC_HOST` → `HG_PD_GRPC_HOST`、`RAFT_ADDRESS` → `HG_PD_RAFT_ADDRESS`、`RAFT_PEERS` → `HG_PD_RAFT_PEERS_LIST`
81+
82+
### Store 变量
83+
84+
| 变量 | 必填 | 默认值 | 映射配置 |
85+
|------|------|--------|----------|
86+
| `HG_STORE_PD_ADDRESS` | 是 | — | `pdserver.address` |
87+
| `HG_STORE_GRPC_HOST` | 是 | — | `grpc.host` |
88+
| `HG_STORE_RAFT_ADDRESS` | 是 | — | `raft.address` |
89+
| `HG_STORE_GRPC_PORT` | 否 | `8500` | `grpc.port` |
90+
| `HG_STORE_REST_PORT` | 否 | `8520` | `server.port` |
91+
| `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | `app.data-path` |
92+
93+
> **已弃用的别名**：`PD_ADDRESS` → `HG_STORE_PD_ADDRESS`、`GRPC_HOST` → `HG_STORE_GRPC_HOST`、`RAFT_ADDRESS` → `HG_STORE_RAFT_ADDRESS`
94+
95+
### Server 变量
96+
97+
| 变量 | 必填 | 默认值 | 映射配置 |
98+
|------|------|--------|----------|
99+
| `HG_SERVER_BACKEND` | 是 | — | `hugegraph.properties` 中的 `backend` |
100+
| `HG_SERVER_PD_PEERS` | 是 | — | `pd.peers` |
101+
| `STORE_REST` | 否 | — | `wait-partition.sh` 使用 |
102+
| `PASSWORD` | 否 | — | 启用鉴权模式 |
103+
104+
> **已弃用的别名**：`BACKEND` → `HG_SERVER_BACKEND`、`PD_PEERS` → `HG_SERVER_PD_PEERS`
105+
106+
## 端口参考
107+
108+
| 服务 | 宿主机端口 | 用途 |
109+
|------|-----------|------|
110+
| pd0 | 8620 | REST API |
111+
| pd0 | 8686 | gRPC |
112+
| pd1 | 8621 | REST API |
113+
| pd1 | 8687 | gRPC |
114+
| pd2 | 8622 | REST API |
115+
| pd2 | 8688 | gRPC |
116+
| store0 | 8500 | gRPC |
117+
| store0 | 8520 | REST API |
118+
| store1 | 8501 | gRPC |
119+
| store1 | 8521 | REST API |
120+
| store2 | 8502 | gRPC |
121+
| store2 | 8522 | REST API |
122+
| server0 | 8080 | Graph API |
123+
| server1 | 8081 | Graph API |
124+
| server2 | 8082 | Graph API |
125+
126+
## 故障排查
127+
128+
1. **容器 OOM 退出（exit code 137）**：将 Docker Desktop 内存增加到 12 GB 以上 (或调整被 kill 的启动 jvm 内存设置)
129+
130+
2. **Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker exec hg-pd0 ping pd1`
131+
132+
3. **分区分配未完成**：检查 `curl http://localhost:8620/v1/stores` — 3 个 Store 必须都显示 `"state":"Up"` 才能完成分区分配
133+
134+
4. **连接被拒**：确保 `HG_*` 环境变量使用容器主机名（`pd0`、`store0`），而非 `127.0.0.1`

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

Lines changed: 81 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ HugeGraph-Store 是 HugeGraph 分布式版本的存储节点组件，负责实
1212

1313
#### 2.1 前置条件
1414

15-
- 操作系统：Linux 或 MacOS（Windows 尚未经过完整测试）
15+
- 操作系统：Linux 或 macOS（Windows 尚未经过完整测试）
1616
- Java 版本：≥ 11
1717
- Maven 版本：≥ 3.5.0
18-
- 已部署的 HugeGraph-PD（如果是多节点部署）
18+
- 如需进行多节点部署，请先部署 HugeGraph-PD
1919

2020
### 3 部署
2121

@@ -50,6 +50,50 @@ mvn clean install -DskipTests=true
5050
# target/apache-hugegraph-incubating-{version}.tar.gz
5151
```
5252

53+
#### 3.3 Docker 部署
54+
55+
HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名是 `hugegraph/store`。
56+
57+
> 注: 后续步骤皆假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录)
58+
59+
使用 docker-compose 文件部署完整的 3 节点集群（PD + Store + Server）：
60+
61+
```bash
62+
cd hugegraph/docker
63+
# 注意版本号请随时保持更新 → 1.x.0
64+
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d
65+
```
66+
67+
通过 `docker run` 运行单个 Store 节点：
68+
69+
```bash
70+
docker run -d \
71+
-p 8520:8520 \
72+
-p 8500:8500 \
73+
-p 8510:8510 \
74+
-e HG_STORE_PD_ADDRESS=<pd-ip>:8686 \
75+
-e HG_STORE_GRPC_HOST=<your-ip> \
76+
-e HG_STORE_RAFT_ADDRESS=<your-ip>:8510 \
77+
-v /path/to/storage:/hugegraph-store/storage \
78+
--name hugegraph-store \
79+
hugegraph/store:1.7.0
80+
```
81+
82+
**环境变量参考：**
83+
84+
| 变量 | 必填 | 默认值 | 描述 |
85+
|------|------|--------|------|
86+
| `HG_STORE_PD_ADDRESS` | 是 | — | PD gRPC 地址（如 `pd0:8686,pd1:8686,pd2:8686`） |
87+
| `HG_STORE_GRPC_HOST` | 是 | — | 本节点的 gRPC 主机名/IP（如 `store0`） |
88+
| `HG_STORE_RAFT_ADDRESS` | 是 | — | 本节点的 Raft 地址（如 `store0:8510`） |
89+
| `HG_STORE_GRPC_PORT` | 否 | `8500` | gRPC 服务端口 |
90+
| `HG_STORE_REST_PORT` | 否 | `8520` | REST API 端口 |
91+
| `HG_STORE_DATA_PATH` | 否 | `/hugegraph-store/storage` | 数据存储路径 |
92+
93+
> **注意**：在 Docker 桥接网络中，`HG_STORE_GRPC_HOST` 应使用容器主机名（如 `store0`）而非 IP 地址。
94+
95+
> **已弃用的别名**：`PD_ADDRESS`、`GRPC_HOST`、`RAFT_ADDRESS` 仍可使用，但会输出弃用警告。新部署请使用 `HG_STORE_*` 名称。
96+
5397
### 4 配置
5498

5599
Store 的主要配置文件为 `conf/application.yml`，以下是关键配置项：
@@ -116,7 +160,7 @@ logging:
116160
启动成功后，可以在 `logs/hugegraph-store-server.log` 中看到类似以下的日志：
117161

118162
```
119-
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)
163+
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)
120164
```
121165
122166
#### 5.2 停止 Store
@@ -188,6 +232,36 @@ pdserver:
188232
address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688
189233
```
190234
235+
#### 6.3 Docker 分布式集群配置
236+
237+
3 节点 Store 集群包含在 `docker/docker-compose-3pd-3store-3server.yml` 中。每个 Store 节点拥有独立的主机名和环境变量：
238+
239+
```yaml
240+
# store0
241+
HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
242+
HG_STORE_GRPC_HOST: store0
243+
HG_STORE_GRPC_PORT: "8500"
244+
HG_STORE_REST_PORT: "8520"
245+
HG_STORE_RAFT_ADDRESS: store0:8510
246+
HG_STORE_DATA_PATH: /hugegraph-store/storage
247+
248+
# store1
249+
HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
250+
HG_STORE_GRPC_HOST: store1
251+
HG_STORE_RAFT_ADDRESS: store1:8510
252+
253+
# store2
254+
HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
255+
HG_STORE_GRPC_HOST: store2
256+
HG_STORE_RAFT_ADDRESS: store2:8510
257+
```
258+
259+
Store 节点仅在所有 PD 节点通过健康检查后才会启动，其中 docker-compose 中的 healthcheck 实际访问的是 PD 的 REST 接口 `/v1/health`（也可以通过 Actuator 暴露的 `/actuator/health` 进行手动检查），并通过 `depends_on: condition: service_healthy` 强制执行依赖关系。
260+
261+
运行时日志可通过 `docker logs <container-name>`（如 `docker logs hg-store0`）直接查看，无需进入容器。
262+
263+
完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。
264+
191265
### 7 验证 Store 服务
192266

193267
确认 Store 服务是否正常运行：
@@ -204,7 +278,9 @@ curl http://localhost:8520/actuator/health
204278
curl http://localhost:8620/v1/stores
205279
```
206280

207-
如果Store配置成功，上述接口的响应中应该包含当前节点的状态信息，状态为Up表示节点正常运行，这里只展示了一个节点配置成功的响应，如果三个节点都配置成功并正在运行，响应中`storeId`列表应该包含三个id，并且`stateCountMap`中`Up`、`numOfService`、`numOfNormalService`三个字段应该为3。
281+
如果 Store 配置成功，上述接口响应中应包含当前节点的状态信息，其中 `state` 为 `Up` 表示节点运行正常。
282+
283+
下方示例仅展示 1 个 Store 节点的返回结果。如果 3 个节点都已正确配置并正在运行，则响应中的 `storeId` 列表应包含 3 个 ID，且 `stateCountMap.Up`、`numOfService` 和 `numOfNormalService` 都应为 `3`。
208284
```javascript
209285
{
210286
"message": "OK",
@@ -241,4 +317,4 @@ curl http://localhost:8620/v1/stores
241317
},
242318
"status": 0
243319
}
244-
```
320+
```

‎content/cn/docs/quickstart/hugegraph/hugegraph-pd.md‎

Lines changed: 61 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ HugeGraph-PD (Placement Driver) 是 HugeGraph 分布式版本的元数据管理
1212

1313
#### 2.1 前置条件
1414

15-
- 操作系统：Linux 或 MacOS（Windows 尚未经过完整测试）
15+
- 操作系统：Linux 或 macOS（Windows 尚未经过完整测试）
1616
- Java 版本：≥ 11
1717
- Maven 版本：≥ 3.5.0
1818

@@ -49,6 +49,56 @@ mvn clean install -DskipTests=true
4949
# target/apache-hugegraph-incubating-{version}.tar.gz
5050
```
5151

52+
#### 3.3 Docker 部署
53+
54+
HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 `hugegraph/pd`。
55+
> 注: 后续步骤皆假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录)
56+
57+
使用 docker-compose 模式部署完整的 3 节点集群（PD + Store + Server）：
58+
59+
```bash
60+
cd hugegraph/docker
61+
# 注意版本号请随时保持更新 → 1.x.0
62+
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d
63+
```
64+
65+
通过 `docker run` 运行单个 PD 节点时，通过环境变量提供配置：
66+
67+
```bash
68+
docker run -d \
69+
-p 8620:8620 \
70+
-p 8686:8686 \
71+
-p 8610:8610 \
72+
-e HG_PD_GRPC_HOST=<your-ip> \
73+
-e HG_PD_RAFT_ADDRESS=<your-ip>:8610 \
74+
-e HG_PD_RAFT_PEERS_LIST=<your-ip>:8610 \
75+
-e HG_PD_INITIAL_STORE_LIST=<store-ip>:8500 \
76+
-v /path/to/data:/hugegraph-pd/pd_data \
77+
--name hugegraph-pd \
78+
hugegraph/pd:1.7.0
79+
```
80+
81+
**环境变量参考：**
82+
83+
| 变量 | 必填 | 默认值 | 描述 |
84+
|------|------|--------|------|
85+
| `HG_PD_GRPC_HOST` | 是 | — | 本节点的 gRPC 主机名/IP（Docker 中使用 `pd0`，裸机使用 `192.168.1.10`） |
86+
| `HG_PD_RAFT_ADDRESS` | 是 | — | 本节点的 Raft 地址（如 `pd0:8610`） |
87+
| `HG_PD_RAFT_PEERS_LIST` | 是 | — | 所有 PD 节点的 Raft 地址（如 `pd0:8610,pd1:8610,pd2:8610`） |
88+
| `HG_PD_INITIAL_STORE_LIST` | 是 | — | 预期的 Store gRPC 地址（如 `store0:8500,store1:8500,store2:8500`） |
89+
| `HG_PD_GRPC_PORT` | 否 | `8686` | gRPC 服务端口 |
90+
| `HG_PD_REST_PORT` | 否 | `8620` | REST API 端口 |
91+
| `HG_PD_DATA_PATH` | 否 | `/hugegraph-pd/pd_data` | 元数据存储路径 |
92+
| `HG_PD_INITIAL_STORE_COUNT` | 否 | `1` | 集群可用所需的最小 Store 数量 |
93+
94+
> **注意**：在 Docker 桥接网络中，`HG_PD_GRPC_HOST` 和 `HG_PD_RAFT_ADDRESS` 应使用容器主机名（如 `pd0`）而非 IP 地址。
95+
96+
> **已弃用的别名**：`GRPC_HOST`、`RAFT_ADDRESS`、`RAFT_PEERS`、`PD_INITIAL_STORE_LIST` 仍可使用，但会输出弃用警告。新部署请使用 `HG_PD_*` 名称。
97+
98+
运行时日志可通过 `docker logs <container-name>`（如 `docker logs hg-pd0`）直接查看，无需进入容器。
99+
100+
完整的集群部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。
101+
52102
### 4 配置
53103

54104
PD 的主要配置文件为 `conf/application.yml`，以下是关键配置项：
@@ -72,7 +122,7 @@ pd:
72122
data-path: ./pd_data
73123
# 自动扩容的检查周期（秒）
74124
patrol-interval: 1800
75-
# 初始 store 列表，在列表内的 store 自动激活
125+
# 集群可用所需的最小 Store 数量
76126
initial-store-count: 1
77127
# store 的配置信息，格式为 IP:gRPC端口
78128
initial-store-list: 127.0.0.1:8500
@@ -116,7 +166,7 @@ partition:
116166
启动成功后，可以在 `logs/hugegraph-pd-stdout.log` 中看到类似以下的日志：
117167

118168
```
119-
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)
169+
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)
120170
```
121171

122172
#### 5.2 停止 PD
@@ -136,3 +186,11 @@ curl http://localhost:8620/actuator/health
136186
```
137187

138188
如果返回 `{"status":"UP"}`，则表示 PD 服务已成功启动。
189+
190+
此外，也可以通过 PD API 查看 Store 节点状态：
191+
192+
```bash
193+
curl http://localhost:8620/v1/stores
194+
```
195+
196+
如果响应中 `state` 为 `Up`，说明对应的 Store 节点运行正常。在一个健康的 3 节点部署中，`storeId` 列表应包含 3 个 ID，且 `stateCountMap.Up`、`numOfService` 和 `numOfNormalService` 都应为 `3`。

0 commit comments

Comments
 (0)
⚡