minikube 鸿蒙 PC 适配全记录：从 Go CLI 到 HNP 应用内远程集群管理

鸽芷咕

11057人浏览 · 2026-09-13 19:53:22

鸽芷咕 · 2026-09-13 19:53:22 发布

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_minikube

一、为什么要适配 minikube

Kubernetes 已经成为云原生开发、测试和交付中的基础设施，但开发者在桌面环境里真正需要的往往不是一套完整生产集群，而是一个可以快速创建、停止和恢复的轻量环境。minikube 将集群初始化、版本选择、运行时配置、Profile 管理和常用插件封装进一个命令行工具，因此长期被用于 Kubernetes 入门、应用联调、CI 复现和单节点集群验证。

HarmonyOS PC 要承载完整的开发者工作流，除了编辑器、终端和语言运行时，也需要能够管理容器与云原生环境的工具。适配 minikube 的价值不只在于“让一个 Go 程序能够启动”，还在于验证以下几条链路能否同时成立：

Go CLI 能否面向 OpenHarmony ARM64 交叉编译并以 HNP 形式交付；
ArkTS 页面能否在应用安全域内稳定启动长时间运行的原生命令；
SSH 私钥、Profile 和 kubeconfig 能否存放在应用私有目录；
HarmonyOS PC 能否通过 SSH 对 Linux 节点完成 Kubernetes 的启动、状态查询、日志读取、停止和恢复；
上游 minikube 对本机虚拟化、资源检测和网络地址的默认假设，能否在远程节点模型下得到正确处理。

这次适配没有尝试在 HarmonyOS PC 本机强行复刻 Docker、Podman、KVM、QEMU 或 VirtualBox。当前平台尚未提供一套能够被上游 minikube 直接复用的本地容器和虚拟化驱动，相关能力还涉及设备节点、守护进程、特权网络与系统安全策略。最终选择的是 minikube 上游已经具备的 SSH Driver：HarmonyOS PC 作为控制端，Kubernetes、kubelet 和 containerd 运行在一台 SSH 可达的 Linux 主机上。

当前交付基于 minikube v1.37.0，HNP 修订版本为 1.37.5。应用 BundleName 为 org.kubernetes.minikube.ohos，目标设备类型为 2in1，Native ABI 为 arm64-v8a。集群侧真机联调使用 Kubernetes v1.33.1、Ubuntu 24.04 ARM64 和 containerd 2.2.1。

二、先明确适配边界：鸿蒙 PC 是控制端，不是 Kubernetes 节点

上游 minikube 最常见的使用方式，是在当前电脑上启动虚拟机或容器，再把它配置成 Kubernetes 节点。这种模型默认“运行 minikube 的机器”和“承载 Kubernetes 的机器”是同一台设备，因此启动流程会读取本机 CPU、内存、网络接口、虚拟化驱动和容器运行时。

SSH Driver 则改变了这个前提。HarmonyOS PC 负责保存配置和发起管理命令，Linux 节点负责真正的计算、存储、容器和系统服务。两端职责如下：

层次	解决的问题	当前实现
应用界面层	节点配置、SSH 私钥导入、操作入口和结果展示	HarmonyOS Stage 模型、ArkTS 与 ArkUI
原生桥接层	从应用安全域启动 CLI、异步收集输出	C++17、N-API、`fork/exec` 与管道
命令交付层	随 HAP 安装 OpenHarmony ARM64 minikube	公共 HNP `minikube.hnp`
集群管理层	创建 Profile、执行 start/status/stop、读取日志	minikube v1.37.0 与 SSH Driver
远程运行层	kubelet、API Server、containerd 和系统 Pod	SSH 可达的 Linux 节点

一次完整操作的调用路径如下：

HarmonyOS PC ArkUI 页面
  └── libminikube_runner.so
        ├── 设置应用私有 HOME / MINIKUBE_HOME
        ├── 设置 SSH 与 API 实际拨号地址
        └── fork/exec HNP 中的 minikube
              └── SSH Driver
                    └── Linux 节点
                          ├── kubelet
                          ├── containerd
                          ├── kube-apiserver
                          └── kube-system Pods

