PJ2026-01060314 Hyper-V Ubuntu 虚拟机

1. 文档控制

字段	内容
编号	PJ2026-01060314
层级	L3 子课题
状态	已生效
上级规格	PJ2026-010603 YAML运维

2. 目的和范围

本规格定义 Windows Hyper-V 宿主上的 Ubuntu 长期运行节点，使虚拟机资源、镜像、网络、初始化、状态和 Provider 身份由 YAML 声明并通过受控 CLI 进入运行面。

范围包括：

Hyper-V 虚拟机、VHDX、处理器、内存和自动启动策略。
独立内部交换机、NAT、固定地址和出网连通性。
Ubuntu cloud-init、SSH、Docker 和受控 k3s 运行角色初始化。
D601-VM 运行 YAML 声明的独立单节点 k3s 空集群。
provider-gateway 的节点身份、常驻恢复和 trans 验收。
后台安装的阶段、日志、错误和终态可见性。

范围不包括：

Windows 11 客户端 Hyper-V 不支持的 GeForce CUDA 直通。
把宿主全部物理内存分配给虚拟机并使宿主失去稳定运行余量。
使用 WSL、Docker Desktop VM 或第三方桌面虚拟化替代 Hyper-V 虚拟机。

3. 原子需求

3.1 HYPERV-VM-REQ-001 YAML 真相

虚拟机名称、宿主 route、CPU、内存、磁盘、镜像 URL 与摘要、网络、 Ubuntu 用户、k3s 版本和 Provider ID 必须来自 config/platform-infra/hyperv-vms.yaml。D601 独立 server、host proxy、 registry endpoint 和拉取验收必须来自集群 owning YAML。实现只能校验、解析引用和渲染，不能维护隐藏运行参数。

3.2 HYPERV-VM-REQ-002 稳定资源边界

虚拟机可以暴露宿主全部逻辑处理器，但必须给 Windows、Hyper-V 和宿主 Provider 保留 YAML 声明的物理内存。虚拟磁盘使用动态 VHDX，并在创建前校验目标卷可用空间。

3.3 HYPERV-VM-REQ-003 网络与初始化

虚拟机应使用独立 Hyper-V 内部交换机和 NAT，不修改宿主物理网卡绑定。Ubuntu 应通过本地 CIDATA seed 完成固定地址、SSH、Docker、k3s 和基础服务初始化，并能访问互联网和 UniDesk 主服务。

3.4 HYPERV-VM-REQ-004 常驻与恢复

Hyper-V 虚拟机必须配置为宿主启动后自动启动、宿主关机时保存状态。Docker、k3s、SSH 和 provider-gateway 必须由 systemd 管理并具备自动恢复策略。

3.5 HYPERV-VM-REQ-005 可观测安装

安装入口必须异步返回。后台过程必须按阶段写入状态 JSON 与轮转日志，至少披露当前阶段、开始时间、更新时间、耗时、下载字节、下载速度、预计剩余秒数、错误码和恢复提示；无输出不得解释为成功。

3.6 HYPERV-VM-REQ-006 验收

完成状态必须同时证明：

VM 为运行状态且资源与 YAML 一致。
Ubuntu 固定地址可达并能正常出网。
Docker daemon 和 k3s 节点健康。
D601 只运行独立 k3s server，旧 agent 已停止。
独立集群只有一个 Ready 节点，且非 kube-system Pod 为零。
NC01 集群内不存在 D601 Node。
provider-gateway 以 YAML 声明的 Provider ID 在线。
trans <provider-id> hostname 和 k3s route 均可用。

3.7 HYPERV-VM-REQ-007 Provider 通道恢复

受控验收入口必须同时验证 Provider host 和原生 k3s route。验收失败时必须披露失败阶段和有界修复入口，不得仅依据 VM、systemd 或容器 active 宣称 Provider 可用。

Provider TCP 数据池恢复必须满足：

默认验收只读，健康时不得重启服务。
只有错误明确证明 Provider 数据通道缺失且显式确认修复时，才能通过宿主 SSH 重启 Provider 的 systemd unit；普通超时、数据池忙或未知失败只能重试，禁止扰动并行会话。
Provider ID、宿主 route、guest 地址、SSH 用户、systemd unit、重试间隔和等待时限必须来自 owning YAML。
修复范围只包含 Provider 服务，不得连带重启 VM、Docker 或 k3s。
同一入口必须在修复后重新执行 host 和 k3s route 验收。

3.8 HYPERV-VM-REQ-008 独立 k3s 运行面

D601-VM 与 NC01 必须作为两个独立集群运行：

config/platform-infra/k3s-clusters.yaml#targets.d601 只声明 D601 独立 server，不得出现 NC01、agent token 或跨地域 CNI 参数。
config/platform-infra/hyperv-vms.yaml 必须以 management.mode=standalone 引用独立集群配置。
D601 只运行单节点 k3s server，k3s-agent 必须 inactive。
D601 非 kube-system Pod 必须为零，全部系统 Deployment 必须 Ready。
CI/CD、GitOps、VM bootstrap 和业务 renderer 禁止安装 agent、创建跨地域 CNI 或把 NC01 workload 自动投递到 D601。
D601 host proxy 可继续为独立集群提供公共依赖出网，不得依赖公共镜像站或新增公共 registry mirror。
集群自有 artifact registry 可以通过公网可信 TLS 向 D601 提供鉴权只读拉取：
- 内部 CI/publish 继续使用集群内写入 endpoint，公网入口不得成为第二个 push authority。
- 公网边缘只允许 Registry V2 拉取所需的 GET 与 HEAD，其他方法必须在反向代理层拒绝。
- endpoint、DNS、上游、允许方法、凭据 sourceRef、镜像摘要和拉取验收参数必须来自集群 owning YAML。
- D601 containerd 继续消费既有镜像引用，只把该内部引用映射到声明的公网 HTTPS endpoint。
- artifact 大文件不得经过 Kubernetes 数据面或受传输时长和对象大小限制的 CDN。
宿主内网 SSH 可以作为 D601 的稳定部署控制通道，provider route 只作为部署后验收入口。

5.5 KiB Raw Blame History Unescape Escape