# HugeGraph-Computer 快速上手

LLMS 索引： [llms.txt](/cn/llms.txt)

---

## 1. 组件说明

[`HugeGraph-Computer`](https://github.com/apache/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. 前置条件与连接

构建和运行 Computer 在**示例固定的 1.7.0 版本需使用 JDK 11**（主线 **1.8.0+ 及 master 要求 JDK 17 或更高版本**，包括集群中各计算节点与 Worker）；
源码构建还需要 **Maven 3.6.3 或更高版本**（1.7.0 需 Maven 3.5+）。在自定义 Java 应用程序中嵌入运行 Computer 1.8.0+ 时，必须配置以下 JVM 运行选项：
`--add-opens=java.base/java.io=ALL-UNNAMED`（用于缓冲文件复制）与 `--add-opens=java.base/java.lang=ALL-UNNAMED`（用于 SOFA RPC 动态代理生成）；
官方发行包启动脚本 `bin/start-computer.sh` 及 Kubernetes Operator 已自动配置上述参数。PageRank 示例要求一个已启动且包含待计算图数据的
HugeGraph-Server，以及可供 master、worker 访问的 etcd。

| 服务 | 示例地址或端口 | 用途 |
|------|----------------|------|
| HugeGraph-Server | `http://127.0.0.1:8080` | 读取图数据并写回算法结果；以 `hugegraph.url` 为准。 |
| etcd | `http://127.0.0.1:2379` | BSP 作业协调；以 `bsp.etcd_endpoints` 为准。 |
| Computer master RPC | TCP `8190` | worker 连接 master；发行配置中的端口。 |
| Computer worker 数据传输 | 本地默认由系统分配；K8s Operator 默认 `8099` | worker 之间传输顶点和消息。跨主机时需保证公告地址和端口可达。 |
| 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 | 按集群配置（CI 测试使用 Hadoop 3.5.0） | 仅当输入或输出配置为 HDFS 时需要。CI 测试使用兼容 Java 17 的 Hadoop 3.5.0 镜像。 |

Kubernetes 作业中的 `hugegraph.url` 必须是各计算 Pod 都能访问的地址，不能填仅在个人电脑上可用的 `localhost`。如果启用了 HugeGraph 认证，
应在配置中填写用户名和密码，并为 REST 查询使用对应凭据。容器化与 Kubernetes 部署中，计算镜像（如 `hugegraph/hugegraph-computer:latest`）基于 Java 17 运行时构建。

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

更多配置项见[Computer 配置参考](/cn/docs/quickstart/computing/hugegraph-computer-config/)。

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

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

```bash
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 构建时可直接克隆并打包：

```bash
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` 指定配置文件：

```bash {tab="终端一：Master"}
# 启动 Computer Master 进程
bin/start-computer.sh -d local -r master
```

```bash {tab="终端二：Worker"}
# 启动 Computer Worker 进程
bin/start-computer.sh -d local -r worker
```

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

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

```bash
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` 替换为实际类型名：

```bash
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`：

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

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

```bash
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](/cn/docs/clients/restful-api/graphs/#634-设置某个图的读模式)。

## 5. 在 Kubernetes 中运行 PageRank

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

```bash
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
```

> [!DETAILS]- 可选：启用 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`。默认不启用快照时可跳过。
>
> ```bash
> 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`（基于 Java 17 运行时）和内置 PageRank 算法包。若在 Kubernetes 或 Docker 环境下测试 HDFS 输入输出，
请搭配兼容 Java 17 的 Apache Hadoop 3.5.0 存储集群或镜像使用。自定义算法可打包进镜像并通过 `jarFile` 指定，也可通过 `remoteJarUri` 从 HTTP(S) 地址下载。
分区数需不小于 worker 数量。

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

```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
```

```bash
kubectl apply -f pagerank-job.yaml
kubectl get hcjob pagerank-sample -n hugegraph-computer-operator-system --watch
```

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

> [!DETAILS]- 可选：保留作业状态、查看日志或清理资源
>
> Operator 默认 `AUTO_DESTROY_POD=true`，短作业的 CR 和 Pod 可能在查看前被清理。若要保留它们，请在提交作业前关闭该选项，并等待 Controller 新 Pod 就绪后再提交；该设置必须改在 Java Operator 的 `controller` 容器中：
>
> ```bash
> 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
> ```
>
> 查看运行信息或失败日志：
>
> ```bash
> kubectl logs --follow <master-pod-name> -n hugegraph-computer-operator-system
> kubectl logs --follow <worker-pod-name> -n hugegraph-computer-operator-system
> ```
>
> 查询完结果后删除 CR 以清理关联资源，并恢复默认策略：
>
> ```bash
> 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 说明](/cn/docs/quickstart/computing/hugegraph-computer-config/#hugegraph-computer-crd)。

## 6. 内置算法与开发入口

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

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

算法实现位于 [`computer/computer-algorithm`](https://github.com/apache/hugegraph-computer/tree/master/computer/computer-algorithm)。自定义算法需要遵循 Computer API 并打包为可加载的 JAR；模块划分和开发入口见[Computer README](https://github.com/apache/hugegraph-computer/blob/master/computer/README.md)。

---

反链：

- [Task](/cn/docs/clients/restful-api/task/)
- [架构概览](/cn/docs/guides/architectural/)
- [系统介绍](/cn/docs/introduction/)
- [图计算（OLAP）](/cn/docs/quickstart/computing/)
- [Computer 配置参考](/cn/docs/quickstart/computing/hugegraph-computer-config/)