这一定义决定了当前适配的能力边界。远程集群的创建、查询、日志、停止和重新启动属于已验证能力；HarmonyOS PC 本地 Docker/Podman 驱动、本地虚拟机、本地目录挂载、特权路由和 GPU 直通不在本次范围内。

三、鸿蒙版本的工程结构与技术路线

仓库根目录继续保留 minikube 上游 Go 源码。所有 HarmonyOS 适配代码、脚本、补丁和验收材料集中在 ohos-migration/ 中，避免把平台产物散落到上游目录：

ohos_minikube/
├── cmd/、pkg/、deploy/                  # minikube 上游 Go 源码
├── go.mod / go.sum                     # 上游 Go 依赖
├── README.OpenHarmony_CN.md            # HarmonyOS 适配说明
└── ohos-migration/
    ├── scripts/
    │   ├── build-minikube-hnp.sh       # 交叉编译并打包 HNP
    │   ├── build-hap.sh                # 构建 ArkTS 页面和 Native runner
    │   ├── device-app-smoke.sh         # 真机界面冒烟检查
    │   └── device-import-test-key.sh   # 联调私钥导入脚本
    ├── patches/                        # SSH 与 API 远程模型兼容补丁
    ├── hnp/minikube/
    │   ├── hnp.json                    # HNP 元数据
    │   └── bin/minikube                # OpenHarmony ARM64 CLI
    ├── ohos/                           # DevEco Studio / Hvigor 工程
    │   ├── AppScope/
    │   ├── hnp/arm64-v8a/minikube.hnp
    │   └── entry/src/main/
    │       ├── ets/pages/Index.ets     # 远程集群管理页面
    │       ├── ets/entryability/       # Stage 模型入口
    │       └── cpp/                    # N-API Native runner
    ├── reports/                        # 构建、签名和设备验证记录
    └── artifacts/                      # HNP、HAP 与真机证据

1. Go CLI 交叉编译

核心程序仍然是上游 minikube，而不是重新实现的一套集群管理逻辑。构建使用 OpenHarmony 官方 Go 1.24 工具链，目标参数为：

GOOS=openharmony
GOARCH=arm64
CGO_ENABLED=0

最终生成静态 AArch64 ELF。构建脚本会检查目标架构，并通过 go version -m 确认产物中的 GOOS=openharmony，避免把普通 Linux ARM64 文件误当成 HarmonyOS 原生程序。

2. HNP 与 HAP 组合交付

交叉编译后的 minikube 使用 SDK 中的 hnpcli 打成公共 HNP，再注入 HarmonyOS HAP。最终安装包同时包含：

hnp/arm64-v8a/minikube.hnp
libs/arm64-v8a/libminikube_runner.so

HNP 负责原生命令的版本化分发，HAP 负责桌面入口、SSH 参数、私钥选择和操作结果展示。两者组合后，用户不需要手工把二进制复制到系统目录。

3. ArkTS 与 Native runner

页面使用 ArkTS/ArkUI 编写，通过 N-API 调用 libminikube_runner.so。Native runner 在后台工作线程中启动 minikube，将 stdout 和 stderr 合并到管道，命令结束后再把退出码和文本结果返回页面。这样 minikube start 和 minikube stop 不会阻塞 UI 线程。

runner 会把 HOME 与 MINIKUBE_HOME 指向应用私有 files 目录。SSH 私钥同样通过系统文档选择器导入到该目录，Profile、证书、kubeconfig 和日志不会写入公共 Downloads。

四、真机上的五项核心功能验证

以下五张截图均在 2026 年 8 月 20 日重新执行完整操作后，由 snapshot_display 直接从 HarmonyOS PC 当前画面取得，分辨率为 3120×2080。验证设备为 HUAWEI MateBook Pro（HAD-W32），系统版本为 6.1.0.117。测试集群位于 Ubuntu 24.04 ARM64 节点，运行 Kubernetes v1.33.1 与 containerd 2.2.1。

