项目

• 1: 平台与限制
• 2: 设计
• 3: 安全与信任
• 4: 参与贡献
• 5: 发布 Mac 原生组件
• 6: 验证历史
• 7: Barn 0.9.3 变更
• 8: Barn 1.1.0 本机完整验收

1 - 平台与限制

Barn 专为 本地开发与测试 设计。在搭建实验环境前，可通过本页核对宿主软硬件要求及两类客机的支持范围。

版本

当前文档对应稳定版 Barn 1.2.0（安装方式与版本变更详见安装指南与 1.2.0 发布说明）。可通过 barn version 查看本地安装版本；Linux 镜像目录通过 barn update 独立更新。

• 稳定版渠道：Barn 1.2.0 于 2026-11-12 作为 GitHub 正式版发布，releases/latest、不带 BARN_VERSION 的下载安装器与 Homebrew 配方都会选择此版本，DEB 与 RPM 软件包从发布页下载；需要固定版本时设置 BARN_VERSION=1.2.0。
• macOS 原生组件：Darwin arm64 归档与 Apple Silicon Homebrew 安装均包含经过签名、公证的 Barn.app 及配套 CLI/helper，无需安装 Go 或 Xcode，详见 macOS 客机指南。
• 1.2.0 变更：新增规格与环境变量覆盖、可恢复的根盘扩容、生命周期 --parallel 和清单 hosts 发布。Linux 默认规格改为 1 vCPU / 2 GiB；显式设置 vm_cpu: 2、vm_mem: 4GiB 可保留 1.1.0 的默认值。已应用 VM 的资源会保留到显式执行资源变更操作为止。
• 历史验证记录：历次真机验收与测试记录归档在验证历史与 Barn 1.1.0 本机完整验收中。

选项可用范围见版本基线，发布证据见 1.2.0 验收记录。

Linux 客机

Barn 为上述四个平台构建发行二进制，真机虚拟化测试主要覆盖 darwin/arm64 与 linux/amd64。Linux 宿主需要可访问的 /dev/kvm 以及 NetworkManager 或 systemd-networkd。可运行 barn doctor 检查宿主环境，或用 barn setup --dry-run 预览依赖安装与网络配置计划。

Barn 1.2.0 内置镜像目录 revision 2026110502 提供 9 个发行版系列、17 个镜像产物，默认镜像为 u24:stable：Ubuntu 22.04/24.04/26.04 LTS、Debian 12/13、Rocky Linux 8/9/10 与 CentOS 7（具体版本号见镜像参考）：

• 每位用户管理一套 Linux 部署，使用私有 RFC1918 /24 网段；节点数量只受网段可用地址与宿主资源限制。
• 跨架构客机使用 QEMU TCG 软件模拟；Rocky Linux 8 arm64 因采用与 Apple HVF 不兼容的 64 KiB 页大小内核，在 Apple Silicon 上同样自动使用 TCG。
• CentOS 7（el7）为 deprecated（已弃用）兼容镜像，仅支持在 linux/amd64 宿主上原生运行。
• vm_shares（QEMU Virtio-9p）支持 Linux 与 macOS 宿主，要求 QEMU 与客机内核支持 9p。若客机内核不支持 9p，仍可使用 SSH/SCP/rsync。

macOS 客机

barn mac 需要 Apple Silicon 芯片、macOS 27 或更高版本、已登录的图形桌面会话以及 Barn.app 原生组件。客机基于 Apple Virtualization.framework 运行 macOS 27，不依赖 QEMU 或 Linux 宿主网络（详见macOS 客机指南）：

• 磁盘空间：准备首台 macOS 虚拟机约需 65 GiB 可用空间，用于存放 .ipsw 恢复镜像、未启动过的基础镜像及虚拟机的 APFS 写时复制克隆。下载支持断点续传，也可通过 --ipsw 指定本地恢复镜像。
• 并发上限：受 Apple 虚拟化框架限制，每台 Mac 最多同时运行两台 macOS 虚拟机（跨所有虚拟化工具及正在安装的基础镜像统一计数）；已停止的虚拟机数量不受此限制。
• 隔离与共享：每台虚拟机拥有独立的私有 /24 NAT 子网、SSH 密钥、登录密码和 APFS 克隆磁盘，支持 VirtioFS 目录共享（--share）与纯文本剪贴板同步。
• 能力边界：不支持 USB 透传、虚拟机快照与挂起恢复；虚拟机内的 Apple 账户登录可能受系统限制。
• Mac 状态损坏：恢复日志损坏时，barn mac image ls、barn mac doctor 的空间估算与镜像清理会失败，直到日志修复。单台机器的状态无法读取时，barn mac ls 会整体失败，其他机器仍可按名称操作。

请使用 barn mac doctor 与 barn mac ls 检查和管理 Mac 虚拟机；顶层 barn status、destroy 与 purge 仅作用于 Linux 实验环境。

数据与生命周期

请将重要代码与数据保存在宿主目录或版本库中：

• Linux 实验环境：barn recreate 会替换根盘与非持久数据盘并保留 persistent: true 的持久盘，清单缺少已有节点时整套部署 recreate 会拒绝执行；barn destroy 会删除根盘与非持久盘。恢复客机时，barn up 会格式化没有任何签名的数据盘；已有的 ext4 或 XFS 文件系统只有在检查工具报告可识别的损坏时才会重置。带分区表、签名缺少 UUID、使用不支持的文件系统特性或检查工具未知失败的磁盘会保留数据并给出警告（详见存储与访问）。
• macOS 虚拟机：barn mac recreate 会用基础镜像的全新克隆替换客机磁盘；barn mac destroy 会删除该虚拟机的磁盘、密钥与状态，宿主上的共享源目录保持不变。

日常排障请参考故障排查，宿主特权、SSH 凭据与镜像信任边界请参考安全与信任，源码构建与发布流程请参考参与贡献。

2 - 设计

Barn 通过同一个命令行入口提供两套独立的虚拟化工作流：多节点 Linux 实验环境与独立命名的 macOS 客机。

下文概述 Linux 实验环境的核心设计，各模块的深层取舍见设计注记。原生 Mac 生命周期解释网络归属、锁、凭据与恢复机制，具体用法见macOS 客机指南与 Mac 命令参考。

每位用户一套 Linux 实验环境

每位系统用户通过一份兼容 Pigsty 的 YAML 清单管理唯一一套存放在 BARN_HOME（默认 ~/.barn）中的 Linux 部署（详见为什么 Barn 没有项目）。由于部署状态与工作目录解耦，日常生命周期与节点访问命令可在任意目录下执行。

节点级收敛

Barn 根据文档规定的 vm_* 字段与 Pigsty 身份字段为每个节点计算规格哈希，并将其与已提交状态及 QEMU 进程身份一同落盘：

• barn up 会创建新增节点、启动已停止节点、在不中断运行中 QEMU 进程的前提下重试未完成的客机初始化，并刷新受管的 /etc/hosts 与 SSH 配置。
• 修改已有节点的规格或从 barn.yml 中删去节点绝不会在后台静默销毁虚拟机——CPU 与内存变更使用 barn resize，其他配置变更需显式运行 barn recreate，删除节点需显式运行 barn destroy。清单缺少已有节点时，整套部署 recreate 会拒绝执行（详见声明式不等于破坏式）。

