imbajin commented on code in PR #501: URL: https://github.com/apache/hugegraph-doc/pull/501#discussion_r4113983838
########## content/cn/docs/clients/restful-api/graphspace.md: ########## @@ -14,7 +14,7 @@ description: "Graphspace（图空间）REST 接口：多租户与资源隔离的 1. 目前图空间功能只支持在 hstore 模式下使用。 2. 如果非 hstore 模式，则只能使用默认的图空间 `DEFAULT`，且不支持创建、删除和更新图空间的操作。 3. 注意在 rest-server.properties 中，设置 `usePD=true`，并且 hugegraph.properties 中，设置 `backend=hstore` -4. 图空间功能必须开启鉴权模式，默认账密为 admin:pa（见 `auth.admin_pa` 配置项），请务必修改默认密码，防止未授权访问。 +4. 生产环境建议启用鉴权，并修改默认管理员密码 `pa`（由 `auth.admin_pa` 配置）。创建、更新、删除图空间及管理角色的接口执行权限校验；列表与详情接口本身没有 `RolesAllowed` 角色注解，仍应结合实际鉴权配置控制暴露范围。 Review Comment: Fixed in ebec0f715. The warning now makes production authentication mandatory, explains that the two GET routes lack method-level role restrictions, and requires identity/role-based gateway access for trusted administrators/operators, IP allowlisting, and gateway auditing. It explicitly says Server authentication alone does not protect the returned DP credentials. ########## content/cn/docs/guides/hugegraph-docker-cluster.md: ########## @@ -31,80 +31,127 @@ HugeGraph 通过 Docker-Compose 可快速运行完整的分布式集群版（PD > 注: 后续步骤皆为假设你本地**已拉取** `hugegraph` 主仓库代码 (至少是 docker 目录) +本页的 HStore 与 HA Compose 操作按当前主线文件编写，必须使用从同一主线源码构建的 PD、Store 和 Server 镜像；不要把这些 Compose 文件与 `1.7.0` 标签的 HStore 组件镜像混用。单机示例单独固定 `hugegraph/hugegraph:1.7.0` 镜像标签。 + ## 鉴权环境 -所有拓扑都从 Compose 环境读取管理员密码和共享 JWT 密钥，通常放在 `docker/.env` 文件中： +以下 `.env` 模板对应当前主线 Compose。尖括号内容和 `replace-with-your-password` 都是占位，必须替换为真实值后才能载入或启动；可参考[主线 docker/README.md 的鉴权环境步骤](https://github.com/apache/hugegraph/blob/master/docker/README.md#create-the-authentication-environment)生成 `.env`，并先替换其中的管理员密码占位： ```bash HUGEGRAPH_ADMIN_PASSWORD='replace-with-your-password' HUGEGRAPH_AUTH_TOKEN_SECRET='<32 字节随机值，例如 openssl rand -hex 32>' +HG_PD_AUTH_SECRET_KEY='<24 字节随机值，例如 openssl rand -hex 24>' ``` -`HUGEGRAPH_ADMIN_PASSWORD` 非空即开启 Server 鉴权，Hubble 通过 Server API 自动识别该模式。不设置或设为空值则关闭鉴权，这只适用于可信的本地环境。保持同一个 JWT 密钥可以在容器重建后继续使用已签发的 token，多 Server 拓扑中的每个副本都会收到同一个密钥。HA 拓扑设置了 `HG_SERVER_REQUIRE_AUTH_TOKEN_SECRET: "true"`，因此只提供密码而没有共享密钥时会快速失败。请不要提交 `.env`。 +在主线 HStore 和 HA 拓扑中，`HG_PD_AUTH_SECRET_KEY` 是 PD REST Basic 鉴权密码，所有 PD 节点、Server 和 Hubble 都必须使用同一个值。当前主线 PD Docker 镜像要求设置该密钥。Hubble 不会直接读取 `.env`，启动前还要用该值生成拓扑对应的本地配置文件，见下文。不要提交 `.env` 或生成的 `.local.properties`。 + +`HUGEGRAPH_ADMIN_PASSWORD` 非空时会以 `PASSWORD` 启用 Server 鉴权，Hubble 通过 Server API 自动识别该模式；该密码只在首次初始化内置 `admin` 账号。不设置或设为空值则关闭鉴权，这只适用于可信的本地环境。 -`HUGEGRAPH_ADMIN_PASSWORD` 只在第一次以鉴权模式启动时初始化内置的 `admin` 账号。之后修改它不会轮换已有密码，请使用用户 API 修改。 +当前主线 Compose 会把 `HUGEGRAPH_AUTH_TOKEN_SECRET` 传给 `HG_SERVER_AUTH_TOKEN_SECRET`。同一密钥可让主线多 Server 副本验证相同 token，并在容器重建后继续验证已签发 token；HA Compose 还要求显式提供该密钥。`hugegraph/hugegraph:1.7.0` 单机镜像的 Docker 入口脚本只根据 `PASSWORD` 开启鉴权，不读取 `HG_SERVER_AUTH_TOKEN_SECRET`，因此不要把 `.env` 中该变量视为该镜像的固定 JWT 配置。若在 1.7.0 中需要固定 JWT secret，请在其认证图配置 `conf/graphs/hugegraph.properties` 中显式设置 `auth.token_secret`，并确保该配置随容器替换保留；认证图路径及密钥生成说明见[鉴权配置指南](/cn/docs/config/config-authentication/)。 + +之后修改 `HUGEGRAPH_ADMIN_PASSWORD` 不会轮换已有密码，请使用用户 API 修改。 ## 单节点快速启动 +本节固定使用 `hugegraph/hugegraph:1.7.0` 单机镜像标签；HStore/HA 示例使用当前主线构建镜像，不能照搬本节的版本号。 + ```bash -cd hugegraph/docker - # 注意版本号请随时保持更新 → 1.x.0 +cd "$(git rev-parse --show-toplevel)/docker" +# 单机 RocksDB Server 镜像示例 HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose.yml up -d --wait ``` 验证： ```bash -curl http://localhost:8080/versions -curl http://localhost:8088/about # Hubble +curl -fsS http://localhost:8080/versions +curl -fsS http://localhost:8088/about # Hubble ``` Hubble 默认只发布在宿主机回环地址（`127.0.0.1:8088`）。只有在 HTTPS 反向代理和可信网络管控之后才应设置 `HUBBLE_PUBLISH_HOST`。 -## 最小 HStore 快速启动 +## 最小 HStore 快速启动（当前主线镜像） + +从 HugeGraph Server 主线仓库根目录构建 PD、Store 和 HStore Server 镜像： ```bash -cd hugegraph/docker -HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-hstore.yml up -d --wait +cd "$(git rev-parse --show-toplevel)" +docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local . +docker build -f hugegraph-store/Dockerfile -t hugegraph/store:local . +docker build -f hugegraph-server/Dockerfile-hstore -t hugegraph/server:local . +``` + +从仓库根目录执行以下命令进入 `docker/`，载入 `.env` 并生成最小拓扑所需的 Hubble 配置。缺少 `hstore.local.properties` 时，Compose 不会为只读 bind mount 自动创建有效配置；先生成文件再启动： + +```bash +cd "$(git rev-parse --show-toplevel)/docker" +set -a; . ./.env; set +a +./set-hubble-pd-password.sh hstore +HUGEGRAPH_VERSION=local HUGEGRAPH_PULL_POLICY=never \ + docker compose -f docker-compose-hstore.yml up -d --wait ``` 验证： ```bash -curl http://localhost:8620/v1/health # PD -curl http://localhost:8520/v1/health # Store -curl http://localhost:8080/versions # Server -curl http://localhost:8088/about # Hubble +set -a; . ./.env; set +a +curl -fsS http://localhost:8620/v1/health # PD +curl -fsS http://localhost:8520/v1/health # Store +curl -fsS http://localhost:8080/versions # Server +curl -fsS http://localhost:8088/about # Hubble +curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?请先载入 .env}" \ + http://localhost:8620/v1/stores # PD REST 认证后查看 Store 注册状态 ``` 若要从本地源码构建该拓扑而不是拉取镜像，可加上开发覆盖文件，并在后续所有生命周期命令中同时带上这两个文件： ```bash +cd "$(git rev-parse --show-toplevel)/docker" +set -a; . ./.env; set +a +./set-hubble-pd-password.sh hstore docker compose -f docker-compose-hstore.yml -f docker-compose.dev.yml up -d --build --wait ``` -## 3 节点集群快速启动 +覆盖文件为本地构建生成 `dev` 标签的镜像；如果已经按上文构建 `local` 标签镜像，则使用基础 Compose 文件和 `HUGEGRAPH_VERSION=local` 启动，不要同时混用两个版本标签。 + +## 3 节点集群快速启动（当前主线镜像） + +HA Compose 文件不包含源码构建覆盖层。先按最小 HStore 一节从同一主线源码构建 `hugegraph/pd:local`、`hugegraph/store:local` 和 `hugegraph/server:local`，然后在 `docker/` 目录载入 `.env`，生成 HA Hubble 配置并启动： ```bash -cd hugegraph/docker -HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d --wait +cd "$(git rev-parse --show-toplevel)/docker" +set -a; . ./.env; set +a +./set-hubble-pd-password.sh hstore-ha +HUGEGRAPH_VERSION=local \ + docker compose -f docker-compose-3pd-3store-3server.yml up -d --wait ``` +HA Hubble bind-mount `conf/hubble/hstore-ha.local.properties`；必须在启动前生成。该文件与最小 HStore 使用的 `hstore.local.properties` 分开生成，但两者从同一 `.env` 读取同一个 `HG_PD_AUTH_SECRET_KEY`。 + 默认内置的启动顺序： 1. PD (节点)最先启动，且必须通过 `/v1/health` 健康检查 2. Store (节点)在所有 PD 健康后再启动 3. Server (节点)在所有 Store + PD 健康后最后启动 -验证集群正常：(重要) +验证集群正常：PD 的 `/v1/health` 和 `/v1/ready` 是无需认证的探针；查询 Store 注册和分区数据属于受保护的 PD REST 管理接口，需用用户名 `hg` 和 `.env` 中的 `HG_PD_AUTH_SECRET_KEY` 进行 Basic 认证。 + ```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 # 分区分配 +set -a; . ./.env; set +a +curl -fsS http://localhost:8620/v1/health # PD 健康检查 +curl -fsS http://localhost:8520/v1/health # Store 健康检查 +curl -fsS http://localhost:8080/versions # Server +for port in 8620 8621 8622; do + curl -fsS "http://localhost:${port}/v1/ready"; | grep -q '"ready":true' Review Comment: Fixed in ebec0f715. A failed per-node readiness probe now exits the pasted block with a nonzero status instead of allowing later requests to hide the failure. ########## content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md: ########## @@ -4,15 +4,15 @@ linkTitle: "HugeGraph-LLM" weight: 1 --- -HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演示服务把 Gradio 页面和 FastAPI 接口挂在同一个进程上，默认监听 `8001` 端口。 +HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演示服务把 Gradio 页面和 FastAPI 接口挂在同一个进程上，入口默认监听 `0.0.0.0:8001`；从本机访问可用 `http://localhost:8001`。仅需本机访问时，可显式指定 `--host 127.0.0.1`。 Review Comment: Fixed in ebec0f715. The guide now distinguishes the Python entrypoint default (127.0.0.1:8001) from Dockerfile.llm's explicit 0.0.0.0:8001 override. ########## content/cn/docs/quickstart/computing/hugegraph-computer.md: ########## @@ -1,241 +1,215 @@ --- -title: "HugeGraph-Computer Quick Start" +title: "HugeGraph-Computer 快速开始" linkTitle: "使用 Computer 进行 OLAP 分析" weight: 2 search_keywords: [HugeGraph Computer, 图计算, OLAP] search_boost: 1.6 --- -## 1 HugeGraph-Computer 概述 +## 1. 组件说明 -[`HugeGraph-Computer`](https://github.com/apache/hugegraph-computer) 是分布式图处理系统 (OLAP). 它是 [Pregel](https://kowshik.github.io/JPregel/pregel_paper.pdf)的一个实现。它可以运行在 Kubernetes(K8s)/Yarn 上。(它侧重可支持百亿~千亿的图数据量下进行图计算, 会使用磁盘进行排序和加速, 这是它和 Vermeer 相对最大的区别之一) +[`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 数据源，但部署和任务配置不能互换。 -- 支持分布式 MPP 图计算，集成 HugeGraph 作为图输入输出存储。 -- 算法基于 BSP(Bulk Synchronous Parallel) 模型，通过多次并行迭代进行计算，每一次迭代都是一次超步。 -- 自动内存管理。该框架永远不会出现 OOM（内存不足），因为如果它没有足够的内存来容纳所有数据，它会将一些数据拆分到磁盘。 -- 边的部分或超级节点的消息可以在内存中，所以你永远不会丢失它。 -- 您可以从 HDFS 或 HugeGraph 或任何其他系统加载数据。 -- 您可以将结果输出到 HDFS 或 HugeGraph，或任何其他系统。 -- 易于开发新算法。您只需要像在单个服务器中一样专注于仅顶点处理，而不必担心消息传输和内存存储管理。 +Computer 支持从 HugeGraph 或 HDFS 读取图数据，并可将结果写回 HugeGraph 或 HDFS。运行时可把部分数据溢写到磁盘；能否完成任务仍取决于输入规模、资源和配置，不应把溢写能力理解为不受资源限制。 -## 2 依赖 +## 2. 前置条件与连接 -### 2.1 安装 Java 11 (JDK 11) +构建和运行需要 JDK 11 或更高版本。源码构建还需要 Maven 3.5 或更高版本。PageRank 示例要求一个已启动且包含待计算图数据的 HugeGraph-Server，以及可供 master、worker 访问的 etcd。 -**必须**在 ≥ `Java 11` 的环境上启动 `Computer`，然后自行配置。 +| 服务 | 示例地址或端口 | 用途 | +|------|----------------|------| +| 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 | 按集群配置 | 仅当输入或输出配置为 HDFS 时需要。 | -**在往下阅读之前务必执行 `java -version` 命令查看 jdk 版本** +Kubernetes 作业中的 `hugegraph.url` 必须是各计算 Pod 都能访问的地址，不能填仅在个人电脑上可用的 `localhost`。如果启用了 HugeGraph 认证，应在配置中填写用户名和密码，并为 REST 查询使用对应凭据。 -## 3 开始 +更多配置项见[Computer 配置参考](/cn/docs/quickstart/computing/hugegraph-computer-config/)。 -### 3.1 在本地运行 PageRank 算法 +## 3. 获取源码并构建发行包 -> 要使用 HugeGraph-Computer 运行算法，必须装有 Java 11 或更高版本。 -> -> 还需要首先部署 HugeGraph-Server 和 [Etcd](https://etcd.io/docs/v3.5/quickstart/). - -有两种方式可以获取 HugeGraph-Computer： - -- 下载已编译的压缩包 -- 克隆源码编译打包 - -#### 3.1.1 下载已编译的压缩包 - -下载最新版本的 HugeGraph-Computer release 包： +Apache 1.7.0 发行目录提供 Computer 源码包 `apache-hugegraph-computer-incubating-1.7.0-src.tar.gz`，不是单独的预编译 Computer 二进制包。下载时同时取得同目录下的 `.sha512` 和 `.asc` 文件。首次验签前还需取得 Apache 项目 [`KEYS`](https://downloads.apache.org/hugegraph/KEYS) 并导入公钥；应先核对密钥指纹来自 Apache 项目发布渠道，再验证签名。后续版本请从 [Apache HugeGraph 下载目录](https://downloads.apache.org/hugegraph/)选择与运行环境匹配的版本。 ```bash -wget https://downloads.apache.org/hugegraph/${version}/apache-hugegraph-computer-incubating-${version}.tar.gz -tar zxvf apache-hugegraph-computer-incubating-${version}.tar.gz -C hugegraph-computer +curl -fLO https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-computer-incubating-1.7.0-src.tar.gz +curl -fLO https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-computer-incubating-1.7.0-src.tar.gz.sha512 +curl -fLO https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-computer-incubating-1.7.0-src.tar.gz.asc +curl -fLO https://downloads.apache.org/hugegraph/KEYS +shasum -a 512 -c apache-hugegraph-computer-incubating-1.7.0-src.tar.gz.sha512 +gpg --import KEYS +gpg --verify apache-hugegraph-computer-incubating-1.7.0-src.tar.gz.asc apache-hugegraph-computer-incubating-1.7.0-src.tar.gz +tar -xzf apache-hugegraph-computer-incubating-1.7.0-src.tar.gz +cd apache-hugegraph-computer-incubating-1.7.0-src/computer +mvn clean package -DskipTests +tar -xzf target/apache-hugegraph-computer-1.7.0.tar.gz +cd apache-hugegraph-computer-1.7.0 ``` -#### 3.1.2 克隆源码编译打包 - -克隆最新版本的 HugeGraph-Computer 源码包： +也可以克隆源码后从 Maven 聚合工程目录构建： ```bash -$ git clone https://github.com/apache/hugegraph-computer.git +git clone https://github.com/apache/hugegraph-computer.git +cd hugegraph-computer/computer +mvn clean package -DskipTests +tar -xzf target/apache-hugegraph-computer-1.7.0.tar.gz +cd apache-hugegraph-computer-1.7.0 ``` -编译生成 tar 包： +发行包由 `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`。在 Maven 聚合工程 `computer/` 中运行 `package` 后，tar 包位于 `computer/target/`，发行目录位于 `computer/apache-hugegraph-computer-1.7.0/`。 -```bash -cd hugegraph-computer -mvn clean package -DskipTests -``` +## 4. 单机运行 PageRank -#### 3.1.3 启动 master 节点 +先编辑发行目录中的 `conf/computer.properties`，按实际环境修改 HugeGraph 地址、图名和认证信息，并确认 `bsp.etcd_endpoints` 指向可访问的 etcd。默认配置已选择内置 `PageRankParams`；master 和 worker 必须使用同一份配置及相同的 `job.id`。每个并行作业应使用不同的 `job.id`。 -> 您可以使用 `-c` 参数指定配置文件，更多 computer 配置请看：[Computer 配置选项](/cn/docs/quickstart/computing/hugegraph-computer-config/#computer-配置选项) +在两个终端中都从发行目录启动进程。启动脚本默认读取 `conf/computer.properties`，也可用 `-c` 指定配置文件。 ```bash -cd hugegraph-computer +# 终端一：启动 master bin/start-computer.sh -d local -r master ``` -#### 3.1.4 启动 worker 节点 - ```bash +# 终端二：启动 worker bin/start-computer.sh -d local -r worker ``` -#### 3.1.5 查询算法结果 +master 会等待配置要求的 worker 注册后运行作业。查看两个终端输出；默认日志配置也会在当前发行目录的 `logs/` 下写入 master 和 worker 日志。只有进程启动成功并不代表计算完成，应确认 master 日志中输入、超步计算和输出阶段均正常结束。 -2.5.1 为 server 启用 `OLAP` 索引查询 +PageRank 参数类将结果写回 HugeGraph，属性名为 `page_rank`。运行前先检查图中每个目标顶点类型都允许此属性；Computer 会按 `DOUBLE`、`OLAP_COMMON` 创建属性键，但不会把它加入顶点类型。若属性键不存在，可先创建： -如果没有启用 OLAP 索引，则需要启用，更多参考：[modify-graphs-read-mode](/cn/docs/clients/restful-api/graphs/#634-设置某个图的读模式该操作需要管理员权限) - -```http -PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode - -"ALL" +```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' ``` -3.1.5.2 查询 `page_rank` 属性值： +如果该属性键已存在，确认其类型为 `DOUBLE` 且 `write_type` 为 `OLAP_COMMON`。先列出图中的顶点类型，再对每个要计算的类型添加可空的 `page_rank` 属性；把示例中的 `person` 替换为实际类型名： ```bash -curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices?page&limit=3"; | gunzip -``` - -### 3.2 在 Kubernetes 中运行 PageRank 算法 +curl --fail --compressed \ + 'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels' -> 要使用 HugeGraph-Computer 运行算法，您需要先部署 HugeGraph-Server +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' +``` -#### 3.2.1 安装 HugeGraph-Computer CRD +若图当前读模式不显示 OLAP 写入，可由管理员把读模式设为 `ALL`： ```bash -# Kubernetes version >= v1.16 -kubectl apply -f https://raw.githubusercontent.com/apache/hugegraph-computer/master/computer-k8s-operator/manifest/hugegraph-computer-crd.v1.yaml - -# Kubernetes version < v1.16 -kubectl apply -f https://raw.githubusercontent.com/apache/hugegraph-computer/master/computer-k8s-operator/manifest/hugegraph-computer-crd.v1beta1.yaml +curl --fail --request PUT \ + --header 'Content-Type: application/json' \ + --data '"ALL"' \ + 'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode' ``` -#### 3.2.2 显示 CRD +查询顶点以确认结果属性： ```bash -kubectl get crd - -NAME CREATED AT -hugegraphcomputerjobs.hugegraph.apache.org 2021-09-16T08:01:08Z +curl --fail --compressed \ + 'http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices?limit=3' ``` -#### 3.2.3 安装 hugegraph-computer-operator&etcd-server +需要认证时，在 `curl` 命令中添加 `--user "$HG_USER:$HG_PASSWORD"`。读模式接口和权限说明见[图读模式 REST API](/cn/docs/clients/restful-api/graphs/#634-设置某个图的读模式)。 + +## 5. 在 Kubernetes 中运行 PageRank + +先确保 HugeGraph-Server 对计算 Pod 可达。Computer Operator 清单会部署 Operator、etcd 和 MinIO（供快照功能使用），但不会安装 cert-manager。清单包含 cert-manager `Certificate`、`Issuer` 资源和 CA 注入标注，因此应用 Operator 清单前必须安装与集群版本兼容的 cert-manager，并等待 controller、cainjector 和 webhook 就绪。以下命令以适配 Kubernetes 1.33–1.36 的 cert-manager 1.21.2 为例，其他集群版本应按 [cert-manager 支持矩阵](https://cert-manager.io/docs/releases/)选择兼容版本。CRD 和 Operator 清单应使用同一 Computer 发行版本。下面以 1.7.0 的 `v1` CRD 为例： ```bash -kubectl apply -f https://raw.githubusercontent.com/apache/hugegraph-computer/master/computer-k8s-operator/manifest/hugegraph-computer-operator.yaml +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.2/cert-manager.yaml +kubectl rollout status deployment/cert-manager -n cert-manager --timeout=120s +kubectl rollout status deployment/cert-manager-cainjector -n cert-manager --timeout=120s +kubectl rollout status deployment/cert-manager-webhook -n cert-manager --timeout=120s + +kubectl apply -f https://raw.githubusercontent.com/apache/hugegraph-computer/1.7.0/computer/computer-k8s-operator/manifest/hugegraph-computer-crd.v1.yaml +kubectl apply -f https://raw.githubusercontent.com/apache/hugegraph-computer/1.7.0/computer/computer-k8s-operator/manifest/hugegraph-computer-operator.yaml +kubectl get pods -n hugegraph-computer-operator-system --watch ``` -#### 3.2.4 等待 hugegraph-computer-operator&etcd-server 部署完成 +若要启用 MinIO 快照，需先修正 Computer 1.7.0 清单中的 Service 端口映射：S3 API 监听 `9000`，而 `9090` 是 Console 端口。等待 Pod 就绪并退出上面的监视命令后，执行以下命令，再将 `snapshot.minio_endpoint` 设为 `http://hugegraph-computer-operator-minio.hugegraph-computer-operator-system.svc:9000`。默认不启用快照时可跳过此步骤。 ```bash -kubectl get pod -n hugegraph-computer-operator-system - -NAME READY STATUS RESTARTS AGE -hugegraph-computer-operator-controller-manager-58c5545949-jqvzl 1/1 Running 0 15h -hugegraph-computer-operator-etcd-28lm67jxk5 1/1 Running 0 15h +kubectl patch service hugegraph-computer-operator-minio \ + -n hugegraph-computer-operator-system \ + --type=json \ + -p='[{"op":"replace","path":"/spec/ports/0/targetPort","value":9000}]' ``` -#### 3.2.5 提交作业 +确认 cert-manager、Operator 和 etcd Pod 已就绪后，提交 `HugeGraphComputerJob`。替换镜像为集群可拉取且包含对应版本运行时与内置算法 JAR 的镜像，并把 HugeGraph 地址改成 Pod 可访问的服务地址。分区数必须不小于 worker 数量。下面为小图示例设置 Master `1Gi`、Worker `2Gi` 内存及 `500m` CPU 限制；实际作业应按图规模和运行配置调整。 -> 更多 computer crd spec 请看：[Computer CRD](/cn/docs/quickstart/computing/hugegraph-computer-config/#hugegraph-computer-crd) -> -> 更多 Computer 配置请看：[Computer 配置选项](/cn/docs/quickstart/computing/hugegraph-computer-config/#computer-配置选项) +Operator 清单默认 `AUTO_DESTROY_POD=true`，作业完成后会删除 CR 和计算资源。短作业可能在用户读取最终状态前就被清理。需要保留 CR、Pod 和日志时，先在 Java Operator 的 `controller` 容器设置 `AUTO_DESTROY_POD=false`；同一 Deployment 中名为 `manager` 的 Go 容器不是此配置入口： + +```bash +kubectl set env deployment/hugegraph-computer-operator-controller-manager \ + -n hugegraph-computer-operator-system \ + --containers=controller AUTO_DESTROY_POD=false Review Comment: Fixed in ebec0f715. The optional job-retention instructions now wait for the controller Deployment rollout after setting AUTO_DESTROY_POD=false and before submitting a job. These troubleshooting steps are folded to keep the main quick-start flow short. ########## content/cn/docs/quickstart/computing/hugegraph-computer-config.md: ########## @@ -6,7 +6,16 @@ weight: 3 ## Computer 配置选项 -表格中的默认值来自 `computer-api` 模块的 `ComputerOptions.java`。分发包的 `conf/computer.properties` 显式覆盖某项时，表格以“代码默认值（打包：实际值）”标注；程序启动后以配置文件中的值为准。 +表格中的默认值来自 `computer-api` 模块的 `ComputerOptions.java`；发行包的 `conf/computer.properties` 显式设置的值以“代码默认值（发行包：实际值）”标注。`rpc.*` 等通用配置由 HugeGraph Commons 提供，以下会单独标出发行包实际值。 + +### 配置文件从哪里来 + +- 源码模板：[`computer/computer-dist/src/assembly/static/conf/computer.properties`](https://github.com/apache/hugegraph-computer/blob/1.7.0/computer/computer-dist/src/assembly/static/conf/computer.properties)；日志配置模板为同目录的 `log4j2.xml`。Maven `package` 阶段将模板复制进发行目录的 `conf/`，并将运行依赖和内置算法 JAR 装入 `lib/`、`algorithm/`。模板由源码维护，没有单独的配置生成命令。 +- 单机、YARN：启动脚本默认读取发行目录的 `conf/computer.properties`，可使用 `bin/start-computer.sh -c <配置文件路径>` 覆盖；master 和 worker 应读到同一组作业参数。 +- Kubernetes Operator：用户在 CRD 的 `spec.computerConf` 中提供键值；Operator 将它写成 ConfigMap，挂载为容器内的 `computer.properties`。Operator 会补入作业 ID、worker 数量、Pod 地址和未指定时的 etcd 地址，并在未指定或设为 `0` 时将数据传输端口设为 `8099`、master RPC 端口设为 `8190`。`transport.server_host` 与 `rpc.server_host` 会被设置为 Pod IP。作业容器启动脚本只对 `${POD_IP}`、`${HOSTNAME}`、`${POD_NAME}`、`${POD_NAMESPACE}` 做环境变量替换。 +- Kubernetes 作业镜像必须包含 Computer 运行时及所需算法 JAR；CRD 的 `jarFile` 可指向镜像内 JAR，`remoteJarUri` 可让启动脚本从 HTTP(S) 地址下载算法 JAR。示例与字段见[Computer 快速开始](/cn/docs/quickstart/computing/hugegraph-computer/)及下方 CRD 表。 Review Comment: Fixed in ebec0f715. The quick-start and configuration reference now explain that the image supplies the Computer runtime and that an algorithm JAR may either be bundled or downloaded through remoteJarUri. The runnable example uses the official Docker Hub image. -- 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]