本次设备与 Linux 虚拟机之间使用 USB 联调通道，因此截图中的 SSH 端口为 2223；在局域网或云主机场景中，可以直接填写 Linux 主机的实际地址和 SSH 端口，不需要这层端口映射。

1. 通过 SSH 启动远程 Kubernetes 集群

应用已经导入 SSH 私钥，填写 Linux 节点、用户、端口和 Profile 后点击“启动集群”。页面在命令完成后显示 启动集群 · 完成（退出码 0），结果中可以看到 minikube v1.37.0、应用私有 MINIKUBE_HOME 和 SSH Driver 启动信息。

在这里插入图片描述

启动结束后，Linux 节点上的 kubelet 为 active，containerd 中有 8 个运行容器，https://127.0.0.1:8443/healthz 返回 ok。这三个结果由 Linux 节点独立检查，不只依赖应用页面的退出码。

2. 查询 Host、Kubelet 与 API Server 状态

点击“查询状态”后，应用执行 minikube status -p ohos-device-e2e --output=json，页面返回 Host、Kubelet、APIServer 均为 Running，Kubeconfig 为 Configured。

在这里插入图片描述

状态查询使用保存于应用私有目录的同一个 Profile。节点身份仍保持 192.168.2.7，测试链路中的回环拨号地址不会覆盖 Kubernetes 证书、节点 Internal IP 或 kubeconfig 中的真实地址。

3. 在应用内读取最近一次启动日志

点击“查看日志”后，Native runner 读取 .minikube/logs/lastStart.txt。页面只展示最后 15500 个字符，以免上游完整启动日志过大而造成桌面窗口卡顿。

在这里插入图片描述

日志中包含插件启用、Pod Ready 等真实启动过程。日志读取与集群命令共用应用私有 MINIKUBE_HOME，不需要把内部文件暴露到公共存储。

4. 停止集群并释放远程容器

点击“停止集群”后，页面返回 停止集群 · 完成（退出码 0），并显示目标节点已停止。

在这里插入图片描述

停止结果随后在 Linux 节点上独立复核：kubelet 变为 inactive，运行中的 CRI 容器从 8 个降为 0，API 健康检查不可访问。SSH 主机本身仍保持在线，这符合 SSH Driver 的语义——停止的是 Kubernetes，而不是关闭用户提供的 Linux 主机。

5. 使用原 Profile 重新启动集群

停止完成后再次点击“启动集群”。应用复用已有 Profile、SSH 私钥、Kubernetes 版本和 containerd 配置，重新完成控制平面恢复，页面再次返回退出码 0。

在这里插入图片描述

重新启动后，Linux 节点恢复为 kubelet active、8 个运行容器、API health ok。这一步比单次 start 更重要，因为它覆盖了 Profile 反序列化、容器运行时恢复和 stop/start 生命周期的连续性。

五、适配过程中最棘手的几个问题

难点一：HarmonyOS PC 缺少上游可直接复用的本地驱动

minikube 的 Docker、Podman、KVM、QEMU 和 VirtualBox 驱动都依赖具体平台运行时。即使 Go 主程序能够编译，驱动所需的守护进程、设备文件、虚拟网络、镜像存储和特权操作也不会随之自动出现。

当前方案没有用一个空壳界面掩盖这些依赖，而是将产品范围收敛到 SSH Driver。这样保留了真实的 minikube Profile 与 Kubernetes 生命周期管理能力，同时把 Linux 节点作为明确的环境前提。代价是当前版本不能在 HarmonyOS PC 本机离线创建容器或虚拟机节点。

难点二：应用安全域与 `hnp_native` 安全域权限不同

公共 HNP 从 hdc shell 直接启动时会进入受限的 hnp_native SELinux 域。真机测试表明，该安全域缺少 minikube SSH Driver 所需的普通文件写入和网络权限，CLI 会在建立完整运行环境前失败。

