# Barn 1.1.0 本机完整验收

> 在 Apple Silicon 宿主上原地升级、重建 Linux 与 macOS 实验环境，并录制可回放的逐项验收。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

本次验收从本机已安装的 Barn 1.0.0 出发，安装公开的 1.1.0 Homebrew 配方，验证升级与日常使用，再重建测试环境。**剧本先于执行编写；本轮已结束，主要功能通过，发现一项恢复问题，另有剪贴板与宿主提权检查未完成。** 已获授权删除本机现有 Barn 虚拟机。

## 环境与证据 {#environment}

- 宿主：macOS 27.0.1、Apple Silicon、18 个逻辑 CPU、128 GiB 内存；QEMU 11.1.3。
- 初始环境：8 台运行中的 Linux VM 与 1 台运行中的 macOS VM `mac1`；正常安装路径为 `/opt/homebrew/bin/barn`。
- 升级对象：公开版本 `v1.1.0`，提交 `b2cc8da8983e710255d504bf26bf5d7b3f182790`。
- 录像、原始输出、断言结果与执行脚本保存在仓库外的独立验收目录。每阶段产生一个 asciicast v2 文件，保留原始时间轴，并生成限制等待时长的观看版本。
- Linux 验收使用真实用户的 `~/.barn`。原生 Mac 深度验收复用源码中的 `tests/mac-live-acceptance.py`，使用专用测试数据目录及已有基础镜像的 APFS 克隆；最后验证正常用户路径。
- 终端录像不采集键盘输入、不输出密码或 SSH 私钥。桌面通过原生应用界面验收，截图在本次验收聊天中；剪贴板结果见下文。

## 执行顺序 {#sequence}

| 阶段 | 操作 | 通过条件 |
|---|---|---|
| U01 升级基线 | 记录旧版本、节点身份、公开 SSH 指纹与数据哨兵，停止 Linux 与 Mac VM | 基线可复查；所有目标正常停止 |
| U02 本机安装 | `brew upgrade pgsty/infra/barn`，检查版本、helper、签名、公证与 `brew test` | 正常 PATH 解析到公开 1.1.0；CLI、helper 与 App 配套 |
| U03 升级恢复 | 启动旧 VM，核对身份、数据与 SSH；随后清理旧 VM | 升级保留身份与数据；显式清理成功 |
| L01 首次运行 | 空工作目录执行 `barn up`，检查生成清单、确认提示、启动进度与 SSH | 默认 Ubuntu 24.04 原生架构客机就绪 |
| L02 清单与目录 | 四种模板；合法/非法 YAML；`-I/-A` 与别名；两个官方签名源；镜像查询与缓存 | 合法输入解析一致；错误分类和退出码正确；覆盖参数不改写清单 |
| L03 双节点与存储 | Ubuntu/Debian 双节点；持久 ext4、临时数据盘、XFS、带空格/中文的路径；只读/可写 9p 共享 | 挂载类型与权限符合配置；宿主与客机双向读写符合预期 |
| L04 网络与访问 | 固定 IP、控制节点到对端 SSH、DNS/HTTPS、SSH 配置；`exec` 参数边界和远程退出码 | 地址、目标节点、标准输出/错误与退出码正确 |
| L05 生命周期 | 重复 `up`、按节点停止/启动/重启、CPU/内存增减、`reload`、选点重建 | 幂等操作保留 PID；资源实际生效；未选节点与持久数据不变 |
| L06 故障与删除 | 配置遗漏、缺失共享目录、客机进程中断后恢复、provision 成功/失败/超时、`purge --ask` 取消 | 无隐式删除；失败可定位；重试恢复；取消不改状态 |
| L07 数据保留 | `recreate`、选点 `destroy`、全量 `destroy`、重新创建、`purge` | 根盘/临时盘重置；持久盘按命令语义保留或删除 |
| L08 镜像矩阵 | 本机支持的 8 个 arm64 镜像系列；Debian amd64 的 TCG 启动 | SSH、架构、系统版本与数据盘可用；el8 arm64 使用预期的 TCG |
| M01 多机与身份 | 原生 Mac 自动验收：双机、独立身份与磁盘、基础镜像不变 | 各项身份独立；克隆与生命周期操作不修改基础镜像 |
| M02 Mac 网络与共享 | 独立子网、宿主连通、客机隔离、DNS/HTTPS、VirtioFS 与远程参数 | 网络与共享语义符合参考手册 |
| M03 Mac 生命周期 | 停止/启动、资源配置、第三台运行限制、重建身份轮换、选点销毁 | 身份保留/轮换符合操作；另一台 VM 不受影响 |
| M04 桌面与剪贴板 | 打开桌面、登录状态、双向文本剪贴板、关闭窗口后 SSH | 桌面可用；双向文本一致；关闭窗口不停止 VM |
| F01 收尾 | 清理专用测试 VM，核对正常安装、状态、诊断与 SSH 配置，汇总录像 | 无遗留测试进程；每个结果有日志或画面依据 |
{.wide .expand}

