镜像

Barn 使用物化的静态 Catalog 与不可变 qcow2 工件。官方与 HTTP Catalog 必须签名； 用户显式选择的本地或 HTTPS 仓库可以不签名。更新 Catalog 不需要发布新的 Barn 二进制，但二进制决定信任哪些签名公钥与镜像安全规则。

别名与拉取顺序

Barn 0.9.0 内置 Catalog 2026092902，包含 9 个 Family、39 个工件。el7 只有 amd64，其余 Family 均有 amd64 与 arm64。 EL9 包含 9.3、9.6、9.7、9.8；EL10 包含 10.0、10.1、10.2。 默认请求为本机架构的 u24:stable（Ubuntu 24.04）。

以下 stable 均覆盖 amd64 和 arm64。这是内置 Catalog 快照，不是实时仓库列表。 运行 barn update，再用 barn image list 查看选定仓库当前的目录。带日期的公开 端点检查与 Guest 小版本观测见当前状态。

Debian 保留离线安装的 XFS 工具和已生成的 en_US.UTF-8，默认 locale 仍为 C.UTF-8。Ubuntu 保留 Canonical 原始镜像，账户与网络由启动时的 cloud-init 配置。 Debian 12 的 9 月 23 日上游构建仍缺少 XFS 工具和 en_US.UTF-8，这两项定制仍然 必要。上述 Ubuntu 原版已包含二者，amd64、arm64 均于 9 月 29 日通过 locale 和 XFS 数据盘检查。 更新 Catalog 只改变新解析的 stable；既有 VM 和显式锁定版本继续引用原来的基础镜像。

barn image list
barn image info d13
barn image info d13:stable
barn image info el9@9.7
barn image pull d13@20260914.2601.2
barn image pull d13 --arch arm64
barn update

Catalog 状态只表达支持策略，不是启动开关：supported 表示已通过声明的支持门禁； testing 可在显式测试/风险接受下使用，但不受支持；deprecated 只为 EOL 兼容保留； unknown 尚无支持分类。非 supported 条目仍可运行，但会打印警告。

拉取时 Barn 会：

1. 为整条命令读取一次选定仓库的本地 Catalog：即本次构建内置的 Catalog，或最近一次 为该仓库通过 barn update/image sync 激活的 Catalog；
2. 解析 image[:channel] 或 image@version-prefix，官方 Catalog 缺省为 u24:stable； 独立 image pull 默认使用本机架构，可通过 --arch 覆盖；生命周期解析遵循 vm_arch；
3. 只有尺寸、SHA-256、qcow2 结构全部匹配时才复用本地文件；
4. 否则下载 Catalog 指定的准确工件，并支持重试和断点续传；两个官方仓库可互相回退， 自定义仓库仍为唯一来源。接受的字节始终须匹配 Catalog；不可变 Upstream URL 只用于溯源。

Release 构建默认使用 https://repo.pigsty.io/barn；仅有长参数的 --mirror 选择 https://repo.pigsty.cc/barn。优先级依次为 --repo、--mirror、BARN_REPO、 全球默认仓库，两个官方根都保持规范的签名 Catalog 信任。仓库选择同时决定本地 Catalog 槽位和下载来源；即使字节已缓存，仍需选择相同的自定义仓库。Barn 不会自动刷新 Catalog，已有激活目录与已校验缓存时，普通镜像解析可以离线进行。 运行 barn update 可获取、校验并激活选定 仓库当前的 Catalog。Catalog 更新使用该指定源，失败时直接报错；镜像下载则在所有 允许的来源均无法提供通过校验的字节时失败。 仅改变 --repo 不会获取或激活该仓库的 Catalog；使用它的自定义别名前，先运行 barn update --repo <root>。

已校验但可写的缓存文件会恢复为只读；损坏且未被引用的缓存会先保留为带 .corrupt-<timestamp> 后缀的文件，再重新下载。仍被 VM 引用的基础镜像保持原位并报错。

运行时策略

匹配架构正常使用原生 HVF/KVM，只有一个 Catalog 已知例外：Stock EL8 arm64 的 64K Granule Kernel 无法通过 Apple HVF 运行，因此 Apple Silicon 会自动选择可见的同架构 TCG。显式外来 vm_arch 也会使用 TCG；arm64 宿主上的 amd64 Guest 使用单翻译线程， 以保留 x86 内存序。TCG 结果不能作为性能证据。

EL7 刻意仅支持 Linux/amd64 原生运行。Linux setup 只安装宿主原生 QEMU；外来架构必须 先安装对应 System Emulator 与 UEFI 固件，up、recreate 才会继续；plan 无需 这些工具就能解析 Catalog 镜像与运行时；但 local-* 命名导入在解析时会检查缓存字节， 仍然需要 qemu-img。

barn image pull d13 --mirror
barn image pull d13 --repo https://mirror.example/barn
BARN_REPO=/absolute/local/repository barn up

未签名仓库必须是本地路径或 HTTPS。HTTP 仓库必须提供可信密钥签名；不可变 Upstream 工件 URL 必须使用 HTTPS。

信任与校验

当前普通构建已经内置两把生产校验公钥；私有签名密钥不在源码仓库中。Catalog 激活会拒绝 未知密钥、畸形内容、同 Revision 异内容，以及低于该仓库独立 High-water Mark 的 Revision；只有操作者显式允许时才可降级。

镜像必须是尺寸与 SHA-256 匹配的纯 qcow2，不得有 backing file、外部数据文件、加密或 未知不兼容 Feature。通过校验的 Base Image 变成只读；节点根盘使用 Overlay，永不修改 Base。