运行时选择

--arch/-A 临时覆盖清单的 vm_arch；二者都未指定时跟随宿主，-A native 可覆盖清单并恢复跟随宿主。镜像参数 -I 不改变架构，已有 VM 切换架构需要重建，详见配置规则。

vm_arch 作用于整套部署（省略或设为 native 时取宿主架构；显式指定 amd64 或 arm64 时选用对应架构镜像）。当客机与宿主架构一致时，Barn 默认使用 HVF/KVM 原生硬件加速；仅在跨架构运行或命中目录声明的内核兼容例外（Apple Silicon 上的 el8 arm64）时才使用 QEMU TCG。若原生加速因其他原因失败，Barn 会直接报错停止，而不会静默退化到软件模拟。

每个节点的已提交状态都会记录实际架构与加速器（可通过 barn status 查看）。在执行破坏性的 recreate 之前，Barn 会预先校验 QEMU 二进制、版本号、网络后端、基础镜像字节、引导方式与固件，确保缺少依赖时不会误删现有的正常节点。

双网卡与单个固定子网

每台 Linux 虚拟机均挂载两张虚拟网卡（详见为什么每个 Barn 节点都有两张网卡）：

• 管理网卡：基于 QEMU 用户态网络，无需修改宿主防火墙即可提供 DHCP、DNS、外网访问与宿主回环端口 SSH 转发。
• 固定 IP 实验网卡：承载 barn.yml 中声明的 RFC1918 /24 静态地址，供宿主与节点互访、节点间复制及 Ansible 连接使用。

为了在保持 QEMU 非特权运行的同时提供固定 IP 子网：

• macOS 宿主：使用固定版本的 socket_vmnet 服务。
• Linux 宿主：优先复用活跃的 NetworkManager（通过 nmcli 管理 barn0 网桥），否则使用 systemd-networkd 配合发行版 qemu-bridge-helper（启动未激活的 systemd-networkd 前会先扫描现有配置，确保不会误接管宿主物理网卡）。在 Debian 上，setup 会向当前用户所属组授予 qemu-bridge-helper 权限，并以普通用户身份实际运行一次 QEMU 挂桥测试，验证通过后才提交网络安装事务。

存储与配置生命周期分离

期望配置（barn.yml）、已应用状态（$BARN_HOME）与基础镜像缓存（$BARN_HOME/images）拥有各自独立的生命周期：

• 更新镜像目录通道（barn update）不会改写已创建节点的根盘。
• 通过校验的基础镜像以只读权限共享，每台虚拟机将根盘写入各自独立的写时复制层（root overlay）。
• 普通 destroy 与 recreate 会保留 persistent: true 的持久数据盘。恢复客机时，up 只会格式化没有任何签名的数据盘，或检查工具报告可识别损坏的 ext4/XFS 文件系统；无法判定的情况会保留数据并给出警告（详见数据盘配置与存储与访问）。
• barn image prune 自动保护活动镜像目录、已应用节点与 local-* 别名所引用的镜像（详见镜像参考）。

安全边界

QEMU 进程与镜像下载均以当前普通用户身份运行；仅安装宿主依赖（setup）、配置宿主网络（network install/uninstall）与更新系统 /etc/hosts（hosts install/uninstall）需要管理员权限。在向进程发送信号或删除节点文件前，Barn 会逐一核验文件属主、路径边界、QMP UUID/名称身份、进程启动时间与命令行哈希元组以及操作日志白名单，任何一项存疑都会立即中止操作（详见PID 不是虚拟机身份）。

3 - 安全与信任

Barn 面向受信任的本地开发工作站。同一套 Linux 实验环境中的所有节点共享同一个私有子网，且控制节点持有可管理其余节点的部署级 SSH 私钥。Barn 的属主与身份检查旨在防止误删无关宿主文件或误杀进程，而非在共享服务器上隔离互不信任的多租户用户。

宿主权限

日常请始终以普通登录用户运行 barn。QEMU 进程、Barn.app 虚拟机、镜像下载、虚拟磁盘与状态文件均归当前普通用户所有并以该身份运行。只有以下三项宿主级操作需要管理员（sudo）权限：

在请求 sudo 授权前，setup、network 与 hosts 都会先打印完整的变更计划。在终端中，如果宿主缺少依赖或 Barn 网络不完整，up、start、restart 与 reload 会提议准备宿主：它们执行同一份 setup 计划、同样只询问一次，且从不默认 --yes。没有终端时这些命令只报告缺少的条件，无人值守准备请执行 barn setup --yes。

请确保 barn 与 /opt/barn/libexec/barn-hosts-helper 来自同一次构建：CLI 调用 helper 前会核对其内嵌 SHA-256 摘要，helper 在每次写入前后都会校验 /etc/hosts 的属主、权限、硬链接数及预期内容摘要。

相比之下，原生的 barn mac 工作流在虚拟机启动时按需创建用户态 vmnet 网络，不安装任何 root 守护进程或特权网络服务（详见设计说明与卸载指南）。

客机访问与 SSH 信任

Linux 实验环境的默认客机管理账号为 dba（密码已锁定、具备免密 sudo 权限，并使用 $BARN_HOME 中生成的 Ed25519 部署密钥登录）。Barn 同时会将该私钥分发到控制节点，以便在控制节点上运行 Ansible 剧本管理其他节点——因此能够登录控制节点的用户即拥有整套 Linux 实验环境的管理权限。

Barn 针对三类 SSH 连接路径采用不同的主机密钥校验策略：

每台 macOS 虚拟机拥有独立的 Ed25519 SSH 密钥对与随机生成的桌面管理员密码（保存在虚拟机目录内权限为 0600 的 password 文件中，可通过 barn mac password 查看）。首次初始化完成后，Linux 与 macOS 客机均强制使用 SSH 公钥认证，关闭 SSH 密码认证与 root 远程登录，并为管理账号配置免密 sudo。提交 Issue 或分享配置时，请先剔除日志和状态文件中的私钥与密码。

首次连接 Mac 客机时，信任依据来自 runner 独占的私有网络，以及 SSH 连接前后的 runner 身份核验，随后将观察到的主机密钥固定到实例 UUID。GUI 密码与 SSH 私钥采用相同的文件权限边界；私钥已经授予客机 sudo 权限，单独将密码存入 Keychain 只会增加签名身份和锁定状态故障，无法进一步保护客机权限。详见原生 Mac 生命周期。

共享文件与测试磁盘

• 宿主目录共享：可写共享（Linux vm_shares 中设 readonly: false 或 barn mac --share 使用 :rw）允许客机进程直接修改所挂载的宿主目录，且客机写入的内容在删除虚拟机后依然保留。请仅共享专门的工作目录；若客机无需写入宿主文件，请优先使用只读共享。
• 持久盘与测试数据盘：普通 Linux destroy 与 recreate 会保留 persistent: true 的持久数据盘。恢复客机时，up 会格式化没有任何签名的数据盘；已有的 ext4 或 XFS 文件系统在检查工具报告可识别的损坏时会被重置，持久盘也不例外；其他探测或检查失败会保留数据并给出警告。重要数据请在实验环境之外做好备份（详见存储与访问）。

