imbajin commented on code in PR #412: URL: https://github.com/apache/incubator-hugegraph-doc/pull/412#discussion_r2458907370
########## content/cn/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,443 @@ +--- +title: "HugeGraph工具链本地测试指南" +linkTitle: "Toolchain本地测试" +weight: 4 +--- + +本指南帮助开发者在本地运行 HugeGraph 工具链测试。 + +## 1. 核心概念 + +### 1.1 核心依赖：HugeGraph Server + +**工具链的集成测试和功能测试都依赖 HugeGraph Server**，包括 Client、Loader、Hubble、Spark Connector、Tools 等组件。 + +### 1.2 测试类型 + +- **单元测试 (Unit Tests)**：测试单个函数/方法，不依赖外部服务 +- **API 测试 (ApiTestSuite)**：测试 API 接口，需要运行中的 HugeGraph Server +- **功能测试 (FuncTestSuite)**：端到端测试，需要完整的系统环境 + +## 2. 环境准备 + +### 2.1 系统要求 + +- **操作系统**：Linux / macOS（Windows 使用 WSL2） +- **JDK**：>= 11，配置好 `JAVA_HOME` +- **Maven**：>= 3.5 +- **Python**：>= 3.11（仅 Hubble 测试需要） + +### 2.2 克隆代码 + +```bash +git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git +cd hugegraph-toolchain +``` + +## 3. 部署测试环境 + +### 方式选择 + +- **脚本部署（推荐）**：通过指定 Commit ID 精确控制 Server 版本，避免接口不兼容 +- **Docker 部署**：快速启动，但可能版本滞后导致测试失败 + +> 详细安装说明参考 [社区文档](https://hugegraph.apache.org/cn/docs/quickstart/hugegraph/hugegraph-server/) + +### 3.1 脚本部署（推荐） + +#### 参数说明 + +- **`$COMMIT_ID`**：指定 Server 源码的 Git Commit ID +- **`$DB_DATABASE` / `$DB_PASS`**：Loader JDBC 测试用的 MySQL 数据库名和密码 + +#### 部署步骤 + +**1. 安装 HugeGraph Server** + +```bash +# 设置版本 +export COMMIT_ID="master" # 或特定 commit hash，如 "8b90977" + +# 执行安装（脚本位于 /assembly/travis/ 目录） +hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID +``` + +- 默认端口：http 8080, https 8443 +- 确保端口未被占用 + +**2. 安装可选依赖** + +```bash +# Hadoop (仅 Loader HDFS 测试需要) +hugegraph-loader/assembly/travis/install-hadoop.sh + +# MySQL (仅 Loader JDBC 测试需要) +hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS +``` + +**3. 健康检查** + +```bash +curl http://localhost:8080/graphs +# 返回 {"graphs":["hugegraph"]} 表示成功 +``` + +### 3.2 Docker 部署 + +> **注意**：Docker 镜像可能版本滞后，如遇兼容性问题请使用脚本部署 + +#### 快速启动 + +```bash +docker network create hugegraph-net +docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest +``` + +#### docker-compose 配置（可选） + +完整配置示例，包含 Server、MySQL、Hadoop 服务（需要 Docker Compose V2）： + +```yaml +version: '3.8' + +services: + hugegraph-server: + image: hugegraph/hugegraph:latest # 可以替换为特定版本，或构建自己的镜像 + container_name: hugegraph-server + ports: + - "8080:8080" # HugeGraph Server HTTP 端口 + environment: + # 根据需要配置HugeGraph Server的参数，例如后端存储 + - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb" + volumes: + # 如果需要持久化数据或挂载配置文件，可以在这里添加卷 + # - ./hugegraph-data:/opt/hugegraph/data + healthcheck: + test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] + interval: 5s + timeout: 3s Review Comment: ‼️ **关键问题：健康检查间隔设置不一致** 在 docker-compose.yml 配置中，HugeGraph Server 的健康检查间隔设置为 10 秒，但其他可选服务(MySQL、NameNode、DataNode)的间隔都是 5 秒。 **问题影响：** - 不一致的配置可能导致服务启动顺序混乱 - HugeGraph Server 是核心依赖服务，应该更快地被检测为就绪状态 **建议修改：** 将 HugeGraph Server 的健康检查间隔改为 5 秒以保持一致性： ```yaml healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] interval: 5s # 从 10s 改为 5s timeout: 3s retries: 5 ``` ########## content/cn/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,443 @@ +--- +title: "HugeGraph工具链本地测试指南" +linkTitle: "Toolchain本地测试" +weight: 4 +--- + +本指南帮助开发者在本地运行 HugeGraph 工具链测试。 + +## 1. 核心概念 + +### 1.1 核心依赖：HugeGraph Server + +**工具链的集成测试和功能测试都依赖 HugeGraph Server**，包括 Client、Loader、Hubble、Spark Connector、Tools 等组件。 + +### 1.2 测试类型 + +- **单元测试 (Unit Tests)**：测试单个函数/方法，不依赖外部服务 +- **API 测试 (ApiTestSuite)**：测试 API 接口，需要运行中的 HugeGraph Server +- **功能测试 (FuncTestSuite)**：端到端测试，需要完整的系统环境 + +## 2. 环境准备 + +### 2.1 系统要求 + +- **操作系统**：Linux / macOS（Windows 使用 WSL2） +- **JDK**：>= 11，配置好 `JAVA_HOME` +- **Maven**：>= 3.5 +- **Python**：>= 3.11（仅 Hubble 测试需要） + +### 2.2 克隆代码 + +```bash +git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git +cd hugegraph-toolchain +``` + +## 3. 部署测试环境 + +### 方式选择 + +- **脚本部署（推荐）**：通过指定 Commit ID 精确控制 Server 版本，避免接口不兼容 +- **Docker 部署**：快速启动，但可能版本滞后导致测试失败 + +> 详细安装说明参考 [社区文档](https://hugegraph.apache.org/cn/docs/quickstart/hugegraph/hugegraph-server/) + +### 3.1 脚本部署（推荐） + +#### 参数说明 + +- **`$COMMIT_ID`**：指定 Server 源码的 Git Commit ID +- **`$DB_DATABASE` / `$DB_PASS`**：Loader JDBC 测试用的 MySQL 数据库名和密码 + +#### 部署步骤 + +**1. 安装 HugeGraph Server** + +```bash +# 设置版本 +export COMMIT_ID="master" # 或特定 commit hash，如 "8b90977" + +# 执行安装（脚本位于 /assembly/travis/ 目录） +hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID +``` + +- 默认端口：http 8080, https 8443 +- 确保端口未被占用 + +**2. 安装可选依赖** + +```bash +# Hadoop (仅 Loader HDFS 测试需要) +hugegraph-loader/assembly/travis/install-hadoop.sh + +# MySQL (仅 Loader JDBC 测试需要) +hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS +``` + +**3. 健康检查** + +```bash +curl http://localhost:8080/graphs +# 返回 {"graphs":["hugegraph"]} 表示成功 +``` + +### 3.2 Docker 部署 + +> **注意**：Docker 镜像可能版本滞后，如遇兼容性问题请使用脚本部署 + +#### 快速启动 + +```bash +docker network create hugegraph-net +docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest +``` + +#### docker-compose 配置（可选） + +完整配置示例，包含 Server、MySQL、Hadoop 服务（需要 Docker Compose V2）： + +```yaml +version: '3.8' + +services: + hugegraph-server: + image: hugegraph/hugegraph:latest # 可以替换为特定版本，或构建自己的镜像 + container_name: hugegraph-server + ports: + - "8080:8080" # HugeGraph Server HTTP 端口 + environment: + # 根据需要配置HugeGraph Server的参数，例如后端存储 + - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb" + volumes: + # 如果需要持久化数据或挂载配置文件，可以在这里添加卷 + # - ./hugegraph-data:/opt/hugegraph/data + healthcheck: + test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] + interval: 5s + timeout: 3s + retries: 5 + networks: + - hugegraph-net + + # 如果需要hugegraph-loader的JDBC测试，可以添加以下服务 + # mysql: + # image: mysql:5.7 + # container_name: mysql-db + # environment: + # MYSQL_ROOT_PASSWORD: ${DB_PASS:-your_mysql_root_password} # 从环境变量读取，或使用默认值 + # MYSQL_DATABASE: ${DB_DATABASE:-hugegraph_test_db} # 从环境变量读取，或使用默认值 + # ports: + # - "3306:3306" + # volumes: + # - ./mysql-data:/var/lib/mysql # 数据持久化 + # healthcheck: + # test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${DB_PASS:-your_mysql_root_password}"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + + # 如果需要hugegraph-loader的Hadoop/HDFS测试，可以添加以下服务 + # namenode: + # image: johannestang/hadoop-namenode:2.0.0-hadoop2.8.5-java8 + # container_name: namenode + # ports: + # - "0.0.0.0:9870:9870" + # - "0.0.0.0:8020:8020" + # environment: + # - CLUSTER_NAME=test-cluster + # - HDFS_NAMENODE_USER=root + # - HADOOP_CONF_DIR=/hadoop/etc/hadoop + # volumes: + # - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml + # - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml + # - namenode_data:/hadoop/dfs/name + # command: bash -c "if [ ! -d /hadoop/dfs/name/current ]; then hdfs namenode -format; fi && /entrypoint.sh" + # healthcheck: + # test: ["CMD", "hdfs", "dfsadmin", "-report"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + + # datanode: + # image: johannestang/hadoop-datanode:2.0.0-hadoop2.8.5-java8 + # container_name: datanode + # depends_on: + # - namenode + # environment: + # - CLUSTER_NAME=test-cluster + # - HDFS_DATANODE_USER=root + # - HADOOP_CONF_DIR=/hadoop/etc/hadoop + # volumes: + # - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml + # - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml + # - datanode_data:/hadoop/dfs/data + # healthcheck: + # test: ["CMD", "hdfs", "dfsadmin", "-report"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + +networks: + hugegraph-net: + driver: bridge +volumes: + namenode_data: + datanode_data: +``` + +#### Hadoop 配置挂载 +`./config`文件夹用于配置挂载，请自行选择是否设置，需要与 `docker-compose.yml` 位于同一文件夹 + +📁 ./config/core-site.xml 内容： + +```xml +<configuration> + <property> + <name>fs.defaultFS</name> + <value>hdfs://namenode:8020</value> + </property> +</configuration> +``` + +📁 ./config/hdfs-site.xml 内容： + +```xml +<configuration> + <property> + <name>dfs.namenode.name.dir</name> + <value>/hadoop/hdfs/name</value> + </property> + <property> + <name>dfs.datanode.data.dir</name> + <value>/hadoop/hdfs/data</value> + </property> + <property> + <name>dfs.permissions.superusergroup</name> + <value>hadoop</value> + </property> + <property> + <name>dfs.support.append</name> + <value>true</value> + </property> +</configuration> +``` + +#### Docker 操作 + +```bash +# 启动服务 +docker compose up -d + +# 检查状态 +docker compose ps +lsof -i:8080 # Server +lsof -i:8020 # Hadoop +lsof -i:3306 # MySQL + +# 停止服务 +docker compose down +``` + +## 4. 运行测试 + +各工具的测试流程： + +<div style="text-align: center;"> + <img src="/docs/images/toolchain-test-mermaid-2.png" alt="HugeGraph工具链测试流程图"> +</div> + +### 4.1 hugegraph-client + +#### 编译 + +```bash +mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp +``` + +#### 依赖服务 + Review Comment: ⚠️ **密码安全问题：测试密码明文暴露** 在多处文档中直接明文展示了测试使用的默认密码 "pa"，这可能导致安全隐患： 1. 用户可能在生产环境误用这个弱密码 2. 没有强调这仅用于测试环境 **建议改进：** 1. 添加醒目的安全警告： ```markdown > ⚠️ **安全警告**：密码 "pa" 仅用于本地测试环境，切勿在生产环境使用！生产环境请使用强密码。 ``` 2. 在第 265 行和其他相关位置添加此警告 ########## content/en/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,445 @@ +--- + +title: "HugeGraph Toolchain Local Testing Guide" +linkTitle: "Toolchain Local Testing" +weight: 4 +--- + +This guide helps developers run HugeGraph toolchain tests locally. + +## 1. Core Concepts + +### 1.1 Core Dependency: HugeGraph Server + +**Integration and functional tests of the toolchain depend on HugeGraph Server**, including Client, Loader, Hubble, Spark Connector, Tools, and other components. + +### 1.2 Test Types + +- **Unit Tests**: Test individual functions/methods, no external dependencies required +- **API Tests (ApiTestSuite)**: Test API interfaces, requires running HugeGraph Server +- **Functional Tests (FuncTestSuite)**: End-to-end tests, require complete system environment + +## 2. Environment Setup + +### 2.1 System Requirements + +- **Operating System**: Linux / macOS (Windows use WSL2) +- **JDK**: >= 11, configure `JAVA_HOME` +- **Maven**: >= 3.5 +- **Python**: >= 3.11 (only required for Hubble tests) + +### 2.2 Clone Code + +```bash +git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git +cd hugegraph-toolchain +``` + +## 3. Deploy Test Environment + +### Deployment Options + +- **Script Deployment (Recommended)**: Precisely control Server version by specifying Commit ID, avoid interface incompatibility +- **Docker Deployment**: Quick start, but may have version lag causing test failures + +> For detailed installation instructions, refer to [Community Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-server/) + +### 3.1 Script Deployment (Recommended) + +#### Parameter Description + +- **`$COMMIT_ID`**: Specify Server source code Git Commit ID +- **`$DB_DATABASE` / `$DB_PASS`**: MySQL database name and password for Loader JDBC tests + +#### Deployment Steps + +**1. Install HugeGraph Server** + +```bash +# Set version +export COMMIT_ID="master" # Or specific commit hash, e.g. "8b90977" + +# Execute installation (script located in /assembly/travis/ directory) +hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID +``` + +- Default ports: http 8080, https 8443 +- Ensure ports are not occupied + +**2. Install Optional Dependencies** + +```bash +# Hadoop (only required for Loader HDFS tests) +hugegraph-loader/assembly/travis/install-hadoop.sh + +# MySQL (only required for Loader JDBC tests) +hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS +``` + +**3. Health Check** + +```bash +curl http://localhost:8080/graphs +# Returns {"graphs":["hugegraph"]} indicates success +``` + +### 3.2 Docker Deployment + +> **Note**: Docker images may have version lag, use script deployment if encountering compatibility issues + +#### Quick Start + +```bash +docker network create hugegraph-net +docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest +``` + +#### docker-compose Configuration (Optional) + +Complete configuration example including Server, MySQL, Hadoop services (requires Docker Compose V2): + +```yaml +version: '3.8' + +services: + hugegraph-server: + image: hugegraph/hugegraph:latest # Can be replaced with a specific version, or build your own image + container_name: hugegraph-server + ports: + - "8080:8080" # HugeGraph Server HTTP port + environment: + # Configure HugeGraph Server parameters as needed, e.g., backend storage + - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb" + volumes: + # If you need to persist data or mount configuration files, add volumes here + # - ./hugegraph-data:/opt/hugegraph/data + healthcheck: + test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] + interval: 10s Review Comment: ⚠️ **文档一致性问题：英文版健康检查间隔与中文版不同** 英文文档中 HugeGraph Server 的健康检查间隔设置为 10 秒，但与中文版相同的问题需要修复。 **建议：** 保持中英文文档配置一致，将间隔改为 5 秒： ```yaml healthcheck: test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] interval: 5s # Change from 10s to 5s timeout: 3s retries: 5 ``` ########## content/en/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,445 @@ +--- Review Comment: 🧹 **文档格式问题：YAML 头部缺少闭合标记** 英文版文档的 front matter 格式不完整，第一行多了一个空行。 **当前格式：** ```yaml --- title: "HugeGraph Toolchain Local Testing Guide" ``` **应该是：** ```yaml --- title: "HugeGraph Toolchain Local Testing Guide" ``` 这可能导致某些静态站点生成器解析错误。 ########## content/cn/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,443 @@ +--- +title: "HugeGraph工具链本地测试指南" +linkTitle: "Toolchain本地测试" +weight: 4 +--- + +本指南帮助开发者在本地运行 HugeGraph 工具链测试。 + +## 1. 核心概念 + +### 1.1 核心依赖：HugeGraph Server + +**工具链的集成测试和功能测试都依赖 HugeGraph Server**，包括 Client、Loader、Hubble、Spark Connector、Tools 等组件。 + +### 1.2 测试类型 + +- **单元测试 (Unit Tests)**：测试单个函数/方法，不依赖外部服务 +- **API 测试 (ApiTestSuite)**：测试 API 接口，需要运行中的 HugeGraph Server +- **功能测试 (FuncTestSuite)**：端到端测试，需要完整的系统环境 + +## 2. 环境准备 + +### 2.1 系统要求 + +- **操作系统**：Linux / macOS（Windows 使用 WSL2） +- **JDK**：>= 11，配置好 `JAVA_HOME` +- **Maven**：>= 3.5 +- **Python**：>= 3.11（仅 Hubble 测试需要） + +### 2.2 克隆代码 + +```bash +git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git +cd hugegraph-toolchain +``` + +## 3. 部署测试环境 + +### 方式选择 + +- **脚本部署（推荐）**：通过指定 Commit ID 精确控制 Server 版本，避免接口不兼容 +- **Docker 部署**：快速启动，但可能版本滞后导致测试失败 + +> 详细安装说明参考 [社区文档](https://hugegraph.apache.org/cn/docs/quickstart/hugegraph/hugegraph-server/) + +### 3.1 脚本部署（推荐） + +#### 参数说明 + +- **`$COMMIT_ID`**：指定 Server 源码的 Git Commit ID +- **`$DB_DATABASE` / `$DB_PASS`**：Loader JDBC 测试用的 MySQL 数据库名和密码 + +#### 部署步骤 + +**1. 安装 HugeGraph Server** + +```bash +# 设置版本 +export COMMIT_ID="master" # 或特定 commit hash，如 "8b90977" + +# 执行安装（脚本位于 /assembly/travis/ 目录） +hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID +``` + +- 默认端口：http 8080, https 8443 +- 确保端口未被占用 + +**2. 安装可选依赖** + +```bash +# Hadoop (仅 Loader HDFS 测试需要) +hugegraph-loader/assembly/travis/install-hadoop.sh + +# MySQL (仅 Loader JDBC 测试需要) +hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS +``` + +**3. 健康检查** + +```bash +curl http://localhost:8080/graphs +# 返回 {"graphs":["hugegraph"]} 表示成功 +``` + +### 3.2 Docker 部署 + +> **注意**：Docker 镜像可能版本滞后，如遇兼容性问题请使用脚本部署 + +#### 快速启动 + +```bash +docker network create hugegraph-net +docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest +``` + +#### docker-compose 配置（可选） + +完整配置示例，包含 Server、MySQL、Hadoop 服务（需要 Docker Compose V2）： + +```yaml +version: '3.8' + +services: + hugegraph-server: + image: hugegraph/hugegraph:latest # 可以替换为特定版本，或构建自己的镜像 + container_name: hugegraph-server + ports: + - "8080:8080" # HugeGraph Server HTTP 端口 + environment: + # 根据需要配置HugeGraph Server的参数，例如后端存储 + - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb" + volumes: + # 如果需要持久化数据或挂载配置文件，可以在这里添加卷 + # - ./hugegraph-data:/opt/hugegraph/data + healthcheck: + test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] + interval: 5s + timeout: 3s + retries: 5 + networks: + - hugegraph-net + + # 如果需要hugegraph-loader的JDBC测试，可以添加以下服务 + # mysql: + # image: mysql:5.7 + # container_name: mysql-db + # environment: + # MYSQL_ROOT_PASSWORD: ${DB_PASS:-your_mysql_root_password} # 从环境变量读取，或使用默认值 + # MYSQL_DATABASE: ${DB_DATABASE:-hugegraph_test_db} # 从环境变量读取，或使用默认值 + # ports: + # - "3306:3306" + # volumes: + # - ./mysql-data:/var/lib/mysql # 数据持久化 + # healthcheck: + # test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${DB_PASS:-your_mysql_root_password}"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + + # 如果需要hugegraph-loader的Hadoop/HDFS测试，可以添加以下服务 + # namenode: + # image: johannestang/hadoop-namenode:2.0.0-hadoop2.8.5-java8 + # container_name: namenode + # ports: + # - "0.0.0.0:9870:9870" + # - "0.0.0.0:8020:8020" + # environment: + # - CLUSTER_NAME=test-cluster + # - HDFS_NAMENODE_USER=root + # - HADOOP_CONF_DIR=/hadoop/etc/hadoop + # volumes: + # - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml + # - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml + # - namenode_data:/hadoop/dfs/name + # command: bash -c "if [ ! -d /hadoop/dfs/name/current ]; then hdfs namenode -format; fi && /entrypoint.sh" + # healthcheck: + # test: ["CMD", "hdfs", "dfsadmin", "-report"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + + # datanode: + # image: johannestang/hadoop-datanode:2.0.0-hadoop2.8.5-java8 + # container_name: datanode + # depends_on: + # - namenode + # environment: + # - CLUSTER_NAME=test-cluster + # - HDFS_DATANODE_USER=root + # - HADOOP_CONF_DIR=/hadoop/etc/hadoop + # volumes: + # - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml + # - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml + # - datanode_data:/hadoop/dfs/data + # healthcheck: + # test: ["CMD", "hdfs", "dfsadmin", "-report"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + +networks: + hugegraph-net: + driver: bridge +volumes: + namenode_data: + datanode_data: Review Comment: ⚠️ **配置说明不清晰：./config 文件夹位置说明有歧义** 文档中提到 "需要与 `docker-compose.yml` 位于同一文件夹"，但没有明确说明： 1. 这个文件夹应该在哪里创建（用户的工作目录？项目根目录？） 2. 是否需要提前创建，还是 docker-compose 会自动创建 **建议改进：** ```markdown #### Hadoop 配置挂载 在与 `docker-compose.yml` 相同的目录下创建 `./config` 文件夹用于挂载 Hadoop 配置文件。如果不需要 HDFS 测试，可以跳过此步骤。 ```bash # 创建配置目录 mkdir -p ./config ``` ``` ########## content/cn/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,443 @@ +--- +title: "HugeGraph工具链本地测试指南" +linkTitle: "Toolchain本地测试" +weight: 4 +--- + +本指南帮助开发者在本地运行 HugeGraph 工具链测试。 + +## 1. 核心概念 + +### 1.1 核心依赖：HugeGraph Server + +**工具链的集成测试和功能测试都依赖 HugeGraph Server**，包括 Client、Loader、Hubble、Spark Connector、Tools 等组件。 + +### 1.2 测试类型 + +- **单元测试 (Unit Tests)**：测试单个函数/方法，不依赖外部服务 +- **API 测试 (ApiTestSuite)**：测试 API 接口，需要运行中的 HugeGraph Server +- **功能测试 (FuncTestSuite)**：端到端测试，需要完整的系统环境 + +## 2. 环境准备 + +### 2.1 系统要求 + +- **操作系统**：Linux / macOS（Windows 使用 WSL2） +- **JDK**：>= 11，配置好 `JAVA_HOME` +- **Maven**：>= 3.5 +- **Python**：>= 3.11（仅 Hubble 测试需要） + +### 2.2 克隆代码 + +```bash +git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git +cd hugegraph-toolchain +``` + +## 3. 部署测试环境 + +### 方式选择 + +- **脚本部署（推荐）**：通过指定 Commit ID 精确控制 Server 版本，避免接口不兼容 +- **Docker 部署**：快速启动，但可能版本滞后导致测试失败 + +> 详细安装说明参考 [社区文档](https://hugegraph.apache.org/cn/docs/quickstart/hugegraph/hugegraph-server/) + +### 3.1 脚本部署（推荐） + +#### 参数说明 + +- **`$COMMIT_ID`**：指定 Server 源码的 Git Commit ID +- **`$DB_DATABASE` / `$DB_PASS`**：Loader JDBC 测试用的 MySQL 数据库名和密码 + +#### 部署步骤 + +**1. 安装 HugeGraph Server** + +```bash +# 设置版本 +export COMMIT_ID="master" # 或特定 commit hash，如 "8b90977" + +# 执行安装（脚本位于 /assembly/travis/ 目录） +hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID +``` + +- 默认端口：http 8080, https 8443 +- 确保端口未被占用 + +**2. 安装可选依赖** + +```bash +# Hadoop (仅 Loader HDFS 测试需要) +hugegraph-loader/assembly/travis/install-hadoop.sh + +# MySQL (仅 Loader JDBC 测试需要) +hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS +``` + +**3. 健康检查** + +```bash +curl http://localhost:8080/graphs +# 返回 {"graphs":["hugegraph"]} 表示成功 +``` + +### 3.2 Docker 部署 + +> **注意**：Docker 镜像可能版本滞后，如遇兼容性问题请使用脚本部署 + +#### 快速启动 + +```bash +docker network create hugegraph-net +docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest +``` + +#### docker-compose 配置（可选） + +完整配置示例，包含 Server、MySQL、Hadoop 服务（需要 Docker Compose V2）： + +```yaml +version: '3.8' + +services: + hugegraph-server: + image: hugegraph/hugegraph:latest # 可以替换为特定版本，或构建自己的镜像 + container_name: hugegraph-server + ports: + - "8080:8080" # HugeGraph Server HTTP 端口 + environment: + # 根据需要配置HugeGraph Server的参数，例如后端存储 + - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb" + volumes: + # 如果需要持久化数据或挂载配置文件，可以在这里添加卷 + # - ./hugegraph-data:/opt/hugegraph/data + healthcheck: + test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] + interval: 5s + timeout: 3s + retries: 5 + networks: + - hugegraph-net + + # 如果需要hugegraph-loader的JDBC测试，可以添加以下服务 + # mysql: + # image: mysql:5.7 + # container_name: mysql-db + # environment: + # MYSQL_ROOT_PASSWORD: ${DB_PASS:-your_mysql_root_password} # 从环境变量读取，或使用默认值 + # MYSQL_DATABASE: ${DB_DATABASE:-hugegraph_test_db} # 从环境变量读取，或使用默认值 + # ports: + # - "3306:3306" + # volumes: + # - ./mysql-data:/var/lib/mysql # 数据持久化 + # healthcheck: + # test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${DB_PASS:-your_mysql_root_password}"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + + # 如果需要hugegraph-loader的Hadoop/HDFS测试，可以添加以下服务 + # namenode: + # image: johannestang/hadoop-namenode:2.0.0-hadoop2.8.5-java8 + # container_name: namenode + # ports: + # - "0.0.0.0:9870:9870" + # - "0.0.0.0:8020:8020" + # environment: + # - CLUSTER_NAME=test-cluster + # - HDFS_NAMENODE_USER=root + # - HADOOP_CONF_DIR=/hadoop/etc/hadoop + # volumes: + # - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml + # - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml + # - namenode_data:/hadoop/dfs/name + # command: bash -c "if [ ! -d /hadoop/dfs/name/current ]; then hdfs namenode -format; fi && /entrypoint.sh" + # healthcheck: + # test: ["CMD", "hdfs", "dfsadmin", "-report"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + + # datanode: + # image: johannestang/hadoop-datanode:2.0.0-hadoop2.8.5-java8 + # container_name: datanode + # depends_on: + # - namenode + # environment: + # - CLUSTER_NAME=test-cluster + # - HDFS_DATANODE_USER=root + # - HADOOP_CONF_DIR=/hadoop/etc/hadoop + # volumes: + # - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml + # - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml + # - datanode_data:/hadoop/dfs/data + # healthcheck: + # test: ["CMD", "hdfs", "dfsadmin", "-report"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + +networks: + hugegraph-net: + driver: bridge +volumes: + namenode_data: + datanode_data: +``` + +#### Hadoop 配置挂载 +`./config`文件夹用于配置挂载，请自行选择是否设置，需要与 `docker-compose.yml` 位于同一文件夹 + +📁 ./config/core-site.xml 内容： + +```xml +<configuration> + <property> + <name>fs.defaultFS</name> + <value>hdfs://namenode:8020</value> + </property> +</configuration> +``` + +📁 ./config/hdfs-site.xml 内容： + +```xml +<configuration> + <property> + <name>dfs.namenode.name.dir</name> + <value>/hadoop/hdfs/name</value> + </property> + <property> + <name>dfs.datanode.data.dir</name> + <value>/hadoop/hdfs/data</value> + </property> + <property> + <name>dfs.permissions.superusergroup</name> + <value>hadoop</value> + </property> + <property> + <name>dfs.support.append</name> + <value>true</value> + </property> +</configuration> +``` + +#### Docker 操作 + +```bash +# 启动服务 +docker compose up -d + +# 检查状态 +docker compose ps +lsof -i:8080 # Server +lsof -i:8020 # Hadoop +lsof -i:3306 # MySQL + +# 停止服务 +docker compose down +``` + +## 4. 运行测试 + +各工具的测试流程： + +<div style="text-align: center;"> + <img src="/docs/images/toolchain-test-mermaid-2.png" alt="HugeGraph工具链测试流程图"> +</div> + +### 4.1 hugegraph-client + +#### 编译 + +```bash +mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp +``` + +#### 依赖服务 + +启动 HugeGraph Server（参考 [第3节](#3-部署测试环境)） + +##### Server 鉴权配置 + +> **注意**：Docker 镜像 <= 1.5.0 不支持鉴权测试，需 1.6.0+ + +ApiTest 需要鉴权配置，使用脚本安装可跳过。使用 Docker 需手动配置： + +```bash +# 1. 修改鉴权模式 +cp conf/rest-server.properties conf/rest-server.properties.backup +sed -i '/^auth.authenticator=/c\auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator' conf/rest-server.properties +grep auth.authenticator conf/rest-server.properties + +# 2. 设置密码 +# 注：测试代码中默认使用 "pa" 作为密码，设置时需与测试保持一致 +bin/stop-hugegraph.sh +export PASSWORD="pa" # 设置为测试默认密码 +echo -e "${PASSWORD}" | bin/init-store.sh +bin/start-hugegraph.sh +``` + Review Comment: ⚠️ **命令说明不完整：缺少错误处理提示** 在第 286-287 行的健康检查命令中，只说明了预期的成功返回值，但没有提示如果返回值不正确该怎么办。 **建议补充：** ```bash # 检查环境 curl http://localhost:8080/graphs # 应返回 {"graphs":["hugegraph"]}，如返回错误请检查 Server 是否正常启动 curl -u admin:pa http://localhost:8080/graphs # 鉴权测试（密码 pa 是测试默认值） # 如果返回 401 错误，说明鉴权未正确配置 # 如果返回连接错误，请检查 Server 是否在运行: ps aux | grep hugegraph ``` -- 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]
