HAMi 企业版离线部署手册

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

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

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

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

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

离线包内容

外层交付包命名格式为：

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

当前 hami-enterprise-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-enterprise-v0.0.2-airgap-amd64.tar.zst	HAMi Enterprise 主部署包
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 示例验证包
collect-hami-license-info.sh	证书申请信息收集脚本
collect-cluster-info.sh	集群诊断信息收集脚本
hami/README.md	hami-enterprise 完整 values 说明文档

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

tar -tvf hami-enterprise-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-enterprise-v0.0.2-airgap-amd64.tar.gz.sha256

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

# 进入解压目录
cd hami-enterprise-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 Enterprise

HAMi Enterprise 主包中的所有组件都设置为可选组件，按部署场景选择 --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	否	按需

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

准备 custom 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 镜像。

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

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

执行部署

最小安装，仅部署 HAMi Enterprise 核心组件：

zarf package deploy hami-enterprise-v0.0.2-airgap-amd64.tar.zst \
  --components=hami-deploy-scripts,hami \
  --values=my-overrides.yaml \
  --features="values=true" \
  --confirm

全量安装，包含工具、HAMi、PrometheusCRD、Prometheus 和 GPU Operator：

zarf package deploy hami-enterprise-v0.0.2-airgap-amd64.tar.zst \
  --components=hami-deploy-scripts,tools,prometheus-crds,prometheus,gpu-operator,hami \
  --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	返回非空值

证书获取

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

执行以下脚本收集许可证信息（需要 kubectl、jq）：

# 在线获取脚本
curl -fsSL https://public.hami.run/collect-hami-license-info.sh | bash

# 离线安装（包内已包含）
bash collect-hami-license-info.sh

执行后可以看到以下 JSON 内容：

{
  "esn": "96565d61-986a-4918-aafb-448ff6e3746b",
  "deviceInstances": [
    {
      "uuid": "GPU-ceee905d-48ac-93de-a81b-17c00e1e5e02",
      "deviceType": "NVIDIA A10"
    }
  ]
}

把上述 JSON 发送给 Dynamia.ai 的售前/技术支持获取证书。

激活后验证

# 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。

示例工作负载验证

外层 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-enterprise-v0.0.2-airgap-amd64.tar.zst /tmp/hami-enterprise-pkg

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

# 离线查看渲染后的 manifests
zarf package inspect manifests hami-enterprise-v0.0.2-airgap-amd64.tar.zst --components=hami

# 离线查看渲染后的 values
zarf package inspect values-files hami-enterprise-v0.0.2-airgap-amd64.tar.zst \
  --components=hami \
  --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 事件

使用 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