下载与镜像信任

Barn 将软件分发与镜像校验划分为四个彼此独立的信任机制：

发布资产均从对应标签的源码构建：配齐 Mac 签名密钥时由标签工作流构建，否则走文档中的本地发布流程。发布提交必须先通过源码 CI；两条路径都要求软件包、归档、SBOM 与校验和验证通过后才能创建 GitHub Release 草稿，本地发布步骤见 Mac 发布手册。

1.2.0 的 release.json 用 signed:false, attested:false 描述通用发行元数据的范围：Git tag、通用校验和及发布元数据没有独立密码学签名或 attestation。目录的 Minisign 校验与 Apple Silicon 代码签名/公证仍分别适用于上表中的对象，最终验收记录逐项验证了这些机制。

两个官方镜像仓库（https://repo.pigsty.io/barn 与 https://repo.pigsty.cc/barn）无论通过默认配置还是 --repo 显式选中，均强制要求有效的 minisign 目录签名。通过 --repo 或 BARN_REPO 显式指定的自定义 HTTPS 仓库或本地目录仓库可以使用未签名目录，请仅添加你信任的镜像源（详见镜像参考）。

报告安全漏洞

发现安全漏洞时，请通过 GitHub 私密安全通告或发送邮件至 [email protected] 私下报告，并附上 barn --json version、宿主系统与架构以及脱敏后的最小复现步骤。安全修复发布在最新的 1.x 补丁版本中：只有最新的 1.x 版本受支持，0.x 版本不再提供修复。完整政策见 SECURITY.md；日常功能缺陷请提交至 GitHub Issues。

4 - 参与贡献

Barn 采用 Apache-2.0 开源许可证，欢迎参与命令行工具、macOS 原生组件、文档站点与镜像构建流水线的改进。

选择仓库

提交问题报告时，请附上 barn version 输出、宿主操作系统与架构、执行的完整命令以及脱敏后的报错信息（移除私钥与密码）。安全漏洞请按安全政策私下报告。准备进行较大规模的实现调整前，建议先提交 Issue 对齐方案；代码规范与 PR 要求详见 CONTRIBUTING.md。

定位源码实现

当前稳定版对应 v1.2.0 标签，相对 1.1.0 的变更见 1.2.0 发布说明。各子系统的实现位置如下：

阅读实现代码时请同步查看同目录下的单元测试——测试完整界定了哪些故障支持自动恢复、哪些歧义状态必须安全中止。

构建与测试

按从源码构建安装锁定版本的工具链后，运行完整本地门禁：

make check

make check 会依次执行 Go 模块与 Shell 脚本检查、单元测试与竞态检测、go vet、staticcheck、govulncheck、四平台交叉编译（darwin/arm64、darwin/amd64、linux/amd64、linux/arm64）、安装器与镜像流水线测试以及许可证检查。如果改动涉及虚拟化加速、宿主网络或 Barn.app 行为，请在对应宿主平台（macOS HVF / Virtualization.framework 或 Linux KVM）上执行真机虚拟机生命周期测试，并在 PR 中注明实测环境。

修改打包逻辑时，安装 packaging/toolchain.env 中声明的工具版本并运行本地快照检查：

make release-check
make release-snapshot SNAPSHOT_DIST=.goreleaser-review

SNAPSHOT_DIST 需指定工作树根目录下尚不存在的新目录；release-snapshot 会在本地生成并校验归档包、.deb/.rpm 软件包、SBOM 与校验和，不会上传任何产物。

编写与校验文档

新的设计决策、研究结论与验收记录统一维护在本站的 content/blog/design/ 与 content/blog/release/，注明日期、实现状态、来源依据和验收条件，入口为设计文章。任务指南和参考契约放在 content/docs/；源码仓库不再维护 docs/ 目录。

