docs: explain easy Helm deployments

content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md

@@ -0,0 +1,152 @@
+---
+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 运行容量。
+
+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 管理员密码。
+变量式示例避免将密码字面值写入 shell 历史，但展开后的凭据可能短暂出现在进程参数中。
+共享终端可选用 `curl --user hg` 提示输入密码，或权限为 `600` 的私有 curl 配置文件；
+[凭据操作说明](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#credentials)
+也包含改密请求体的处理方式。不要记录或提交凭据文件。
+
+## 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 数，操作在线集群前先核对
+[拓扑约束](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#topology-and-scheduling)；chart 不负责迁移已有 shard 元数据。
+
+## 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 控制器更新。
+发现缺成员或无 leader 时停止继续替换。
+[运维参考](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 文件恢复，也不把持久化成员配置替换为全新的节点。
+Store 丢盘后，新建空 PVC 并不能恢复原有数据。
+local 磁盘不能在节点故障时自动迁移文件。备份应放在这些 PV 之外，并单独验证恢复；chart 不提供自动备份和自动恢复。
+[恢复说明](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md#rolling-store-updates-and-recovery)列出恢复约束，不是完整的恢复操作顺序。
+破坏性变更前，应结合部署版本、剩余副本或备份制定并验证恢复方案。
+
+## 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。

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/server` 和 `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)。