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.3-airgap-amd64.tar.gz 中包含以下关键文件：
| 文件 | 用途 |
|---|---|
zarf-linux-amd64 | Linux amd64 Zarf CLI |
zarf-init-amd64-v0.82.0.tar.zst | Zarf init 离线包 |
hami-enterprise-v0.0.3-airgap-amd64.tar.zst | HAMi Enterprise 主部署包 |
zarf-package-hami-example-gpu-burn-amd64-v0.0.2.tar.zst | GPU burn 示例验证包 |
zarf-package-hami-example-vllm-qwen-amd64-v0.0.4.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.3-airgap-amd64.tar.gz
前置条件清单
| 类型 | 要求 | 验证命令 |
|---|---|---|
| Kubernetes | ≥ 1.24 | kubectl version --short |
| 容器运行时 | containerd、CRI-O 等 Kubernetes CRI 运行时；GPU 节点已配置 NVIDIA Container Toolkit | kubectl get nodes -o wide |
| GPU 驱动 | NVIDIA driver ≥ 470（推荐 ≥ 550） | nvidia-smi |
| Prometheus CRD | 启用 Prometheus 或 VictoriaMetrics 监控对接时，需要 monitoring.coreos.com CRD；选择 prometheus-crds 组件可由离线包安装 | kubectl api-resources --api-group=monitoring.coreos.com |
| GPU Operator | 如已安装，必须设置 devicePlugin.enabled=false；离线包内 GPU Operator 已预置该值，推荐版本为 v25.10.1 | helm list -A | grep gpu-operator |
| 存储空间 | 建议大于 30 GB | df -h |
关键约束：HAMi 自带 device-plugin，与 NVIDIA GPU Operator 内置 device-plugin 冲突。选择离线包内 gpu-operator 组件时已通过包内 values 禁用；使用集群中已有 GPU Operator 时，必须确认 devicePlugin.enabled=false。
解压、校验和安装 Zarf
# 下载交付包和校验文件
curl -L -O <URL>
curl -L -O <SHA256_URL>
# 校验完整性
shasum -a 256 -c hami-enterprise-v0.0.3-airgap-amd64.tar.gz.sha256
# 解压外层 tar.gz
tar -xzf hami-enterprise-v0.0.3-airgap-amd64.tar.gz
# 进入解压目录
cd hami-enterprise-v0.0.3-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。建议使用 labeled 策略，仅改写显式标记的 Namespace 或工作负载镜像。
使用 Zarf 内置 registry：
zarf init zarf-init-amd64-v0.82.0.tar.zst \
--agent-mutation-policy=labeled \
--confirm
使用外部 registry：
zarf init zarf-init-amd64-v0.82.0.tar.zst \
--agent-mutation-policy=labeled \
--registry-url=harbor.example.com/zarf-amd64 \
--registry-push-username=<username> \
--registry-push-password=<password> \
--confirm
💡 多架构集群必须使用不同的 registry 前缀。 AMD64 和 ARM64 集群可以共用同一个 Harbor 实例，但不得共用同一个 Zarf registry Project 或仓库前缀。Zarf 离线包中的镜像已按目标架构打包。将 AMD64 与 ARM64 包依次部署到同一路径时，同名 tag 不会自动合并为多架构 manifest；后一次推送可能覆盖前一次推送的 tag，导致另一架构的 Pod 在重建或重新调度后拉取到不兼容的镜像。
初始化集群时，请为每种架构指定独立的
--registry-url，例如 AMD64 使用registry.example.com/zarf-amd64，ARM64 使用registry.example.com/zarf-arm64。请提前创建对应的 Harbor Project 或仓库前缀，并确保 Zarf 使用的账号具备推送和拉取权限。
外部 registry 参数说明：
| 参数 | 说明 |
|---|---|
--registry-url | 外部镜像仓库地址 |
--registry-push-username | 用于推送镜像的用户名 |
--registry-push-password | 用于推送镜像的密码 |
初始化完成后，zarf package deploy 会导入包内镜像，并通过 admission webhook 将受管工作负载的镜像地址改写到 Zarf registry。使用 labeled 策略时，只处理带 zarf.dev/agent: mutate 标签的资源，或位于带该标签 Namespace 中的资源；资源自身的标签优先于 Namespace 标签。HAMi 主包会为其管理的 Namespace 设置该标签 ，自行创建的离线工作负载也应先确认 Namespace 已标记。标签变更不会影响已经创建的 Pod，需要重新创建 Pod 才会再次触发改写。
仅当目标 registry 的 TLS 证书确实无法校验、且已经评估中间人攻击风险时，才在对应命令中临时使用 --insecure-skip-tls-verify。生产环境应优先修复证书链或为 Zarf Agent 配置可信 CA，不应把跳过 TLS 校验作为默认参数。
部署 HAMi Enterprise
HAMi Enterprise 主包中的所有组件都设置为可选组件，按部署场景选择 --components。组件顺序请保持文档中的顺序。
组件清单如下：
| 组件名称 | 说明 | 必须安装 | 推荐安装 |
|---|---|---|---|
tools | 运维工具集：jq、nerdctl 等 | 否 | 按需 |
hami-deploy-scripts | HAMi 部署脚本与预检脚本 | 是 | 是 |
hami | hami-enterprise Helm Chart | 否 | 是 |
prometheus-crds | Prometheus Operator CRD，使用 Server-Side Apply 安装 | 否 | 启用监控时安装 |
prometheus | kube-prometheus-stack Helm Chart | 否 | 按需 |
gpu-operator | NVIDIA GPU Operator，包内 values 已禁用内置 device-plugin | 否 | 按需 |
企业版部署需要使用自定义 values 文件覆盖集群、调度和监控配置。Zarf v0.82.0 可直接使用 --values，不再需要 --features="values=true"；少量字段也可用 --set-values key.path=value 覆盖。合并顺序为：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.3-airgap-amd64.tar.zst \
--components=tools,hami-deploy-scripts,hami,prometheus-crds,prometheus,gpu-operator \
--values=my-overrides.yaml
执行部署
昇腾卡集群： 如果目标集群使用昇腾卡，请在部署命令的 --components 中紧跟 hami 添加 ascend-device-plugin。该组件使用包内默认 values，无需在 my-overrides.yaml 中添加配置。
最小安装，仅部署 HAMi Enterprise 核心组件：
zarf package deploy hami-enterprise-v0.0.3-airgap-amd64.tar.zst \
--components=hami-deploy-scripts,hami \
--values=my-overrides.yaml \
--confirm
全量安装，包含工具、HAMi、PrometheusCRD、Prometheus 和 GPU Operator：
zarf package deploy hami-enterprise-v0.0.3-airgap-amd64.tar.zst \
--components=tools,hami-deploy-scripts,hami,prometheus-crds,prometheus,gpu-operator \
--values=my-overrides.yaml \
--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。
如果目标资源已经由其他 Helm release 管理，且确认要交由当前 Zarf 包接管，可在核对资源范围后使用 --take-ownership。--force-conflicts 只用于 Server-Side Apply 字段所有权冲突；它会覆盖其他 field manager 管理的字段，仅在确认冲突字段可以由本次部署接管时使用，不能作为通用重试参数。
启用 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 的售前/技术支持获取证书。
激活后验证
kubectl -n hami-system get pods
kubectl describe node <gpu-node>
kubectl get events --field-selector involvedObject.name=hami-license -n hami-system
kubectl get nodes -o custom-columns='NODE:.metadata.name,LICENSE:.metadata.annotations.hami\.io/nvidia-license'
事件中出现 LicenseValid 表示许可证校验通过。确认已选择组件的 Pod 处于 Running 或 Completed 状态，并确认受管节点已注册加速卡资源。
示例工作负载验证
外层 airgap 包内已经包含两个独立的 Zarf 示例包，不需要再手动 kubectl apply 本地 YAML。
GPU burn 验证
zarf package deploy zarf-package-hami-example-gpu-burn-amd64-v0.0.2.tar.zst --confirm
部署后检查 Deployment / Pod 运行状态：
kubectl -n hami-example get deploy turbo-gpu-burn
kubectl -n hami-example get pods -l app=turbo-gpu-burn
kubectl -n hami-example logs -l app=turbo-gpu-burn --tail=50
该示例会创建 hami-example/turbo-gpu-burn Deployment，请在验证完成后按需清理：
kubectl -n hami-example delete deploy turbo-gpu-burn
vLLM + Qwen 验证
zarf package deploy zarf-package-hami-example-vllm-qwen-amd64-v0.0.4.tar.zst --confirm
部署后检查推理服务状态：
kubectl -n hami-example get deploy vllm-qwen3
kubectl -n hami-example get pods -l app=vllm-qwen3
kubectl -n hami-example 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.3-airgap-amd64.tar.zst /tmp/hami-enterprise-pkg
# 查看包定义
cat /tmp/hami-enterprise-pkg/zarf.yaml
# 离线查看渲染后的 manifests
zarf package inspect manifests hami-enterprise-v0.0.3-airgap-amd64.tar.zst --components=hami
# 离线查看渲染后的 values
zarf package inspect values-files hami-enterprise-v0.0.3-airgap-amd64.tar.zst \
--components=hami \
--values=my-overrides.yaml
常见问题
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 镜像拉取失败 | Namespace 或工作负载未标记 zarf.dev/agent: mutate、Pod 在添加标签前已经创建，或镜像未包含在 Zarf package 中 | 检查 Namespace 或工作负载标签、Zarf Agent webhook 和日志，以及 Pod 的实际镜像地址。确认镜像已包含在 package 中。修正标签后重新创建 Pod。 |
hami-device-plugin Pod 为 Pending 或不存在 | 节点未添加 gpu=on 标签 | 运行 kubectl label nodes <node> gpu=on。 |
hami-device-plugin Pod 反复重启 | 与 NVIDIA GPU Operator 的默认 device-plugin 冲突 | 确认 GPU Operator 已设置 devicePlugin.enabled=false。 |
| 无法查询 HAMi 指标 | Prometheus 或 VictoriaMetrics 的 selector 与监控对象标签不匹配 | 检查监控组件的 selector，并确认其与 HAMi ServiceMonitor 的标签一致。 |
nvidia-smi 报错 | GPU 驱动未就绪 | 检查 gpu-operator Namespace 中的 driver Pod 状态。 |
示例工作负载一直为 Pending | 许可证未激活、GPU 资源不足或节点标签缺失 | 检查许可证状态、GPU 节点标签、可用 GPU 资源和 kubectl describe pod 事件。 |
使用 Zarf 安装组件带来的限制
镜像改写范围应通过标签明确控制
建议在初始化时使用 zarf init --agent-mutation-policy=labeled。此策略只改写带 zarf.dev/agent: mutate 标签的资源，或位于带该标签 Namespace 中的资源；需要保留原镜像地址的单个工作负载可标记 zarf.dev/agent: ignore，且资源标签优先于 Namespace 标签。因此，同一集群甚至同一 Namespace 中可以按资源划分是否由 Zarf 改写，不再需要让 Agent 默认接管全部业务 Namespace。需要注意：只有已经打入 Zarf package 的镜像才能在离线环境中被改写并拉取；修改标签后还需重新创建 Pod，已创建 Pod 不会自动变化。
同一批资源应由单一交付链管理
Zarf 通过 Helm 管理 package 中的 Chart release。对同一批 Kubernetes 资源再并行使用另一套原生 Helm 流程，仍可能产生 release ownership、字段所有权和升级顺序冲突。日常升级应继续使用新的 Zarf package；若确需把已有资源交给 Zarf 管理，应先核对 release 和资源范围，再使用 --take-ownership。--force-conflicts 仅用于确认可以覆盖的 Server-Side Apply 字段冲突，不应作为常规安装参数。
获取支持
-
售前 / 技术支持：400-026-7800
-
已签订商业合同的客户请通过专属支持渠道提交 Issue