跳转到主要内容

HugeGraph-Computer 快速上手

1. 组件说明

HugeGraph-Computer 是基于 BSP（Bulk Synchronous Parallel，批量同步并行）模型的 Java 分布式图计算框架，算法按超步迭代运行。它可由 Kubernetes Operator 或 YARN 调度，也可在单机上启动 master 和 worker 进程进行小规模试跑。

它与同一仓库中的 Vermeer 是两套实现：Computer 使用 Java/BSP 运行时，面向分布式计算；Vermeer 是 Go 实现的内存图计算平台，采用 master-worker 结构。两者共享 HugeGraph 数据源，但部署和任务配置不能互换。

Computer 支持从 HugeGraph 或 HDFS 读取图数据，并可将结果写回 HugeGraph 或 HDFS。运行时可把部分数据溢写到磁盘；能否完成任务仍取决于输入规模、资源和配置，不应把溢写能力理解为不受资源限制。

2. 前置条件与连接

构建和运行需要 JDK 11 或更高版本。源码构建还需要 Maven 3.5 或更高版本。PageRank 示例要求一个已启动且包含待计算图数据的 HugeGraph-Server，以及可供 master、worker 访问的 etcd。

服务示例地址或端口用途
HugeGraph-Serverhttp://127.0.0.1:8080读取图数据并写回算法结果；以 hugegraph.url 为准。
etcdhttp://127.0.0.1:2379BSP 作业协调；以 bsp.etcd_endpoints 为准。
Computer master RPCTCP 8190worker 连接 master；发行配置中的端口。
Computer worker 数据传输本地默认由系统分配；K8s Operator 默认 8099worker 之间传输顶点和消息。跨主机时需保证公告地址和端口可达。
MinIO（K8s 清单）HTTP 9000用于输入分区快照。Computer 1.7.0 清单把 Service 的 9000 错映射到 MinIO Console 的 9090；启用快照前需将 targetPort 改为 9000。默认 snapshot.write=false、snapshot.load=false，不启用快照时无需访问 MinIO。
cert-manager（K8s）集群内服务Operator 清单使用 cert-manager.io/v1 的 Certificate、Issuer 和 CA 注入功能；部署 Operator 前必须先安装兼容版本。
HDFS按集群配置仅当输入或输出配置为 HDFS 时需要。

Kubernetes 作业中的 hugegraph.url 必须是各计算 Pod 都能访问的地址，不能填仅在个人电脑上可用的 localhost。如果启用了 HugeGraph 认证，应在配置中填写用户名和密码，并为 REST 查询使用对应凭据。

警告

生产环境必须为 HugeGraph Server 开启认证与授权（见认证与授权说明）并保留 Server 审计日志（标准日志文件为 audit-*.log），为 Computer 使用只具备作业所需读写权限的专用账号，并为 Server 网络入口设置来源 IP 白名单。hugegraph.username 和 hugegraph.password 只是 Computer 连接 Server 的凭据，不能替代 Server 端认证。

更多配置项见Computer 配置参考。

3. 获取源码并构建发行包

Apache HugeGraph 下载目录按版本提供 Computer 源码包，不提供单独的预编译 Computer 二进制包。下面以 VERSION=1.7.0 为例；该发布版的源码包和构建产物文件名含 -incubating-，其他版本请按下载目录中的实际文件名调整。

VERSION=1.7.0 # 替换为要下载的发布版本
ARCHIVE="apache-hugegraph-computer-incubating-${VERSION}-src.tar.gz"
DOWNLOAD_BASE="https://downloads.apache.org/hugegraph/${VERSION}"
curl -fLO "${DOWNLOAD_BASE}/${ARCHIVE}"
curl -fLO "${DOWNLOAD_BASE}/${ARCHIVE}.sha512"
curl -fLO "${DOWNLOAD_BASE}/${ARCHIVE}.asc"
curl -fLO https://downloads.apache.org/hugegraph/KEYS
shasum -a 512 -c "${ARCHIVE}.sha512"
gpg --import KEYS
gpg --verify "${ARCHIVE}.asc" "${ARCHIVE}"
tar -xzf "${ARCHIVE}"
cd "apache-hugegraph-computer-incubating-${VERSION}-src/computer"
mvn clean package -DskipTests
tar -xzf "target/apache-hugegraph-computer-incubating-${VERSION}.tar.gz"
cd "apache-hugegraph-computer-incubating-${VERSION}"

