From 02383e93626a5a76ecd839bd717eee7a3ff242b8 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Wed, 14 Oct 2026 03:49:23 +0800
Subject: [PATCH 1/8] docs: explain easy Helm deployments

- add bilingual installation and access instructions
- document strict defaults and explicit overrides
- cover internal images, persistent storage and GitOps
- explain upgrade, credentials and startup troubleshooting
---
 .../hugegraph/hugegraph-helm-operations.md    | 114 +++++++++++++++++
 .../quickstart/hugegraph/hugegraph-helm.md    | 115 +++++++++++++++++
 .../hugegraph/hugegraph-helm-operations.md    | 118 ++++++++++++++++++
 .../quickstart/hugegraph/hugegraph-helm.md    | 115 +++++++++++++++++
 4 files changed, 462 insertions(+)
 create mode 100644 content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
 create mode 100644 content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
 create mode 100644 content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
 create mode 100644 content/en/docs/quickstart/hugegraph/hugegraph-helm.md

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
new file mode 100644
index 000000000..c5fa25c13
--- /dev/null
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -0,0 +1,114 @@
+---
+title: "HugeGraph Kubernetes 运维"
+linkTitle: "Kubernetes 运维"
+weight: 5
+search_keywords: [HugeGraph Helm 运维, local PV, NetworkPolicy, PD, Store]
+---
+
+本文配合 [Helm 部署](./hugegraph-helm.md)使用。生命周期检查和恢复说明见
+[运维参考](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md)，所有参数说明见 chart 的 `values.yaml`。
+命令假设 release 和 namespace 都是 `hugegraph`，覆盖名称时请替换实际工作负载名。
+
+## 1 存储和内网镜像 {#1-storage-and-private-images}
+
+默认安装需要七个持久卷。动态存储需要正常的 provisioner，静态 local 存储需要预建目录和绑定节点的匹配 PV。
+[完整例子](https://github.com/apache/hugegraph/tree/master/helm/hugegraph/examples)包含七个 local PV、`WaitForFirstConsumer`、镜像仓库和 GitOps Secret。
+`WaitForFirstConsumer` 的 PVC 初期 Pending 可以是正常等待；持续 Pending 应检查 PVC/Pod 事件和 PV 匹配。
+PVC 已绑定但目录不存在或权限不匹配时可能挂载失败，不能把故障 PVC 静默替换成临时目录。
+
+```bash
+kubectl -n hugegraph get pvc,pods
+kubectl -n hugegraph describe pvc <claim-name>
+kubectl -n hugegraph describe pod <pod-name>
+kubectl get pv,storageclass
+```
+
+出现 `ImagePullBackOff` 时检查 Pod 事件、仓库连通性和拉取凭据。默认只需四个组件镜像，等待 Store/Helm test 复用已包含 curl 的组件镜像。
+如显式覆盖 helper 镜像，该镜像也需要同步到内网仓库。
+
+## 2 端口和健康检查 {#2-ports-and-health}
+
+PD 端口为 REST 8620、gRPC 8686、Raft 8610；Store 为 REST 8520、gRPC 8500、Raft 8510；Server HTTP 为 8080；Hubble HTTP 为 8088。
+客户端 Service 隐藏 Pod 地址，NodePort 是节点上另外分配的端口，与应用监听端口不同。
+PD `/v1/ready` 需要 Raft leader，`/v1/health` 只说明监听器已启动，Store 等待多数 PD peer ready 后启动。
+Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTimeoutSeconds` 调整。
+本地模板渲染不能验证集群连通性、卷挂载或 JVM 运行容量。
+
+## 3 调度 {#3-scheduling}
+
+默认 `preferred` 反亲和允许节点少于副本数时调度；`values-cluster.yaml` 对 PD/Store 设置 required 反亲和，因此需要至少三个可调度节点。
+显式 affinity 优先于预设。local PV 节点亲和必须匹配工作负载位置约束，PV 容量声明不等于文件系统配额。
+持久化 PD/Store 的 Raft 主机名和端口会记录为成员身份，不能作为普通配置随意变更。
+
+## 4 分区副本 {#4-partition-sharding}
+
+首次初始化时，Store 至少三个则默认每个分区三副本，否则一副本。
+PD 会持久化分区设置，初始化后修改 chart 值不会覆盖已有元数据，应使用 PD 配置 API 并协调分区巡检。
+显式 shard 数必须为奇数且不超过 Store 数，操作在线集群前参照 README 的完整过程。
+
+## 5 NetworkPolicy {#5-networkpolicy}
+
+easy 模式及普通集群预设默认关闭，strict 模式默认开启；显式 `networkPolicy.enabled` 在任何模式都优先。
+集群网络插件必须支持策略执行，才有实际隔离效果。
+生成策略允许组件间通信和 DNS，外部客户端、Ingress 控制器需要适当的 `networkPolicy.<component>.extraIngress`，
+外部发现地址可能还需要 `extraEgress`。空列表合法但可能阻止外部访问；支持 Kubernetes 原生规则，包括允许全部的 `{}`，不要求额外来源确认。
+按实际来源地址或 selector 配置，并考虑 NodePort SNAT 和控制器行为。
+
+```yaml
+networkPolicy:
+  enabled: true
+  server:
+    extraIngress:
+      - from:
+          - ipBlock:
+              cidr: 10.20.0.0/16
+        ports:
+          - protocol: TCP
+            port: 8080
+  hubble:
+    extraIngress:
+      - from:
+          - ipBlock:
+              cidr: 10.20.0.0/16
+        ports:
+          - protocol: TCP
+            port: 8088
+```
+
+## 6 逐个升级 Store {#6-rolling-store-images-safely}
+
+集群预设使用 `store.updateStrategy.type=OnDelete` 便于维护时控制逐个替换。
+每次只删除一个 Store Pod，下一次删除前确认上一个 Pod Ready、Store 心跳新鲜，并从 PD leader 查询每个 shard group 都有完整成员及唯一 leader。
+PD 的 `Up` 状态本身不证明 shard 恢复完成。PDB 限制主动驱逐，不限制 StatefulSet 控制器更新。
+按 README 完整检查 shard 状态，发现缺副本或无 leader 时停止继续替换。
+
+## 7 灾难恢复 {#7-disaster-recovery}
+
+保留原卷、claim 身份和 PD 成员关系，不通过删除 RocksDB lock 文件恢复，也不把持久化成员配置替换为全新的节点。
+Store 丢盘需要按 shard 替换/恢复流程处理，新建空 PVC 并不自动恢复数据。
+local 磁盘不能在节点故障时自动迁移文件。备份应放在这些 PV 之外，并单独验证恢复；chart 不提供自动备份和自动恢复。
+破坏性变更前先按 README 的恢复顺序检查。
+
+## 8 扩缩容 {#8-scaling}
+
+Server 副本可以常规变更，HPA 还需要 CPU requests。Store 扩容需要协调存储和 shard。
+PD 扩缩容及 Store 缩容不能仅修改副本数，需要先更新持久化 Raft/shard 成员关系。
+chart 对已初始化 StatefulSet 检查不支持的身份和成员变更，首次安装不执行升级专用查询。
+按生命周期流程扩缩容，避免直接 `kubectl scale` 使 Hubble 的 Store metrics 配置过期。
+
+## 9 集群外的 Hubble {#9-running-hubble-outside-the-cluster}
+
+direct 模式只需要可达的 Server URL；PD discovery 还需要集群外可达的 PD gRPC，PD 注册的 Server 地址也必须可达。
+必要时用 `server.advertiseUrl` 注册共享 Server 地址，这会影响所有 discovery 客户端，包括集群内 Hubble。
+chart 内置 Hubble 已配置内部服务发现，不需要公开 PD 入口。
+HTTP 可以直接使用，TLS 终止可选。Hubble 仍是单副本，当前登录依赖 Server 鉴权。
+
+## 10 Gremlin 报 Could not rebind {#10-when-gremlin-fails-with-could-not-rebind}
+
+PD 滚动更新期间，Server 可能 Ready、能响应 REST，但 Gremlin binding 失败。
+执行 `helm test hugegraph -n hugegraph --logs --timeout 5m` 检查每个 Server Pod 的鉴权图查询；PD 稳定后替换失败 Pod 并再次验证。
+只查询 `/versions` 不证明图绑定成功，还应检查 Hubble 新登录和图查询。
+
+出现 `ERROR: missing required env 'HG_PD_AUTH_SECRET_KEY'` 时，检查 PD Pod 的 Secret 引用和对应 key，不要把 Secret 值输出到日志。
+chart 正常情况下自动注入共享 PD REST 凭据，自定义容器或 manifest 必须向 PD 和客户端提供同一值。
+GitOps 先创建外部 Secret 再调谐工作负载，普通 Helm 保留自动创建的 release Secret。
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
new file mode 100644
index 000000000..3de5cf157
--- /dev/null
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -0,0 +1,115 @@
+---
+title: "使用 Helm 部署 HugeGraph"
+linkTitle: "Helm 部署"
+weight: 4
+search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble, 内网部署]
+---
+
+本文对应 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)。
+
+## 1 安装
+
+默认部署 **3 PD + 3 Store + 3 Server 和 Hubble**，开启鉴权和持久化。
+需要默认动态 StorageClass 或匹配的静态 PV，共七个卷，分别为 3 个 10 GiB 的 PD 卷、3 个 50 GiB 的 Store 卷、1 个 1 GiB 的 Hubble 卷。
+chart 创建 PVC，不创建存储 provisioner 或宿主机目录。
+
+```bash
+git clone https://github.com/apache/hugegraph.git
+cd hugegraph
+kubectl config current-context
+kubectl get nodes
+kubectl get storageclass
+helm install hugegraph ./helm/hugegraph -n hugegraph \
+  --create-namespace --wait --timeout 15m
+```
+
+默认保留镜像的 JVM 内存计算方式。按容量要求配置 requests/limits，并为九个图服务 JVM 和 Hubble 提供足够内存。
+
+## 2 模式和访问入口
+
+默认 `mode: easy`，Server 和 Hubble 自动分配 NodePort，PD 保持 ClusterIP。可以直接使用 HTTP，无需域名、证书或额外确认参数。
+`mode: strict` 默认将 Server/Hubble 设为 ClusterIP，并开启 NetworkPolicy。两个模式都保留鉴权和持久化。
+优先级是组件显式参数高于全局参数，全局参数高于模式默认值，显式 `false` 也会生效。
+全局参数包括 `persistence.enabled` 和 `global.imageRegistry`，严格预设为 `values-strict.yaml`。
+
+| 入口 | 访问方式 | 前提 |
+|---|---|---|
+| NodePort | `http://<可达节点IP>:<分配的NodePort>` | 节点网络可达且防火墙放行，无需额外控制器 |
+| ClusterIP | 集群内虚拟 Service IP/DNS，如 `hugegraph-server.hugegraph.svc:8080` | 集群外通过 port-forward 或已有网关访问 |
+| LoadBalancer | 基础设施分配的地址 | 集群有对应负载均衡控制器 |
+| Ingress | 通过控制器路由 HTTP 请求 | 已安装 Ingress 控制器，域名和 TLS 都可选 |
+
+```bash
+kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble
+kubectl get nodes -o wide
+kubectl -n hugegraph get secret hugegraph-admin \
+  -o jsonpath='{.data.password}' | base64 --decode
+```
+
+使用 Hubble 的 NodePort 打开页面，以 `admin` 和查出的密码登录。
+默认 `externalTrafficPolicy: Cluster` 下，访问的节点不必运行目标 Pod。ClusterIP 是集群内部的虚拟服务地址，不是节点 IP，普通笔记本通常不能直接访问。
+也可以运行 `kubectl -n hugegraph port-forward svc/hugegraph-hubble 8088:8088`，在本机打开 `http://127.0.0.1:8088`。
+
+三个客户端 Service 都支持 `externalTrafficPolicy`、`loadBalancerClass`、`loadBalancerIP`、`loadBalancerSourceRanges`、`externalIPs`
+和 `allocateLoadBalancerNodePorts`，具体行为取决于集群及负载均衡实现。LoadBalancer 专用字段应配合对应类型使用。
+NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据集群配置的范围校验，chart 不再强制 `30000–32767`。
+原 HTTP 暴露确认参数保留兼容，但不再阻止渲染。
+
+## 3 内网镜像和存储
+
+[完整例子](https://github.com/apache/hugegraph/tree/master/helm/hugegraph/examples)包含内网镜像、动态存储、七个 local PV、
+GitOps 凭据、仅 API 部署以及无域名的 HTTP Ingress。
+
+`global.imageRegistry` 为未指定 registry 的镜像仓库加前缀，组件指定完整 registry 地址时优先采用组件配置。
+默认只需镜像仓库中的 `hugegraph/pd`、`hugegraph/store`、`hugegraph/hugegraph` 和 `hugegraph/hubble` 四个镜像，标签或 digest 按实际配置选取。
+等待 PD 的 init container 复用 Store 镜像，Helm test 复用 Server 镜像。这两个镜像已包含 `curl`，无需额外 curl 镜像或启动时安装软件。
+自定义镜像可以继续使用显式 `store.waitImage` 和 `server.waitImage` 覆盖。
+
+`storageClassName` 为空时继承集群默认 StorageClass，`"-"` 表示显式不使用 StorageClass。
+local PV 需要预建宿主机目录、匹配容量、`nodeAffinity` 和 `kubernetes.io/no-provisioner` StorageClass。
+`WaitForFirstConsumer` 根据 Pod 调度约束绑定，创建资源前请查看七个卷的完整例子。
+新建临时实例可以设置 `persistence.enabled=false` 使用 `emptyDir`，组件存储开关优先。
+PVC 失败不会自动降级为临时存储，已经初始化的 PD/Store 切换存储模式会被拒绝。
+
+## 4 鉴权和 Secret
+
+普通 Helm 安装自动生成、复用三份凭据，分别为 `<release>-admin` 的 `password`、`<release>-auth-token` 的 `token_secret`
+以及 `<release>-pd-auth` 的 `secret-key`。PD REST 使用共享的 PD Secret，通过 `HG_PD_AUTH_SECRET_KEY` 注入 PD 容器，
+Server 等待存储和 Hubble 使用同一份凭据，不需要用户为每个 PD Pod 单独发明密码。
+
+GitOps 使用加密的固定值，或预先创建 Secret 并配置 `pd.auth.existingSecret`、`server.auth.admin.existingSecret`
+和 `server.auth.token.existingSecret`。`existingSecret` 高于内联值，chart 不管理这类外部 Secret。
+管理员密码需要可打印 ASCII，不能包含空格、冒号、反斜杠；PD 密码需要可打印 ASCII，不能包含首尾空白和反斜杠；JWT key 至少 32 字节。
+离线渲染器不能通过 `lookup` 读取在线已生成 Secret，因此不能依赖每次渲染随机生成凭据。
+
+管理员 Secret 是**初始凭据**，更新 Secret 不会修改已经创建的账户密码。
+先使用旧密码调用 `PUT /graphspaces/DEFAULT/auth/users/admin`，请求体为 `{"user_password":"<新密码>"}`，
+再把 Secret 和源配置同步为新密码，最后重启 Server Deployment 清理所有副本的鉴权缓存。
+
+Hubble 默认开启，当前镜像的登录仍依赖 Server 鉴权。只使用 API 可以设置 `hubble.enabled=false`，
+如需关闭 API 鉴权，再设置 `server.auth.enabled=false`。未使用的凭据配置可以留在 values 中。
+
+## 5 升级和验证
+
+使用 Helm 原生值复用保留旧部署的 UI、入口、存储和凭据设置。
+
+```bash
+helm get values hugegraph -n hugegraph --all
+helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \
+  --wait --timeout 15m
+helm test hugegraph -n hugegraph --logs --timeout 5m
+```
+
+旧值中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。
+要采用新的默认值，先审阅已有配置，再使用 `--reset-values` 和保留镜像、凭据、存储、拓扑设置的配置文件。
+PD 成员、持久存储和共享凭据变更需要按生命周期说明协调处理。
+
+`server.storageWaitTimeoutSeconds` 默认 300，通过 `WAIT_STORAGE_TIMEOUT_S` 传给启动脚本。
+未指定的启动探针阈值按存储等待加 150 秒推导；显式探针不会被改写，但预算必须覆盖存储等待和至少 120 秒 Server 启动时间。
+矛盾预算会在渲染时报出对应参数。这个等待超时不是 JVM 内存配置。
+
+Kubernetes Ready 和 `helm test` 不代表 UI 登录已经验证。安装或恢复后还应测试新登录及图查询。
+调度、NetworkPolicy、滚动升级和恢复见 [Kubernetes 运维](./hugegraph-helm-operations.md)。
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
new file mode 100644
index 000000000..b842c57cf
--- /dev/null
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -0,0 +1,118 @@
+---
+title: "Operate HugeGraph on Kubernetes"
+linkTitle: "Kubernetes Operations"
+weight: 5
+search_keywords: [HugeGraph Helm operations, local PV, NetworkPolicy, PD, Store]
+---
+
+This guide accompanies [Helm deployment](./hugegraph-helm.md). Detailed lifecycle checks and recovery notes are maintained in the
+[operations reference](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md); all parameters are commented in `values.yaml`.
+Commands assume release/namespace `hugegraph`; substitute the actual workload names if overridden.
+
+## 1 Storage and private images
+
+The default installation needs seven persistent volumes. Dynamic storage requires a working provisioner; static local storage requires prepared directories
+and matching PVs on the named nodes. Use the [complete examples](https://github.com/apache/hugegraph/tree/master/helm/hugegraph/examples)
+for all seven local PVs, `WaitForFirstConsumer`, registry mirrors and GitOps Secrets.
+An initially Pending PVC with `WaitForFirstConsumer` can be normal; persistent Pending needs PVC/Pod events and PV matching checks.
+A bound claim with a missing directory or permission mismatch can fail mounting. Do not replace failed PVCs with temporary data directories.
+
+```bash
+kubectl -n hugegraph get pvc,pods
+kubectl -n hugegraph describe pvc <claim-name>
+kubectl -n hugegraph describe pod <pod-name>
+kubectl get pv,storageclass
+```
+
+For `ImagePullBackOff`, inspect Pod events and registry access/credentials. The default image inventory contains four component images;
+Store wait and Helm test reuse existing component images with `curl` already installed. Explicit helper-image overrides must also be mirrored.
+
+## 2 Ports and health
+
+PD listens on REST 8620, gRPC 8686 and Raft 8610; Store on REST 8520, gRPC 8500 and Raft 8510; Server HTTP on 8080; Hubble HTTP on 8088.
+Client Services hide individual Pod addresses. NodePort is a separate allocated port on reachable nodes, not the application listener port.
+PD `/v1/ready` requires a Raft leader; `/v1/health` only confirms the listener. Store startup waits for a majority of ready PD peers.
+Server waits up to `server.storageWaitTimeoutSeconds` (default 300) before its application startup; adjust it for slow storage bootstrap.
+No local Helm rendering verifies live cluster reachability, volumes or JVM capacity.
+
+## 3 Scheduling
+
+The default `preferred` anti-affinity permits scheduling with fewer nodes than replicas. `values-cluster.yaml` sets required PD/Store anti-affinity,
+so it needs at least three schedulable nodes. Explicit affinity takes priority over presets.
+Local PV node affinity must match the workload's placement constraints; PV capacity declarations do not enforce filesystem quotas.
+Do not change a persisted PD/Store Raft hostname or port as an ordinary upgrade: those addresses are recorded identities.
+
+## 4 Partition sharding
+
+At first bootstrap, the chart seeds three shard replicas when there are at least three Stores, and one otherwise.
+PD persists the partition settings; changing chart values after initialization does not rewrite that metadata.
+Use the PD configuration API and a coordinated partition patrol for an existing cluster. An explicit shard count must be odd and no greater than Store replicas.
+See the README's partition sharding procedure before changing a live cluster.
+
+## 5 NetworkPolicy
+
+Easy mode, including the ordinary cluster preset, defaults policies off. Strict mode enables them; explicit `networkPolicy.enabled` wins in either mode.
+The cluster network plugin must enforce NetworkPolicy for these resources to have an effect.
+The generated policies admit component traffic and DNS. External clients and Ingress controllers need suitable
+`networkPolicy.<component>.extraIngress` rules; external discovery addresses may need matching `extraEgress`.
+An empty list is valid and can block external traffic. Native Kubernetes rules are accepted, including `{}` to allow all;
+there is no separate source-acknowledgement gate. Use your actual source addresses/selectors, considering NodePort SNAT and controller behavior.
+
+```yaml
+networkPolicy:
+  enabled: true
+  server:
+    extraIngress:
+      - from:
+          - ipBlock:
+              cidr: 10.20.0.0/16
+        ports:
+          - protocol: TCP
+            port: 8080
+  hubble:
+    extraIngress:
+      - from:
+          - ipBlock:
+              cidr: 10.20.0.0/16
+        ports:
+          - protocol: TCP
+            port: 8088
+```
+
+## 6 Rolling Store images safely
+
+Use `store.updateStrategy.type=OnDelete` for a controlled maintenance rollout, as the cluster preset does.
+Delete one Store Pod at a time. Before replacing the next, verify the previous Pod is Ready, has a fresh Store heartbeat and each shard group has its
+full membership and exactly one leader, read from the PD leader. PD's `Up` status alone does not prove completed shard recovery.
+PDBs limit voluntary eviction, not StatefulSet controller disruption. Consult the README's full per-group checks and stop on missing shards or leaders.
+
+## 7 Disaster recovery
+
+Preserve existing volumes, claim identities and PD membership. Do not delete RocksDB lock files to recover a deployment, or replace persisted membership
+with freshly generated nodes. Loss of one Store disk requires a documented shard replacement/recovery procedure, not merely a new empty PVC.
+Local disks cannot migrate their files automatically when a node fails. Take backups outside these PVs and test recovery separately;
+the chart does not implement backup or automatic recovery. Follow the README's recovery sequence before destructive changes.
+
+## 8 Scaling
+
+Server replicas are routinely mutable; an HPA also needs CPU requests. Store growth is a coordinated storage/shard operation.
+PD growth/shrink and Store shrink cannot be handled as ordinary replica changes, because persistent Raft/shard membership must be updated first.
+Chart upgrade checks reject unsupported identity/membership changes on initialized StatefulSets; fresh installs do not query StatefulSets for upgrade checks.
+Scale through the documented lifecycle procedure rather than `kubectl scale`, which can leave Hubble's Store metrics configuration stale.
+
+## 9 Running Hubble outside the cluster
+
+Direct mode only needs an externally reachable Server URL. PD discovery also needs externally reachable PD gRPC, and Server addresses registered with PD
+must be reachable from that external Hubble. Set `server.advertiseUrl` to a shared reachable Server URL when needed; it affects all discovery clients,
+including in-cluster Hubble. In-chart Hubble already uses internal service discovery and needs no public PD entry point.
+HTTP is supported directly; TLS termination remains optional. Hubble remains single-replica and its current login requires Server authentication.
+
+## 10 When Gremlin fails with Could not rebind
+
+A Server can become Ready and serve REST while Gremlin binding failed during a PD rollout. Run `helm test hugegraph -n hugegraph --logs --timeout 5m`;
+the hook checks authenticated graph-bound Gremlin on every Server Pod. Once PD is stable, replace the failing Server Pod and verify again.
+A test that only calls `/versions` does not prove graph binding; also check fresh Hubble login and a graph query.
+
+For `ERROR: missing required env 'HG_PD_AUTH_SECRET_KEY'`, inspect the PD Pod's Secret reference and the corresponding key, not the Secret value in logs.
+The chart normally injects this shared PD REST credential automatically. Custom containers/manifests must provide the same value to PD and its clients.
+In GitOps, create the external Secret before workload reconciliation; with ordinary Helm, retain the chart-generated release Secret.
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
new file mode 100644
index 000000000..475b832b7
--- /dev/null
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -0,0 +1,115 @@
+---
+title: "Deploy HugeGraph with Helm"
+linkTitle: "Helm Deployment"
+weight: 4
+search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble]
+---
+
+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).
+
+## 1 Install
+
+Defaults deploy **3 PD + 3 Store + 3 Server and Hubble**, with authentication and persistent storage enabled.
+Provide a default dynamic StorageClass, or matching static PVs: three PD volumes of 10 GiB, three Store volumes of 50 GiB and one Hubble volume of 1 GiB.
+The chart creates claims; it does not create a storage provisioner or host directories.
+
+```bash
+git clone https://github.com/apache/hugegraph.git
+cd hugegraph
+kubectl config current-context
+kubectl get nodes
+kubectl get storageclass
+helm install hugegraph ./helm/hugegraph -n hugegraph \
+  --create-namespace --wait --timeout 15m
+```
+
+Default resources preserve image JVM sizing. Set requests/limits for your capacity requirements; nine graph JVMs plus Hubble need sufficient memory.
+
+## 2 Modes and entry points
+
+`mode: easy` is the default. Server and Hubble use automatic NodePorts; PD stays ClusterIP. HTTP works without a domain, certificate or acknowledgement.
+`mode: strict` defaults Server/Hubble to ClusterIP and enables NetworkPolicy. Both modes keep authentication and persistence.
+Explicit component parameters take priority over global parameters, which take priority over mode defaults; explicit `false` remains an override.
+The global parameters are `persistence.enabled` and `global.imageRegistry`. Strict mode is also available through `values-strict.yaml`.
+
+| Entry | Access | Requirements |
+|---|---|---|
+| NodePort | `http://<reachable-node-ip>:<assigned-node-port>` | Node connectivity and firewall access; no additional controller |
+| ClusterIP | Internal Service IP/DNS, for example `hugegraph-server.hugegraph.svc:8080` | External clients use port-forward or an existing gateway |
+| LoadBalancer | Infrastructure-assigned address | Compatible load balancer controller |
+| Ingress | HTTP routing through a controller | Installed controller; hostname and TLS optional |
+
+```bash
+kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble
+kubectl get nodes -o wide
+kubectl -n hugegraph get secret hugegraph-admin \
+  -o jsonpath='{.data.password}' | base64 --decode
+```
+
+Open Hubble on its assigned NodePort and log in as `admin` with this password. A node need not host the Pod with default `externalTrafficPolicy: Cluster`.
+The internal ClusterIP is a virtual Service address, not a node IP; a laptop normally cannot reach it directly.
+Use `kubectl -n hugegraph port-forward svc/hugegraph-hubble 8088:8088` for a local browser at `http://127.0.0.1:8088`.
+
+Each client Service supports `externalTrafficPolicy`, `loadBalancerClass`, `loadBalancerIP`, `loadBalancerSourceRanges`, `externalIPs`
+and `allocateLoadBalancerNodePorts`, subject to the cluster/controller's capabilities. Use LoadBalancer fields with that Service type.
+NodePort omission or `0` means automatic allocation. Fixed ports are validated against the cluster's configured range by Kubernetes;
+the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields remain accepted but no longer gate rendering.
+
+## 3 Internal images and storage
+
+[Complete examples](https://github.com/apache/hugegraph/tree/master/helm/hugegraph/examples) cover private registries, dynamic storage, seven local PVs,
+GitOps credentials, API-only deployment and a hostless HTTP Ingress.
+
+Set `global.imageRegistry` to prefix unqualified image repositories; an explicit registry in a component repository takes precedence.
+The default mirror inventory is only `hugegraph/pd`, `hugegraph/store`, `hugegraph/hugegraph` and `hugegraph/hubble`, at the configured tags/digests.
+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.
+
+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.
+For a new temporary installation, set `persistence.enabled=false` to use `emptyDir`; component storage flags override it.
+The chart never replaces a failed PVC with temporary storage and rejects PD/Store storage-mode changes on initialized releases.
+
+## 4 Authentication and secrets
+
+Normal Helm installations generate and reuse three credentials: `<release>-admin` (`password`), `<release>-auth-token` (`token_secret`)
+and `<release>-pd-auth` (`secret-key`). PD REST requires the shared PD secret, supplied to the PD container as `HG_PD_AUTH_SECRET_KEY`;
+Server's storage wait and Hubble read the same credential. It is not a separate user password that must be invented for each Pod.
+
+For GitOps, use fixed encrypted values or pre-created Secrets through `pd.auth.existingSecret`, `server.auth.admin.existingSecret`
+and `server.auth.token.existingSecret`. `existingSecret` wins over inline values and is not managed by the chart.
+The admin password must be printable ASCII without spaces, colons or backslashes; the PD secret must be printable ASCII without surrounding whitespace
+or backslashes; the JWT signing key must be at least 32 bytes. Offline renderers cannot reuse live generated Secrets through `lookup`.
+
+The admin Secret is an **initial** credential. Updating it does not rotate an existing account.
+Change the password through `PUT /graphspaces/DEFAULT/auth/users/admin` with `{"user_password":"<new-password>"}` using the existing credential,
+update the Secret/source to that same password, then restart the Server Deployment to clear every replica's auth cache.
+
+Hubble is enabled by default and its current login requires Server authentication. Set `hubble.enabled=false` for API-only access;
+optionally also set `server.auth.enabled=false` for an unauthenticated API. Inactive credential settings may remain in your values file.
+
+## 5 Upgrade and verification
+
+Use native Helm value reuse to preserve an old release'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
+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.
+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.
+
+`server.storageWaitTimeoutSeconds` defaults to 300 and is passed as `WAIT_STORAGE_TIMEOUT_S`. An unspecified startup probe threshold is derived
+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.
+For scheduling, NetworkPolicy, rolling updates and recovery, see [Kubernetes operations](./hugegraph-helm-operations.md).

From d3b0a6696ee8f0514e7364568be50dba38aa172d Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Wed, 14 Oct 2026 05:20:21 +0800
Subject: [PATCH 2/8] docs: correct Helm images and recovery guidance

- name the HStore Server image in both inventories
- link the current topology and rollout constraints
- clarify the limits of disk loss recovery guidance
---
 .../hugegraph/hugegraph-helm-operations.md      | 12 ++++++++----
 .../docs/quickstart/hugegraph/hugegraph-helm.md |  2 +-
 .../hugegraph/hugegraph-helm-operations.md      | 17 ++++++++++++-----
 .../docs/quickstart/hugegraph/hugegraph-helm.md |  2 +-
 4 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index c5fa25c13..145d36ae8 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -44,7 +44,8 @@ Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTim
 
 首次初始化时，Store 至少三个则默认每个分区三副本，否则一副本。
 PD 会持久化分区设置，初始化后修改 chart 值不会覆盖已有元数据，应使用 PD 配置 API 并协调分区巡检。
-显式 shard 数必须为奇数且不超过 Store 数，操作在线集群前参照 README 的完整过程。
+显式 shard 数必须为奇数且不超过 Store 数，操作在线集群前先核对
+[拓扑约束](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#topology-and-scheduling)；chart 不负责迁移已有 shard 元数据。
 
 ## 5 NetworkPolicy {#5-networkpolicy}
 
@@ -80,14 +81,17 @@ networkPolicy:
 集群预设使用 `store.updateStrategy.type=OnDelete` 便于维护时控制逐个替换。
 每次只删除一个 Store Pod，下一次删除前确认上一个 Pod Ready、Store 心跳新鲜，并从 PD leader 查询每个 shard group 都有完整成员及唯一 leader。
 PD 的 `Up` 状态本身不证明 shard 恢复完成。PDB 限制主动驱逐，不限制 StatefulSet 控制器更新。
-按 README 完整检查 shard 状态，发现缺副本或无 leader 时停止继续替换。
+发现缺成员或无 leader 时停止继续替换。
+[运维参考](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#rolling-store-updates-and-recovery)说明这些升级条件，
+但不提供完整的逐组诊断或丢盘恢复步骤。
 
 ## 7 灾难恢复 {#7-disaster-recovery}
 
 保留原卷、claim 身份和 PD 成员关系，不通过删除 RocksDB lock 文件恢复，也不把持久化成员配置替换为全新的节点。
-Store 丢盘需要按 shard 替换/恢复流程处理，新建空 PVC 并不自动恢复数据。
+Store 丢盘后，新建空 PVC 并不能恢复原有数据。
 local 磁盘不能在节点故障时自动迁移文件。备份应放在这些 PV 之外，并单独验证恢复；chart 不提供自动备份和自动恢复。
-破坏性变更前先按 README 的恢复顺序检查。
+[恢复说明](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#rolling-store-updates-and-recovery)列出恢复约束，不是完整的恢复操作顺序。
+破坏性变更前，应结合部署版本、剩余副本或备份制定并验证恢复方案。
 
 ## 8 扩缩容 {#8-scaling}
 
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
index 3de5cf157..f9d7d3c98 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -64,7 +64,7 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据
 GitOps 凭据、仅 API 部署以及无域名的 HTTP Ingress。
 
 `global.imageRegistry` 为未指定 registry 的镜像仓库加前缀，组件指定完整 registry 地址时优先采用组件配置。
-默认只需镜像仓库中的 `hugegraph/pd`、`hugegraph/store`、`hugegraph/hugegraph` 和 `hugegraph/hubble` 四个镜像，标签或 digest 按实际配置选取。
+默认只需镜像仓库中的 `hugegraph/pd`、`hugegraph/store`、`hugegraph/server` 和 `hugegraph/hubble` 四个镜像，标签或 digest 按实际配置选取。
 等待 PD 的 init container 复用 Store 镜像，Helm test 复用 Server 镜像。这两个镜像已包含 `curl`，无需额外 curl 镜像或启动时安装软件。
 自定义镜像可以继续使用显式 `store.waitImage` 和 `server.waitImage` 覆盖。
 
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index b842c57cf..8c53d15bb 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -47,7 +47,8 @@ Do not change a persisted PD/Store Raft hostname or port as an ordinary upgrade:
 At first bootstrap, the chart seeds three shard replicas when there are at least three Stores, and one otherwise.
 PD persists the partition settings; changing chart values after initialization does not rewrite that metadata.
 Use the PD configuration API and a coordinated partition patrol for an existing cluster. An explicit shard count must be odd and no greater than Store replicas.
-See the README's partition sharding procedure before changing a live cluster.
+See the [topology constraints](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#topology-and-scheduling)
+before changing a live cluster; the chart does not migrate existing shard metadata.
 
 ## 5 NetworkPolicy
 
@@ -84,14 +85,20 @@ networkPolicy:
 Use `store.updateStrategy.type=OnDelete` for a controlled maintenance rollout, as the cluster preset does.
 Delete one Store Pod at a time. Before replacing the next, verify the previous Pod is Ready, has a fresh Store heartbeat and each shard group has its
 full membership and exactly one leader, read from the PD leader. PD's `Up` status alone does not prove completed shard recovery.
-PDBs limit voluntary eviction, not StatefulSet controller disruption. Consult the README's full per-group checks and stop on missing shards or leaders.
+PDBs limit voluntary eviction, not StatefulSet controller disruption. Stop on missing members or leaders.
+The [operations reference](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#rolling-store-updates-and-recovery)
+summarizes these rollout conditions;
+it does not provide a complete per-group diagnostic or disk-loss recovery procedure.
 
 ## 7 Disaster recovery
 
 Preserve existing volumes, claim identities and PD membership. Do not delete RocksDB lock files to recover a deployment, or replace persisted membership
-with freshly generated nodes. Loss of one Store disk requires a documented shard replacement/recovery procedure, not merely a new empty PVC.
-Local disks cannot migrate their files automatically when a node fails. Take backups outside these PVs and test recovery separately;
-the chart does not implement backup or automatic recovery. Follow the README's recovery sequence before destructive changes.
+with freshly generated nodes. A new empty PVC does not restore the data from a lost Store disk.
+Local disks cannot migrate their files automatically when a node fails. Take backups outside these PVs and test recovery separately.
+The chart does not implement backup or automatic recovery. The
+[recovery notes](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#rolling-store-updates-and-recovery)
+describe constraints, not a complete recovery sequence.
+Before destructive changes, establish and validate a recovery plan for the deployed version and remaining replicas or backups.
 
 ## 8 Scaling
 
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
index 475b832b7..fcb478ebc 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -64,7 +64,7 @@ the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields rem
 GitOps credentials, API-only deployment and a hostless HTTP Ingress.
 
 Set `global.imageRegistry` to prefix unqualified image repositories; an explicit registry in a component repository takes precedence.
-The default mirror inventory is only `hugegraph/pd`, `hugegraph/store`, `hugegraph/hugegraph` and `hugegraph/hubble`, at the configured tags/digests.
+The default mirror inventory is only `hugegraph/pd`, `hugegraph/store`, `hugegraph/server` and `hugegraph/hubble`, at the configured tags/digests.
 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.
 

From 4cde498ce8f1396cd52a9d7f79a6f9340f89d8af Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Wed, 14 Oct 2026 14:25:50 +0800
Subject: [PATCH 3/8] docs(helm): clarify PD and Store operations

- show PD REST service credentials and Secret usage
- separate partition patrol from manual leader balance
- explain Store replacement and compression behavior
---
 .../hugegraph/hugegraph-helm-operations.md    | 30 ++++++++++++++++++
 .../hugegraph/hugegraph-helm-operations.md    | 31 +++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 145d36ae8..3848d2b21 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -34,6 +34,22 @@ PD `/v1/ready` 需要 Raft leader，`/v1/health` 只说明监听器已启动，S
 Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTimeoutSeconds` 调整。
 本地模板渲染不能验证集群连通性、卷挂载或 JVM 运行容量。
 
+Server API 根据 `Accept-Encoding` 协商响应压缩。支持 gzip 的客户端可请求 `gzip` 或使用 `curl --compressed`；
+`identity` 或未请求压缩时返回未压缩内容。需从更新后的源码重新构建 Server 镜像才能包含该行为，仅更新 chart 不会改变现有镜像。
+
+### PD REST 鉴权 {#pd-rest-authentication}
+
+PD REST 使用 HTTP Basic 鉴权，`hg`、`store`、`hubble` 和 `vermeer` 共用 PD REST Secret 密码。
+Server 的 `admin` 不是 PD REST 账户，使用它会返回 401。默认 release/Secret 的查询示例，地址应为可达的 PD REST 地址：
+
+```bash
+PD_SECRET=$(kubectl -n hugegraph get secret hugegraph-pd-auth \
+  -o jsonpath='{.data.secret-key}' | base64 --decode)
+curl --user "hg:${PD_SECRET}" "http://<pd-rest-address>:8620/v1/stores"
+```
+
+使用 `pd.auth.existingSecret` 或自定义 `pd.auth.key` 时读取实际 Secret 和 key，不使用 Server 管理员密码。
+
 ## 3 调度 {#3-scheduling}
 
 默认 `preferred` 反亲和允许节点少于副本数时调度；`values-cluster.yaml` 对 PD/Store 设置 required 反亲和，因此需要至少三个可调度节点。
@@ -85,6 +101,20 @@ PD 的 `Up` 状态本身不证明 shard 恢复完成。PDB 限制主动驱逐，
 [运维参考](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#rolling-store-updates-and-recovery)说明这些升级条件，
 但不提供完整的逐组诊断或丢盘恢复步骤。
 
+即使副本完整，替换单个 Store 时，Raft leader 和客户端路由收敛期间仍可能出现请求失败或超时，不保证零错误。
+继续维护前同时观察应用错误和 shard 恢复状态，不要盲目重试写请求。
+
+### PD 巡检和 leader 均衡 {#pd-patrol-and-leader-balance}
+
+分区巡检修复 shard 成员关系；leader 均衡是单独的手动任务，不会自动定时执行。
+执行前通过鉴权的 `/v1/members` 查询 `data.pdLeader.restUrl`，并确认该 PD 的 `/v1/ready` 返回 `isLeader: true`。
+GET 任务 `/v1/task/patrolPartitions` 和 `/v1/task/balanceLeaders` 会改变集群状态，应携带 PD REST 凭据请求已确认的 leader。
+成员恢复和 split/move 任务完成后才能执行 leader 均衡；Store 心跳需新鲜，各组成员需完整、健康。
+忙碌任务返回 body `status: 1001`。follower 可能返回空成功，leader 转移是异步的，HTTP 200 或转移计划不代表执行完成。
+继续维护前重新检查 `/v1/partitions`、`/v1/stores` 和应用错误。
+[任务操作步骤](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#pd-patrol-and-leader-balance)
+说明巡检和均衡的独立操作；维护忙碌时不要循环请求任务。
+
 ## 7 灾难恢复 {#7-disaster-recovery}
 
 保留原卷、claim 身份和 PD 成员关系，不通过删除 RocksDB lock 文件恢复，也不把持久化成员配置替换为全新的节点。
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 8c53d15bb..69324639b 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -35,6 +35,23 @@ PD `/v1/ready` requires a Raft leader; `/v1/health` only confirms the listener.
 Server waits up to `server.storageWaitTimeoutSeconds` (default 300) before its application startup; adjust it for slow storage bootstrap.
 No local Helm rendering verifies live cluster reachability, volumes or JVM capacity.
 
+Server API responses negotiate compression through `Accept-Encoding`. Gzip-capable clients can request `gzip` or use `curl --compressed`;
+`identity` or no compression request keeps the response uncompressed. Build a new Server image from the updated source to include this behavior;
+updating the chart alone does not update an existing image.
+
+### PD REST authentication
+
+PD REST uses HTTP Basic auth: `hg`, `store`, `hubble` and `vermeer` share the PD REST Secret password.
+Server's `admin` account is not a PD REST account and receives 401. For the default release/Secret and a reachable PD REST address:
+
+```bash
+PD_SECRET=$(kubectl -n hugegraph get secret hugegraph-pd-auth \
+  -o jsonpath='{.data.secret-key}' | base64 --decode)
+curl --user "hg:${PD_SECRET}" "http://<pd-rest-address>:8620/v1/stores"
+```
+
+With `pd.auth.existingSecret` or a custom `pd.auth.key`, read the actual Secret and key. Do not use the Server admin password.
+
 ## 3 Scheduling
 
 The default `preferred` anti-affinity permits scheduling with fewer nodes than replicas. `values-cluster.yaml` sets required PD/Store anti-affinity,
@@ -90,6 +107,20 @@ The [operations reference](https://github.com/apache/hugegraph/blob/master/helm/
 summarizes these rollout conditions;
 it does not provide a complete per-group diagnostic or disk-loss recovery procedure.
 
+A single Store replacement can cause request errors or timeouts while Raft leadership and client routes converge, even with full replicas.
+There is no zero-error guarantee. Observe application errors as well as shard recovery before continuing; do not blindly retry writes.
+
+### PD patrol and leader balance
+
+Partition patrol repairs shard membership; leader balance is a separate manual task and is not scheduled automatically.
+Before either task, identify the PD leader through authenticated `/v1/members` (`data.pdLeader.restUrl`) and confirm its `/v1/ready` reports `isLeader: true`.
+The GET tasks `/v1/task/patrolPartitions` and `/v1/task/balanceLeaders` change cluster state; target that confirmed leader with PD REST credentials.
+Wait for membership recovery and split/move tasks to finish before balancing leaders; Stores must have fresh heartbeats and groups full, healthy membership.
+A busy task returns body `status: 1001`. A follower may return empty success, and leader transfers are asynchronous:
+HTTP 200 or a transfer plan does not prove completion. Recheck `/v1/partitions`, `/v1/stores` and application errors before further maintenance.
+Follow the [task procedure](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#pd-patrol-and-leader-balance)
+for the separate patrol and balance steps; do not loop task requests while maintenance is busy.
+
 ## 7 Disaster recovery
 
 Preserve existing volumes, claim identities and PD membership. Do not delete RocksDB lock files to recover a deployment, or replace persisted membership

From 9e7968d16e31a5c3ef7c1534a9926afc0b221516 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Wed, 14 Oct 2026 14:42:46 +0800
Subject: [PATCH 4/8] docs(helm): explain optional credential files

- retain simple PD credential examples
- explain shell history and process argument exposure
- link optional private credential and payload handling
---
 .../cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md | 4 ++++
 .../en/docs/quickstart/hugegraph/hugegraph-helm-operations.md | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 3848d2b21..67e1ba598 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -49,6 +49,10 @@ curl --user "hg:${PD_SECRET}" "http://<pd-rest-address>:8620/v1/stores"
 ```
 
 使用 `pd.auth.existingSecret` 或自定义 `pd.auth.key` 时读取实际 Secret 和 key，不使用 Server 管理员密码。
+变量式示例避免将密码字面值写入 shell 历史，但展开后的凭据可能短暂出现在进程参数中。
+共享终端可选用 `curl --user hg` 提示输入密码，或权限为 `600` 的私有 curl 配置文件；
+[凭据操作说明](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#credentials)
+也包含改密请求体的处理方式。不要记录或提交凭据文件。
 
 ## 3 调度 {#3-scheduling}
 
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 69324639b..fc6be6608 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -51,6 +51,10 @@ curl --user "hg:${PD_SECRET}" "http://<pd-rest-address>:8620/v1/stores"
 ```
 
 With `pd.auth.existingSecret` or a custom `pd.auth.key`, read the actual Secret and key. Do not use the Server admin password.
+Variables avoid literal passwords in shell history, but expanded credentials can briefly appear in process arguments.
+On shared terminals, use `curl --user hg` to prompt for the password or a private curl config with permissions `600`;
+the [credentials guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#credentials)
+also covers password-update payloads. Keep credential files out of logs and version control.
 
 ## 3 Scheduling
 

From 69fb1227c5f2609f816f25360f144486757384fb Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Thu, 15 Oct 2026 03:54:17 +0800
Subject: [PATCH 5/8] docs(helm): add version routes and polish quickstart
 prerequisites

---
 .../quickstart/hugegraph/hugegraph-helm.md    | 10 +++----
 .../quickstart/hugegraph/hugegraph-helm.md    | 12 ++++----
 data/version_routes.json                      | 28 +++++++++++++++++++
 3 files changed, 40 insertions(+), 10 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
index f9d7d3c98..655e8e66d 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -12,9 +12,11 @@ search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble, 内网部署]
 
 ## 1 安装
 
-默认部署 **3 PD + 3 Store + 3 Server 和 Hubble**，开启鉴权和持久化。
-需要默认动态 StorageClass 或匹配的静态 PV，共七个卷，分别为 3 个 10 GiB 的 PD 卷、3 个 50 GiB 的 Store 卷、1 个 1 GiB 的 Hubble 卷。
-chart 创建 PVC，不创建存储 provisioner 或宿主机目录。
+> [!NOTE]
+> **默认部署规格与存储要求**
+> - **拓扑组成**：默认部署 **3 PD + 3 Store + 3 Server 与 1 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
@@ -26,8 +28,6 @@ helm install hugegraph ./helm/hugegraph -n hugegraph \
   --create-namespace --wait --timeout 15m
 ```
 
-默认保留镜像的 JVM 内存计算方式。按容量要求配置 requests/limits，并为九个图服务 JVM 和 Hubble 提供足够内存。
-
 ## 2 模式和访问入口
 
 默认 `mode: easy`，Server 和 Hubble 自动分配 NodePort，PD 保持 ClusterIP。可以直接使用 HTTP，无需域名、证书或额外确认参数。
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
index fcb478ebc..b6cbeb9c6 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -12,9 +12,13 @@ Advanced lifecycle procedures are in the [operations reference](https://github.c
 
 ## 1 Install
 
-Defaults deploy **3 PD + 3 Store + 3 Server and Hubble**, with authentication and persistent storage enabled.
-Provide a default dynamic StorageClass, or matching static PVs: three PD volumes of 10 GiB, three Store volumes of 50 GiB and one Hubble volume of 1 GiB.
-The chart creates claims; it does not create a storage provisioner or host directories.
+> [!NOTE]
+> **Default Topology & Storage Prerequisites**
+> - **Components**: Deploys **3 PD + 3 Store + 3 Server and Hubble** by default, with authentication and persistent storage enabled.
+> - **Volume Requirements**: Requires a default dynamic StorageClass or matching pre-created static PVs, totaling 7 persistent volumes
+>   (3 × 10 GiB PD volumes, 3 × 50 GiB Store volumes, and 1 × 1 GiB Hubble volume).
+> - **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
@@ -26,8 +30,6 @@ helm install hugegraph ./helm/hugegraph -n hugegraph \
   --create-namespace --wait --timeout 15m
 ```
 
-Default resources preserve image JVM sizing. Set requests/limits for your capacity requirements; nine graph JVMs plus Hubble need sufficient memory.
-
 ## 2 Modes and entry points
 
 `mode: easy` is the default. Server and Hubble use automatic NodePorts; PD stays ClusterIP. HTTP works without a domain, certificate or acknowledgement.
diff --git a/data/version_routes.json b/data/version_routes.json
index 7f6e06257..cbdc3625d 100644
--- a/data/version_routes.json
+++ b/data/version_routes.json
@@ -701,6 +701,20 @@
       "1.3": null,
       "1.0": null
     },
+    "cn:quickstart/hugegraph/hugegraph-helm": {
+      "latest": "cn/docs/quickstart/hugegraph/hugegraph-helm/",
+      "1.7": null,
+      "1.5": null,
+      "1.3": null,
+      "1.0": null
+    },
+    "cn:quickstart/hugegraph/hugegraph-helm-operations": {
+      "latest": "cn/docs/quickstart/hugegraph/hugegraph-helm-operations/",
+      "1.7": null,
+      "1.5": null,
+      "1.3": null,
+      "1.0": null
+    },
     "cn:quickstart/hugegraph/hugegraph-hstore": {
       "latest": "cn/docs/quickstart/hugegraph/hugegraph-hstore/",
       "1.7": "cn/docs/quickstart/hugegraph/hugegraph-hstore/",
@@ -1415,6 +1429,20 @@
       "1.3": null,
       "1.0": null
     },
+    "en:quickstart/hugegraph/hugegraph-helm": {
+      "latest": "docs/quickstart/hugegraph/hugegraph-helm/",
+      "1.7": null,
+      "1.5": null,
+      "1.3": null,
+      "1.0": null
+    },
+    "en:quickstart/hugegraph/hugegraph-helm-operations": {
+      "latest": "docs/quickstart/hugegraph/hugegraph-helm-operations/",
+      "1.7": null,
+      "1.5": null,
+      "1.3": null,
+      "1.0": null
+    },
     "en:quickstart/hugegraph/hugegraph-hstore": {
       "latest": "docs/quickstart/hugegraph/hugegraph-hstore/",
       "1.7": "docs/quickstart/hugegraph/hugegraph-hstore/",

From 91aa006f246ef0a2fc1decc90b123329c99f7529 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Thu, 15 Oct 2026 04:26:54 +0800
Subject: [PATCH 6/8] docs(helm): describe per-Pod query assertions

- document index-state checks and their coverage limits
- explain business assertions and execution credentials
- link the full operations example
---
 .../quickstart/hugegraph/hugegraph-helm-operations.md | 10 ++++++++++
 .../quickstart/hugegraph/hugegraph-helm-operations.md | 11 +++++++++++
 2 files changed, 21 insertions(+)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 67e1ba598..6d5dce6c1 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -34,6 +34,16 @@ PD `/v1/ready` 需要 Raft leader，`/v1/health` 只说明监听器已启动，S
 Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTimeoutSeconds` 调整。
 本地模板渲染不能验证集群连通性、卷挂载或 JVM 运行容量。
 
+### Helm test 检查范围 {#helm-test-coverage}
+
+`helm test` 逐 Server Pod 检查 `DEFAULT-hugegraph` 绑定，并拒绝当前可见关联索引的 `INVALID` 状态。
+它按 ID 读取索引，不刷新全量索引缓存；不证明索引查询结果或完整 schema 一致性。
+对已有数据，可在 Helm 升级时用 `--set-file server.testGremlin=assertions.groovy` 添加逐 Pod 的只读业务断言。
+脚本必须用 `assert` 或抛异常表示结果不符，仅返回 `false` 不会让请求失败。
+[业务查询断言](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#business-query-assertions)
+给出了示例与检查边界。未配置脚本时明确显示业务断言已跳过，默认 hook 不创建 schema 或数据。
+自定义脚本使用 hook 的 Server 凭据执行（开启鉴权时为 `admin`），不强制只读；请提供可信的只读断言。
+
 Server API 根据 `Accept-Encoding` 协商响应压缩。支持 gzip 的客户端可请求 `gzip` 或使用 `curl --compressed`；
 `identity` 或未请求压缩时返回未压缩内容。需从更新后的源码重新构建 Server 镜像才能包含该行为，仅更新 chart 不会改变现有镜像。
 
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index fc6be6608..6f7b44ad3 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -35,6 +35,17 @@ PD `/v1/ready` requires a Raft leader; `/v1/health` only confirms the listener.
 Server waits up to `server.storageWaitTimeoutSeconds` (default 300) before its application startup; adjust it for slow storage bootstrap.
 No local Helm rendering verifies live cluster reachability, volumes or JVM capacity.
 
+### Helm test coverage
+
+`helm test` checks `DEFAULT-hugegraph` binding and rejects visible associated indexes in `INVALID` state on each Server Pod.
+It reads indexes by ID without refreshing the full index cache; it does not prove index query results or complete schema consistency.
+For existing data, use `--set-file server.testGremlin=assertions.groovy` during Helm upgrade to add read-only business assertions on every Pod.
+The script must use `assert` or throw on unexpected results; returning `false` alone does not fail the request.
+See [business query assertions](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#business-query-assertions)
+for an example and coverage limits. Without a script, business assertions are reported as skipped.
+The default hook creates no schema or data. Custom scripts use the hook's Server credential (`admin` with auth enabled);
+read-only execution is not enforced, so supply trusted, read-only assertions.
+
 Server API responses negotiate compression through `Accept-Encoding`. Gzip-capable clients can request `gzip` or use `curl --compressed`;
 `identity` or no compression request keeps the response uncompressed. Build a new Server image from the updated source to include this behavior;
 updating the chart alone does not update an existing image.

From c976b03dcaeebe01ea8951178d22af3bd7f36b15 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Thu, 15 Oct 2026 12:06:32 +0800
Subject: [PATCH 7/8] docs(helm): complete navigation and test guidance

- add Helm pages to the shared navigation tree
- align per-Pod index checks with completed index jobs
- update native navigation validation expectations
---
 .../hugegraph/hugegraph-helm-operations.md    |  3 +-
 .../hugegraph/hugegraph-helm-operations.md    |  3 +-
 data/docs_nav.json                            | 30 ++++++++++++++++++-
 scripts/versioning.py                         | 12 ++++----
 4 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 6d5dce6c1..e3494c23a 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -36,7 +36,8 @@ Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTim
 
 ### Helm test 检查范围 {#helm-test-coverage}
 
-`helm test` 逐 Server Pod 检查 `DEFAULT-hugegraph` 绑定，并拒绝当前可见关联索引的 `INVALID` 状态。
+`helm test` 逐 Server Pod 检查 `DEFAULT-hugegraph` 绑定，并要求当前可见关联索引处于 `CREATED` 状态。
+请在索引任务结束后执行；测试会在 `server.testTimeoutSeconds` 内重试短暂的构建状态。
 它按 ID 读取索引，不刷新全量索引缓存；不证明索引查询结果或完整 schema 一致性。
 对已有数据，可在 Helm 升级时用 `--set-file server.testGremlin=assertions.groovy` 添加逐 Pod 的只读业务断言。
 脚本必须用 `assert` 或抛异常表示结果不符，仅返回 `false` 不会让请求失败。
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 6f7b44ad3..76220e929 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -37,7 +37,8 @@ No local Helm rendering verifies live cluster reachability, volumes or JVM capac
 
 ### Helm test coverage
 
-`helm test` checks `DEFAULT-hugegraph` binding and rejects visible associated indexes in `INVALID` state on each Server Pod.
+`helm test` checks `DEFAULT-hugegraph` binding and requires visible associated indexes to be in `CREATED` state on each Server Pod.
+Run it after index jobs finish; the test retries temporary construction states within `server.testTimeoutSeconds`.
 It reads indexes by ID without refreshing the full index cache; it does not prove index query results or complete schema consistency.
 For existing data, use `--set-file server.testGremlin=assertions.groovy` during Helm upgrade to add read-only business assertions on every Pod.
 The script must use `assert` or throw on unexpected results; returning `false` alone does not fail the request.
diff --git a/data/docs_nav.json b/data/docs_nav.json
index d4b412543..4a5503ece 100644
--- a/data/docs_nav.json
+++ b/data/docs_nav.json
@@ -34,6 +34,12 @@
             },
             {
               "page": "/docs/quickstart/hugegraph/hugegraph-pd"
+            },
+            {
+              "page": "/docs/quickstart/hugegraph/hugegraph-helm"
+            },
+            {
+              "page": "/docs/quickstart/hugegraph/hugegraph-helm-operations"
             }
           ]
         },
@@ -406,6 +412,16 @@
               "page": "/docs/quickstart/hugegraph/hugegraph-pd",
               "url": "/docs/quickstart/hugegraph/hugegraph-pd/",
               "children": []
+            },
+            {
+              "page": "/docs/quickstart/hugegraph/hugegraph-helm",
+              "url": "/docs/quickstart/hugegraph/hugegraph-helm/",
+              "children": []
+            },
+            {
+              "page": "/docs/quickstart/hugegraph/hugegraph-helm-operations",
+              "url": "/docs/quickstart/hugegraph/hugegraph-helm-operations/",
+              "children": []
             }
           ]
         },
@@ -906,6 +922,16 @@
       "/docs/quickstart/hugegraph/",
       "/docs/quickstart/hugegraph/hugegraph-pd/"
     ],
+    "/docs/quickstart/hugegraph/hugegraph-helm/": [
+      "@group/components",
+      "/docs/quickstart/hugegraph/",
+      "/docs/quickstart/hugegraph/hugegraph-helm/"
+    ],
+    "/docs/quickstart/hugegraph/hugegraph-helm-operations/": [
+      "@group/components",
+      "/docs/quickstart/hugegraph/",
+      "/docs/quickstart/hugegraph/hugegraph-helm-operations/"
+    ],
     "/docs/quickstart/toolchain/": [
       "@group/components",
       "/docs/quickstart/toolchain/"
@@ -1347,7 +1373,9 @@
     ],
     "/docs/quickstart/hugegraph/": [
       "/docs/quickstart/hugegraph/hugegraph-hstore",
-      "/docs/quickstart/hugegraph/hugegraph-pd"
+      "/docs/quickstart/hugegraph/hugegraph-pd",
+      "/docs/quickstart/hugegraph/hugegraph-helm",
+      "/docs/quickstart/hugegraph/hugegraph-helm-operations"
     ],
     "/docs/quickstart/toolchain/": [
       "/docs/quickstart/toolchain/visualization",
diff --git a/scripts/versioning.py b/scripts/versioning.py
index bc49a05ea..f4f0a10f1 100644
--- a/scripts/versioning.py
+++ b/scripts/versioning.py
@@ -133,36 +133,36 @@
 DOCS_NAV_EXPECTED_STATS = {
     "latest": {
         "groups": 5,
-        "pages": 92,
+        "pages": 94,
         "removed": 4,
         "scopedLinks": 0,
-        "treeSha256": "15de4de385857f877b46083de8e65d2887769d811687c4fe7ade3069401fc929",
+        "treeSha256": "c610cc9128f26a85e0f60843f9e5255f95daa8ba7d1d3a62d19a07a799a3e520",
     },
     "1.7": {
         "groups": 5,
         "pages": 85,
-        "removed": 5,
+        "removed": 7,
         "scopedLinks": 10,
         "treeSha256": "c87538b82b0e3506eef59417411686ddc188e0f33d0e3a1cda687de8d6f88747",
     },
     "1.5": {
         "groups": 5,
         "pages": 77,
-        "removed": 13,
+        "removed": 15,
         "scopedLinks": 10,
         "treeSha256": "ac29ab8f0e7020496a3a1afe480687043d751e32c93ffb848e2210e3500cd483",
     },
     "1.3": {
         "groups": 5,
         "pages": 68,
-        "removed": 22,
+        "removed": 24,
         "scopedLinks": 10,
         "treeSha256": "e8c9b0a64dac6dd3e47827ec5072697eb7d3ed79659e0b5c4a9c5df8e1408d38",
     },
     "1.0": {
         "groups": 5,
         "pages": 59,
-        "removed": 21,
+        "removed": 23,
         "scopedLinks": 10,
         "treeSha256": "bd45db511d9b6728e1523bd3c5ebd9d18912ee85aeabf79c77bcca7e511f977a",
     },

From b471d3959dee9d846b9a5ea0ae40e9b57bafdc16 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Thu, 15 Oct 2026 13:03:49 +0800
Subject: [PATCH 8/8] docs(helm): correct hook retry guidance

- describe the existing 150-second internal retry window
- distinguish the hook deadline from Helm command timeout
- keep private HTTP access with an optional PD port-forward path
---
 .../docs/quickstart/hugegraph/hugegraph-helm-operations.md  | 6 +++++-
 .../docs/quickstart/hugegraph/hugegraph-helm-operations.md  | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index e3494c23a..04910854d 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -37,7 +37,8 @@ Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTim
 ### Helm test 检查范围 {#helm-test-coverage}
 
 `helm test` 逐 Server Pod 检查 `DEFAULT-hugegraph` 绑定，并要求当前可见关联索引处于 `CREATED` 状态。
-请在索引任务结束后执行；测试会在 `server.testTimeoutSeconds` 内重试短暂的构建状态。
+请在索引任务结束后执行；hook 会在内部的 150 秒窗口内重试短暂的构建状态。
+Helm 的 `--timeout` 不会修改这个内部窗口。
 它按 ID 读取索引，不刷新全量索引缓存；不证明索引查询结果或完整 schema 一致性。
 对已有数据，可在 Helm 升级时用 `--set-file server.testGremlin=assertions.groovy` 添加逐 Pod 的只读业务断言。
 脚本必须用 `assert` 或抛异常表示结果不符，仅返回 `false` 不会让请求失败。
@@ -59,6 +60,9 @@ PD_SECRET=$(kubectl -n hugegraph get secret hugegraph-pd-auth \
 curl --user "hg:${PD_SECRET}" "http://<pd-rest-address>:8620/v1/stores"
 ```
 
+以上 HTTP 示例适用于可信内网。其他访问路径可使用 HTTPS 网关，或按需执行
+`kubectl -n hugegraph port-forward service/hugegraph-pd-client 8620:8620`，再访问 `http://127.0.0.1:8620`。
+
 使用 `pd.auth.existingSecret` 或自定义 `pd.auth.key` 时读取实际 Secret 和 key，不使用 Server 管理员密码。
 变量式示例避免将密码字面值写入 shell 历史，但展开后的凭据可能短暂出现在进程参数中。
 共享终端可选用 `curl --user hg` 提示输入密码，或权限为 `600` 的私有 curl 配置文件；
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
index 76220e929..d5899972e 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md
@@ -38,7 +38,8 @@ No local Helm rendering verifies live cluster reachability, volumes or JVM capac
 ### Helm test coverage
 
 `helm test` checks `DEFAULT-hugegraph` binding and requires visible associated indexes to be in `CREATED` state on each Server Pod.
-Run it after index jobs finish; the test retries temporary construction states within `server.testTimeoutSeconds`.
+Run it after index jobs finish; the hook retries temporary construction states within its 150-second internal window.
+Helm's `--timeout` does not change this internal window.
 It reads indexes by ID without refreshing the full index cache; it does not prove index query results or complete schema consistency.
 For existing data, use `--set-file server.testGremlin=assertions.groovy` during Helm upgrade to add read-only business assertions on every Pod.
 The script must use `assert` or throw on unexpected results; returning `false` alone does not fail the request.
@@ -62,6 +63,9 @@ PD_SECRET=$(kubectl -n hugegraph get secret hugegraph-pd-auth \
 curl --user "hg:${PD_SECRET}" "http://<pd-rest-address>:8620/v1/stores"
 ```
 
+The HTTP example assumes a trusted internal network. For other access paths, use an HTTPS gateway or optionally forward the PD Service:
+`kubectl -n hugegraph port-forward service/hugegraph-pd-client 8620:8620`, then query `http://127.0.0.1:8620`.
+
 With `pd.auth.existingSecret` or a custom `pd.auth.key`, read the actual Secret and key. Do not use the Server admin password.
 Variables avoid literal passwords in shell history, but expanded credentials can briefly appear in process arguments.
 On shared terminals, use `curl --user hg` to prompt for the password or a private curl config with permissions `600`;