barn update
barn image sync --repo https://repo.example/barn \
  https://repo.example/barn/catalog.json
barn image sync --repo /absolute/repo --allow-downgrade /absolute/repo/catalog.json
barn image reset

image reset 恢复二进制内置的 Catalog，但不会清除防回滚 High-water Mark。

barn update 立即检查仓库并激活更新的 Catalog。Barn 不会自动刷新 Catalog；每个版本 内嵌的 Catalog 会一直使用到你运行 update。image sync 是指定精确 URL 或文件（含降级）的 恢复路径。

按仓库恢复时要显式传入同一个根目录：

barn image sync --repo /srv/barn --allow-downgrade /srv/barn/catalog.json
barn image reset --repo /srv/barn

--repo 决定独立的活动 Catalog 与 High-water 槽，位置参数中的源不会改变这个选择。 image sync、image reset 接受 --repo，不接受 --mirror；省略 --repo 时使用 BARN_REPO 或编译期默认值。未签名自定义 Catalog 的精确源必须是选定根下的 catalog.json。

静态仓库格式

发布根刻意保持很小：

barn/
├── repo.yaml
├── catalog.json
├── catalog.json.minisig       # 官方与 HTTP 仓库必需
└── images/
    └── <image>-<version>-<arch>.qcow2

repo.yaml 保存人工意图：默认值、别名、Channel、精确版本、架构、启动模式、状态和可选、 只用于溯源的 Upstream URL。source_user 记录镜像声明的源登录身份，例如上游镜像的 rocky，或经过 Barn 官方归一化后的 dba。流水线清理候选镜像时另行接收上游账号。 Catalog/导入元数据不会替换 deployment SSH 用户（默认 dba），也不会自行归一化镜像。 该文件不保存任何生成的摘要或大小；catalog.json 保持同一逻辑树， 但为每个 Variant 物化文件名、SHA-256、工件大小和虚拟大小。repo.yaml 是 schema: 1； 生成的 catalog.json 则是 Barn 内嵌并签名的 Schema-3 Catalog。

schema: 1
revision: 1
defaults: { image: u24, channel: stable, arch: native, boot: uefi }
images:
  u24:
    aliases: [ubuntu24, noble, ubuntu]
    channels: { stable: "1" }
    versions:
      "1":
        status: unknown
        variants:
          amd64: {}
          arm64: {}

不显式设置 file 时，两个预期工件分别是 images/u24-1-amd64.qcow2 与 images/u24-1-arm64.qcow2；已有自定义文件可在 Variant 中覆盖为安全 basename。

Channel 与数值前缀都是可移动 Selector。存在精确 Key 时优先精确匹配；否则只在点分量 边界匹配并选择数值语义最新版本（el9@9.7 选择最新 9.7 Build，el9@9 选择最新 9.x Release）。不可变工件身份仍是 (image, exact version, arch)：

d13:stable + native
  -> d13@20260914.2601.2 + arm64
  -> images/d13-20260914.2601.2-arm64.qcow2

barn repo scan 只读；build 执行严格 YAML 校验、完整 qcow2 inspect/check， 并原子替换 Catalog，永不修改 repo.yaml 或 QCOW 字节；verify 要求新鲜物化结果与 现有 Catalog 逐字节一致。build、verify 需要本机 qemu-img，scan 不需要。 应在安装 QEMU 的机器上构建，先发布不可变工件，最后发布 Catalog 与匹配签名，尽量 一起切换两者；正文与签名不一致时验签会失败。 修改 Catalog 内容时必须增加 revision。

本地布局与导入

镜像位于 BARN_HOME/images（默认 ~/.barn/images）：各 Family 目录保存下载工件， manifests/ 保存当前激活的 Catalog 与每个仓库独立的 High-water 状态，local/ 与 local-images.json 保存导入镜像。

barn image import --sha256 <digest> /path/to/base.qcow2
barn image import --name local-mybase --boot uefi \
  --source-user ubuntu --sha256 <digest> /path/to/base.qcow2

CLI 中 --sha256 是可选参数；提供独立获得的可信摘要，才能在必做的 qcow2 检查之外加入 显式真实性校验。导入只复制和校验文件，不会清理凭据、安装 cloud-init、识别 Guest CPU 架构或证明镜像可启动。

命名本地别名必须以 local- 开头，避免未来签名 Catalog 遮蔽它们。--name、--boot、 --source-user 必须同时提供。命名导入记录执行导入的宿主原生架构，没有 image import --arch 参数；外来架构镜像应使用声明明确 Variant 的静态仓库。 别名不可变，镜像字节或元数据改变时应使用新名字。在 Inventory 中通过 vm_image: local-mybase 选择命名导入；不指定名字的导入只填充缓存。

清理

barn image prune --dry-run
barn image prune --yes

不带参数的 prune 与 --dry-run 只报告候选，--yes 才执行删除。保护集合是选定活动 Catalog 中的全部工件、已应用节点的镜像摘要，以及注册的本地别名。因此，即使没有 VM 使用，当前 Catalog 镜像和命名导入仍会保留。未被保护的镜像与识别出的过期 Staging File 才是候选；不安全或损坏的文件会导致报错。检查自定义 Catalog 的缓存策略时，要传入 相同 --repo。执行 destroy、destroy --purge 与 purge 后镜像仍会保留。

使用 go run ./tools/catalogexport /absolute/new/catalog.json 可逐字节导出编译期 Schema-3 Catalog。 公开 Catalog 若使用相同版本，就必须使用完全相同的字节；同版本不同内容会按 equivocation 拒绝。Release 签名与镜像 Catalog 签名仍属于不同信任域。