文档站点的每篇文档均由英文 page.md 与中文 page.zh.md 成对组成。修改时请保持中英文的命令、默认值、显式 {#id} 标题锚点（供 OINK v1.5.1 双语对照模式 compare: true 同步章节）、表格与注意事项严格对齐，先说明用户要完成的任务，再展开实现细节，并将 Linux 实验环境与 barn mac 工作流区分清楚。

在网站仓库根目录运行：

make check

make check 会校验 Go 模块、在清除本地主题替换并关闭 Go workspace 的纯净环境下使用 Hugo Extended 与锁定的 OINK v1.5.1 构建全站，随后调用 bin/check_internal_links.py public 检查全部内部链接、标题锚点与静态资源。需要联调本地相邻的 OINK 主题工作区时，请使用 make check-local 或 make build-local。文中的命令行示例请对照 barn <command> --help 核验，YAML 清单示例请使用临时 BARN_HOME 跑通 barn validate 与 barn plan。

发布产物与门禁

自 1.0.0 起的稳定版作为 GitHub 最新正式版（latest）发布；低于 1.0.0 或带预发布后缀的版本标记为 pre-release（预发布版），使用安装脚本时需显式指定 BARN_VERSION。每次发布包含 darwin/linux .tar.gz 归档（含 bin/barn、bin/barn-hosts-helper 与 licenses/）、Linux .deb 与 .rpm 软件包（安装至 /usr/bin/barn 与 /opt/barn/libexec/barn-hosts-helper）、checksums.txt、release.json 及 SPDX 物料清单。

从 0.9.2 开始，Darwin arm64 归档还包含 bin/Barn.app，CLI、helper 与 App 均经过 Developer ID 签名与 Apple 公证。Homebrew 将 App 安装在 libexec 下，普通安装无需 Go 或 Xcode。

自动发布工作流要求配齐全部 6 项 Apple 签名/公证密钥，并成功构建原生组件。6 项均未配置时跳过自动创建发布；仅配置部分时直接报错。Mac 发布手册说明本地签名发布流程、载荷身份、CI 密钥与安装验收。

正式发布版本的验收步骤：

1. 执行 make catalog-check：在全新临时数据目录中验证两个官方源的签名，要求目录与内置 JSON 逐字节一致，并检查全部 stable 产物的 URL 与大小。目录有变更时先同步内置快照、修订号、时间及 repo.yaml。再运行镜像目录测试，并用全新临时 BARN_HOME 执行 barn update；go run ./tools/catalogcheck -verify-bytes 还会下载并校验全部 stable 产物摘要，不保留下载文件。正式原生构建与两条发布路径均强制执行目录门禁。
2. 在目标提交上跑通源码 CI 与打包工作流，核对版本号、配对的 barn-hosts-helper 摘要、许可证、SBOM 与 checksums.txt。
3. 完成 Linux 真机虚拟机验收测试（分发 Barn.app 时同步完成 Mac 真机虚拟机验收）。
4. 公开 GitHub Release 并更新 Homebrew Formula（pgsty/infra/barn），最后发布文档站并验证公网安装脚本与包管理安装链路。

维护镜像目录

使用镜像流水线工具（packaging/image-pipeline/build.sh 与 build-official.py）校验并离线归一化候选 qcow2 镜像，完成真机启动测试后更新 repo.yaml 并签发 catalog.json。

将二进制内置的 Schema-3 镜像目录逐字节导出到新路径：

go run ./tools/catalogexport /absolute/new/catalog.json

catalogexport 采用原子写入并要求目标路径尚不存在，支持相对路径、~/ 与目录符号链接，并自动创建缺失的父目录。使用 make catalog-sign 与 make catalog-verify 配合离线保存的 Minisign 密钥完成签名与验签（生产环境私钥严禁进入源码仓库或 CI）。客户端侧的验签与缓存策略见镜像参考。

5 - 发布 Mac 原生组件

维护者通过常规的 barn_VERSION_darwin_arm64.tar.gz 归档交付 Mac 原生组件。从 0.9.2 起，标准安装脚本与 pgsty/infra/barn Homebrew Formula 会一并安装 CLI、配套的 hosts helper 与 macOS 宿主上的原生应用包 Barn.app。本文是维护中的发布手册，于 2026-11-12 对照 v1.2.0 发布脚本核验；开发构建请参阅从源码构建。

统一发布身份

原生载荷与 GoReleaser 归档必须使用同一个版本号和源码提交。packaging/mac-release.py 导出 MACOS.md、MACOS.json、bin/barn、bin/barn-hosts-helper 与 Barn.app，清单记录文件权限、摘要和签名状态。VM 磁盘、凭据、恢复镜像与已安装服务不属于发布载荷。

App 的 Bundle ID 为 com.pgsty.barn，内部可执行文件为 barn-mac-runner。CLI 会检查带版本号的 runner 协议，也识别早期的 Barn Mac.app 包名。替换 App 时，$BARN_HOME/mac 下的 VM 状态保持不变。

CLI 内嵌了 helper 的摘要，因此必须按以下顺序签名：

1. 构建并签名 barn-hosts-helper。
2. 构建 barn 时嵌入已签名 helper 的 SHA-256，再签名 CLI。
3. 为 Barn.app 签名，启用 hardened runtime 与安全时间戳。
4. 将 CLI、helper 与 App 一同提交 Apple 公证；获准后为 App 装订票据（staple），验证票据并检查 Gatekeeper。
5. 导出并重新解包载荷，再次核验签名与票据。组装发行包时，将 Darwin arm64 归档中的 CLI/helper 替换为这批已签名的字节，重新生成 SPDX 文档与校验和。

载荷构建器与归档检查器会强制核对配套关系。构建 CLI 后再次签名 helper 会改变摘要，导致配对失败。

在本地构建正式版本

准备运行 macOS 27+ 的 Apple Silicon Mac、Xcode 27+、锁定的工具链、Developer ID Application 身份及已保存的 notarytool 配置。用 security find-identity -v -p codesigning 选择签名身份，用 xcrun notarytool store-credentials 创建公证配置；证书私钥和密码保存在仓库外。

检出带有 v$RELEASE_VERSION 标签的干净源码，将 RELEASE_VERSION 设为目标发布版本，并在源码仓库外选择新的制品目录：

export BARN_CODESIGN_IDENTITY='Developer ID Application: your organization (TEAMID)'
export BARN_NOTARY_PROFILE=barn-release
export BARN_MAC_REQUIRE_NOTARIZATION=1
VERSION="${RELEASE_VERSION:?Set RELEASE_VERSION to the checked-out release tag version}"
COMMIT="$(git rev-parse HEAD)"
export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
export BARN_BUILD_DATE="$(date -u -r "$SOURCE_DATE_EPOCH" +%Y-%m-%dT%H:%M:%SZ)"
RELEASE_DIR="$(mktemp -d "${TMPDIR:-/tmp}/barn-release.XXXXXX")"

python3 packaging/mac-release.py build \
  "$VERSION" "$COMMIT" "$SOURCE_DATE_EPOCH" "$RELEASE_DIR/native.tar.gz"
BARN_MAC_PAYLOAD="$RELEASE_DIR/native.tar.gz" \
  make release-local VERSION="$VERSION" OUTPUT="$RELEASE_DIR/assets"

正式原生构建与 release-local 都会在构建前执行 make catalog-check 对应的门禁。官方镜像目录发生变化时，先按发布门禁同步并测试。快照或 uncommitted 载荷不能用于正式本地发布。release-local 核验归档、软件包、SBOM、校验和与 CLI/helper 配对，将完整制品写入指定目录。

开发打包逻辑时，可用 BARN_MAC_PAYLOAD=/absolute/native.tar.gz make release-snapshot 验证原生载荷合并。载荷版本必须匹配 .goreleaser.yaml 选择的快照版本，例如 v1.2.0 之后为 1.2.1-next；脏工作树使用 uncommitted，干净源码使用完整提交号。快照接受 ad-hoc 签名，正式发行检查要求载荷已经过 Developer ID 签名与公证。

配置自动签名

标签工作流使用以下 6 项仓库密钥。全部未配置时跳过自动创建发布，维护者可使用本地流程；只配置部分时立即失败；全部配置后，原生构建、签名或公证任一失败都会阻止组装发行包。

Mac 工作流将签名材料导入临时 runner 钥匙串，并在任务结束时删除。PR 与快照使用 ad-hoc 构建。发布工作流验证完整载荷后创建发布草稿。

验证安装并发布

运行 make check、make mac-native-test 以及包含原生载荷的完整快照。在隔离目录中验证首次安装、重复安装与升级，并在受支持的物理 Mac 上使用打包后的 App 验证启动、SSH、桌面窗口与正常关机。替换 App 必须保留实例 ID、机器 ID、SSH 密钥和已固定的主机密钥。

已有的 tests/mac-live-acceptance.py 要求绝对 --barn 路径、专用可丢弃的 --home、与其分离的新建或空 --output 证据目录，并用 --allow-test-root 显式授权该测试目录。先用 --plan 查看流程；--gui 增加桌面/剪贴板检查，--allow-download 允许在未准备基底时从 Apple 下载。脚本保留失败现场与证据。测试 SSH 集成时，除了 BARN_HOME 还应隔离进程的用户主目录，因为受管的 ~/.ssh/config 条目位于 VM 状态目录之外。

发布组装从 packaging/homebrew/barn.rb.tmpl 生成 barn.rb。Formula 将 barn 安装到 bin，将 helper 与 App 安装到 libexec；安装与测试逻辑应与 Tap 保持一致。带后缀的版本需要显式 version 行，避免 Homebrew 从架构后缀误推导出 64；普通版本省略该行。0.9.1 的公开归档早于 App 随包交付，仅支持 Linux 客机。

核对本地制品后，推送源码与标签，上传到 GitHub Release 草稿并核验上传字节，再公开发布。低于 1.0.0 或带预发布后缀的版本标记为 pre-release，稳定版设为 latest。公开制品可用后更新 Homebrew 四个平台的 URL 与摘要，随后用已发布的字节验证公开归档、安装脚本与 Homebrew 升级。签名、公证、VM 验收与公开安装的结果分别记入验证历史。

6 - 验证历史

Barn 1.2.0 最终验收 — 2026-11-12

• CI 与打包：源码/Mac CI与完整打包 CI均通过发布提交。标签工作流通过签名配置检查并跳过远端组装；正式发行包按文档中的本机签名流程构建。make release-local、签名、公证、staple 与 Gatekeeper 均通过。
• 最终制品与目录：全部 20 个 draft 附件及 20 个匿名公开下载的大小与 SHA-256 均匹配已核验本地字节。两个官方目录均通过验签、全新数据根激活和内置字节比对，每个镜像源的 17 个 stable 制品通过可达性/大小检查；运行时选用镜像的下载也核验了制品摘要。
• 最终运行时：回下载 Linux 归档通过 18 步 KVM 验收，覆盖 ext4/XFS 根盘扩容、幂等性、拒绝缩盘、客机工具失败、CLI 中断、身份/数据保留、并发与销毁。原生 Mac 回下载载荷完成全部 15 阶段，补充通过桌面、双向剪贴板、关窗后后台运行、SSH 与正常关机检查。一次 Apple HTTPS 超时保留日志，重新核验身份与基底后续跑成功，产品字节未改动。
• 公开交付：darwin/arm64、linux/amd64 均通过公网 latest 与指定版本安装；隔离的 1.1.0 安装器升级及重复安装通过。Homebrew 更新通过真实 1.1.0 → 1.2.0 升级、brew test、style 与严格在线 audit。双语参考按 1.2.0 记录 57 个命令，每种语言含 174 项本地选项。

物理宿主运行覆盖为 darwin/arm64 与 linux/amd64；darwin/amd64 和原生 linux/arm64 完成交叉构建及制品检查。首页历史 1.1.0 录像已明确标注版本。候选升级证据、重试记录及范围限制见完整发布核对。

Barn 1.2.0 发布准备 — 2026-11-12

1.2.0 发布准备核对记录了未提交候选版本的源码、镜像目录、完整 snapshot、Linux/KVM 与原生 Mac 检查，以及随后完成的提交、CI、签名和公开发布门禁。

Barn 1.1.0 最终验收 — 2026-11-09

• 源码与打包：发布提交在打标签前通过源码/Mac CI与完整打包 CI。本地 make check、make mac-native-test 和 make release-snapshot 也全部通过。Tag 工作流通过签名配置检查；仓库未配置自动签名密钥，因此完整发行包按发布手册在本机签名构建。
• 回下载制品：重新下载 draft 的全部 20 个附件，大小与 SHA-256 均与本地原件一致。19 项校验清单、归档/软件包一致性、四平台二进制架构、文件权限、helper 配对与 SPDX 物料清单全部通过检查。Apple 接受公证提交 cabe1b9c-fc54-4f07-b8bf-d834f0226013；下载后的 App 通过签名、票据装订与 Gatekeeper 检查。移入 Homebrew 的 bin/libexec 布局后，CLI 仍能找到匹配的原生组件。
• 镜像目录：两个官方源均通过签名验证、临时数据目录激活及内置字节比对，两个镜像源各自的 17 个 stable 制品均通过 HTTP 可达性与大小检查。最终下载的二进制也在全新的 BARN_HOME 中激活了官方目录。
• Linux 运行时：下载的 linux/amd64 二进制通过 -I d13 -A x86_64 创建 Debian 13 客机，清单文件保持原样。CPU/内存 2/2 GiB → 3/3 GiB → 2/2 GiB 调整、停止/启动、远程参数与退出码 17 均通过检查；VM UUID、SSH 公钥、machine ID 与持久盘数据哨兵在资源调整和重启后保持不变。随后通过 -A aarch64 启动 ARM64 Debian 13 客机，QEMU 使用 TCG 与 cortex-a72，SSH 返回 aarch64。两台测试客机均在验收后删除。
• Mac 运行时：新建的隔离 macOS 27 客机通过创建、SSH、远程退出码 17、停止/启动、身份与数据保留、销毁检查。用户现有 SSH 文件保持不变，原先运行的 Mac 虚拟机继续运行。公开签名安装器在独立目录中的安装与重复安装也通过验证。
• 公开交付：全部 20 个公开附件均可匿名下载，字节与已核验 draft 一致。默认安装器与显式 BARN_VERSION=1.1.0 均安装了公开版本。Homebrew 更新同步了四个平台的归档 URL 与摘要。首轮公开安装录像在 Ubuntu 26.04 上验证了公网安装与首次 Linux VM 启动；当前首页录像展示 Apple Silicon macOS（macOS 27.0.1、QEMU 11.1.3）上的真实 brew install pgsty/infra/barn、./configure -c full、四节点 barn up 与 barn status 过程。随后的 Apple Silicon 16 阶段原地升级与多发行版完整验收记录见 Barn 1.1.0 本机完整验收。

物理宿主覆盖 darwin/arm64 与 linux/amd64，另验证了 TCG 下的 linux/arm64 客机；darwin/amd64 与原生 linux/arm64 的证据范围是交叉构建与制品检查。GUI 和剪贴板保留此前记录的验证日期与范围。早期验收脚本重试修正了不存在的超时参数、需要客机 sudo 的测试写入，以及未接受 thread=multi 选项的 TCG 断言；失败日志与成功结果一并保留。

Barn 1.0.0 最终验收 — 2026-11-05

最终验收记录将下载制品与公开安装检查绑定到以下发布身份：

• 源码与下载制品：最终提交通过源码/Mac CI与打包 CI。自动签名密钥未配置，本轮使用本地 Developer ID 签名流程。20 个上传附件全部重新下载，大小与 SHA-256 和原始制品一致；19 项校验和，以及归档/软件包、CLI/helper 配对、架构、权限、SBOM 与身份核验全部通过。
• 镜像实际字节：两个官方目录验签通过，与内置字节一致；从每个源流式下载全部 17 个 stable 制品，共 34 次大小和摘要检查通过。全新 BARN_HOME 的 barn update 成功激活目录。
• Mac 下载件验收：CLI/helper/App 的 Developer ID、公证、staple 与 Gatekeeper 检查通过，安装后及移动到 Homebrew 布局后再次验证通过。隔离安装器完成 0.9.3 → 1.0.0 升级，保留旧版本及已有 VM 的身份、SSH 密钥和数据哨兵；新 VM 通过 SSH、写入、stop/start、身份/数据保持及销毁检查。
• Linux 实机：下载的 linux/amd64 程序在全新状态目录中创建两台 Debian 13 客机，固定 IP、账号、XFS 数据盘、stop/start/restart、参数边界与远端退出码 17 均通过。清单缺节点时重建在停机前拒绝；删除控制节点后接任成功；destroy 后重新 up 更换机器身份并保留持久盘哨兵。
• 公开渠道：正式发布后，默认安装器与显式 BARN_VERSION=1.0.0 均完成公开安装。真实 Homebrew 从 0.9.2 → 1.0.0 升级，通过 brew test、在线 audit 与 Tap 测试。Tap 更新和站点更新完成发布，公开双语发布页及安装页通过检查。

物理宿主运行覆盖为 darwin/arm64 与 linux/amd64，darwin/amd64 与 linux/arm64 完成交叉构建及制品检查。前一轮候选的 GUI、剪贴板与故障注入实验保留下方原有身份。

加固与候选演练 — 2026-11-04–05

377061c 的加固检查点通过源码检查及不含 Mac 原生载荷的 0.9.4-next 打包快照。随后真机测试从 0.9.4-next 开始，修复后完成定向复测，再构建签名公证的 1.0.0-rc.1，使用目录 2026102802。候选演练覆盖数据盘保留、取消 sudo 后锁释放、共享 networkd 卸载、Mac 15 阶段生命周期、GUI/剪贴板与中断 recreate 恢复。最终发行包随后改用目录 2026110502 和上方正式身份。

记录同时保留失败与成功重跑：短时 SSH 探测需要有界重试，资源不足的构建和共享模块缓存故障需要修正环境，一处验收断言错误地要求成功空输出必须含有 stdout 字段。dm-error 实验在整盘保护分支就被拒绝，尚未进入文件系统检查器。这些观察明确了实际执行过的产品路径，以及属于测试脚本或环境的失败。

Barn 0.9.1 本地候选验收 — 2026-10-22

0.9.1 记录包含通过的 make check、原生组件测试、四平台打包与 ad-hoc 原生载荷。CLI 候选为 0.9.1-dev.1，完整快照为 0.9.1-next；通过本地下载夹具，从真实 0.9.0 归档完成隔离升级，验证重复安装、旧版本保留、helper 配对与 App 发现。Homebrew 检查覆盖 bin/libexec 布局，原生测试和 mac doctor 没有启动 VM。公开 0.9.1 制品只有 CLI/helper 归档与 Linux 软件包，不含 Barn.app；原记录后半的公开发布清单描述后续流程，不能当作已完成的运行证据。

0.9.0 发布前检查点 — 2026-09-29

在 2026-09-29 检查点时，Barn 0.9.0 是完成项目更名后的首个候选发布版本。现行安装方式请参见快速上手。

文档基线

macOS 客机

在 2026-09-29 检查点，barn mac 通过 Barn Mac.app（签名标识 io.pgsty.barn.mac-runner，后于 Barn 0.9.1 统一为 Barn.app / com.pgsty.barn）在 Apple Silicon 上运行 macOS 27 客机，状态独立保存在 $BARN_HOME/mac 下（现行用法见macOS 客机指南与 Mac 命令参考）。

2026-09-29 完成更名后，本地 CLI 与 barn-hosts-helper 单元测试、原生 Bridge/镜像/退出提示/菜单测试、runner 编译、ad-hoc 签名校验与 probe 探测全部通过，与同日早些时候完成的 16 阶段 Mac 真机生命周期验收相衔接。

更名记录明确将更名后构建的证据限定为上述检查，没有重跑 VM 生命周期。2026-10-03 的归档更正保留原有日期、版本、提交与测试范围，没有把更早的 VM 实验归到更名后构建。

0.9.0 发布前待收口项

在 2026-09-29 检查点，正式公开 0.9.0 前剩余的门禁项包括：

• 最终发布标签提交上的完整源码测试、四平台归档、DEB/RPM 软件包、安装脚本与跨平台检查。
• 新名称下的全新宿主环境准备、Linux/macOS 虚拟机生命周期与卸载清理复核。
• macOS 原生组件的 Developer ID 签名、公证与发布。
• GitHub 仓库、Homebrew Tap、两地 /barn 官方镜像源与 barn.pgsty.com 公开可用性核验。

早期 Mac 实现记录

• 2026-09-26–27：初期实现日志记录完整 IPSW 下载与 CLI 恢复安装、基础镜像不变性、双客机生命周期及安装器拒绝篡改包。最终 12 阶段流程耗时 140.305 秒，起点是已经初始化的客机，使用退役的固定槽位/共享网络实现及 ad-hoc 开发签名。
• 2026-09-28：复杂度复核在简化实现时保留身份、锁与恢复保护，并验证就绪检查不重写 SSH 材料。首轮关机超时与客机高负载同时出现，随后完整重跑通过，没有强制断电或调整超时；记录将高负载保留为观察，没有将其认定为根因。

Barn Mac 实机记录：2026-09-29

2026-09-29，更名前的开发源码在搭载 Apple Silicon、运行 macOS 27.0（26A428）的 Mac 上使用 ad-hoc 签名构建完成全套实机验证；测试复用 2026-09-26 基于 Apple 27.0 恢复镜像准备好的基础镜像 APFS 克隆：

• 源码与组件包检查：完整 make check、原生 Swift 组件测试，以及应用包构建、解包校验和、代码签名与 probe 检查全部通过。
• 16 阶段自动化真机验收（耗时 244.9 秒）：覆盖从基础镜像创建虚拟机、带 VirtioFS 共享目录的命名虚拟机、独立机器标识与 sshd 策略、磁盘隔离、每台虚拟机独立的子网隔离、DNS 与公网 HTTPS、退出码透传、exec 参数边界、共享目录双向读写、正常 stop/start、configure、拒绝启动第三台并发虚拟机、recreate 重置身份、打开桌面窗口、双向纯文本剪贴板同步、重复 up 幂等性以及 destroy。
• 人工计时与恢复验证：从已准备好的基础镜像创建虚拟机到 SSH 就绪耗时 22 秒，正常关机耗时 6.5 秒，二次启动到 SSH 就绪耗时 6–12 秒，强制断电耗时 0.7 秒。同时验证了引导进入 macOS 恢复模式（--recovery）、更换 --subnet 后保持固定 SSH 主机密钥，以及通过已安装的 ~/.ssh/barn-mac_config 直接执行 ssh mac1。

当时留待后续里程碑验证的事项：

• 原生应用包的 Developer ID 签名、Apple 公证与公开发布。
• 通过 CLI 从零下载 IPSW 并准备基础镜像（无基础镜像时首次 barn mac up 或 barn mac image update）。
• 桌面窗口菜单中的 Restart… 与 Shut Down… 动作、更多 Apple Silicon 机型以及物理宿主重启验证。

同一份具名机器记录还包含稍后的 07ebfd4 候选重跑：首轮五秒 SSH 探测失败、后续观察恢复应答后，全部 16 阶段在 298.9 秒内通过。两次都复用了已有 26A428 基底，该检查点未覆盖从零下载与恢复安装。

更名前的 Linux 验证概览

在 0.8.0 四机验收中，每台宿主均实测了 Rocky Linux 9.8/10.2、Debian 12.15/13.7 与 Ubuntu 22.04.5/24.04.5/26.04.1（共 28 个客机实例全部通过，验收后已清理测试虚拟机）。两个公网端点提供的镜像目录 2026092001 摘要均为 23e8dbf6c19bd192d56c6d71eb30901f17945b3487e427a43abe108463780306，并通过了隔离客户端 barn update 验签以及 10 个新增镜像对象的 HTTP HEAD 长度核对。

当时待补充的测试覆盖

• 启用 NetworkManager + firewalld 的 EL9 宿主，以及最新 systemd-networkd 宿主重放。
• 物理宿主重启后的部署状态保持。
• darwin/amd64 与 linux/arm64 宿主的真机虚拟化运行（除交叉编译与打包检查外）。
• linux/amd64 原生 el7 完整生命周期重放。
• 完整 Pigsty configure → barn up → install.yml 部署流程。
• 通过公网安装脚本、Homebrew Formula 或已发布 DEB/RPM 软件包在全新宿主上从零执行 setup 与创建虚拟机。

Barn 历次版本验证记录

Barn 0.8.0 — 2026-09-21

• 发布 CI 与公开制品：标签 v0.8.0（320a32afa8f6fca02592215aa0d5607ca4e852b2）通过源码 CI、打包快照工作流与标签发布工作流，产出 20 个发行资产（含 19 项校验和载荷）。全部 20 个公开资产通过匿名下载与 SHA-256 校验，公网安装脚本在 darwin/arm64 与 linux/amd64 的隔离用户目录中成功安装并验证 0.8.0（320a32a）。
• Homebrew Tap：提交 9c34019 将四平台 Formula 更新至 0.8.0，通过本地 brew fetch、audit 及 Tap CI。
• 四机七系统真机验收：在基线提交 6d7870e26cb2f4082a00c188f746783fc027687e 上清空四台宿主（两台安装 .deb 的 Linux amd64 宿主 m0/m3，两台使用校验归档安装的 macOS arm64 宿主 m1/m5），从局域网镜像源从零拉起七系统 pro 清单。随后将包含 Homebrew 认证顺序修复的候选提交 1c054a027420b5410c6f6feb344e27e001ae1af1 原位更新到四台宿主，验证幂等 up（保持 QEMU 进程、VM UUID 与磁盘 inode 不变）、两轮客机 SSH、stop/start、/data 数据盘读写、Debian locale/XFS、控制节点到各节点 SSH 以及 Ansible 配置读取（两台 Mac 额外跑通 7 节点 ansible all -m ping）。详细计时样本见 0.8.0 发布说明。

Barn 0.7.0 — 2026-09-16

• 发布 CI 与公开制品：提交 9c6d4896d93733d1cb60a7e5d8591e9a06659c9d（v0.7.0）通过源码 CI、打包快照工作流与标签发布工作流。全部 20 个公开资产通过匿名下载与摘要核验，darwin/arm64 与 linux/amd64 公网安装脚本验证通过，pgsty/infra/barn Formula 通过本地升级与 brew test。
• Ubuntu amd64/KVM 存储与中断恢复矩阵：实测损坏的 ext4/XFS 数据盘自动重置（3.2 秒恢复并保留运行中 QEMU 进程）、recreate 保留持久盘、探测失败与忙碌挂载保护（保留原有数据与磁盘 UUID）、只读 9p 共享降级回退，以及在 3.3 秒内接续恢复一台此前因出网探测失败而中断的 0.6.0 虚拟机（由于 0.6.0 已清理暂存的控制节点私钥，恢复后按预期报告 control-ssh 告警，详见 0.7.0 发布说明）。镜像目录保持 2026090501。

Barn 0.6.0 — 2026-09-05

• 发布 CI 与公开制品：完成生命周期、命令交互、发布元数据与 CI 测试夹具审查后，提交 057774e3a13477782a2ae07bd71127d03c0f1ae7（v0.6.0）通过 Go 1.27.1 源码 CI、打包检查（13d9d70）与标签工作流，生成并校验全部 20 个发布资产。在 darwin/arm64 隔离目录中验证了从 0.5.0 升级至 0.6.0、barn init 与 Ubuntu 24.04 barn plan。
• macOS arm64/HVF 生命周期验收：验证首次启动、不重启控制节点的在线扩容、控制节点到同伴节点 SSH、stop/start、reload、局部 recreate、缩容、客机 /etc/hosts 刷新、无效镜像 reload 与冲突局部 recreate 的停机前拦截、部分节点异常时的 status 展示，以及 SSH 退出码 255 原样透传。
• 镜像目录 2026090501：将默认镜像切换为 u24:stable，合并 2026090302 的 Debian/Rocky 更新，全部 27 个产物通过字节校验并在两个官方端点完成隔离客户端 barn update 验签。

Barn 0.5.0 — 2026-09-03

提交 fc85b65ff6a24b0933b56ae1179be9ada2ba91b1（v0.5.0）通过 Go 1.27.1 源码门禁与 GoReleaser 打包检查并发布 20 个预发布资产。0.5.0 新增无需确认的整套部署清理命令 barn purge，将全球默认镜像源设为 https://repo.pigsty.io/barn 并提供 --mirror 切换 https://repo.pigsty.cc/barn，移除镜像下载时的隐式上游 URL 回退，并新增锁定摘要的八目标 Debian/Rocky 官方候选镜像构建脚本 build-official.py。

Barn 0.4.0 — 2026-09-02

通过 make check 及发布工作流的归档、DEB/RPM、SBOM、校验和、安装脚本与 Homebrew Formula 门禁。barn up 支持在未初始化的交互式终端宿主上自动引导执行 setup，vm_disks[].fs 默认值改为 auto，客机就绪失败报错附带最后一行错误详情，并统一了全命令行的输出样式。

Barn 0.3.0 — 2026-09-02

通过 make check 及全部发布打包门禁。将镜像目录刷新改为显式的 barn update 与 barn image sync 操作，并在客机就绪失败时输出各节点所处阶段与对应的 barn logs 排查命令。

Barn 0.2.0 — 2026-09-01

提交 59d1b62aebb3d044a317e4006cc8a0bf56f4feaf（v0.2.0）通过源码 CI、打包工作流及本地四平台归档、DEB/RPM 与 SPDX 校验。darwin/arm64 HVF 真机重放验证了选定节点 u24-1 的创建/SSH/停启、已缓存 el9-1 的增量创建、包含未创建节点的全局 status，以及全局 destroy 与 SSH 配置片段清理；Ubuntu 26.04 amd64/KVM 验证了存量四节点部署的状态审计与控制客机连通。

Schema-3 镜像目录收口 — 2026-08-29

镜像目录 2026082903（9 个系列、27 个产物，SHA-256 571b1ff9c7d4d42355df3392ea62a339471c2d01d868669a7625fac8b93f245d，生产公钥 4686B39A40F9B562 签名）通过了内置目录与公网端点逐字节比对、全部 27 个 qcow2 文件（共 19 GiB）全量 SHA-256 扫描，以及 darwin/arm64 空白客户端拉取 d13:stable（409.3 MiB）与 qemu-img 结构检查。

0.1.0 候选验证 — 2026-08-28 与 2026-08-29

在 0.2.0 发布前验证了两项关键修复：

• QMP 套接字局部恢复：在 darwin/arm64 四节点环境中，当其中两台运行中节点的 QMP 套接字被外部删除后，Barn 仅重启受影响的两台节点（13.7 秒恢复就绪），其余两台正常节点的 boot ID 保持不变。
• 无 QEMU 环境下的目录查询：消除了 barn image list 与源码测试在不校验本地 qcow2 缓存时对 qemu-img 的依赖，使 make check 在未安装 QEMU 的纯净机器上即可跑通。

EL7/EL8 兼容性恢复 — 2026-08-28

提交 7c666c7 修复了破坏性操作前的运行时预检顺序与签名镜像目录基线迁移逻辑，补充回归测试并恢复了 el7/el8 支持。镜像目录 2026082801（9 个系列、17 个镜像产物及 2 份 socket_vmnet 归档）通过全量 SHA-256 与签名校验；darwin/arm64 隔离重放通过内置 TCG 兼容规则启动 Rocky Linux 8.10 arm64，stop/start 后在 44.2 秒内达到就绪状态，验证了 NetworkManager、固定 IP、dba UID/GID 88 与客机初始化标记。

真机重放基线 — 2026-08-27

在 darwin/arm64 与 linux/amd64（mx）两台宿主上验证了固定 IP、SSH 就绪、默认 CPU/内存/根盘/数据盘、cloud-init、stop/start、跨目录命令执行、扩容期间保持控制节点 boot ID 不变、控制节点到同伴节点 SSH、忽略非 Barn 管理的 Pigsty 字段变更，以及仅在显式 destroy 时删除虚拟机。Linux 宿主额外验证了免密 sudo 自动化、Debian qemu-bridge-helper 用户组授权、普通用户 QEMU 挂桥测试、挂有四个 tap 接口时拒绝卸载网络，以及 destroy 后精确还原宿主状态。

7 - Barn 0.9.3 变更

本页记录 Barn 0.9.3（2026-10-31）中已经发布的用户可见变更。路径、共享与工作流调整始于源码提交 27f17bb，其余恢复与资源变更在后续提交中完成。核对其他构建时请使用 barn version。

升级摘要与完整双语说明见 Barn 0.9.3 发布说明。

资源调整与中断恢复

修改 vm_cpu 或 vm_mem 后执行 barn resize [node...]。运行中的虚拟机有预留容量且 QEMU 后端支持时，增加的资源会热插拔；减少资源、旧虚拟机或不支持的后端会自动停机再启动。虚拟机身份、磁盘与 SSH 密钥保持不变。resize 会拒绝镜像、磁盘、网络、共享目录、创建、删除和部署级变更，应根据 next: 字段使用 recreate、up、destroy 或完整的选择操作。

Linux 与 macOS 的生命周期、持久盘及替换操作会记录转换状态。进程被中断或收到 SIGINT、SIGTERM 后，下一次生命周期命令可以继续恢复；取消的命令返回结构化的 cancelled 结果。在 macOS 上，barn mac up --no-wait 在虚拟机进程启动后返回，首次启动的 SSH 与 sudo 初始化可能仍在进行；请再次执行 barn mac up NAME 等待就绪。

路径

barn init 与 setup 支持通过目录符号链接工作，init -o ./lab/config/barn.yml 还会自动创建缺失的父目录。覆盖已有文件仍需 --force，写入不会跟随或替换输出文件本身的符号链接。

用户传入的路径支持常见开发目录布局：

命令行相对路径以当前工作目录为基准，相对 BARN_HOME 也遵循这条规则。跨目录操作同一部署时，请使用绝对 BARN_HOME。Barn 仍拒绝将 / 或用户主目录作为数据根目录，并校验受管状态的属主与结构。归当前用户所有的 ~/.ssh 目录可以通过目录符号链接访问；若 ~/.ssh/config 本身是链接，仍需手动添加 Include。

共享目录与挂载路径

Linux 客机使用 QEMU Virtio-9p，现已支持 macOS 与 Linux 宿主，但 QEMU 和客机内核均须支持 9p。原生 macOS 客机继续通过 barn mac --share 使用 VirtioFS。

• Linux 共享源按当前用户的实际文件系统权限访问，可归其他用户所有、与其他源重叠，或由多个客机同时读写。并发写入由用户协调，与多个宿主进程共用目录相同。
• 宿主源路径支持空格、Unicode 与逗号。Linux 客机挂载路径会自动规范化，并正确转义 Shell 命令与 fstab 中的空格、Unicode 和 Shell 标点。
• Mac 共享名称支持空格与中文，须为 1–255 字节的有效 UTF-8，不能是 .、..，也不能含 / 或 ASCII 控制字符；共享源支持目录符号链接。
• 移除 8 个共享的固定上限，实际仍受后端设备与宿主资源约束。Linux 共享源不能与 BARN_HOME 重叠，客机挂载目标不能与其他目标、系统目录、数据盘挂载点或客机 SSH 目录重叠。

Linux 共享示例见存储与访问，原生 macOS 共享见 Mac 命令。Barn 不会为了让共享可写而修改宿主文件属主。

仅应用选定节点的变更

显式选择节点执行 plan、up、reload 或 recreate 时，其余节点保留已应用定义，即使当前清单已修改或省略它们。未创建且未选中的节点不要求解析镜像，因此可以一次编辑多个节点，再分批应用：

barn plan node-1 -f barn.yml
barn recreate node-1 -f barn.yml
barn plan node-2 -f barn.yml

整份清单仍须通过语法解析。与已应用节点的地址、别名、控制节点角色或部署公共设置发生冲突时，Barn 会在停机删盘前报错。不传选择器时仍检查整份清单，删除 YAML 条目不会自动删除虚拟机。操作流程见日常管理。

生成模板时选择镜像

barn init [模板] --image <引用> 会把显式的 vm_image 写入 all.vars，让所有生成节点继承该镜像。准备生成模板时，barn setup [模板] --image <引用> 也采用同样的行为。引用可以是镜像别名、频道或版本选择器；该参数不会下载镜像。通过 -f 指定或自动发现的已有清单不会被此参数改写。

镜像与开发工作流限制

Provisioning 仍默认串行、超时一小时，每个节点分别最多捕获 1 MiB 的 stdout 与 stderr。这些用户参数与内部虚拟机启动调度并发是不同的设置。镜像摘要、声明大小、qcow2 结构、持久盘兼容性及进程身份仍需通过校验；贡献者镜像流水线也保留自身的配方边界。

8 - Barn 1.1.0 本机完整验收

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

环境与证据

• 宿主：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 私钥。桌面通过原生应用界面验收，截图在本次验收聊天中；剪贴板结果见下文。

执行顺序

判定与重试

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

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

结果与回放

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

阶段结果

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

镜像矩阵

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

强制终止后的就绪标记问题

在 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、对端节点和持久数据均保留：

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 的 就绪探测 和 初始化重试入口。

未完成的检查

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

本地证据

证据目录为 ~/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 参数和错误分类等剧本修正均保留初次录像及后续重试。完整记录存放在本机，本站只保存这份验收说明。