HAMi 平台版离线部署手册

本文档面向 SRE / 平台工程师，说明如何使用 All-in-One 离线包在 Kubernetes 集群中部署 HAMi AI Platform，并完成证书激活、GPU 节点启用和示例工作负载验证。

本交付包使用 Zarf，是为了在无外网或受限网络中完成镜像导入、Helm Charts 安装和后续升级，减少用户手工同步镜像与维护安装顺序的成本。

Zarf 是面向 Kubernetes 离线 / 半离线环境的应用打包与部署工具，可以把镜像、Helm chart、脚本和部署动作封装成一个可携带的包。

安装过程本身不依赖证书，您可以先完成部署，再通过后续步骤申请并导入证书。

简而言之：先装软件，后拿证书；不激活则 vGPU 切分与调度功能不可用，验证也会失败。

离线包内容

外层交付包命名格式为：

hami-ai-platform-v<VERSION>-airgap-<ARCH>.tar.gz
hami-ai-platform-v<VERSION>-airgap-<ARCH>.tar.gz.sha256

当前 hami-ai-platform-v0.0.2-airgap-amd64.tar.gz 中包含以下关键文件：

文件	用途
zarf-linux-amd64	Linux amd64 Zarf CLI
zarf-init-amd64-v0.76.0.tar.zst	Zarf init 离线包
hami-ai-platform-v0.0.2-airgap-amd64.tar.zst	HAMi AI Platform 主部署包
zarf-package-hami-example-gpu-burn-amd64-v0.0.1.tar.zst	GPU burn 示例验证包
zarf-package-hami-example-vllm-qwen-amd64-v0.0.2.tar.zst	vLLM + Qwen 示例验证包
kantaloupe/	kantaloupe values 示例和完整 values 说明文档
hami/README.md	hami-enterprise 完整 values 说明文档
collect-hami-license-info.sh	证书申请信息收集脚本
collect-cluster-info.sh	集群诊断信息收集脚本

可用以下命令先查看外层包内容，确认交付物完整：

tar -tvf hami-ai-platform-v0.0.2-airgap-amd64.tar.gz

前置条件清单

类型	要求	验证命令
Kubernetes	≥ 1.24	kubectl version --short
容器运行时	containerd 或 Docker	kubectl get nodes -o wide
Helm	≥ 3.14	helm version --short
GPU 驱动	NVIDIA driver ≥ 470（推荐 ≥ 550）	nvidia-smi
Prometheus CRD	必须安装 Prometheus monitoring CRD 以兼容不同的监控指标采集系统：Prometheus, VictoriaMetrics, etc.	kubectl api-resources | grep monitoring.coreos.com/v1
GPU Operator	已安装且 devicePlugin.enabled = false，推荐版本：v25.3.2）	helm list -A | grep gpu-operator
存储空间	建议大于 30 GB	df -h

关键约束：HAMi 自带 device-plugin，与 NVIDIA GPU Operator 内置 device-plugin 冲突。若已安装 GPU Operator，务必通过--set devicePlugin.enabled=false 禁用其内置 plugin。

解压、校验和安装 Zarf

# 下载交付包和校验文件
curl -L -O <URL>
curl -L -O <SHA256_URL>

# 校验完整性
shasum -a 256 -c hami-ai-platform-v0.0.2-airgap-amd64.tar.gz.sha256

# 解压外层 tar.gz
tar -xzf hami-ai-platform-v0.0.2-airgap-amd64.tar.gz

# 进入解压目录
cd hami-ai-platform-v0.0.2-airgap-amd64

交付包内已经包含 Linux amd64 版本的 Zarf CLI。进入解压目录后，先安装包内 Zarf：

chmod +x ./zarf-linux-amd64
sudo install -m 0755 ./zarf-linux-amd64 /usr/local/bin/zarf
zarf version

Zarf 自带 Helm 工具，后续排查 Helm release、values 和 chart 状态时请使用 zarf tools helm，避免目标环境没有单独安装 Helm：

zarf tools helm version
zarf tools helm list -A

初始化 Zarf

第一次在目标集群部署 Zarf 包前，需要先执行 zarf init。

使用 Zarf 内置 registry：

zarf init zarf-init-amd64-v0.76.0.tar.zst --confirm

使用外部 registry：

