关于 Barn

• 1: 设计
• 2: 当前状态
• 3: 工程与发布

1 - 设计

一个有用的抽象

Barn 把一份 Pigsty Inventory 启动成一套本地 QEMU deployment。它刻意不再拥有 project marker、项目注册表、租约模型、Provider Layer 或第二种配置格式。

状态位于当前 Unix 用户的 BARN_HOME（默认 ~/.barn）。产品假设每台电脑只有一套运行中的 Pigsty； 这并不是 root 强制的跨用户单例。

节点级收敛

Barn 只提取已记录的 VM 与 Pigsty 原生字段，计算逐节点哈希，并保存应用状态与完整 进程身份。新增节点增量创建；up 也会启动选中的已停止节点，保留运行中同伴的进程， 同时重试未完成的初始化、刷新托管 hosts 与 SSH 配置。无法识别或确认损坏的测试数据 文件系统可能被清空重建，包括持久盘，详见数据盘。 定义变更需要显式节点重建；配置缺席永远不授权删除。

运行时选择

Guest 架构是部署级期望状态。省略或 native 跟随宿主；显式 amd64/arm64 会准确 选择对应 Catalog 工件。HVF/KVM 原生加速仍是默认路径；外来架构或 Catalog 已知的 镜像/宿主不兼容规则才会选择固定 TCG Profile。没有用户可传的 Accelerator 参数，也不会 因任意原生失败静默回退。

实际架构与加速器保存在每个 QEMU Invocation 中，并通过 status 展示。执行破坏性 recreate 前，Barn 会证明所选 QEMU 二进制与版本、网络后端、镜像字节、启动模式与固件。 以后若新二进制改变运行时策略，也不能把新旧节点混跑：Runtime Drift 必须整体重建。

双网卡与一个固定子网

管理网卡负责 DHCP、DNS、出网与回环 SSH；固定 IP 网卡负责宿主、节点间与 Ansible 流量。macOS 使用 socket_vmnet；Linux 优先跟随当前 NetworkManager，否则使用 systemd-networkd，并通过发行版 bridge helper 接入。若 networkd 尚未启动，只有在 Activation-safety 扫描证明现有 Unit 不会接管真实宿主链路后才启动。

Debian helper 会临时、可逆地限制给调用者真实加入的组。setup 必须通过一次非特权 QEMU bridge smoke；失败后自动回滚安装。

存储与配置有不同生命周期

Inventory 保存期望的 VM 定义；应用状态记录已经创建的内容，包括精确基础镜像身份与 运行时 Invocation。Catalog Channel 移动不会改写已有根盘。

通过校验的基础镜像只读共享，每台 VM 写入自己的根盘 Overlay。数据盘遵循独立的保留 契约：普通 Destroy 保留持久盘，显式磁盘删除或 Purge 才清除它们。镜像缓存清理又有 独立边界，还会保护活动 Catalog 与已注册本地别名。详见存储与访问 和镜像参考。

安全边界

QEMU 与所有 Guest 工件都以调用者身份运行。root 仅用于宿主软件包安装、网络与可选 hosts publisher。 销毁必须同时匹配属主、路径包含、节点身份、QMP/进程身份与工件白名单；任何歧义都会停止。

2 - 当前状态

Barn 0.9.0 是尚未发布的候选版本。源码检查、本地构建、软件包、CI、发行和线上文档 分别核验。安装方式见快速上手。

文档基线

最终发布提交、制品摘要与安装渠道将在完成发布和下载核验后记录。

macOS 客机

barn mac 在 Apple 芯片上运行 macOS 27 虚拟机，见教程与 命令参考。组件名称为 Barn Mac.app，签名标识为 io.pgsty.barn.mac-runner，状态独立保存在 $BARN_HOME/mac。

2026-09-29，本地 CLI/hosts-helper 测试、原生 Bridge/镜像/退出提示/菜单测试、runner 编译、 ad-hoc 签名验证与 probe 通过。这些检查没有启动 VM，不代表完整 Mac 实机生命周期验收。

发行前仍需核验

• 最终 Barn 提交的完整源码、归档、DEB/RPM、安装器与跨平台检查；
• 全新宿主准备、Linux/macOS VM 生命周期与清理；
• Mac Developer ID 签名与公证；
• Barn 0.9.0 的发布与下载核验，包括 Homebrew。

Linux 镜像 Catalog：2026-09-29

两个官方 /barn 入口均已发布签名 Catalog 2026092902：9 个系列、39 个工件。 经过规范化的 Debian 与 Rocky Linux 镜像，其内部配置与元数据统一使用 Barn。

6 个 Debian 13、Rocky Linux 镜像通过 UEFI 启动、SSH、双网卡、UID/GID 88、Python、 cloud-init 与 XFS 数据盘检查。amd64 使用 KVM，Debian 13 和 Rocky Linux 9 arm64 使用 HVF；Rocky Linux 8 arm64 因上游 64 KiB 内核不兼容 Apple HVF，使用 TCG。 Rocky Linux 8 使用自带的 RHEL chrony 模板和 chronyd 服务。

Debian 12 与 Ubuntu 镜像通过原生 KVM/HVF 启动、SSH、双网卡、UID/GID 88、locale 和 XFS 数据盘检查。Debian 镜像包含锁定版本的 XFS 工具与 en_US.UTF-8，默认 locale 保持 C.UTF-8；Ubuntu 保留 Canonical 原始字节。镜像检查采用隔离的 QEMU user 网络， 完整宿主网络及 VM 生命周期仍需独立验收。

