Copilot commented on code in PR #455: URL: https://github.com/apache/hugegraph-doc/pull/455#discussion_r2985712962
########## content/en/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -617,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 `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 Review Comment: This section suggests starting the Cassandra compose with `HUGEGRAPH_VERSION=1.7.0 ...`, but the YAML shown below uses `image: hugegraph/hugegraph` (no `${HUGEGRAPH_VERSION}` interpolation). As written, the env var won’t affect the compose run. Please either update the YAML to use `${HUGEGRAPH_VERSION}` (or an explicit tag) or remove the `HUGEGRAPH_VERSION=...` prefix from the command. ########## 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 Review Comment: In “3.2 Compile from source”, step 1 says “Clone the source code” but the `git clone https://github.com/apache/hugegraph.git` command is missing, so the following `cd hugegraph` step can’t be followed as written. Please add the clone command back or adjust the steps. ```suggestion # 1. Clone the source code git clone https://github.com/apache/hugegraph.git ``` ########## content/cn/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -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 Review Comment: 中文文档这里直接使用 `docker compose up -d`，但英文版同一段落使用了 `HUGEGRAPH_VERSION=1.7.0 docker compose up -d` 来固定镜像版本。建议两种语言保持一致：要么都显式指定版本（推荐），要么都说明默认会使用哪个版本/标签。 ```suggestion HUGEGRAPH_VERSION=1.7.0 docker compose up -d ``` ########## content/en/docs/guides/hugegraph-docker-cluster.md: ########## @@ -0,0 +1,133 @@ +--- +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) + +> **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 Review Comment: The quickstart assumes the compose files already exist locally (`cd hugegraph/docker`), but earlier the doc only links to the GitHub `docker/` directory. Please add an explicit step to obtain those files (e.g., `git clone https://github.com/apache/hugegraph.git` or a download instruction) so the commands work from a clean machine. ```suggestion ```bash git clone https://github.com/apache/hugegraph.git ``` ########## content/en/docs/quickstart/hugegraph/hugegraph-server.md: ########## @@ -699,7 +725,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 Review Comment: In the PRELOAD docker-compose example, the YAML already pins `image: hugegraph/hugegraph:1.7.0`, so prefixing the startup command with `HUGEGRAPH_VERSION=1.7.0` is misleading (it won’t change the image). Please remove the env var from the command or change the YAML to reference `${HUGEGRAPH_VERSION}`. ```suggestion Use `docker-compose up -d` to start the container ``` ########## 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）： Review Comment: 这里示例使用 `hugegraph/pd:latest` 会导致部署不可复现（不同时间拉取到的镜像内容可能不同），且与英文文档使用固定版本标签（如 `:1.7.0`）不一致。建议改用明确的发布版本标签，或至少说明 `latest` 仅用于体验开发版。 ########## 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）： Review Comment: 这里示例使用 `hugegraph/store:latest` 会导致部署不可复现，且与英文文档使用固定版本标签（如 `:1.7.0`）不一致。建议改用明确的发布版本标签，或在文档中强调 `latest` 仅用于开发/体验用途。 ########## 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 Review Comment: In “3.2 Compile from source”, step 1 says “Clone the source code” but the actual `git clone https://github.com/apache/hugegraph.git` command is missing, making the subsequent `cd hugegraph` step invalid. Please restore the clone command or rewrite the steps accordingly. ```suggestion # 1. Clone the source code git clone https://github.com/apache/hugegraph.git ``` ########## 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` Review Comment: 故障排查里使用了 `docker exec hg-pd0 ping pd1`，但文档没有说明容器名一定是 `hg-pd0`。为避免依赖 container_name 约定，建议改为 `docker compose exec pd0 ping pd1`，或在文档中明确 compose 文件中实际的容器名。 ```suggestion **Raft 选举超时**：检查所有 PD 节点的 `HG_PD_RAFT_PEERS_LIST` 是否一致。验证连通性：`docker compose exec pd0 ping pd1` ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
