imbajin commented on code in PR #412: URL: https://github.com/apache/incubator-hugegraph-doc/pull/412#discussion_r2458907581
########## 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 Review Comment: 🧹 **图片说明缺失：流程图缺少描述性文字** 在第 245 行插入了流程图，但只有简单的 alt 文本，缺少对流程图内容的解释。 **建议补充：** ```markdown 各工具的测试流程如下图所示，展示了从环境准备到测试执行的完整依赖关系： <div style="text-align: center;"> <img src="/docs/images/toolchain-test-mermaid-2.png" alt="HugeGraph工具链测试流程图"> </div> 流程说明： - **蓝色节点**：必需依赖服务 - **绿色节点**：可选依赖服务 - **箭头**：依赖关系 ``` 这样可以帮助读者更好地理解流程图的含义。 -- 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]