从当前 master 构建时可直接克隆并打包：

git clone https://github.com/apache/hugegraph-computer.git
cd hugegraph-computer/computer
mvn clean package -DskipTests

发行包由 computer/computer-dist 组装，包含 bin/start-computer.sh、运行依赖 lib/、内置算法 algorithm/builtin-algorithm.jar 及默认配置 conf/computer.properties、conf/log4j2.xml。源码默认配置位于 computer/computer-dist/src/assembly/static/conf/computer.properties。1.7.0 发布源码的构建产物带 -incubating-，当前 master 的发行名不带该标记，且版本号由源码 POM 决定；不要混用两种源码对应的 tar 包名。

4. 单机运行 PageRank

先编辑发行目录中的 conf/computer.properties，按实际环境修改 HugeGraph 地址、图名和认证信息，并确认 bsp.etcd_endpoints 指向可访问的 etcd。默认配置已选择内置 PageRankParams；master 和 worker 必须使用同一份配置及相同的 job.id。每个并行作业应使用不同的 job.id。

在两个终端中都从发行目录启动进程。启动脚本默认读取 conf/computer.properties，也可用 -c 指定配置文件。

# 终端一：启动 master
bin/start-computer.sh -d local -r master
# 终端二：启动 worker
bin/start-computer.sh -d local -r worker

master 会等待配置要求的 worker 注册后运行作业。查看两个终端输出；默认日志配置也会在当前发行目录的 logs/ 下写入 master 和 worker 日志。只有进程启动成功并不代表计算完成，应确认 master 日志中输入、超步计算和输出阶段均正常结束。

PageRank 参数类将结果写回 HugeGraph，属性名为 page_rank。运行前先检查图中每个目标顶点类型都允许此属性；Computer 会按 DOUBLE、OLAP_COMMON 创建属性键，但不会把它加入顶点类型。若属性键不存在，可先创建：

curl --fail --request POST \
  --header 'Content-Type: application/json' \
  --data '{"name":"page_rank","data_type":"DOUBLE","cardinality":"SINGLE","write_type":"OLAP_COMMON"}' \
  'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/propertykeys'

如果该属性键已存在，确认其类型为 DOUBLE 且 write_type 为 OLAP_COMMON。先列出图中的顶点类型，再对每个要计算的类型添加可空的 page_rank 属性；把示例中的 person 替换为实际类型名：

curl --fail --compressed \
  'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels'

curl --fail --request PUT \
  --header 'Content-Type: application/json' \
  --data '{"name":"person","properties":["page_rank"],"nullable_keys":["page_rank"]}' \
  'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels/person?action=append'

若图当前读模式不显示 OLAP 写入，可由管理员把读模式设为 ALL：

curl --fail --request PUT \
  --header 'Content-Type: application/json' \
  --data '"ALL"' \
  'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode'

查询顶点以确认结果属性：

curl --fail --compressed \
  'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices?limit=3'

需要认证时，在 curl 命令中添加 --user "$HG_USER:$HG_PASSWORD"。读模式接口和权限说明见图读模式 REST API。

5. 在 Kubernetes 中运行 PageRank

先确保 HugeGraph-Server 对计算 Pod 可达，并按 cert-manager 官方安装文档安装与集群兼容的 cert-manager。Computer Operator 清单会部署 Operator、etcd 和 MinIO；CRD 与 Operator 清单应使用同一 Computer 发行版本。下面以 1.7.0 发布版为例：

VERSION=1.7.0 # CRD 和 Operator 清单使用同一发布版本
kubectl apply -f "https://raw.githubusercontent.com/apache/hugegraph-computer/${VERSION}/computer/computer-k8s-operator/manifest/hugegraph-computer-crd.v1.yaml"
kubectl apply -f "https://raw.githubusercontent.com/apache/hugegraph-computer/${VERSION}/computer/computer-k8s-operator/manifest/hugegraph-computer-operator.yaml"
kubectl rollout status deployment/hugegraph-computer-operator-controller-manager \
  -n hugegraph-computer-operator-system --timeout=120s
可选：启用 MinIO 快照（1.7.0）

