AI Platform

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.3-airgap-amd64.tar.gz 中包含以下关键文件：

文件	用途
`zarf-linux-amd64`	Linux amd64 Zarf CLI
`zarf-init-amd64-v0.82.0.tar.zst`	Zarf init 离线包
`hami-ai-platform-v0.0.3-airgap-amd64.tar.zst`	HAMi AI Platform 主部署包
`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 示例验证包
`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.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-ai-platform-v0.0.3-airgap-amd64.tar.gz.sha256

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

# 进入解压目录
cd hami-ai-platform-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 AI Platform

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

组件清单如下：

组件名称	说明	必须安装	推荐安装
`tools`	运维工具集：jq、nerdctl 等	否	按需
`hami-deploy-scripts`	HAMi 部署脚本与预检脚本	是	是
`hami`	hami-enterprise Helm Chart	否	是
`prometheus-crds`	Prometheus Operator CRD	否	是
`prometheus`	kube-prometheus-stack Helm Chart	否	按需
`gpu-operator`	NVIDIA GPU Operator	否	按需
`envoy-gateway-crds`	Gateway API 与 Envoy Gateway CRD	否	启用平台 Gateway 时安装
`envoy-gateway`	Envoy Gateway	否	启用平台 Gateway 时安装
`hami-ai-platform`	HAMi AI Platform（Kantaloupe）	否	是

envoy-gateway-crds 使用 Envoy Gateway v1.6.2 官方 CRD Chart 的固定渲染结果，在 Helm release 之外通过 Server-Side Apply 管理 12 个 Gateway API v1.4.1 Experimental CRD 和 8 个 Envoy Gateway CRD，避免大型 CRD 导致 Helm release Secret 超过 Kubernetes 1 MiB 上限。若目标集群已经安装 Gateway API，则不会覆盖现有版本，但会检查所需的 12 个 CRD 是否齐全；Envoy Gateway CRD 会幂等更新并等待 Established。envoy-gateway 使用已移除 crds/ 的官方主 Chart 副本，避免重复安装或降级 CRD。

平台版部署需要使用自定义 values 文件覆盖集群、调度、服务暴露和监控配置。Zarf v0.82.0 可直接使用 --values，不再需要 --features="values=true"；少量字段也可用 --set-values key.path=value 覆盖。合并顺序为：Chart 默认值 → 包内 values/*.yaml → --values → --set-values。离线包中的 prometheus、gpu-operator 已带有包内 values，通常无需重复配置；Kantaloupe 应按实际入口、认证和监控环境准备自定义 values。

准备 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: {}

替换 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
  listeners:
    - name: http
      port: 80
      protocol: HTTP
  envoy:
    service:
      type: NodePort
      ports:
        http:
          nodePort: 30080

hamiNamespace: hami-system

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

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

执行部署

昇腾卡集群： 如果目标集群使用昇腾卡，请在部署命令的 --components 中紧跟 hami 添加 ascend-device-plugin。该组件使用包内默认 values，无需在 my-overrides.yaml 中添加配置。

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

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

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

zarf package deploy hami-ai-platform-v0.0.3-airgap-amd64.tar.zst \
  --components=envoy-gateway-crds,envoy-gateway,hami-ai-platform \
  --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`	返回非空值

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

证书获取

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

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

激活后验证

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 状态，并确认受管节点已注册加速卡资源。

HAMi AI Platform验证

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

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

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

创建工作负载

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

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

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

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

示例工作负载验证

外层 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-ai-platform-v0.0.3-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.3-airgap-amd64.tar.zst \
  --components=hami-ai-platform \
  --values=my-overrides.yaml

# 离线查看渲染后的 values
zarf package inspect values-files hami-ai-platform-v0.0.3-airgap-amd64.tar.zst \
  --components=hami,hami-ai-platform \
  --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` 事件。
`Gateway` 没有入口地址	Gateway API 或 Envoy Gateway CRD 未就绪、Envoy Gateway release 异常，或 Envoy Service 类型不适配集群	检查 20 个相关 CRD 的 `Established` 状态，运行 `zarf tools helm status eg -n envoy-gateway-system`，并检查 `Gateway` 条件和 Envoy `Service`。不要通过卸载 CRD release 或删除 CRD 重试。

使用 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 字段冲突，不应作为常规安装参数。

获取支持

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

离线包内容​

前置条件清单​

解压、校验和安装 Zarf​

初始化 Zarf​

部署 HAMi AI Platform​

准备 custom values​

hami-enterprise values​

kantaloupe values​

执行部署​

启用 GPU 节点​

监控对接​

验证指标采集​

证书获取​

激活后验证​

HAMi AI Platform验证​

创建工作负载​

示例工作负载验证​

GPU burn 验证​

vLLM + Qwen 验证​

排障​

常见问题​

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

镜像改写范围应通过标签明确控制​

同一批资源应由单一交付链管理​

获取支持​