## 判定与重试 {#criteria}

每条命令记录参数、退出码、耗时与原始输出。断言失败立即保留现场；修正剧本错误后另起重试记录，产品缺陷单独记录，不把失败片段从录像中删去。长等待只在观看副本中加速，原始记录保留。

已有宿主网络先通过只读检查与复用路径验证。需要宿主 sudo 的安装、卸载或 hosts 操作先检查实际授权与执行计划；不能完成的项目明确标记阻塞。Apple 系统镜像更新、Intel Mac 实机与 Linux KVM 属于其他环境的验收范围。

## 结果与回放 {#results}

本轮于 2026-11-09 11:08（Asia/Shanghai）结束。正常 PATH 已指向公开的 Barn 1.1.0；旧有 8 台 Linux VM 和 1 台 Mac VM 的升级恢复检查通过后，按授权删除。验收创建的 VM、专用 Mac 数据目录和额外的 120 GiB 基础镜像均已清理，原有默认 macOS 基础镜像保留。

### 阶段结果 {#stage-results}

| 项目 | 结果与依据 |
|---|---|
| Homebrew 安装与升级 | 通过；CLI、原生组件、签名、公证与 `brew test` 正常，原 VM 的身份和持久路径数据保留 |
| CLI、清单与镜像目录 | 通过；首次运行、四种模板、架构别名、错误输入、两个官方签名源、本地目录构建/验证/导入/清理 |
| Linux 双节点与生命周期 | 通过；固定 IP、控制节点 SSH、DNS/HTTPS、参数/退出码、ext4/XFS、只读/可写 9p、资源调整、重建和持久盘重挂载 |
| 故障与恢复 | 缺失共享目录、provision 失败/超时、取消 purge 和同步磁盘后的进程中断恢复通过；立即断电的就绪标记问题见下节 |
| 原生 Mac 自动验收 | 15 个阶段通过；双机身份/磁盘/网络隔离、基础镜像不变、资源配置、并发上限、重建与选点删除 |
| 正常 Mac 路径 | 通过；从已有 IPSW 完整安装 120 GiB 新基础镜像、只读/可写 VirtioFS、SSH Include、默认基础镜像保留及新增缓存清理 |
| 交互式终端 | Linux 和 Mac 均通过；实际分配客机 TTY，交互 shell 的退出码 `17` 原样返回；三类 Linux 日志可解析为 JSON |
| 桌面 | 已目视确认登录后的 Finder 桌面；关闭窗口后同一 VM 进程和 SSH 继续运行；双向剪贴板未完成 |
| 源码检查 | 发布提交上的 `make check` 和 `make mac-native-test` 均通过 |
| 最终状态 | Linux 和 Mac VM 均为零；无遗留测试 VM 进程；`barn doctor`、`barn mac doctor` 与网络状态正常 |
{.wide .expand}

删除控制节点后，Barn 会提升剩余节点的控制角色。本次按提示更新清单中的 `admin_ip` 后重新创建原节点，保留盘重新挂载，另一节点的 PID 和数据保持不变。旧清单要求恢复原控制角色时，`up` 明确拒绝隐式重建。