项目最终采用应用内 fork/exec：ArkTS 页面调用 N-API 动态库，由 Native runner 在应用安全域内启动 HNP 程序。这样既保留 HNP 分发方式，也能使用应用被授予的网络权限和私有目录。当前版本因此定位为“应用内运行的 HNP 命令”，不把系统终端全局执行列为已支持能力。

难点三：节点身份地址与实际拨号地址不能混为一谈

USB 联调时，应用实际连接的是设备回环地址和 HDC 反向端口；但 Kubernetes 证书、节点 Internal IP、API Server 地址和 Profile 必须保存 Linux 节点的真实地址。如果直接把 Profile 中的节点 IP 改成 127.0.0.1，SSH 可能暂时可用，TLS 与节点身份却会出现错误。

适配补丁增加 MINIKUBE_SSH_DIAL_ADDRESS 与 MINIKUBE_API_DIAL_ADDRESS。它们只改变 TCP 实际拨号目标，不改变 Profile 中的节点身份和 TLS ServerName。正式局域网环境不需要端口转发时，两者可以直接使用同一个可达地址。

难点四：上游本机资源判断不适用于 SSH 节点

上游启动流程会根据运行 minikube 的本机 CPU 和内存限制节点配置。在当前架构中，HarmonyOS PC 只是控制端，真正提供资源的是远程 Linux。继续使用本机判断会把控制端资源错误套用到远程节点，甚至在 Linux 资源充足时提前拒绝启动。

SSH 兼容补丁跳过不适用的本地主机限制，并从远程主机读取内存信息。这个修改只作用于 SSH Driver，不改变其他上游驱动的资源语义。

难点五：`stop` 返回成功，不代表 Kubernetes 一定已经停止

早期联调中出现过一次隐蔽问题：minikube stop 返回退出码 0，但 kubelet 和 containerd 容器仍在运行。原因是上游 machine wrapper 会把“SSH 主机仍然可连接”解释为机器仍处于 Running，并且从 Profile 恢复 SSH Driver 时，容器运行时可能回落为 Docker。

当前补丁让 SSH Profile 直接执行 Kubernetes stop，并通过 MINIKUBE_SSH_CONTAINER_RUNTIME=containerd 恢复真实运行时，只停止处于 Running 状态的容器。验收不再只看 CLI 输出，而是同时检查 kubelet、CRI 容器数量和 API 健康端点。

难点六：长时间命令、输出量和应用生命周期需要同时处理

集群启动通常持续几十秒到数分钟。如果 ArkTS 页面同步等待 Native 函数，窗口会失去响应；如果无限保存 stdout/stderr，又可能因日志过大占用内存。

Native runner 使用 napi_async_work 把命令放到后台线程执行，通过管道收集输出，完成后再解析 Promise。页面在运行期间禁用相关按钮，日志视图只保留有限尾部。这样既避免重复启动，也让状态查询、日志和停止操作保持一致的结果模型。

六、构建、签名、安装与运行

本项目不是 Electron 或 Qt 工程，鸿蒙界面使用 ArkTS/ArkUI，核心 CLI 使用 Go，原生桥接层使用 C++17。开发机需要安装 DevEco Studio、HarmonyOS/OpenHarmony SDK，并准备以下工具：

工具	用途
OpenHarmony Go 1.24.5	编译 `openharmony/arm64` minikube
`hnpcli`	生成 `minikube.hnp`
Hvigor / ohpm	构建 ArkTS 与 HAP
OpenHarmony Native SDK / CMake	编译 N-API runner
HAP 签名工具	使用与 BundleName、设备 UDID 匹配的 Profile 签名
HDC	安装、启动与真机调试

1. 准备 OpenHarmony Go 工具链

cd ohos-migration
git clone --branch release-branch.go1.24 \
  https://atomgit.com/openharmony-sig/ohos_golang_go.git \
  .tools/ohos-go-src

cd .tools/ohos-go-src/src
GOROOT_BOOTSTRAP=<本机 Go 根目录> ./make.bash

构建后检查目标列表：

../bin/go tool dist list | grep openharmony/arm64

2. 构建 minikube HNP

cd ohos-migration
./scripts/build-minikube-hnp.sh