内嵌与公开 Catalog 字节一致，两个官方入口均通过签名校验，新镜像通过公网下载检查。 版本选择与更新行为见镜像参考。

3 - 工程与发布

本页描述 Barn 0.9.0 发布候选。构建命令使用当前工作区，请同时记录提交与 未提交变更。源码构建和本地检查通过不代表已经正式发布。

仓库边界

Barn 源码仓库包含代码、测试、构建/打包定义、法律声明、README.md、CHANGELOG.md、 CONTRIBUTING.md、SECURITY.md 与双语应用发布说明。本网站提供用户、设计、运维 与发布文档。运行行为和命令参数需要以匹配的源码及二进制核对；未发布源码的行为不能 代表公开软件包。

Review 记录、临时 Inventory、生成二进制与 Release 输出树不是生产源码输入。

以下输出随时可重建：

• bin/：开发构建；
• dist/ 与 .goreleaser-*：Release/Snapshot Staging；
• 根目录 barn、barn-hosts-helper、catalogsign 二进制；
• Hugo 的 public/ 与 resources/。

构建与源码门禁

make check

make check 包含模块与 Shell 检查、维护脚本归属、单元/Race 测试、Vet、Staticcheck、 死代码与 errcheck 检查、漏洞扫描、四目标跨平台构建、安装器/镜像流水线测试及许可证 检查，准确清单以 Makefile 为准。CI 还单独检查固定工具链、Go 格式、空白与 GoReleaser 配置。质量工具安装步骤见从源码构建。

打包逻辑变更还需要独立 Snapshot 门禁：

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

安装 packaging/toolchain.env 指定的 GoReleaser、nFPM、Syft 等版本；Snapshot 还需要 验证脚本使用的归档与系统软件包检查工具。输出必须是工作区根目录下尚不存在的新目录， 已有目录会被拒绝。Snapshot 仅在本地生成，不上传 Release。

源码检查不等于真机验证。macOS HVF、Linux KVM/网络、软件包消费、Release 发布与 线上网站渲染需要分别验证。make image-pipeline-native-test 是独立真机镜像流水线 门禁，需要 QEMU/libguestfs 与显式镜像输入。必填的 BARN_IMAGE_PIPELINE_NATIVE_* 变量见 tests/image-pipeline-native-test.sh， 该测试不会下载镜像。

Release 与软件包契约

packaging/、.goreleaser.yaml 与 .github/workflows 属于源码；它们生成的目录不是。 Archive 与 Linux Package 携带配套 CLI 和 hosts-helper 二进制、LICENSE、源码 README，以及根据 go.mod 锁定模块版本重建的准确上游许可证字节。Archive 的二进制 位于 bin/、许可证位于 licenses/；Linux Package 安装 /usr/bin/barn、 /opt/barn/libexec/barn-hosts-helper，文档位于 /usr/share/doc/barn/。

Linux Package 包含 BUILD_INFO.json。GoReleaser Archive 的构建身份在二进制中，发布元数据随资产单独提供，不能假定每种 Archive 都包含 该文件。依赖许可证在构建时生成暂存，详细用户文档保留在本网站。

应用 Release 由 GitHub Actions 构建，提供 checksums.txt、发布元数据与 SPDX SBOM 资产。当前工作流不生成单独的应用发布签名或 provenance/attestation 包。用于认证镜像 Catalog 的 Minisign 签名属于另一套信任机制。

Commit、Tag、归档/软件包验证、CI、草稿上传、公开发行与匿名下载验证应分别记录。 Tag 工作流创建草稿，不会直接发布。pre-1.0 版本在 GitHub 标记为预发布，安装器需要 显式指定 BARN_VERSION。

make release-local VERSION=<version> 在本地构建并验证，不执行发布。它要求干净 工作区正好位于对应 v<version> Tag，配置 origin，使用固定工具，并且暂存/输出 目录尚不存在。未打标签的候选版应使用 Snapshot 路径审核。

镜像归一化

底层 packaging/image-pipeline/build.sh 只接受显式本地 qcow2，不下载也不上传。它复制并 哈希源文件，强制 qcow2 解析，拒绝 Backing/External/Encryption/未知 Feature，运行 qemu-img check，并可在显式 QEMU Sandbox 中做无网络 Offline Guest Mutation。 UID/GID 88 冲突会拒绝，不会含糊改写。

build-official.py 为 Debian 12/13、Rocky Linux 8/9 的 amd64/arm64 目标增加固定、 摘要锁定的 Wrapper。它只允许获取锁定的源镜像与离线软件包输入，输出未签名的 testing Candidate，并可组装独立候选仓库。真机 Smoke、双构建比较、生产签名、上传与 Catalog 激活仍是后续门禁。

Catalog 逐字节导出命令：

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

导出器原子写入，拒绝已存在的输出路径。make catalog-sign 与 make catalog-verify 使用 Catalog Minisign 密钥对，生产私钥不进入源码或 CI。应用 checksum 不能替代 Catalog 签名。

证据纪律

设计说明实现取舍，当前状态记录验证结果。每条状态结论应说明 日期、宿主、路径与剩余检查；源码变更需要相应验证。