1.7.0 清单中的 MinIO Service 把 S3 API 的 9000 端口映射到了 Console 的 9090；启用快照时先修正映射，并将 snapshot.minio_endpoint 设为 http://hugegraph-computer-operator-minio.hugegraph-computer-operator-system.svc:9000。默认不启用快照时可跳过。

kubectl patch service hugegraph-computer-operator-minio \
  -n hugegraph-computer-operator-system \
  --type=json \
  -p='[{"op":"replace","path":"/spec/ports/0/targetPort","value":9000}]'

替换 HugeGraph 地址为计算 Pod 可访问的服务地址后，提交 HugeGraphComputerJob。示例使用官方 Docker Hub 的 hugegraph/hugegraph-computer:latest，并引用镜像内置的 PageRank JAR；自定义算法 JAR 可预置在镜像内通过 jarFile 指定，也可用 remoteJarUri 从 HTTP(S) 地址下载。分区数需不小于 worker 数量。

将以下 YAML 保存为 pagerank-job.yaml，然后应用该文件：

apiVersion: operator.hugegraph.apache.org/v1
kind: HugeGraphComputerJob
metadata:
  namespace: hugegraph-computer-operator-system
  name: pagerank-sample
spec:
  jobId: pagerank-sample
  algorithmName: page_rank
  image: hugegraph/hugegraph-computer:latest # 官方 Docker Hub 镜像
  jarFile: /hugegraph/hugegraph-computer/algorithm/builtin-algorithm.jar
  pullPolicy: IfNotPresent
  workerInstances: 1
  masterCpu: 500m
  workerCpu: 500m
  masterMemory: 1Gi
  workerMemory: 2Gi
  computerConf:
    job.partitions_count: "1"
    algorithm.params_class: org.apache.hugegraph.computer.algorithm.centrality.pagerank.PageRankParams
    hugegraph.url: http://hugegraph-server:8080
    hugegraph.name: hugegraph
kubectl apply -f pagerank-job.yaml
kubectl get hcjob pagerank-sample -n hugegraph-computer-operator-system --watch

SUCCEEDED 表示作业完成。Operator 默认会在作业完成后删除 CR 和计算资源；需要保留结果或排查失败作业时，可按需展开下方说明。

可选：保留作业状态、查看日志或清理资源

Operator 默认 AUTO_DESTROY_POD=true，短作业的 CR 和 Pod 可能在查看前被清理。若要保留它们，请在提交作业前关闭该选项，并等待 Controller 新 Pod 就绪后再提交；该设置必须改在 Java Operator 的 controller 容器中：

kubectl set env deployment/hugegraph-computer-operator-controller-manager \
  -n hugegraph-computer-operator-system \
  --containers=controller AUTO_DESTROY_POD=false
kubectl rollout status deployment/hugegraph-computer-operator-controller-manager \
  -n hugegraph-computer-operator-system --timeout=120s

查看运行信息或失败日志：

kubectl logs --follow <master-pod-name> -n hugegraph-computer-operator-system
kubectl logs --follow <worker-pod-name> -n hugegraph-computer-operator-system

查询完结果后删除 CR 以清理关联资源，并恢复默认策略：

kubectl delete hcjob pagerank-sample -n hugegraph-computer-operator-system
kubectl set env deployment/hugegraph-computer-operator-controller-manager \
  -n hugegraph-computer-operator-system \
  --containers=controller AUTO_DESTROY_POD=true

PageRank 写回 HugeGraph 后按上一节设置读模式并查询。若改用 HDFS 输出，结果位于 output.hdfs_path_prefix/<job.id>/ 下，文件名和分区布局由作业配置决定。

完整 CRD 字段见Computer 配置参考中的 CRD 说明。

6. 内置算法与开发入口

当前源码中的内置算法包括：

  • 中心性：PageRank、Betweenness Centrality、Closeness Centrality、Degree Centrality。
  • 社区与结构：Clustering Coefficient、K-core、LPA、Triangle Count、WCC。
  • 路径与采样：环检测、带过滤的环检测、单源最短路径、Random Walk。

算法实现位于 computer/computer-algorithm。自定义算法需要遵循 Computer API 并打包为可加载的 JAR；模块划分和开发入口见Computer README。

最后修改 2026-09-30 · docs: sync core modules guides (#501) (a8c685794)