脚本会提取上游 v1.37.0 源码、应用 SSH/API 兼容补丁、交叉编译 CLI、检查 ELF 架构，再调用 hnpcli 生成：

ohos-migration/artifacts/minikube.hnp
ohos-migration/ohos/hnp/arm64-v8a/minikube.hnp

3. 构建 HAP

./scripts/build-hap.sh

未签名产物为：

ohos-migration/artifacts/hap/entry-default-unsigned-hnp.hap

签名前应检查 HAP 内同时存在 HNP 与 Native runner。签名材料必须与 org.kubernetes.minikube.ohos 和目标 PC 的 UDID 匹配，且不应提交到公开仓库。

4. 安装并启动

hdc list targets
hdc install -r ohos-migration/artifacts/hap/minikube-ohos-signed.hap
hdc shell aa start \
  -b org.kubernetes.minikube.ohos \
  -m entry \
  -a EntryAbility

首次使用时，在页面中填写 Linux 地址、SSH 用户、端口和 Profile 名称，通过系统文件选择器导入 SSH 私钥，然后执行启动。远程 Linux 节点需要提前具备 SSH、systemd、containerd，以及与目标 Kubernetes 版本匹配的基础资产。

七、当前已经覆盖的能力与限制

当前版本已经在 HarmonyOS PC 真机上跑通：

OpenHarmony ARM64 minikube v1.37.0 交叉编译与 ELF 校验；
HNP 打包、HAP 注入、授权签名、覆盖安装和 Ability 启动；
ArkTS 页面调用 N-API Native runner；
SSH 私钥导入并保存到应用私有目录；
使用 SSH Driver 启动远程 Kubernetes v1.33.1；
containerd 2.2.1 运行时识别；
Host、Kubelet、API Server 与 Kubeconfig 状态查询；
最近一次启动日志的有界读取；
停止 kubelet 和当前 Profile 的运行容器；
停止后使用原 Profile 重新启动；
默认 StorageClass 与 storage-provisioner 插件；
应用私有 Profile、证书和 kubeconfig 持久化。

当前没有作为完整能力承诺的部分包括：

HarmonyOS PC 本地 Docker 或 Podman 驱动；
KVM、QEMU、VirtualBox 等本地虚拟化驱动；
本地 host mount、特权路由与 minikube tunnel；
GPU 直通和本地设备映射；
从系统终端直接运行公共 HNP；
minikube dashboard 与 minikube service 的浏览器自动拉起体验；
任意网络环境下在线下载 Kubernetes 镜像、CNI 和辅助程序；
多 Profile 的图形化列表、切换和批量管理。

因此，当前成果更准确的定位是“HarmonyOS PC 上的远程单节点 Kubernetes 管理工具”。它保留 minikube 的核心 CLI 和 Profile 语义，但计算与容器运行仍由用户提供的 Linux 节点承担。

八、总结

minikube 的鸿蒙 PC 适配不是简单地把 Go 二进制换成 ARM64，也不是给命令行工具套一层启动页面。真正需要解决的是本地驱动缺失后的产品边界、OpenHarmony Go 目标、HNP 与应用安全域、SSH 节点身份与拨号地址分离、远程资源判断、containerd stop 语义，以及长时间原生命令如何与 ArkTS 页面协同。

当前方案用 OpenHarmony Go 保留上游 minikube CLI，用 HNP 完成原生命令交付，用 ArkTS/ArkUI 提供桌面操作入口，再通过 C++ N-API runner 在应用安全域中调用 SSH Driver。首次启动、状态查询、日志读取、停止和重新启动五项真机结果，组成了从安装到完整集群生命周期的连续证据。

后续工作的重点应放在可直接访问的局域网与云主机配置、多 Profile 管理、远程资产预检、错误诊断和浏览器集成。若 HarmonyOS PC 后续提供稳定的本地容器或虚拟化能力，还可以在保持现有 SSH 路线的基础上评估新的本地 Driver；在此之前，明确控制端与运行端的职责，是保证功能真实可用、故障可以定位的关键。