# PJ2026-01060314 Hyper-V Ubuntu 虚拟机

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01060314 |
| 层级 | L3 子课题 |
| 状态 | 已生效 |
| 上级规格 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) |

## 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 只作为部署后验收入口。
