使用 Helm 部署 HugeGraph

本文对应 HugeGraph 开发分支的 chart。发布镜像完成前标签仍为 latest，实际部署请固定自己的镜像版本。需要 Helm 3 和 Kubernetes 1.23 或更高版本。常用命令和参数见 chart README，生命周期操作见运维参考。

1 安装

说明

默认部署规格与存储要求

拓扑组成：默认部署 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 提供足够内存。

 1git clone https://github.com/apache/hugegraph.git
 2cd hugegraph
 3kubectl config current-context
 4kubectl get nodes
 5kubectl get storageclass
 6# 默认标准集群安装（3 PD + 3 Store + 3 Server + 1 Hubble，需 7 个 PV）：
 7helm install hugegraph ./helm/hugegraph -n hugegraph \
 8  --create-namespace --wait --timeout 15m
 9
10# 本地测试 / 单节点轻量环境（Minikube、Kind 等，仅各 1 副本且关闭反亲和）：
11# helm install hugegraph ./helm/hugegraph -n hugegraph \
12#   -f ./helm/hugegraph/values-single.yaml \
13#   --create-namespace --wait --timeout 10m

2 模式和访问入口

HugeGraph Helm 核心文件与结构

helm/hugegraph/
- Chart.yamlChart 元数据与版本定义
- values.yaml默认配置（easy 模式：3 PD + 3 Store + 3 Server + 1 Hubble，NodePort 入口）
- values-single.yaml单节点预设（本地 Minikube/Kind 测试，1 副本且关闭反亲和与 PDB）
- values-cluster.yaml生产集群预设（跨节点反亲和调度，Store 采用 OnDelete 逐个滚动升级）
- values-strict.yaml安全加固预设（strict 模式：全部 ClusterIP，强制启用 NetworkPolicy 隔离）
- values.schema.jsonvalues 配置参数校验规范
- templates/Kubernetes 资源编排模板
  - pd-statefulset.yamlPD 服务有状态副本集（元数据与调度中心）
  - store-statefulset.yamlStore 存储节点有状态副本集（分布式存储引擎）
  - server-deployment.yamlServer 引擎无状态 Deployment（注入 serviceId / graphSpace）
  - hubble-deployment.yaml可视化控制台 Deployment
  - tests/冒烟验证测试钩子（helm test，支持自定义 testGraphAlias）
- examples/7 种生产场景完整示例（含 local PV、GitOps 凭据、Ingress 等）
- docs/operations.md生命周期进阶运维与故障恢复手册

默认 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 都可选

1kubectl -n hugegraph get svc hugegraph-server hugegraph-hubble
2kubectl get nodes -o wide
3kubectl -n hugegraph get secret hugegraph-admin \
4  -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 暴露确认参数保留兼容，但不再阻止渲染。

服务身份与图空间

默认 server.serviceId 与 server.graphSpace 均为 DEFAULT。如需将 Server 注册到指定的业务服务名或图空间，可通过 values 指定：

1helm upgrade --install hugegraph ./helm/hugegraph -n hugegraph \
2  --set-string server.serviceId=analytics \
3  --set-string server.graphSpace=team_a \
4  --set-string server.testGraphAlias=team_a-demo

注意：非默认图空间必须在启动 Server 前先调用 PD API 创建；server.testGraphAlias 用于指定 helm test 验证的 Gremlin 图别名（区分大小写），不会从 graphSpace 自动推导。请勿在 server.extraEnv 中重复声明服务 ID 或图空间。

3 内网镜像和存储

完整例子包含内网镜像、动态存储、七个 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、入口、存储和凭据设置。

1helm get values hugegraph -n hugegraph --all
2helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \
3  --wait --timeout 15m
4helm 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 运维。