### 镜像矩阵 {#image-results}

以下 9 组均通过镜像获取、启动、SSH、系统/架构核对、数据盘写入、停止/启动和清理。`-I/-A` 未修改清单文件。EL7/arm64 因目录无对应制品返回 `usage / 2`；本宿主上的 EL7/amd64 返回 `capability / 3`，没有创建部署。

| 镜像 | 客机架构 | 加速器 | 结果 |
|---|---|---|---|
| `u22@20261020.0.1` | `arm64` | `hvf` | 通过 |
| `u24@20261017.0.1` | `arm64` | `hvf` | 通过 |
| `u26@20261016.0.1` | `arm64` | `hvf` | 通过 |
| `d12@20261026.2643.1` | `arm64` | `hvf` | 通过 |
| `d13@20261103.2651.1` | `arm64` | `hvf` | 通过 |
| `el8@8.10.20240528.3` | `arm64` | `tcg,thread=multi` | 通过 |
| `el9@9.8.20260525.2` | `arm64` | `hvf` | 通过 |
| `el10@10.2.20260525.0` | `arm64` | `hvf` | 通过 |
| `d13@20261103.2651.1` | `amd64` | `tcg,thread=single` | 通过 |
{.wide .expand}

### 强制终止后的就绪标记问题 {#recovery-gap}

在 Ubuntu 24.04 arm64/HVF 节点重建成功后立即强制终止 QEMU，随后 `up` 启动了客机，但 `/var/lib/barn/ready.json` 与 `error.json` 均不存在。SSH 和持久数据可用，cloud-init 已结束，`up` 等待 180 秒后以退出码 `5` 失败。这是本轮实际观察到的一项恢复缺口，记录在 `03-linux-lifecycle-r3` 与 `03-power-loss-investigation`。

本次通过以下操作恢复就绪状态，运行中的 VM PID、对端节点和持久数据均保留：

```bash
barn exec meta -- sudo -n /usr/local/libexec/barn-finalize
barn up meta -f barn.yml
```

再次试验时先在客机执行 `sudo sync`，再核对 QEMU 命令行和 QMP UUID 后强制终止；这次 `up` 自动恢复成功。立即断电的现象仅在上述条件下观察到一次，落盘时机与其他镜像的表现仍需进一步定位。代码依据为 1.1.0 的 [就绪探测](https://github.com/pgsty/barn/blob/v1.1.0/internal/vm/lifecycle.go#L584) 和 [初始化重试入口](https://github.com/pgsty/barn/blob/v1.1.0/internal/private/start.go#L162)。

### 未完成的检查 {#limits}

- 双向剪贴板：桌面自动化未能可靠注入宿主系统剪贴板，浏览器工具的剪贴板又是隔离的；本轮结束时尚未取得宿主端人工复制输入，保留为未验证项。
- 宿主提权变更：`sudo -n` 要求密码，网络安装/卸载读取 root 所有的状态也需要提权。已验证现有网络复用、权限拒绝分类和只读 hosts 计划，未执行系统网络重装/卸载或 `/etc/hosts` 写入。
- 本轮宿主为 Apple Silicon；Intel Mac、Linux/KVM 和 Apple 系统镜像更新仍属于其他环境的覆盖范围。

### 本地证据 {#playback}

证据目录为 `~/barn-acceptance/1.1.0-20261109-101029/`。打开 `player/index.html` 可离线播放 23 段 asciicast；原始时间轴合计约 58.9 分钟，观看版约 12.1 分钟。观看版只调整时间戳，逐段核对输出字节和 SHA-256。终端录像不包含桌面画面，桌面截图在本次验收聊天中。

`evidence/plan-before-execution.md` 与 `.zh.md` 保存执行前剧本；各阶段目录保存执行脚本快照、命令、退出码和原始输出；`findings.json` 记录恢复问题与未完成项。Homebrew 提示、SSH 别名、计划中的 create/recreate 分类、控制角色提升、TCG 参数和错误分类等剧本修正均保留初次录像及后续重试。完整记录存放在本机，本站只保存这份验收说明。