zarf init zarf-init-amd64-v0.76.0.tar.zst \
  --registry-url=<registry.example.com> \
  --registry-push-username=<username> \
  --registry-push-password=<password> \
  --confirm

外部 registry 参数说明：

参数	说明
--registry-url	外部镜像仓库地址
--registry-push-username	用于推送镜像的用户名
--registry-push-password	用于推送镜像的密码

初始化完成后，后续 zarf package deploy 时会自动导入镜像、“重写”（实际上依赖 admission webhook 实现镜像名称的 “redirect”） 容器 image 字段并部署 Helm Charts。

部署 HAMi AI Platform

HAMi AI Platform 主包中的所有组件都设置为可选组件，按部署场景选择 --components。组件顺序请保持文档中的顺序。

组件清单如下：

组件名称	说明	必须安装	推荐安装
tools	运维工具集：jq、nerdctl等	否	按需
hami-deploy-scripts	HAMi 部署脚本与预检脚本	是	是
hami	hami-enterprise Helm Chart	否	是
prometheus-crds	Prometheus monitoring crd	否	是
prometheus	Kube-prometheus-stack Helm Chart	否	按需
gpu-operator	NVIDIA GPU Operator	否	按需
gateway-api-crds	Gateway API Standard channel CRD 预安装	否	按需
envoy-gateway	Envoy Gateway（API 网关）	否	按需
kantaloupe	HAMi AI 平台（Kantaloupe）	否	是

gateway-api-crds 安装的是官方 Gateway API Standard channel v1.5.0 CRD 集合。若目标集群已经安装过 Gateway API，该组件会自动跳过，不做升级。

