diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 4c4e5b3a93..5decfc0f9e 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -593,6 +593,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode > 合法的图模式包括:NONE,RESTORING,MERGING,LOADING +存在活跃的 loading owner 时,此枚举 PUT 会拒绝所有模式修改,包括 `"LOADING"`。请先停止导入 worker,再释放其 owner。 + ##### Response Status ```javascript @@ -671,6 +673,77 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode } ``` +#### 6.3.5 LOADING owner 管理 {#loading-ownership} + +自 HugeGraph 1.8.0 起提供 owner 协议 1 接口(需配合返回 `protocol: 1` 的新版 Server 与对应 Loader;当前 `master` 分支暂未包含该协议); +Loader 需使用配套的 1.8.0 及以上版本客户端。旧版本发行包、早期 1.8 构建以及当前 `master` 分支均不包含该协议;仅支持 `LOADING` 枚举不能说明支持这些接口。 +启用鉴权时,两个接口沿用模式设置接口的权限要求,即图空间管理权限(`space`)或该图所有者权限,并校验 STATUS 写权限。 +Server 将句柄绑定到实际鉴权用户;token 本身不赋予权限。申请、释放和重试必须保持相同身份。 + +```text +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +`200` 能力响应包含图实例 UUID、当前非负 epoch 及状态 revision: + +```json +{ + "protocol": 1, + "instance": "", + "epoch": 0, + "revision": 0 +} +``` + +每轮导入生成一个新的小写连字符 UUID(lowercase hyphenated UUID)作为 `token`,保留返回的 `instance` 和 `epoch`,通过以下请求申请,并设置 `Content-Type: application/json`: + +```text +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +```json +{ + "action": "acquire", + "instance": "", + "epoch": 0, + "token": "" +} +``` + +只有响应中包含 `state: "active"` 时才表示申请成功;此时返回 `200` 并回显 `protocol`、`instance`、`epoch`、`token` 以及 `mode: "LOADING"`。 +若返回 `200` 但 `state: "released"`,说明该句柄已失效或已被提前取消,此时并未获得 owner 保护;必须先停止并排空该次导入尝试,然后再通过 GET 获取新的 `instance` 和 `epoch` 并使用新 token 重新发起尝试。 +释放时将 `action` 设置为 `release`,句柄保持不变;响应中包含 `state: "released"` 和当前实际模式。未申请前直接调用释放会被记录,并导致后续使用该句柄的申请直接返回 `released`。 +重试保留同一句柄;Server 校验其鉴权身份、instance 和 epoch。已释放句柄不能再次申请。 + +当异常中断(如 `kill -9`)导致句柄残留时,管理员可发起强制恢复请求: + +```text +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +```json +{ + "action": "recover", + "instance": "", + "epoch": 0, + "revision": 0, + "confirm": "I'm sure all imports have stopped" +} +``` + +管理员恢复需要全局管理员权限(`admin`)。调用方必须传入从 `GET /mode/owners` 获取的当前 `revision`、`instance` 和 `epoch`, +以及确认文案 `confirm: "I'm sure all imports have stopped"`。 +若传入的 `revision` 与服务端当前状态不一致,请求将被拒绝并返回 HTTP `409 Conflict`。 +恢复成功后服务端清除所有残留 owner,将图模式重置为 `NONE` 并递增 epoch,返回 HTTP `200`(含 `state: "recovered"` 和 `mode: "NONE"`)。 + +首个 owner 要求 `NONE`;其他 owner 共享由 owner 管理的 `LOADING`,最后一个释放后恢复 `NONE`。 +手动设置的 `LOADING`、`RESTORING` 和 `MERGING` 不会被接管;owner 活跃时,旧枚举 PUT 会拒绝模式修改。 + +该协议保护同一 Server 上实际运行的图实例中的普通导入,句柄绑定到实际鉴权身份、instance 和 epoch。 +它不提供跨 Server 协调、数据写入隔离或自动过期。请使用固定的 Server 直连地址,在导入停止后释放。 +升级后的 Loader 仅在 owner 探测返回接口路由不受支持的 `404` 时回退到旧行为;其他错误仍失败。 +图数据源和恢复导入保留原有枚举模式行为,参见 [Loader 兼容与恢复说明](/cn/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership)。 + ### 6.4 Snapshot #### 6.4.1 创建快照 diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 49722ff265..3ec6a692e9 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -221,12 +221,25 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ | `HG_SERVER_PD_REST_ENDPOINT` | 由 `pd.peers` 把 `:8686` 改写为 `:8620` 得到 | `wait-storage.sh` 轮询的 PD REST 地址 | | `PD_AUTH_USER` | `store` | `wait-storage.sh` 访问 PD REST API 的 Basic 用户名 | | `PD_AUTH_PASSWORD` | 空 | PD REST Basic 密码;启用 PD REST 鉴权时须与 `HG_PD_AUTH_SECRET_KEY` 相同 | -| `WAIT_PARTITION_TIMEOUT_S` | `120` | `wait-partition.sh` 等待分区分配的时长 | +| `WAIT_PARTITION_TIMEOUT_S` | `120` | 分区轮询超时;包含下文修复的构建还会限制最终诊断 | + +包含鉴权属性修复的 master 镜像会保留显式签名密钥中的空格、反斜杠和 Unicode,各 Server 副本应使用同一密钥。 +如果旧镜像曾错误读取这类密钥,升级时应重新显式提供原本想使用的 `HG_SERVER_AUTH_TOKEN_SECRET`;仅复用旧配置仍会保留错误读取后的密钥。 +若实际生效的密钥改变,须重新登录获取 token。上文所述 1.7.0 镜像限制仍适用。 + +旧镜像在初始化程序继承 C locale 时,可能错误初始化 Unicode 管理员密码。升级或再次设置 `PASSWORD` 不会修复已有账号存储的密码, +须由仍可登录的管理员通过[用户 API](/cn/docs/clients/restful-api/auth/)修改。若已无可用管理员身份,本修复不提供自动恢复;应保留现有数据,安排账号恢复后再升级。 > **已弃用的别名**:`BACKEND` → `HG_SERVER_BACKEND`、`PD_PEERS` → `HG_SERVER_PD_PEERS` `wait-storage.sh` 最多等待 300 秒直到出现状态为 `Up` 的 Store。该时长写死在脚本中,无法通过环境变量调整。 +在当前 master Server 构建中,HStore 启动时,分区轮询和最终 +`/v1/partitions` 诊断分别使用独立的 `WAIT_PARTITION_TIMEOUT_S` 预算。旧构建仅限制轮询时间,最终诊断请求没有超时。 +使用默认配置时,最终响应停滞会在 120 秒后超时;设为 `0` 会禁用 GNU timeout 的时限。 +入口脚本在等待 Java 进程前会先等待 `wait-partition.sh`。若 Java 进程在分区轮询阶段提前退出,轮询仍可能消耗完整超时预算后入口脚本才感知到退出; +若轮询成功,后续的最终诊断也可能再次消耗完整的超时预算。信号触发的关闭仍可正常中断检查。 + `HG_SERVER_INIT_STORE_ENABLED` 只接受 `HugeConfig` 能识别的写法(忽略大小写):`y`、`t`、`yes`、`on`、`true`、`n`、`f`、`no`、`off`、`false`。其他取值(包括 `0` 和 `1`)都会让入口脚本终止。 入口脚本在初始化成功后写入 `docker/init_complete`,后续启动会跳过重新初始化,但仍会再执行一次 `bin/init-store.sh`,以便关闭状态下每次启动都重新校验配置。 @@ -309,8 +322,7 @@ HugeGraph JVM 都已退出后可以删除旧目录,但不要动正在运行的 Compose 中 Server 服务的 `environment:` 里添加,自带的 Compose 文件没有设置它,或在 Kubernetes 中使用 `env`;只在宿主机 shell 中导出不会生效),这样会保留镜像默认的 `JAVA_OPTS`;把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM 生效,而且会替换镜像默认值(`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`),需要把这些参数一并写上。 -> **版本范围**:上文描述的是基于当前 master 构建的镜像(PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980),HStore Server 见 -> [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258))。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`,包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`:`docker logs` +> **版本范围**:上文描述的是基于当前 master 构建的镜像。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`,包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`:`docker logs` > 只能看到入口脚本的输出,服务日志仍在容器内的 `logs/` 中(Server 为 `logs/hugegraph-server.log`)。 ## 容器监控与健康检查 @@ -324,14 +336,18 @@ Compose 中 Server 服务的 `environment:` 里添加,自带的 Compose 文件 现在,入口脚本直接监控 Java 进程: - **PD 和 Store 容器**:入口脚本向启动脚本传入 `-d false` 参数,启动脚本通过 `exec` 直接替换为 Java 进程。容器进程即为 Java 进程,当 Java 退出(崩溃或正常关闭)时,容器立即退出,Docker 的重启策略随即触发。 -- **Server 容器**:入口脚本使用 `tail --pid=$PID -f /dev/null` 阻塞,直到 Java 退出。`SIGTERM`/`SIGINT` 信号陷阱会将 `docker stop` 信号转发给 Java 并等待其正常关闭(退出码 0)。若 Java 崩溃,入口脚本以退出码 1 退出,从而触发重启策略。 +- **Server 容器**:入口脚本持有前台 launcher 并等待 Java。服务就绪后保留 Java 的实际退出码,包括 `0`、`42` 和 `SIGKILL` 对应的 `137`。 + `SIGTERM` 和 `SIGINT` 请求协作关闭、回收持有的就绪/分区检查进程,并在关闭后分别返回 `143` 和 `130`。 - 所有镜像中的 PID 1 均为 `dumb-init`,负责将 Docker 信号转发给入口脚本进程。 ### Server 启动等待超时 -`HG_SERVER_STARTUP_TIMEOUT_S` 控制 Server 启动脚本等待 REST 服务响应的时长,未设置时默认 **120 秒**。取值必须是不带前导零的十进制整数,范围为 **1–86400 秒**。空字符串、`0`、负数、小数和超出范围的值都会使入口脚本记录错误并以退出码 `1` 退出。 +`HG_SERVER_STARTUP_TIMEOUT_S` 设置 Docker 入口脚本等待 REST 就绪的期限,未设置时默认 **120 秒**。取值必须是不带前导零的十进制整数,范围为 **1–86400 秒**。空字符串、`0`、负数、小数和超出范围的值都会使入口脚本记录错误并以退出码 `1` 退出。 -入口脚本通过 `bin/start-hugegraph.sh -t` 传入该值。如果 Server 在等待期限内未就绪,或进程提前退出,启动失败,容器以退出码 `1` 退出;配置的重启策略可能会重新启动容器。此时长不包括此前的存储初始化或等待后端就绪的时间。 +入口脚本也通过 `bin/start-hugegraph.sh -t` 传入该值;前台 launcher 本身等待 Java,不轮询 REST。 +启动期限失败、或 Java 在就绪前以 `0` 退出时,入口脚本返回 `1`;提前以非零码退出则保留该退出码。 +此时长不包括此前的存储初始化或等待后端就绪的时间。关闭时可以中断就绪和分区检查;启动期限失败会请求终止 Java 并返回,不增加无限等待。 +未响应终止请求的 Java 进程仍依靠容器终止完成最终清理。 例如,在 HugeGraph 仓库的 `docker/` 目录下,将单机 Server 的启动等待时间增加到 300 秒(Compose 文件会将该变量传入容器): diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 80540bfdb2..a7ae6ee913 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -2,13 +2,22 @@ title: "使用 Helm 部署 HugeGraph" linkTitle: "Helm 部署" weight: 4 -search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble, 内网部署] +search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, 内网部署, OCI, GHCR, Artifact Hub] --- -本文对应 HugeGraph 开发分支的 chart。发布镜像完成前标签仍为 `latest`,实际部署请固定自己的镜像版本。 -需要 Helm 3 和 Kubernetes 1.23 或更高版本。常用命令和参数见 -[chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md),生命周期操作见 -[运维参考](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md)。 +本文适用于 HugeGraph **1.8.0 及以后版本**,需要支持 OCI 的 Helm **3.8+** 和 Kubernetes (K8s) **1.23+**。 +可从 GHCR 或 Docker Hub 安装 `hugegraph-helm`。Chart 与 HugeGraph 服务分别维护版本,例如 `0.2.x` 的 Chart 可以部署 `1.8.x` 的服务。 + +> [!WARNING] +> 当前开发 Chart 使用 `latest` 镜像,适合测试。 +> 对应 HugeGraph 服务正式发布后,生产环境请选择稳定 Chart,并检查其中的镜像版本。 +> 镜像标签可能变化;需要固定镜像内容时,请配置各组件的 `image.digest`。 + +[Artifact Hub](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) 方便查找 Chart、查看版本和安装说明,实际安装包仍从 GHCR 或 Docker Hub 下载。 +参数和源码开发方式见 [chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md), +生命周期操作见 [运维参考](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md)。 + +![在 Artifact Hub 选择版本,从 GHCR 或 Docker Hub 下载 Chart,再使用 Helm 安装到 Kubernetes](/images/helm-oci-install-cn.png) ## 1 安装 @@ -18,26 +27,47 @@ search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble, 内网部署] > - **存储依赖**:需要集群具备默认动态 StorageClass 或预先匹配的静态 local PV,共需 7 个持久卷(3 个 10 GiB PD 卷、3 个 50 GiB Store 卷、1 个 1 GiB Hubble 卷)。 > - **内存考量**:保留镜像内 JVM 内存自动推导;按需调整 resource requests/limits,确保宿主机给 9 个图服务 JVM 与 Hubble 提供足够内存。 -```bash -git clone https://github.com/apache/hugegraph.git -cd hugegraph +选择一个下载源即可,公共 CI 推荐 GHCR。本地轻量测试可直接使用单节点预设。 + +> [!TIP] +> `--devel` 按版本号选择最新 Chart,包含开发版和稳定版,不限于某个版本系列。 +> 生产部署或需要复现时,将 `--devel` 换成 `--version <已发布版本>`,固定你选定的版本。 + +```bash {tab="GHCR(推荐)"} +CHART=oci://ghcr.io/hugegraph/hugegraph-helm +kubectl config current-context +kubectl get nodes +kubectl get storageclass +helm install hugegraph "$CHART" --devel -n hugegraph \ + --create-namespace --wait --timeout 15m +``` + +```bash {tab="Docker Hub"} +CHART=oci://registry-1.docker.io/hugegraph/hugegraph-helm kubectl config current-context kubectl get nodes kubectl get storageclass -# 默认标准集群安装(3 PD + 3 Store + 3 Server + 1 Hubble,需 7 个 PV): -helm install hugegraph ./helm/hugegraph -n hugegraph \ +helm install hugegraph "$CHART" --devel -n hugegraph \ --create-namespace --wait --timeout 15m +``` -# 本地测试 / 单节点轻量环境(Minikube、Kind 等,仅各 1 副本且关闭反亲和): -# helm install hugegraph ./helm/hugegraph -n hugegraph \ -# -f ./helm/hugegraph/values-single.yaml \ -# --create-namespace --wait --timeout 10m +```bash {tab="单节点试用"} +# 适合本地 Minikube/Kind 等轻量测试;直接安装本次下载的 Chart +CHART=oci://ghcr.io/hugegraph/hugegraph-helm +helm pull "$CHART" --devel --untar +helm install hugegraph ./hugegraph-helm -n hugegraph \ + -f ./hugegraph-helm/values-single.yaml \ + --create-namespace --wait --timeout 10m ``` +单节点试用预设替代默认安装,将各组件设为 1 副本并放宽调度限制,适合资源受限环境。 + ## 2 模式和访问入口 +解压后目录为 `hugegraph-helm/`,源码目录仍为 `helm/hugegraph/`。 + ```filetree {.hg-filetree-notes title="HugeGraph Helm 核心文件与结构"} -helm/hugegraph/ +hugegraph-helm/ Chart.yaml # Chart 元数据与版本定义 values.yaml # 默认配置(easy 模式:3 PD + 3 Store + 3 Server + 1 Hubble,NodePort 入口) values-single.yaml # 单节点预设(本地 Minikube/Kind 测试,1 副本且关闭反亲和与 PDB) @@ -87,7 +117,7 @@ NodePort 省略或设为 `0` 时自动分配,固定端口由 Kubernetes 根据 默认 `server.serviceId` 与 `server.graphSpace` 均为 `DEFAULT`。如需将 Server 注册到指定的业务服务名或图空间,可通过 values 指定: ```bash -helm upgrade --install hugegraph ./helm/hugegraph -n hugegraph \ +helm upgrade --install hugegraph "$CHART" --devel -n hugegraph \ --set-string server.serviceId=analytics \ --set-string server.graphSpace=team_a \ --set-string server.testGraphAlias=team_a-demo @@ -106,6 +136,39 @@ GitOps 凭据、仅 API 部署以及无域名的 HTTP Ingress。 等待 PD 的 init container 复用 Store 镜像,Helm test 复用 Server 镜像。这两个镜像已包含 `curl`,无需额外 curl 镜像或启动时安装软件。 自定义镜像可以继续使用显式 `store.waitImage` 和 `server.waitImage` 覆盖。 +### 离线安装和私库 + +先选择最新版本,再按该版本下载 Chart,将 `.tgz` 搬入内网。可以直接安装,也可以接入已有的 OCI 或 HTTP 私库。 + +```bash +CHART=oci://ghcr.io/hugegraph/hugegraph-helm +CHART_VERSION=$(helm show chart "$CHART" --devel | sed -n 's/^version: //p') +helm pull "$CHART" --version "$CHART_VERSION" +``` + +```bash {tab="直接安装"} +helm install hugegraph "./hugegraph-helm-${CHART_VERSION}.tgz" -n hugegraph \ + --create-namespace --wait --timeout 15m +``` + +```bash {tab="OCI 私库"} +helm registry login registry.example.com +helm push "./hugegraph-helm-${CHART_VERSION}.tgz" oci://registry.example.com/charts +helm install hugegraph oci://registry.example.com/charts/hugegraph-helm \ + --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m +``` + +```bash {tab="HTTP 私库"} +# 按私库的上传方式接收同一个 .tgz,并更新 index.yaml。 +# 自建静态 HTTP 源可用 helm repo index 生成索引;helm push 只适用于 OCI。 +helm repo add hugegraph-internal https://charts.example.com +helm repo update hugegraph-internal +helm install hugegraph hugegraph-internal/hugegraph-helm \ + --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m +``` + +私库地址请替换为实际地址。Chart 包不包含容器镜像;完整离线部署还需搬运配置引用的所有容器镜像,并覆盖镜像地址。 + `storageClassName` 为空时继承集群默认 StorageClass,`"-"` 表示显式不使用 StorageClass。 local PV 需要预建宿主机目录、匹配容量、`nodeAffinity` 和 `kubernetes.io/no-provisioner` StorageClass。 `WaitForFirstConsumer` 根据 Pod 调度约束绑定,创建资源前请查看七个卷的完整例子。 @@ -132,16 +195,17 @@ Hubble 默认开启,当前镜像的登录仍依赖 Server 鉴权。只使用 A ## 5 升级和验证 -使用 Helm 原生值复用保留旧部署的 UI、入口、存储和凭据设置。 +使用 Helm 原生值复用保留已有部署的 UI、入口、存储和凭据设置。 ```bash helm get values hugegraph -n hugegraph --all -helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ - --wait --timeout 15m +# 测试环境继续跟随最新版本;生产升级请改用 --version 指定已审阅的稳定版本。 +helm upgrade hugegraph "$CHART" --devel -n hugegraph \ + --reuse-values --wait --timeout 15m helm test hugegraph -n hugegraph --logs --timeout 5m ``` -旧值中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。 +已有配置中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。 要采用新的默认值,先审阅已有配置,再使用 `--reset-values` 和保留镜像、凭据、存储、拓扑设置的配置文件。 PD 成员、持久存储和共享凭据变更需要按生命周期说明协调处理。 @@ -149,5 +213,5 @@ PD 成员、持久存储和共享凭据变更需要按生命周期说明协调 未指定的启动探针阈值按存储等待加 150 秒推导;显式探针不会被改写,但预算必须覆盖存储等待和至少 120 秒 Server 启动时间。 矛盾预算会在渲染时报出对应参数。这个等待超时不是 JVM 内存配置。 -Kubernetes Ready 和 `helm test` 不代表 UI 登录已经验证。安装或恢复后还应测试新登录及图查询。 +默认 `helm test` hook 检查连接和读取。安装或恢复后,还应重新登录 UI,并验证应用实际使用的读写查询。 调度、NetworkPolicy、滚动升级和恢复见 [Kubernetes 运维](./hugegraph-helm-operations.md)。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 17a3dcb643..c953c9bf10 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -39,7 +39,7 @@ Apache 下载页目前提供 1.7.0 的完整二进制包,其中包含 PD、Sto ```bash # 1.7.0 是项目孵化期发布的历史版本,因此文件名和目录名仍带 incubating -wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz +curl -fLO --connect-timeout 10 --max-time 1800 https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz tar zxf apache-hugegraph-incubating-1.7.0.tar.gz cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-store-incubating-1.7.0 ``` @@ -293,15 +293,20 @@ Store 使用无界队列处理 gRPC 回调,避免队列满时丢弃取消或 ./bin/start-hugegraph-store.sh ``` -启动脚本支持四个参数: +下文的生命周期与下载时限说明适用于包含启动脚本修复的 master 构建;上文下载的 1.7.0 启动脚本不包含这些修复。 +启动脚本支持四个参数,GC 的版本限制见下文: | 参数 | 取值 | 默认值 | 说明 | |------|------|--------|------| | `-d` | `true`、`false` | `true` | 守护进程模式,见下文。 | -| `-g` | `ZGC`、`zgc` | 未设置 | 垃圾回收器。不传该参数即使用默认的 G1。除 `ZGC` 和 `zgc` 之外的任何取值都会直接退出,包括 `g1`,尽管脚本自身的用法提示里写了它。 | +| `-g` | 见下文版本限制 | 未设置 | 选择垃圾回收器;不支持的参数会中止启动。 | | `-j` | JVM 参数字符串 | 空 | 附加的 JVM 参数,例如 `-j "-Xmx16g -Xms8g"`。 | | `-y` | `true`、`false` | `false` | 挂载 OpenTelemetry Java agent(首次使用时下载到 `plugins/`),并将 trace 导出到 `127.0.0.1:4317`。 | +master 构建接受 `g1`、`G1`、`zgc` 和 `ZGC`。 +上文下载的 1.7.0 启动脚本仅接受显式指定 `zgc` 或 `ZGC`;`-g g1`、`-g G1` 和其他参数会中止启动。 +默认路径请省略 `-g`;参数被拒绝时,查看 `logs/hugegraph-store-server.log`。 + 守护进程模式: - `-d true`(默认):以后台守护进程方式运行,脚本立即返回,并把 Java 进程号写入 `bin/pid`。 @@ -311,6 +316,10 @@ JVM 内存方面,如果没有自行设置 `JAVA_OPTIONS`:`-Xms512m`,`-Xmx` 当 `ulimit -n` 或 `ulimit -u` 低于 1024 时脚本会拒绝启动;在 x86_64 和 arm64 上,如果能成功下载并校验对应的动态库,脚本会预加载 jemalloc。 +主线构建中,每次可选 jemalloc 下载的连接时限为 5 秒,总时限为 30 秒。 +1.7.0 的下载 helper 没有连接或总时限。超时或校验失败时沿用已有回退路径,不预加载下载库并继续启动。 +校验有效的缓存库仍可复用,失败下载的临时文件会被清理。 + 启动成功后,可以在 `logs/hugegraph-store-server.log` 中看到类似以下的日志: ```text diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 5aeac92e71..1a969d142f 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -41,7 +41,7 @@ Apache 下载页目前提供 1.7.0 的完整二进制包,其中包含 PD、Sto ```bash # 1.7.0 是项目孵化期发布的历史版本,因此文件名和目录名仍带 incubating -wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz +curl -fLO --connect-timeout 10 --max-time 1800 https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz tar zxf apache-hugegraph-incubating-1.7.0.tar.gz cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-pd-incubating-1.7.0 ``` @@ -304,15 +304,20 @@ HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610 脚本要求 `PATH` 或 `JAVA_HOME` 中有 17 及以上版本的 JDK(1.7.0 要求 11 及以上);如果发现已有 Java 进程在使用本安装目录的 `conf` 目录,脚本会直接退出,不做任何事。 -支持的参数: +下文的生命周期说明适用于当前主线构建;上文下载的 1.7.0 启动脚本不包含这些修复。 +支持的参数如下,GC 的版本限制见下文: | 参数 | 取值 | 默认值 | 描述 | |------|------|--------|------| | `-d` | `true`、`false` | `true` | 守护进程模式,详见下文。 | -| `-g` | `zgc`、`ZGC` | 不设置 | 垃圾回收器。不带该参数即使用默认的 G1GC;填其他值(包括 `g1`)会导致启动中止。 | +| `-g` | 见下文版本限制 | 不设置 | 选择垃圾回收器;不支持的参数会中止启动。 | | `-j` | JVM 参数 | 空 | 额外的 JVM 参数,例如 `-j "-Xmx8g -Xms8g"`。 | | `-y` | `true`、`false` | `false` | 挂载 OpenTelemetry Java agent。首次使用时会把 agent 下载到 `plugins/` 并校验 MD5,trace 通过 gRPC 上报到 `http://127.0.0.1:4317`。 | +master 构建接受 `g1`、`G1`、`zgc` 和 `ZGC`。 +上文下载的 1.7.0 启动脚本仅接受显式指定 `zgc` 或 `ZGC`;`-g g1`、`-g G1` 和其他参数会中止启动。 +默认路径请省略 `-g`;参数被拒绝时,查看 `logs/hugegraph-pd-stdout.log`。 + `-d` 参数控制守护进程模式: - `-d true`(默认):以后台守护进程方式运行,脚本立即返回。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index d22d6b6628..9ef4904a00 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -152,6 +152,48 @@ HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose.yml up -d --wait 完整的部署指南请参阅 [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md)。 +#### 使用 PD 的 Server 服务标识 + +对于使用 PD 的 Server,Helm chart 提供 `server.serviceId` 和 `server.graphSpace` 配置项。 +二者默认为 `DEFAULT`,此时保留 `conf/rest-server.properties` 中已有的 `server.service_id` 和 `server.graphspace`。 +非默认值会向 Server 容器注入 `HG_SERVER_SERVICE_ID` 或 `HG_SERVER_GRAPHSPACE`。 +注意:这些服务身份相关的 Chart 配置项(`server.serviceId`、`server.graphSpace` 和 `server.testGraphAlias`)适用于开发中的 1.8.0+ 版本镜像与 Chart; +目前尚无已发布的 Chart 或镜像支持这些选项。不要将本示例与未支持该特性的旧版本搭配使用。 +通过 `HG_SERVER_SERVICE_ID`、`SERVICE_ID` 或 `server.serviceId` 传入的非空服务 ID 仅支持可打印 ASCII,包含空格和反斜杠; +部署校验会拒绝非 ASCII 和控制字符。此限制仅针对这些配置入口,不改变 Core Service 名称协议和已有的手工 properties 配置。 +Helm 会将 `server.serviceId` 中的美元符号(包括 `$(POD_IP)`)按字面量保留,不展开 Kubernetes 环境变量引用。 +重读服务元数据或清理图空间时,会保留完整的服务 ID,包括其中的 `/` 和 `-`。 +使用上述 chart values 设置身份;Server 的 `extraEnv` 会保留对应的新旧身份变量名,禁止重复覆盖。 +`HG_SERVER_GRAPHSPACE`、生效的旧变量 `GRAPH_SPACE` 和 `server.graphSpace` 遵循同一规则: +接受 `DEFAULT`,或以小写字母开头、最多 48 位的小写字母、数字和下划线组成的已有空间名称: + +```bash +helm upgrade --install hg ./helm/hugegraph \ + --set-string server.serviceId=analytics \ + --set-string server.graphSpace=team_a +``` + +部署分配到 `team_a` 的 Server 前,先通过现有 `DEFAULT` 空间的 Server,用具有创建图空间权限的账号创建该空间。 +chart 和这些环境变量不会自动创建图空间;同一个 Server Deployment 的所有副本使用相同服务标识。 + +用 `helm test` 检查该空间中的图前,先创建目标图,再将 `--set-string server.testGraphAlias=team_a-demo` 设置为它实际的 Gremlin 绑定。 +创建图空间不会自动创建 `hugegraph` 图。 + +容器部署中的 `HG_SERVER_SERVICE_ID` 和 `HG_SERVER_GRAPHSPACE` 写入上述两个配置项。 +旧名称 `SERVICE_ID` 和 `GRAPH_SPACE` 仍可使用;非空的新变量优先于对应旧变量。 +同一配置项的新旧变量均未设置或为空时,保留已有值。Compose 不会自动传入宿主机上的这些变量, +需要在 Compose override 的 Server `environment:` 中显式添加。详见 Helm chart 配置说明。 + +这些设置选择 Server 在 PD 中的服务元数据,不会搬迁已有图,也不会修改未指定图空间的 REST 路径所用的 `server.path_graphspace`。 +请求使用 `/graphspaces/team_a/...` 路径,并在 Hubble 中选择匹配的图空间和服务;开启鉴权时,显式指定路径仍须获得授权。 + +`server.testGraphAlias` 默认为 `DEFAULT-hugegraph`。hook 会逐个 Server Pod 检查这一已有本地图绑定,不会从 `server.graphSpace` 自动派生别名。 +别名的大小写须与实际绑定一致:本地 `Demo.properties` 可以绑定为 `DEFAULT-Demo`;通过 REST 创建的图使用小写名称。 +本地图绑定可以独立于 Server 在 PD 中分配的图空间存在,因此默认 hook 成功不能证明 `team_a` 中的图可查询。 +出现 `Could not rebind` 时,先确认目标图存在且别名正确;重启 Pod 不能创建缺失的图或纠正别名。 + +配置渲染和入口脚本检查不能单独证明 Linux 上的非默认服务发现、鉴权或跨图空间隔离已通过验收。 + > [!NOTE] > > 1. HugeGraph 的 Docker 镜像主要用于便捷地快速启动 HugeGraph,并不是 **ASF 官方发布物料包**。你可以从 [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) 中了解更多细节。 @@ -594,7 +636,7 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式,每次启动到 Java 阶段仍会创建空的 `heapdump_*` 目录,除非创建失败而改为写入 `logs/`。如果日志路径中包含双引号或 `%`,启动脚本会给出警告,堆转储直接写入 `logs/`,不使用每次启动的目录,也不设置崩溃日志的默认值;通过 `JAVA_TOOL_OPTIONS` 关闭堆转储的方式仍然有效。同时包含两种引号的路径则完全不设置堆转储默认值。由于设置了这些默认值,JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 -> **版本范围**:以上行为适用于当前 master([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258))。1.7.0 只在未设置 `JAVA_OPTIONS` 时添加堆转储参数,堆转储直接写入 +> **版本范围**:以上行为适用于当前开发分支/master 分支。1.7.0 只在未设置 `JAVA_OPTIONS` 时添加堆转储参数,堆转储直接写入 > `logs/java_pid.hprof`,JVM 崩溃日志写入安装目录。 ### 5.2 使用 Docker diff --git a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md index 8cdcd4eab5..a555a7ddfb 100644 --- a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md @@ -28,6 +28,10 @@ HugeGraph-Loader 是 HugeGraph 的数据导入组件,能够将多种数据源 > > **测试指南**:如需在本地运行 Loader 测试,请参考 [工具链本地测试指南](/cn/docs/guides/toolchain-local-test) +> **并发导入保护方案**:自 1.8.0 起,普通导入支持在同一 Server 实例上获取 owner 保护 +> (需配合返回 `protocol: 1` 的新版 Server 与对应 Loader;当前 `master` 分支暂未包含该协议)。 +> 旧版 Server 保持下文说明的原有导入行为。 + ### 2 获取 HugeGraph-Loader 可以通过以下三种方式获取 HugeGraph-Loader: @@ -982,6 +986,40 @@ bin/hugegraph-loader.sh \ 本例用独立的 `docs_smoke_person` 标签和 `docs_*` 属性,避免与预置的 `person` 样例数据冲突。成功时统计中应显示顶点写入成功数为 `2`、边写入成功数为 `0`。也可以在 Hubble 的 Gremlin 工作台查询 `g.V().hasLabel('docs_smoke_person').values('docs_name')`,结果应包含 `docs-smoke-alice` 和 `docs-smoke-bob`。 +#### 3.4.6 并发导入与 LOADING owner {#loading-ownership} + +自 1.8.0 版本起,Loader 支持并发导入模式所有权保护协议 +(需配合返回 `protocol: 1` 的新版 Server 与对应 Loader;当前 `master` 分支暂未包含该协议)。 + +```mermaid +graph TD + A["图模式 NONE"] -->|首个 Loader 申请所有权| B["进入 LOADING 模式 (分配 token)"] + B -->|其他并发 Loader 加入| B + B -->|部分 Loader 导入完成释放| B + B -->|最后一个 Loader 释放| C["自动恢复 NONE 模式"] + B -.->|"异常/进程中断 (Token 残留)"| D["管理员恢复 / 释放 / 重启图实例"] + D -.->|"最后一个 owner 释放,或 recover/重启"| A + D -.->|"仍有其他 owner 活跃"| B +``` + +1. **探测与获取**:Loader 启动后探测 `/mode/owners`。首个 Loader 获取所有权句柄(`instance/epoch/token`),图模式由 `NONE` 转为 `LOADING`;并发 Loader 可申请加入该模式。 +2. **数据导入**:持有有效句柄的 Loader 并行执行数据导入。 +3. **安全释放**:导入完成后停止 worker 并释放对应句柄。当最后一个 owner 释放时,图模式自动恢复为 `NONE`。 +4. **异常恢复**:若因异常中断(如 `kill -9`)导致句柄残留,请先停止并排空所有相关的导入任务与图写操作, + 然后通过 [RESTful API 管理员恢复接口](/cn/docs/clients/restful-api/graphs/#loading-ownership) 执行恢复,或重启 Server。 + 直接调用 `release` 仅适用于仍持有 Token 的调用方(如直接调用 REST API 的客户端)。 +{.steps} + +> [!NOTE] +> **兼容性与运维说明** +> - **旧版本兼容**:普通导入时仅在接口返回不支持该路由的 `404` 响应时回退至旧版 `LOADING`/`NONE` 枚举流程(支持 1.7 等旧版 Server,但不提供并发隔离)。 +> 权限、网络、图不存在或无效响应错误不会触发回退。 +> - **恢复与图源导入**:保留 `RESTORING` 模式,不探测 owner 且不自动重置。恢复导入完成后须手动将图模式设回 `NONE`,否则后续普通导入无法获取首个所有权。 +> 在活跃 owner 存在期间,请勿运行恢复导入、图源导入、Spark connector 或旧版 Loader 导入。 +> - **作用范围与生命周期**:所有权属于直连 Server 实例,不跨节点同步;owner 无自动租期过期机制。 +> 对于嵌入式程序集成,调用方必须调用 `HugeGraphLoader.shutdown()` 执行单次句柄释放;若释放失败,不会自动重试; +> 该 owner 可能会在 Server 端保持活跃,此时可能需要通过上述管理员恢复流程处理。 + ### 4 完整示例 下面给出的是 hugegraph-loader 包中 example 目录下的例子。([GitHub 地址](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader/assembly/static/example/file)) diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md index f50090c021..74e6f1d68e 100644 --- a/content/en/docs/clients/restful-api/auth.md +++ b/content/en/docs/clients/restful-api/auth.md @@ -247,8 +247,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role Groups grant corresponding resource permissions, and users are assigned to different groups, thereby having different resource permissions. The group interface includes APIs for creating groups, deleting groups, modifying groups, and querying group-related information. -> `GroupAPI` remains at `/auth/groups`, the only group route on 1.7.0. Current `master` also serves `/graphspaces/DEFAULT/auth/groups`, -> added by [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096). +> `GroupAPI` remains at `/auth/groups` on 1.7.0; current `master` also serves `/graphspaces/DEFAULT/auth/groups`. > > The GraphSpace API generates each persisted group name as `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 hex digits. > For `DEFAULT`, the name and ID look like `~hubble_role:v1:REVGQVVMVA:<32 hex>`; request `group_name` is only a client diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 1573c7b703..6a5fca65df 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -593,6 +593,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode > Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING +While loading owners are active, this enum PUT rejects all mode changes, including `"LOADING"`. Release the owners after their import workers stop. + ##### Response Status ```javascript @@ -677,6 +679,84 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode } ``` +#### 6.3.5 LOADING ownership {#loading-ownership} + +Starting with HugeGraph 1.8.0, the Server provides the protocol 1 endpoints for LOADING ownership +(requires a Server whose `GET .../mode/owners` returns `protocol: 1` and a matching Loader; current `master` does not include it yet); +Loader integration requires a matching 1.8.0 or newer client. +Released packages, earlier 1.8 builds, and current `master` builds lack this protocol. Support for the `LOADING` enum alone does not imply support for it. +With authentication enabled, both endpoints use the mode setter's permissions: graph-space management (`space`) or graph ownership, with STATUS write +authorization. Server binds the handle to the authenticated principal; a token grants no permission. Keep the same identity for acquire, release and retries. + +```text +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +The `200` capability response contains the graph-instance UUID, current nonnegative epoch, and state revision: + +```json +{ + "protocol": 1, + "instance": "", + "epoch": 0, + "revision": 0 +} +``` + +Generate a new lowercase hyphenated UUID `token` for each import, retain the returned `instance` and `epoch`, +and acquire with `Content-Type: application/json`: + +```text +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +```json +{ + "action": "acquire", + "instance": "", + "epoch": 0, + "token": "" +} +``` + +An acquire succeeded only when the response returns `200` with `state: "active"`, echoing `protocol`, `instance`, `epoch`, `token`, and `mode: "LOADING"`. +A `200` response with `state: "released"` means the handle is finished or was preemptively released; it does not grant ownership. In that case, stop and drain +that import attempt, then start a new attempt with a fresh GET for `instance` and `epoch` and generate a new token. +Release with `action: "release"` and the same handle; its response has `state: "released"` and the effective graph mode. Calling release before acquire is +recorded and causes a subsequent acquire with that handle to return `released`. +Keep one handle for retries; Server checks its principal, instance and epoch. A released handle cannot acquire again. + +To clear orphaned handles after an abnormal exit (e.g. `kill -9`), an administrator can execute an explicit recovery request: + +```text +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +```json +{ + "action": "recover", + "instance": "", + "epoch": 0, + "revision": 0, + "confirm": "I'm sure all imports have stopped" +} +``` + +Administrator recovery requires the global administrator role (`admin`). Callers must supply the current `revision`, `instance`, and `epoch` +obtained from `GET /mode/owners`, plus the confirmation string `confirm: "I'm sure all imports have stopped"`. +If the provided `revision` does not match the Server's current state, the request is rejected with HTTP `409 Conflict`. +On success, the Server clears all active owners, resets graph mode to `NONE`, and increments the epoch, returning HTTP `200` with +`state: "recovered"` and `mode: "NONE"`. + +The first owner requires `NONE`. Other owners share owner-managed `LOADING`; the last release restores `NONE`. +Manually set `LOADING`, `RESTORING` and `MERGING` are not adopted. While owners are active, the legacy enum PUT rejects mode changes. + +This protects ordinary imports on one live Server graph instance, with the handle bound to its authenticated principal, instance and epoch. +It provides no cross-Server coordination, data-write isolation or automatic expiry. Use a fixed direct Server endpoint and release after the import stops. +The upgraded Loader falls back to old behavior only for an unsupported-route `404` from its ownership probe; other errors remain failures. +Graph-source and restore imports retain their original enum-mode behavior. See +[Loader compatibility and recovery](/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership). + ### 6.4 Snapshot #### 6.4.1 Create a snapshot diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 0360a7c634..14c553f2f5 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -221,12 +221,30 @@ Unlike PD and Store, Server has no mandatory entrypoint variables: only set valu | `HG_SERVER_PD_REST_ENDPOINT` | Derived from `pd.peers` by replacing `:8686` with `:8620` | PD REST address polled by `wait-storage.sh` | | `PD_AUTH_USER` | `store` | Basic username for PD REST calls from `wait-storage.sh` | | `PD_AUTH_PASSWORD` | Empty | PD REST Basic password; must match `HG_PD_AUTH_SECRET_KEY` when PD REST authentication is enabled | -| `WAIT_PARTITION_TIMEOUT_S` | `120` | Partition allocation wait time in `wait-partition.sh` | +| `WAIT_PARTITION_TIMEOUT_S` | `120` | Partition polling timeout; also bounds the final diagnostic in builds with the fix described below | + +Master builds that include authentication property fixes preserve spaces, backslashes and Unicode in explicit +signing keys. Use the same key on every Server replica. When upgrading from an image that misread such a key, explicitly supply the intended +`HG_SERVER_AUTH_TOKEN_SECRET` again; retaining the old configuration also retains its misread key. If the active key changes, sign in again to +obtain new tokens. The 1.7.0 image limitation above still applies. + +Older images could initialize a Unicode administrator password incorrectly when the initializer inherited the C locale. Upgrading or setting +`PASSWORD` again does not repair an existing account's stored password. A working administrator must change it through the +[user API](/docs/clients/restful-api/auth/). This fix provides no automatic recovery when no administrator identity is usable; preserve the +existing data and arrange account recovery before upgrading. > **Deprecated aliases**: `BACKEND` → `HG_SERVER_BACKEND`, `PD_PEERS` → `HG_SERVER_PD_PEERS`. `wait-storage.sh` waits up to 300 seconds for an `Up` Store. This duration is hardcoded and cannot be changed through environment variables. +In master builds, HStore startup gives partition polling +and the final `/v1/partitions` diagnostic separate `WAIT_PARTITION_TIMEOUT_S` budgets. Earlier builds bound polling only; the final diagnostic +request has no timeout. With the default value, a stalled final response times out after 120 seconds; setting the value to `0` disables +GNU timeout's limit. +The entrypoint waits for `wait-partition.sh` before waiting for the Java launcher. If Java exits while partition polling is still waiting, +that poll can consume its full timeout before the entrypoint observes the exit. If polling succeeds, the diagnostic step can then consume +a second full timeout before observation finishes; signal-triggered shutdown remains interruptible. + `HG_SERVER_INIT_STORE_ENABLED` accepts only the case-insensitive boolean values recognized by `HugeConfig`: `y`, `t`, `yes`, `on`, `true`, `n`, `f`, `no`, `off`, `false`. Other values, including `0` and `1`, terminate the entrypoint. After successful initialization, the entrypoint writes `docker/init_complete`; later starts skip reinitialization but still invoke `bin/init-store.sh` to revalidate configuration each time initialization is disabled. @@ -318,8 +336,7 @@ which the shipped Compose files do not set, or `env` in Kubernetes; exporting it putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. -> **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store -> and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets +> **Version scope**: the paragraph above describes current master images. No 1.7.0 or older image sets > `STDOUT_MODE`, including the standalone `hugegraph/hugegraph:1.7.0` used above: `docker logs` shows only entrypoint output, and service logs stay in `logs/` > inside the container (`logs/hugegraph-server.log` for the Server). @@ -334,14 +351,22 @@ Previously, all three entrypoints ended with `tail -f /dev/null`, keeping contai Entrypoints now monitor Java directly: - **PD and Store**: The entrypoint passes `-d false` to the startup script, which replaces itself with Java using `exec`. When Java exits, the container exits immediately and Docker's restart policy applies. -- **Server**: The entrypoint waits with `tail --pid=$PID -f /dev/null`. `SIGTERM`/`SIGINT` traps forward Docker stop signals to Java and wait for graceful shutdown (exit 0). If Java crashes, the entrypoint exits with code 1, triggering the restart policy. +- **Server**: The entrypoint owns the foreground launcher and waits for Java. After readiness, it preserves Java's exit status, + including `0`, `42`, and `137` for `SIGKILL`. `SIGTERM` and `SIGINT` request cooperative shutdown, reap owned readiness/partition checks, + and return `143` and `130` respectively after shutdown. - PID 1 in every image is `dumb-init`, which forwards Docker signals to the entrypoint. ### Server Startup Timeout -`HG_SERVER_STARTUP_TIMEOUT_S` controls how long the Server startup script waits for a REST response; the default is **120 seconds**. Values must be decimal integers without leading zeros, from **1 to 86400 seconds**. Empty strings, `0`, negative numbers, fractions, and out-of-range values log an error and exit with code `1`. +`HG_SERVER_STARTUP_TIMEOUT_S` sets the Docker entrypoint's REST readiness deadline; the default is **120 seconds**. +Values must be decimal integers without leading zeros, from **1 to 86400 seconds**. +Empty strings, `0`, negative numbers, fractions, and out-of-range values log an error and exit with code `1`. -The entrypoint passes this value to `bin/start-hugegraph.sh -t`. If Server does not become ready within the deadline or exits early, startup fails and the container exits with code `1`; its restart policy may restart it. This duration excludes earlier storage initialization and backend readiness waits. +The entrypoint also passes this value to `bin/start-hugegraph.sh -t`; the foreground launcher itself waits for Java, without polling REST. +A startup deadline failure or Java exiting with `0` before readiness returns `1`; +an early nonzero Java exit keeps its status. The deadline excludes earlier storage initialization and backend readiness waits. +Readiness and partition checks remain interruptible during shutdown. A deadline failure requests termination and returns without an indefinite wait; +an unresponsive Java process relies on container termination for final cleanup. For example, from the HugeGraph repository's `docker/` directory, extend the standalone Server wait to 300 seconds (Compose passes this variable to the container): diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index b61ad5fd15..65d93c02e4 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -2,13 +2,24 @@ title: "Deploy HugeGraph with Helm" linkTitle: "Helm Deployment" weight: 4 -search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble] +search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, OCI, GHCR, Artifact Hub] --- -This guide follows the chart in the HugeGraph development branch. Image tags remain `latest` until release images are published; -pin images for your installation. The chart requires Helm 3 and Kubernetes 1.23 or later. -Start with the [chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md) for common commands and settings. -Advanced lifecycle procedures are in the [operations reference](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md). +This guide covers HugeGraph **1.8.0 and later**, using Helm **3.8+** with OCI support and Kubernetes (K8s) **1.23+**. +Install `hugegraph-helm` from GHCR or Docker Hub. Chart and HugeGraph versions are maintained separately: +for example, a `0.2.x` Chart can deploy a `1.8.x` service. + +> [!WARNING] +> The current development Chart uses `latest` images and is intended for testing. +> For production, choose a stable Chart once the corresponding HugeGraph service has been released, and review its image versions. +> Image tags can change; set each component's `image.digest` to keep using the same image content. + +[Artifact Hub](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) helps you find the Chart, browse versions and read installation instructions. +The packages themselves are downloaded from GHCR or Docker Hub. +See the [chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md) for settings and source-based development, +and the [operations reference](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md) for lifecycle procedures. + +![Find a Chart version on Artifact Hub, download from GHCR or Docker Hub, and install with Helm](/images/helm-oci-install.png) ## 1 Install @@ -20,26 +31,47 @@ Advanced lifecycle procedures are in the [operations reference](https://github.c > - **Memory Sizing**: Retains container JVM memory auto-calculation; configure resource requests/limits to allocate sufficient physical memory > for the 9 JVMs and Hubble. -```bash -git clone https://github.com/apache/hugegraph.git -cd hugegraph +Choose either registry; GHCR is recommended for public CI. For local lightweight testing, use the single-node preset. + +> [!TIP] +> `--devel` selects the highest Chart version, including development and stable versions, without limiting the version series. +> For production or reproducible installations, replace `--devel` with `--version ` to pin your chosen version. + +```bash {tab="GHCR (recommended)"} +CHART=oci://ghcr.io/hugegraph/hugegraph-helm +kubectl config current-context +kubectl get nodes +kubectl get storageclass +helm install hugegraph "$CHART" --devel -n hugegraph \ + --create-namespace --wait --timeout 15m +``` + +```bash {tab="Docker Hub"} +CHART=oci://registry-1.docker.io/hugegraph/hugegraph-helm kubectl config current-context kubectl get nodes kubectl get storageclass -# Standard cluster deployment (3 PD + 3 Store + 3 Server + 1 Hubble; requires 7 PVs): -helm install hugegraph ./helm/hugegraph -n hugegraph \ +helm install hugegraph "$CHART" --devel -n hugegraph \ --create-namespace --wait --timeout 15m +``` -# Local testing or single-node environments (Minikube, Kind; 1 replica and no anti-affinity): -# helm install hugegraph ./helm/hugegraph -n hugegraph \ -# -f ./helm/hugegraph/values-single.yaml \ -# --create-namespace --wait --timeout 10m +```bash {tab="Single-node trial"} +# For local testing (Minikube, Kind): install the Chart downloaded below +CHART=oci://ghcr.io/hugegraph/hugegraph-helm +helm pull "$CHART" --devel --untar +helm install hugegraph ./hugegraph-helm -n hugegraph \ + -f ./hugegraph-helm/values-single.yaml \ + --create-namespace --wait --timeout 10m ``` +The single-node preset replaces the default installation with one replica per component and relaxed scheduling constraints. + ## 2 Modes and entry points +The extracted package is rooted at `hugegraph-helm/`; the source directory remains `helm/hugegraph/`. + ```filetree {.hg-filetree-notes title="HugeGraph Helm Chart Layout"} -helm/hugegraph/ +hugegraph-helm/ Chart.yaml # Chart metadata and version definitions values.yaml # Default values (easy mode: 3 PD + 3 Store + 3 Server + 1 Hubble, NodePort) values-single.yaml # Single-node preset (local Minikube/Kind testing with 1 replica and no anti-affinity) @@ -89,7 +121,7 @@ the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields rem Both `server.serviceId` and `server.graphSpace` default to `DEFAULT`. To register the Server with a specific service name or graph space in PD: ```bash -helm upgrade --install hugegraph ./helm/hugegraph -n hugegraph \ +helm upgrade --install hugegraph "$CHART" --devel -n hugegraph \ --set-string server.serviceId=analytics \ --set-string server.graphSpace=team_a \ --set-string server.testGraphAlias=team_a-demo @@ -108,6 +140,41 @@ The default mirror inventory is only `hugegraph/pd`, `hugegraph/store`, `hugegra Store's PD wait init container and the Helm test reuse Store and Server images respectively, which already contain `curl`. No separate curl image or runtime package installation is required. Explicit `store.waitImage` / `server.waitImage` overrides remain supported. +### Offline installation and internal repositories + +Select the latest version, download that Chart and move the `.tgz` into your network. +Install it directly or upload it to an existing OCI or HTTP repository. + +```bash +CHART=oci://ghcr.io/hugegraph/hugegraph-helm +CHART_VERSION=$(helm show chart "$CHART" --devel | sed -n 's/^version: //p') +helm pull "$CHART" --version "$CHART_VERSION" +``` + +```bash {tab="Install archive"} +helm install hugegraph "./hugegraph-helm-${CHART_VERSION}.tgz" -n hugegraph \ + --create-namespace --wait --timeout 15m +``` + +```bash {tab="Internal OCI"} +helm registry login registry.example.com +helm push "./hugegraph-helm-${CHART_VERSION}.tgz" oci://registry.example.com/charts +helm install hugegraph oci://registry.example.com/charts/hugegraph-helm \ + --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m +``` + +```bash {tab="Internal HTTP"} +# Upload the same .tgz using your repository's upload mechanism and update index.yaml. +# For a static HTTP repository, use helm repo index. Native helm push only supports OCI. +helm repo add hugegraph-internal https://charts.example.com +helm repo update hugegraph-internal +helm install hugegraph hugegraph-internal/hugegraph-helm \ + --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m +``` + +Replace the example registry addresses with your own. +The archive contains no container images: mirror all configured container images separately, then override their addresses. + For storage, empty `storageClassName` inherits the cluster default, while `"-"` explicitly selects no StorageClass. Local PVs require prepared host directories, matching capacities, `nodeAffinity` and a `kubernetes.io/no-provisioner` StorageClass; `WaitForFirstConsumer` binds with the Pod's scheduling constraints. See the complete seven-volume example before creating resources. @@ -134,16 +201,17 @@ optionally also set `server.auth.enabled=false` for an unauthenticated API. Inac ## 5 Upgrade and verification -Use native Helm value reuse to preserve an old release's UI, entry, storage and credentials: +Use native Helm value reuse to preserve an existing deployment's UI, entry, storage and credentials: ```bash helm get values hugegraph -n hugegraph --all -helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \ - --wait --timeout 15m +# Follow the latest version for testing; use --version with a reviewed stable version for production. +helm upgrade hugegraph "$CHART" --devel -n hugegraph \ + --reuse-values --wait --timeout 15m helm test hugegraph -n hugegraph --logs --timeout 5m ``` -Older explicit helper images also remain under `--reuse-values`; add `--set-string store.waitImage= --set-string server.waitImage=` to reuse component images. +Existing explicit helper images also remain under `--reuse-values`; add `--set-string store.waitImage= --set-string server.waitImage=` to reuse component images. Adopt new defaults deliberately with `--reset-values` and a reviewed file retaining your image, credential, storage and topology settings. Do not treat PD membership, storage or credential changes as ordinary independent overrides; consult the lifecycle reference. @@ -151,5 +219,6 @@ Do not treat PD membership, storage or credential changes as ordinary independen from that wait plus 150 seconds; an explicit threshold is preserved and must cover the storage wait plus at least 120 seconds of Server startup. A contradictory budget fails rendering with the relevant parameter names. Storage wait timeout is not a JVM memory setting. -Kubernetes readiness and `helm test` do not prove fresh UI login. Test login and graph queries after install/recovery. +The default `helm test` hook checks connectivity and reads. After installation or recovery, also test a new UI login and your application's +read/write queries. For scheduling, NetworkPolicy, rolling updates and recovery, see [Kubernetes operations](./hugegraph-helm-operations.md). diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 5e987e695b..58f7b80912 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -22,7 +22,8 @@ Each Store node keeps graph data in RocksDB and replicates it with Raft (JRaft): #### 2.1 Requirements - Operating System: Linux or macOS (Windows has not been fully tested) -- Java version: Java 17 for HugeGraph 1.8.0+ (the Maven build accepts only JDK 17; the start script rejects older runtimes; 1.7.0 is the last release supporting Java 11) +- Java version: Java 17 for HugeGraph 1.8.0+ (the Maven build accepts only JDK 17; + the start script rejects older runtimes; 1.7.0 is the last release supporting Java 11) - Maven version: ≥ 3.6.3 (for building from source) - Deploy HugeGraph-PD first for multi-node deployment @@ -39,7 +40,7 @@ Apache downloads currently provide the complete 1.7.0 binary bundle containing P ```bash # Historical release 1.7.0 retains incubating in filenames and directories -wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz +curl -fLO --connect-timeout 10 --max-time 1800 https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz tar zxf apache-hugegraph-incubating-1.7.0.tar.gz cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-store-incubating-1.7.0 ``` @@ -297,15 +298,21 @@ Ensure that the PD service is already started, then in the Store installation di ./bin/start-hugegraph-store.sh ``` -The script accepts four flags: +The lifecycle and timeout details below describe master builds that include launcher script repairs. +The downloaded 1.7.0 launcher does not include those repairs. +The script accepts four flags, with GC version limits noted below: | Flag | Values | Default | Description | |------|--------|---------|-------------| | `-d` | `true`, `false` | `true` | Daemon mode. See below. | -| `-g` | `ZGC`, `zgc` | not set | Garbage collector. Omit the flag for G1, which is the default. Any value other than `ZGC` or `zgc` aborts the start, including `g1`, even though the script's own usage line suggests it. | +| `-g` | See version limits below | not set | Select the garbage collector. Unsupported values abort startup. | | `-j` | JVM options string | empty | Extra JVM options, for example `-j "-Xmx16g -Xms8g"`. | | `-y` | `true`, `false` | `false` | Attach the OpenTelemetry Java agent, downloading it into `plugins/` on first use, and export traces to `127.0.0.1:4317`. | +Master builds accept `g1`, `G1`, `zgc` and `ZGC`. +The downloaded 1.7.0 launcher accepts only `zgc` or `ZGC` as explicit choices; `-g g1`, `-g G1` and other values abort startup. +Omit `-g` for the default path. For rejected values, inspect `logs/hugegraph-store-server.log`. + Daemon mode: - `-d true` (default): run as a background daemon. The script returns immediately and writes the Java pid to `bin/pid`. @@ -315,6 +322,11 @@ JVM memory, unless you set `JAVA_OPTIONS` yourself: `-Xms512m`, and `-Xmx` set t The script refuses to start if `ulimit -n` or `ulimit -u` is below 1024, and it preloads jemalloc on x86_64 and arm64 when the shared object can be downloaded and verified. +In master builds, each optional jemalloc download allows +5 seconds to connect and 30 seconds in total. The 1.7.0 helper has no connection or total timeout. +A timeout or failed verification follows the existing fallback: +startup continues without preloading the downloaded library. Verified cached libraries can still be reused; partial downloads are removed. + After successful startup, you can see logs similar to the following in `logs/hugegraph-store-server.log`: ```text diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index c0afa9b7bd..1692929078 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -25,7 +25,8 @@ PD listens on three ports: #### 2.1 Requirements - Operating System: Linux or macOS (Windows has not been fully tested) -- Java version: Java 17 for HugeGraph 1.8.0+ (the Maven build accepts only JDK 17; the start script rejects older runtimes; 1.7.0 is the last release supporting Java 11) +- Java version: Java 17 for HugeGraph 1.8.0+ (the Maven build accepts only JDK 17; + the start script rejects older runtimes; 1.7.0 is the last release supporting Java 11) - Maven version: ≥ 3.6.3 (for building from source) ### 3 Deployment @@ -41,7 +42,7 @@ Apache downloads currently provide the complete 1.7.0 binary bundle containing P ```bash # Historical release 1.7.0 retains incubating in filenames and directories -wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz +curl -fLO --connect-timeout 10 --max-time 1800 https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz tar zxf apache-hugegraph-incubating-1.7.0.tar.gz cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-pd-incubating-1.7.0 ``` @@ -307,15 +308,20 @@ In the PD installation directory, execute: The script requires Java 17 or later on `PATH` or in `JAVA_HOME` (Java ≥ 11 on 1.7.0). It exits without doing anything if it finds a Java process already using this installation's `conf` directory. -Supported flags: +The lifecycle details below describe current master builds. The downloaded 1.7.0 launcher does not include those repairs. +Supported flags, with GC version limits noted below: | Flag | Values | Default | Description | |------|--------|---------|-------------| | `-d` | `true`, `false` | `true` | Daemon mode. See the note below. | -| `-g` | `zgc`, `ZGC` | not set | Garbage collector. Leave the flag off for the default G1GC. Any other value, `g1` included, aborts the start. | +| `-g` | See version limits below | not set | Select the garbage collector. Unsupported values abort startup. | | `-j` | JVM options | empty | Extra JVM options, for example `-j "-Xmx8g -Xms8g"`. | | `-y` | `true`, `false` | `false` | Attach the OpenTelemetry Java agent. The agent is downloaded into `plugins/` on first use, its MD5 is verified, and traces are exported over gRPC to `http://127.0.0.1:4317`. | +Master builds accept `g1`, `G1`, `zgc` and `ZGC`. +The downloaded 1.7.0 launcher accepts only `zgc` or `ZGC` as explicit choices; `-g g1`, `-g G1` and other values abort startup. +Omit `-g` for the default path. For rejected values, inspect `logs/hugegraph-pd-stdout.log`. + The `-d` flag controls daemon mode: - `-d true` (default): run as a background daemon; the script returns immediately. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 82edbb43a4..f1c899be91 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -156,6 +156,59 @@ The standalone `docker-compose.yml` example uses `hugegraph/hugegraph:1.7.0`; it See [docker/README.md](https://github.com/apache/hugegraph/blob/master/docker/README.md) for the full setup guide. +#### Server service identity with PD + +For a PD-backed Server, the Helm chart exposes `server.serviceId` and `server.graphSpace`. +Both default to `DEFAULT`, which preserves the existing `server.service_id` and `server.graphspace` +values in `conf/rest-server.properties`. A non-default chart value injects `HG_SERVER_SERVICE_ID` +or `HG_SERVER_GRAPHSPACE` into the Server container. +These service identity chart settings (`server.serviceId`, `server.graphSpace`, and `server.testGraphAlias`) +apply to development 1.8.0+ builds and charts; older versions such as 1.7.0 do not support these options. +Do not use this example with older chart or image versions lacking these features. +Non-empty service IDs supplied through `HG_SERVER_SERVICE_ID`, `SERVICE_ID`, or `server.serviceId` +must use printable ASCII; spaces and backslashes are supported, while deployment checks reject +non-ASCII and control characters. This entrypoint restriction does not change Core Service naming +or existing manually supplied properties. Helm preserves dollar signs in `server.serviceId` literally, +including `$(POD_IP)`; this field does not expand Kubernetes environment references. +The full service ID, including `/` and `-`, is retained when service metadata is reloaded or its graph space is cleared. +Set the identity through these chart values; Server `extraEnv` reserves both the new and legacy identity variable names. +`HG_SERVER_GRAPHSPACE`, the effective `GRAPH_SPACE` fallback, +and `server.graphSpace` accept `DEFAULT` or an existing space name of up to 48 lowercase letters, digits, +and underscores, starting with a letter: + +```bash +helm upgrade --install hg ./helm/hugegraph \ + --set-string server.serviceId=analytics \ + --set-string server.graphSpace=team_a +``` + +Before deploying Servers assigned to `team_a`, create that graph space through an existing Server +in `DEFAULT`, using an account with permission to create graph spaces. The chart and these environment +variables do not create graph spaces; all replicas in the Server Deployment use the same identity. + +To check a graph in that space with `helm test`, first create the target graph and set +`--set-string server.testGraphAlias=team_a-demo` to its actual Gremlin binding. Creating the graph space does not create a `hugegraph` graph. + +For container deployments, `HG_SERVER_SERVICE_ID` and `HG_SERVER_GRAPHSPACE` write the same two +properties. The legacy `SERVICE_ID` and `GRAPH_SPACE` names remain accepted: a non-empty new variable +wins over its legacy counterpart. If both names for a property are unset or empty, its existing value +is preserved. Compose does not automatically forward these host variables; add explicit Server +`environment:` entries in a Compose override. See the Helm chart documentation for details. + +These settings select the Server's PD service metadata. They do not move existing graphs or change +`server.path_graphspace` for REST paths that omit the graph space. Use `/graphspaces/team_a/...` paths +and select the matching graph space and service in Hubble. When authentication is enabled, explicit paths +still require authorization. + +`server.testGraphAlias` defaults to `DEFAULT-hugegraph`. The hook checks this existing local binding on every Server Pod; +it does not derive the alias from `server.graphSpace`. A local binding may exist independently of the Server's assigned PD graph space, +so a successful default hook does not validate graphs in `team_a`. If `Could not rebind` appears, first check that the requested graph exists +and that its alias is correct. A Pod restart cannot create a missing graph or correct an alias. +Match the binding's case: a local `Demo.properties` can bind `DEFAULT-Demo`, while REST-created graph names are lowercase. + +Configuration rendering and entrypoint checks alone do not establish non-default Linux discovery, +authentication, or isolation between graph spaces. + > [!NOTE] > > 1. HugeGraph Docker images are provided as a convenient way to start HugeGraph quickly, but they are not official ASF distribution artifacts. You can find more details in the [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub). @@ -607,7 +660,7 @@ it failed and dumps fell back to `logs/`. If the logs path contains a double quo per-launch directory and no crash log default; the `JAVA_TOOL_OPTIONS` opt-out still applies. A path with both quote characters gets no heap dump default at all. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. -> **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump flags are +> **Version scope**: this applies to current development/master builds. In 1.7.0 the heap dump flags are > added only when `JAVA_OPTIONS` is unset, heap dumps go directly to `logs/java_pid.hprof`, and JVM crash logs go to the install directory. ### 5.2 Use Docker to startup diff --git a/content/en/docs/quickstart/toolchain/hugegraph-loader.md b/content/en/docs/quickstart/toolchain/hugegraph-loader.md index fa94864b7d..147910383d 100644 --- a/content/en/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/en/docs/quickstart/toolchain/hugegraph-loader.md @@ -27,6 +27,10 @@ It will be explained in detail below. > Note: HugeGraph-Loader requires HugeGraph Server service, please refer to [HugeGraph-Server Quick Start](/docs/quickstart/hugegraph/hugegraph-server) to download and start Server +> **Concurrency protection:** starting with HugeGraph 1.8.0, ordinary imports acquire same-Server ownership protection +> (requires a Server whose `GET .../mode/owners` returns `protocol: 1` and a matching Loader; current `master` does not include it yet). +> Older Servers retain the legacy import behavior described below. + > **Testing Guide**: For running HugeGraph-Loader tests locally, please refer to [HugeGraph Toolchain Local Testing Guide](/docs/guides/toolchain-local-test) ### 2 Get HugeGraph-Loader @@ -986,6 +990,44 @@ bin/hugegraph-loader.sh \ Expected result: two vertices and zero edges imported. This example uses dedicated schema names to avoid conflicts with a preloaded `person` label. In Hubble, run `g.V().hasLabel('docs_smoke_person').values('docs_name')` to confirm `docs-smoke-alice` and `docs-smoke-bob`. +#### 3.4.6 Concurrent imports and LOADING ownership {#loading-ownership} + +Starting with HugeGraph 1.8.0, Loader supports concurrent import protection via the LOADING ownership protocol +(requires a Server whose `GET .../mode/owners` returns `protocol: 1` and a matching Loader; current `master` does not include it yet). + +```mermaid +graph TD + A["Graph Mode: NONE"] -->|First Loader acquires owner| B["LOADING Mode (Acquires Token)"] + B -->|Concurrent Loaders join| B + B -->|Loader finishes & releases| B + B -->|Last Loader releases| C["Restores to NONE"] + B -.->|Abnormal exit / kill -9| D["Manual Release / Recovery / Restart"] + D -.->|"Last owner released, or recover/restart"| A + D -.->|"Other owners still active"| B +``` + +1. **Probe and Acquire**: Loader probes `/mode/owners`. The first Loader obtains an ownership handle (`instance/epoch/token`), + transitioning graph mode from `NONE` to `LOADING`; concurrent Loaders can join. +2. **Data Import**: Loaders holding valid handles execute concurrent imports while preserving `LOADING` mode. +3. **Graceful Release**: When an import completes, Loader drains its workers and releases its handle. When the last owner releases, + graph mode automatically returns to `NONE`. +4. **Failure Recovery**: If abnormal exit (e.g. `kill -9`) leaves an orphaned owner, stop and drain all related imports and graph writes, + then perform administrator recovery via the [RESTful API recovery endpoint](/docs/clients/restful-api/graphs/#loading-ownership) or + restart the Server. Manual `release` applies only when the caller still holds its token (e.g. a direct REST client). +{.steps} + +> [!NOTE] +> **Compatibility and Operational Notes** +> - **Legacy Compatibility**: During ordinary imports, only an unsupported-route `404` status on `/mode/owners` falls back to the legacy enum +> `LOADING`/`NONE` flow (maintains compatibility with Server 1.7, without multi-loader protection). +> Network or permission errors, or a `404` for a missing graph, do not trigger fallback. +> - **Restore and Graph Source Imports**: Retain the `RESTORING` flow without ownership probes or automatic resets. After a restore import completes, +> manually reset graph mode to `NONE` before starting ordinary imports. +> Do not run restore, graph-source, Spark connector, or older Loader imports while owned imports are active. +> - **Scope & Lifecycle**: Ownership is bound to the target Server instance without cross-node synchronization or automatic lease expiry. +> For embedded programmatic integrations, callers must invoke `HugeGraphLoader.shutdown()` to attempt a single graceful release. If release +> fails, the handle is not retried; the owner may remain active on the Server, and the administrator recovery step above may be required. + ### 4 Complete example Given below is an example in the example directory of the hugegraph-loader package. ([GitHub address](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader/assembly/static/example/file)) diff --git a/static/images/helm-oci-install-cn.png b/static/images/helm-oci-install-cn.png new file mode 100644 index 0000000000..17c08d23af Binary files /dev/null and b/static/images/helm-oci-install-cn.png differ diff --git a/static/images/helm-oci-install.png b/static/images/helm-oci-install.png new file mode 100644 index 0000000000..c74c555fe8 Binary files /dev/null and b/static/images/helm-oci-install.png differ