平台版部署需要使用自定义 Helm Chart values 文件覆盖集群、镜像、调度和监控相关配置。部署时必须同时传入 --values 和 --features="values=true"。Helm Chart values 的合并顺序为：Chart 默认值 -> 包内 values/*.yaml -> --values -> --set-values。离线包中的 prometheus, gpu-operator 都已经做了包内 values 配置，无需再次配置（除非你有特别的需求）。而 kantaloupe 需要做较多自定义配置，后文会详细介绍。

准备 custom values

hami-enterprise values

包内 hami/README.md 提供了 hami-enterprise 的完整 values 说明文档。常见配置项速查：

参数	说明	默认值
dra.enabled	是否部署启用 DRA	false
scheduler.leaderElect	是否启用 hami-scheduler 的多节点选举。单节点集群强烈建议关闭。	true
scheduler.replicas	调整 hami-scheduler 的实例数量	1
scheduler.kubeScheduler.image.registry	hami-scheduler 使用的 kube-scheduler 镜像仓库	registry.cn-hangzhou.aliyuncs.com
scheduler.kubeScheduler.image.repository	hami-scheduler 使用的 kube-scheduler 镜像名	google_containers/kube-scheduler
scheduler.kubeScheduler.image.tag	hami-scheduler 使用的 kube-scheduler 镜像版本，应与目标集群一致	""

最小配置示例：my-overrides.yaml

dra:
  enabled: false

scheduler:
  leaderElect: true

HAMi scheduler 依赖一个与目标 Kubernetes 集群版本匹配的 kube-scheduler 镜像。只有当目标集群的 kube-scheduler 没有运行在集群内（无法从 kube-system 直接复用镜像）时才需要额外配置；这类情况常见于云厂商的 Kubernetes 托管控制面集群。如果集群内存在kube-scheduler Pod，可以跳过以下配置：

scheduler:
  kubeScheduler:
    image:
      registry: your-registry.example.com
      repository: google_containers/kube-scheduler
      tag: v1.29.8

本离线包内置的 kube-scheduler 镜像版本为 v1.36.0。如果目标集群的 Kubernetes 版本与之不同，且无法复用集群内已有的 kube-scheduler，需要在离线环境自行准备并导入与集群版本匹配的 kube-scheduler 镜像。

kantaloupe values

包内 kantaloupe/README.md 提供了 kantaloupe 的完整 values 说明文档。

kantaloupe 由于需要配置功能特性、服务暴露、监控指标采集等功能，配置项较多，请按需配置，完整 values 配置请见 kantaloupe Helm Chart Value Reference。

常见的配置 values 示例如下，你可以拼接多段示例构成完整values文件：

• 配置默认平台管理员信息

auth:
  jwtSecret: "your-own-jwt-secret"
  bootstrapAdminUsername: "bootstrap-platform-admin"
  bootstrapAdminPassword: "admin12345"
  bootstrapAdminFullName: "Platform Administrator"
  bootstrapAdminEmail: "admin@email.com"

• 使用 envoy-gateway NodePort 暴露服务，在集群外部使用LoadBalancer（云厂商负载均衡、自建负载均衡等）转发四层流量。

gateway:
  enabled: true
  hostnames:
    - your-domain.example.com
  apiserverCors:
    enabled: true
    allowCredentials: true
    allowOrigins:
      - https://your-domain.example.com
  envoy:
    service:
      ports:
        http:
          nodePort: 30080
        https:
          nodePort: 30443
      type: NodePort
  listeners:
    - name: http
      port: 80
      protocol: HTTP
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRef:
          name: your-domain-tls-secret
        redirectFromHttp: true

• 使用 envoy-gateway NodePort 暴露服务，简单 PoC

gateway:
  enabled: true
  listeners:
    - name: http
      port: 80
      protocol: HTTP
  envoy:
    service:
      type: NodePort
      ports:
        http:
          nodePort: 30080

• 使用云厂商或裸金属服务提供的负载均衡 controller 接手的 LoadBalancer service

gateway:
  enabled: true
  hostnames:
    - your.domain
  listeners:
    - name: http
      port: 80
      protocol: HTTP
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRef:
          name: your-tls-secret
        redirectFromHttp: true
  envoy:
    service:
      type: LoadBalancer
      ports:
        http: {}
        https: {}

• 不使用 Gateway API，自行处理服务暴露。

gateway:
  enabled: false

• 替换 prometheus Query API addr（默认为 http://prometheus-kube-prometheus-prometheus.monitoring.svc.cluster.local:9090）

apiserver:
  prometheusAddr: http://your-prometheus-query-api.com:9090

controllerManager:
  prometheusAddr: http://your-prometheus-query-api.com:9090

生产或交付环境建议整理成一个 my-overrides.yaml，同时放入 HAMi 和平台 Gateway 配置：

dra:
  enabled: false

scheduler:
  leaderElect: true

gateway:
  enabled: true
  service:
    type: NodePort
    nodePort: 30080
  tls:
    enabled: false

hamiNamespace: hami-system

部署前建议先离线检查 values 合并结果：

zarf package inspect values-files hami-ai-platform-v0.0.2-airgap-amd64.tar.zst \
  --components=tools,hami-deploy-scripts,hami,prometheus-crds,prometheus,gpu-operator,gateway-api-crds,envoy-gateway,hami-ai-platform \
  --values=my-overrides.yaml \
  --features="values=true"

执行部署

全量安装，包含工具、HAMi、Prometheus、GPU Operator、Gateway API CRD、Envoy Gateway 和 AI Platform：

zarf package deploy hami-ai-platform-v0.0.1-airgap-amd64.tar.zst \
  --components=tools,hami-deploy-scripts,hami,prometheus-crds,prometheus,gpu-operator,envoy-gateway,hami-ai-platform \
  --values=my-overrides.yaml \
  --features="values=true" \
  --confirm

如果集群已经部署 HAMi Enterprise，后续只需要加装 Gateway 和 AI Platform：

zarf package deploy hami-ai-platform-v0.0.2-airgap-amd64.tar.zst \
  --components=gateway-api-crds,envoy-gateway,hami-ai-platform \
  --values=my-overrides.yaml \
  --features="values=true" \
  --confirm

如果某个 component 长时间卡住不动，说明安装出现了问题。可以使用 zarf tools helm 对组件进行诊断；如果是 values 错误导致 Helm 渲染或安装失败，先修正 my-overrides.yaml 并重新执行同一条 zarf package deploy ... 命令。

部署中断后，可以处理问题并用相同的 zarf package deploy ... --components=... --values=... 命令继续。镜像 digest 未变化时 Zarf 会跳过重复导入；Helm Charts 或 values 变化时会进行 Helm upgrade。

如果 zarf package deploy 由于 Helm resource ownership 不同导致某些字段冲突而失败，可以尝试添加 --force-conflicts flag 来强制覆盖。

启用 GPU 节点

HAMi device-plugin 仅在带 gpu=on 标签（可以通过）的节点上启动：

kubectl label nodes <node-name> gpu=on

验证：kubectl -n hami-system get pods 应能看到 hami-device-plugin-*、hami-scheduler-* 处于 Running 状态。

监控对接

确保集群里的监控指标系统（kube-prometheus-stack Prometheus，VictoriaMetrics vmagent 等）能采集 HAMi 与 DCGM-Exporter 指标。

如果使用 Prometheus， ServiceMonitor 资源的 metadata.labels 必须与 Prometheus 资源的 spec.serviceMonitorSelector 字段匹配，否则 Prometheus不会采集这些指标。

如果使用 VictoriaMetrics，ServiceMonitor 资源的 metadata.labels必须与 VMServiceScrape 资源的 spec.serviceScrapeSelector 字段匹配，否则 vmagent 不会采集这些指标。

验证指标采集

Exporter	查询指标	预期
dcgm-exporter	DCGM_FI_DEV_GPU_UTIL	返回非空值
hami-exporter	HostCoreUtilization	返回非空值
hami-device-plugin-exporter	GPUDeviceCoreAllocated	返回非空值

除了 exporter 的指标，还需要查询 kantaloupe_gpu_temp 验证 kantaloupe 服务指标是否被正确采集。

证书获取

请完成上述安装任务，确保所有组件的 Pod 都正常启动后再开始激活流程。

1. 使用 平台管理员 账号登录 HAMi AI Platform。
2. 进入 License 与系统信息 页面
3. 按照页面提示获取授权申请信息。
4. 将授权申请信息发送给密瓜智能销售或交付人员。
5. 根据指引完成激活。

激活后验证

# 1. Pod 状态
kubectl -n hami-system get pods

# 2. Device Plugin 注册的 GPU 资源
kubectl describe node <gpu-node> | grep -A 5 'Capacity:'
# 期望看到：nvidia.com/gpu: <N>  以及 nvidia.com/gpumem: <MB>

# 3. 提交一个测试 Pod 验证调度
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: hami-smoke
spec:
  restartPolicy: Never
  containers:
  - name: cuda
    image: nvidia/cuda:12.4.0-base-ubuntu22.04
    command: ["nvidia-smi"]
    resources:
      limits:
        nvidia.com/gpu: 1
        nvidia.com/gpumem: 2000
EOF

kubectl logs hami-smoke

期望：nvidia-smi 输出可见 GPU 信息，且显存被限制为 2000 MiB。

HAMi AI Platform验证

# 1. Pod 状态
kubectl -n kantaloupe-system get pods

# 2. 服务可达
kubectl -n kantaloupe-system get svc

HAMi AI Platform 服务暴露后，打开站点，确认前后端正常工作。

创建工作负载

在控制台 工作负载 页面，创建应用（如 gpu-burn）：

创建完成后，确认以下验证项均通过：

1. 创建成功，控制台无报错
2. 负载列表：应用状态、检索、列表指标与监控面板（GPU SM / GPU MEM / CPU / Memory）正常，时间切换与图表符合预期

1. 应用详情：基础信息、资源总览、与监控数据正常；从详情页跳转 GPU / 节点页面，资源总览与监控数据正常

示例工作负载验证

外层 airgap 包内已经包含两个独立的 Zarf 示例包，不需要再手动 kubectl apply 本地 YAML。

GPU burn 验证

zarf package deploy zarf-package-hami-example-gpu-burn-amd64-v0.0.1.tar.zst --confirm

部署后检查 Deployment / Pod 运行状态：

kubectl -n default get deploy turbo-gpu-burn
kubectl -n default get pods -l app=turbo-gpu-burn
kubectl -n default logs -l app=turbo-gpu-burn --tail=50

该示例会创建 default/turbo-gpu-burnDeployment，请在验证完成后按需清理：

kubectl -n default delete deploy turbo-gpu-burn

vLLM + Qwen 验证

zarf package deploy zarf-package-hami-example-vllm-qwen-amd64-v0.0.2.tar.zst --confirm

部署后检查推理服务状态：

kubectl -n default get deploy vllm-qwen3
kubectl -n default get pods -l app=vllm-qwen3
kubectl -n default get svc vllm-qwen3-webui

待 Pod 就绪后，通过任意节点 IP + NodePort（30081）访问 Open WebUI：

# 获取集群节点 IP（任选一个可访问的节点即可）
kubectl get nodes -o wide

# 浏览器访问
# http://<node-ip>:30081

Open WebUI 已与同 Pod 内的 vLLM sidecar 自动对接，打开页面即可直接体验对话。

如果 Pod 一直 Pending，优先检查证书是否已激活、GPU 节点是否已打 gpu=on 标签，以及节点 GPU 驱动是否正常。

排障

常用检查命令：

kubectl get pods -A | grep -E 'hami|gpu-operator|prometheus|vllm|gpu-burn'
kubectl get events -A --sort-by=.lastTimestamp | tail -50
zarf package list

收集诊断信息：

bash collect-cluster-info.sh

手动查看主包内容：

# 解压主包到临时目录，需预留足够空间
zarf tools archiver decompress hami-ai-platform-v0.0.2-airgap-amd64.tar.zst /tmp/hami-ai-platform-pkg

# 查看包定义
cat /tmp/hami-ai-platform-pkg/zarf.yaml

# 离线查看渲染后的 manifests
zarf package inspect manifests hami-ai-platform-v0.0.2-airgap-amd64.tar.zst \
  --components=hami-ai-platform \
  --values=my-overrides.yaml \
  --features="values=true"

# 离线查看渲染后的 values
zarf package inspect values-files hami-ai-platform-v0.0.2-airgap-amd64.tar.zst \
  --components=hami,hami-ai-platform \
  --values=my-overrides.yaml \
  --features="values=true"

常见问题

现象	可能原因	处理
镜像拉不下来	Node 没有外部网络或者与 ghcr.io 连接不畅。	联系 Dynamia.ai 的售前/技术支持获取国内镜像仓库地址或 All-in-One 离线一体包。
hami-device-plugin Pod Pending 或者不存在	节点未打 gpu=on 标签	kubectl label nodes <node> gpu=on
hami-device-plugin Pod CrashLoopBackOff	与 NVIDIA 默认 device-plugin 冲突	禁用 GPU Operator 的 devicePlugin（--set devicePlugin.enabled=false）。
查不到 HAMi 指标	Prometheus 资源的serviceMonitorSelector 与 ServiceMonitor 资源中的 label 不匹配	对齐 prometheus/prometheus-kube-prometheus-prometheus 的 spec.serviceMonitorSelector 和 hami-enterprise 的 serviceMonitor labels。
nvidia-smi 报错	GPU 驱动未就绪	检查 gpu-operator namespace 下 driver Pod 状态。
示例 workload Pending	证书未激活、GPU 不足或节点标签缺失	检查证书、GPU 节点标签和 kubectl describe pod 事件
Gateway 没有入口地址	Envoy Gateway 未就绪或 Service 类型不适配集群	检查 envoy-gateway-system Service 和 Gateway 状态

使用 Zarf 安装组件带来的限制

不能在同一个 namespace 里混用内外部镜像仓库（在同一集群里使用多个镜像仓库会有障碍）

Zarf 使用 admission webhook 的方式悄悄地替换了掌控 namespace 中所有容器的镜像，将他们替换成私有镜像仓库的版本。一个集群中可以做到部分 namespace 绕开 Zarf，正常访问其他镜像仓库，但不能在同一个 namespace 里再使用不同镜像仓库的镜像。你可以通过给 namespace 打上 zarf.dev/agent=ignore 标签忽略这一特性，使得你在其他 namespace 里可以使用其他镜像仓库而非 zarf init --registry-url ... 里指定的 registry。

不能再使用原生 Helm 管理同一批资源

一旦让 Zarf 接手了一批组件，再试图用另一套 Helm 流程去管理同一批资源，后面很容易遇到 ownership 冲突、升级打架或者状态难以判断的问题。这不是 Zarf 独有的毛病，是交付边界没划清时几乎必然会出现的结果。用 Zarf 可以很方便地拉起一套组件，但可不能想着装完以后就把 Zarf 一脚踢开，再用回 Helm 做日常迭代。因此，如无必要，请依赖密瓜智能团队做定期版本升级，不要自行迭代HAMi Enterprise。

很难灵活迭代

Zarf 的设计决定了每次我都在传输全量软件栈。这就注定和“灵活”不沾边。

获取支持

• 邮箱：info@dynamia.ai
• 售前 / 技术支持：400-026-7800
• 已签订商业合同的客户请通过专属支持渠道提交 Issue