参考

• 1: 命令参考
  • 1.1: 准备与工具
  • 1.2: Linux 生命周期
  • 1.3: 客机访问与 hosts
  • 1.4: 镜像命令
  • 1.5: 仓库命令
  • 1.6: 宿主网络命令
  • 1.7: macOS 命令
• 2: 配置
• 3: CLI 契约
• 4: Mac 运行时参考
• 5: 镜像
• 6: 镜像流水线

1 - 命令参考

从下表选择命令，查看参数、完整局部选项、示例与操作范围。组织方式参考 PIG 的命令索引与命令组详解；结构化输出及退出码见 CLI 契约，清单字段见配置参考。

版本基线

本参考对应 2026-11-12 发布的 Barn 1.2.0，源码为 90f6158。中英文页面均已对照 CLI 帮助核对，覆盖 57 个操作命令与 174 项局部选项。

升级时如需保留旧默认值，请显式设置 vm_cpu: 2、vm_mem: 4GiB，并检查 barn plan。已应用 VM 的资源会保留到显式执行资源变更操作为止。用 barn version 和 barn COMMAND --help 核对已安装构建；另见发布说明与发布验收。

命令索引

全局选项

barn [--json|--yaml] [-v|--verbose] COMMAND [arguments] [local options]

全局输出选项可放在子命令前后，但必须在 ssh、exec 使用的远程命令分隔符 -- 之前。-f、-I、-A、-p、--yes 都是局部选项，以对应命令的表格为准。logs -f 表示跟随日志，mac logs -n 表示行数。长布尔选项支持 =true 或 =false。

BARN_OUTPUT、BARN_VERBOSE 设置输出默认值。BARN_HOME 选择私有状态目录，默认 ~/.barn，跨目录操作时建议使用绝对路径。Linux 与 Mac 机器共用数据根目录，但生命周期相互独立。详见环境变量与退出码。

barn 与帮助

barn
barn --help
barn help resize
barn image pull --help
barn --json

无参数时，文本模式打印完整帮助并退出 0，JSON/YAML 模式返回建议操作 actions[]。显式帮助始终输出可读文本。image、repo、network、hosts、mac image 命令组要求子命令，缺少时退出 2；mac 是例外，默认执行 mac ls。Linux 和 Intel Mac 的根帮助隐藏 mac，但仍可显式查看 Mac 命令帮助。

简写在父命令范围内生效，例如 barn im ls 等同 barn image list，barn mac st 等同 barn mac ls；各命令页列出了对应别名。purge 没有 rm 别名。

1.1 - 准备与工具

生成清单、准备宿主、校验配置，以及查看版本和生成补全脚本。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn setup

barn setup [meta|dual|trio|full] [flags]

准备宿主软件包、固定 IP 网络、镜像与所选清单，然后运行 barn up 创建 Linux VM。meta、dual、trio、full 模板分别包含 1、2、3、4 个节点；未指定模板或 -f 时复用发现的清单，没有清单才生成 meta。-c 与规格选项用于生成模板，显式规格选项不能用来改写已有清单；1.2.0 复用清单时也忽略规格环境变量。

--dry-run 预览整个事务。执行需要终端确认或 --yes，系统提权仍可能询问密码。新生成且未经编辑的默认模板遇到子网冲突时，setup 可以选择空闲私有 /24，并将原模板备份为 barn.yml.before-network-change；显式清单保留原子网。Linux 宿主运行异架构客机时，需要另外安装目标 QEMU 模拟器与固件。

别名：s。

barn setup --dry-run
barn setup full -I el9 --yes
barn setup -f pigsty.yml --yes
barn up

barn init

barn init [meta|dual|trio|full] [flags]

生成兼容 Pigsty 的 YAML 清单，默认在 ./barn.yml 写入单节点 meta 模板，控制节点地址为 .10；dual、trio、full 依次增加 .11、.12、.13 节点。覆盖已有文件必须加 --force，-o - 将清单输出到 stdout。本命令不下载镜像或准备宿主。

Barn 1.2.0 每节点默认 1 vCPU、2 GiB，使用 64 GiB 根盘和独立的 128 GiB /data 盘；生成的模板保存六项规格字段，包括 vm_scale。1.1.0 的 CPU 与内存默认值为 2 vCPU、4 GiB。详见规格默认值。

barn init
barn init full -I el9 -A amd64 -o lab.yml
barn init dual -c 10.20.30.0/24 -o -

barn validate

barn validate [flags]

读取清单并校验 Barn 使用的字段，输出解析后的节点；不接受节点位置参数。未指定 -f 时依次在当前目录寻找 barn.yml、barn.yaml、pigsty.yml、pigsty.yaml；找不到清单就报错，即使存在已应用状态也不回退。覆盖参数仅对本次校验生效，--json 可查看解析后的规格，与现有部署比较则用 plan。

别名：v。

barn validate -f lab.yml
barn --json validate -f lab.yml -I u24 -A arm64

barn doctor

barn doctor [flags]

检查 QEMU、原生加速、固件、OpenSSH、短暂的加速启动测试和宿主网络；不接受清单或节点参数。缺少计算能力时命令失败，尚未准备网络则作为提示报告。网络细节用 barn network status 检查，原生 macOS VM 用 barn mac doctor。

别名：dt。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn doctor
barn --json doctor
barn doctor --verbose

barn version

barn version [flags]

输出版本、源码提交、构建时间、宿主操作系统与架构。1.2.0 通常显示 dev，正式版本标识来自构建时写入的信息。核对文档或提交问题时保留这份输出，也可用根命令的 barn --version。

别名：ver。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn version
barn --json version

barn completion

barn completion [bash|zsh|fish|powershell] [flags]

必须指定 bash、zsh、fish 或 powershell 中的一种 shell，将补全脚本输出到 stdout；命令本身不安装脚本。补全涵盖各命令的选项、模板、镜像别名与可读取的节点名，升级 Barn 后应重新加载。加载 shell 代码时使用文本输出。

除 --help 外没有局部选项，仍可使用全局输出选项。

source <(barn completion bash)
barn completion zsh > "${fpath[1]}/_barn"
barn completion fish > ~/.config/fish/completions/barn.fish
barn completion powershell

实现依据

command_setup.go · command_misc.go · command_root.go

发布源码与相对 1.1.0 的变化见版本基线。

1.2 - Linux 生命周期

规划、创建、启停、调整、查看和显式删除 Linux 虚拟机。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

节点参数使用 meta、node-1 等解析后的名称，省略时选择该命令清单或已应用范围内的全部节点；IP、组名、vm_alias 均不能作为选择器。plan、up、reload、resize、recreate 依次读取 -f、当前目录清单、已应用状态，其他生命周期命令直接使用已应用状态。

规格覆盖、缩放和环境变量见配置参考。1.2.0 并发选项只适用于下文列出 --parallel 的命令，plan、resize、status 不接受它。结构化结果与退出码见 CLI 契约。

barn plan

barn plan [node...] [flags]

将有效期望清单与已应用状态比较，输出精确镜像、资源、逐盘动作，以及需要创建、调整资源、重建、启动或显式移除的节点，不改变 VM 或下载镜像。目录镜像仅需本地元数据，具名本地镜像还需要 qemu-img。

退出码 0 表示成功生成计划，也可能是因清单遗漏节点而阻塞的计划；脚本需检查 action、blocked 和变更数组。显式选择节点时保留其他节点的已应用定义。结果格式见计划输出。

别名：pl。

barn plan
barn plan -f pigsty.yml meta
barn --json plan -I u24 -A amd64

barn up

barn up [node...] [flags]

创建缺失节点、启动已停止节点，并在保留健康 VM 进程的同时重试未完成的客机配置。默认等待管理 SSH 就绪，随后更新宿主 SSH 别名、客机 hosts 与控制节点 SSH 条目；非致命客机配置问题放入 warnings，已就绪节点仍视为成功。

首次交互运行时可以准备缺失的宿主依赖；清单与部署状态都不存在时会生成 meta。脚本应先运行 setup --yes。已有节点的定义变化需用 resize 或 recreate，清单遗漏的节点需显式 destroy。--rollback 仅清理本轮准备失败节点中尚未提交且可安全回收的制品。

barn up
barn up -f pigsty.yml meta
barn up --mirror --rollback
barn up meta --no-wait

barn start

barn start [node...] [flags]

按已应用状态启动所选已停止节点并等待 SSH，使用同一 BARN_HOME 时可从任意目录执行，不读取清单或创建新节点。启动会刷新 SSH 访问配置；已经运行的 VM 需要补做客机配置时用 up。共享目录不可用只影响对应节点，独立节点继续执行。

barn start
barn start meta --no-wait

barn stop

barn stop [node...] [flags]

核验已记录的进程身份后停止所选 Linux VM，保留根盘、数据盘、密钥与部署状态。未指定名称时停止整套 Linux 部署；原生 macOS VM 和宿主网络分别由各自命令管理。

barn stop meta
barn stop

barn restart

barn restart [node...] [flags]

使用已应用状态停止并重新启动已有节点，不读取清单修改。需要重新读取清单用 reload，应用已有节点的定义变化用 resize 或 recreate。默认等待 SSH，--no-wait 可跳过等待。

barn restart
barn restart meta --no-wait

barn reload

barn reload [node...] [flags]

先校验期望规格与启动依赖，通过后才停止所选节点并按 up 流程收敛，可以创建清单中新增加的节点。需要调整资源或重建的变更，以及清单遗漏的已应用节点，都会在停止任何 VM 前阻止执行。仅按已记录配置重启时用 restart。

barn reload -f pigsty.yml
barn reload meta --mirror

barn resize

barn resize [node...] [flags]

调整 CPU/内存并扩大根盘，保留 VM 身份、磁盘与 SSH 密钥。目标规格来自清单、环境变量或命令行覆盖。支持的 CPU/内存增加操作使用热插拔，减少资源或不支持在线修改时使用停机再启动。镜像、架构、数据盘、网络、共享目录、节点创建和移除均不能通过 resize 应用。

1.2.0 还接受资源参数，并可用 -D 128GiB 原地扩容根盘：停止 QEMU、扩展镜像、启动客机扩展并核验最后一个普通 ext4/XFS 根分区，原先停止的 VM 最后恢复为停止状态。目标只能增加，且须对齐 512 字节。中断后用同一目标重试；不支持缩小、LVM、加密根盘或非末尾分区。详见根盘扩容与恢复。命令行覆盖不改写清单。

barn plan -f pigsty.yml meta
barn resize -f pigsty.yml meta
barn --json status meta

barn recreate

barn recreate [node...] [flags]

按期望清单替换所选 VM，会删除这些节点的根盘与非持久数据盘，并重新挂接兼容的持久盘。先用 plan 检查范围；终端要求输入 recreate，脚本必须传 --yes 或 --force，没有 -y 简写。

不选节点时应用整个清单；清单遗漏已有节点会在停止 VM 前报错，需先显式销毁该节点或将它加回清单。选择性重建保留其他节点，成功后也会刷新 SSH 访问配置。

别名：rc。

barn plan meta
barn recreate meta
barn recreate -f pigsty.yml meta --yes

barn status

barn status [node...] [flags]

检查已记录的节点配置与当前 QEMU 进程身份，无需位于清单目录。running 表示已核验 VM 进程存在，不能据此判断 SSH 就绪。--verbose 增加运行时细节，--json 返回节点记录、正在进行的操作说明和失败信息。退化节点可能使命令退出 5，健康节点仍会列出。1.2.0 文本输出使用 2c4g 这样的紧凑 SPEC 值。

别名：st。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn status
barn status meta --verbose
barn --json status

barn destroy

barn destroy [node...] [flags]

删除所选 VM，未指定节点时删除整套部署。根盘与非持久数据盘会被删除，持久盘默认保留；终端要求输入 destroy，脚本必须传 --yes 或 --force，没有 -y。

--delete-persistent 和 --purge 仅支持整套部署，后者还删除部署密钥与状态。镜像缓存、宿主网络和原生 Mac VM 保留。删除控制节点后，第一个剩余节点接任控制角色；随后更新 admin_ip 并运行 up 配置其控制 SSH 访问。

别名：de。

barn destroy meta
barn destroy --yes
barn destroy --yes --purge

barn purge

barn purge [flags]

立即删除整套 Linux 部署，包括根盘、持久数据盘、密钥、状态和默认 SSH 配置片段，不接受节点名或读取清单。没有 --yes、-y、--force 选项；需要先审阅范围时用 --ask，输入 y/yes 确认，回车取消。

镜像缓存、宿主网络和 Mac VM 保留。部署不存在时幂等成功，遗留制品身份不明时仍需核验。1.2.0 的 --parallel 控制清理过程中的节点并发。

barn purge --ask
barn --json purge

实现依据

command_lifecycle.go · main.go

发布源码与相对 1.1.0 的变化见版本基线。

1.3 - 客机访问与 hosts

连接 Linux 客机、执行脚本、读取日志，以及发布 SSH 和 hosts 条目。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn ssh

barn ssh [flags] [node] [-- command...]

打开所选已准备节点的交互 SSH 会话，默认选择已准备的控制节点，否则选第一个已准备节点。远程命令必须放在 -- 后，参数会像普通 ssh 一样合并后交给远程 shell 解析；Barn 选项放在分隔符前。节点参数必须是解析后的节点名，不能使用 IP、别名或组名。

远程命令的退出码原样传回。结构化交互 SSH 将会话输出发送到 stderr，最终报告写入 stdout。详见 SSH 参数规则。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn ssh
barn ssh meta
barn ssh meta -- 'df -h /data; id'

barn exec

barn exec [flags] [node] -- command...

在所选已准备节点运行一个远程命令，默认节点选择规则与 ssh 一致。必须使用 --，首个命令参数不能为空；分开的参数保留空格、引号以及后续空值。管道、重定向和变量展开请用 sh -c，也兼容将单个完整字符串作为 shell 命令。

文本模式转发子进程输出与退出码；结构化结果包含 success、exit_code、stdout、stderr。远程非零退出码原样返回，应先检查报告再判断是否属于 Barn 自身错误。

别名：ex。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn exec meta -- hostname
barn exec meta -- printf '<%s>\n' 'a b' ''
barn --json exec meta -- sh -c 'echo out; exit 17'

barn logs

barn logs [node] [flags]

读取所选节点的串口或 QEMU 诊断日志，默认选已准备的控制节点或第一个已准备节点。--source events 读取部署级有界事件日志，不接受节点参数，可在部署状态建立前使用。跟随模式持续输出流，-f 在这里表示跟随日志，不是清单文件。QEMU 参数仅在详细输出开启时显示。

别名：l。

barn logs meta
barn logs meta --source qemu
barn logs --source events --follow
barn --json logs meta --follow

barn provision

barn provision [node...] [flags]

通过已验证的部署 SSH 连接，将本地 Bash 脚本流式发送给所选运行中节点；未选节点时针对全部节点。脚本不会作为文件留在客机，执行记录包含脚本摘要；命令不创建或启动 VM。

必须指定 --script，默认串行执行，整个操作默认超时一小时。此处 --parallel 0 无效，与 1.2.0 生命周期并发规则不同。--sudo 在客机使用非交互的 sudo -n，需确保客机用户已有权限。结构化输出可以检查各节点的执行结果与失败。

barn provision --script ./check.sh meta
barn provision --script ./bootstrap.sh --sudo --parallel 2 --timeout 30m

barn ssh-config

barn ssh-config [node...] [flags]

默认打印 Linux 部署的 OpenSSH 配置片段。--install 写入片段并在 ~/.ssh/config 加一条 Include，打印和安装都可选节点；--remove 只移除指定的 Barn 片段，不依赖部署状态，也不接受节点名。安装与移除选项互斥。

默认前缀为 barn，片段路径为 ~/.ssh/barn_config，普通生命周期命令会自动维护。用户 SSH 配置无法安全修改时，Barn 给出需要手工加入的 Include，直接使用 barn ssh 仍可连接。

别名：sc。

barn ssh-config
barn ssh-config --install meta
barn ssh-config --install --name lab
barn ssh-config --remove --name lab

barn hosts install

barn hosts install [flags]

通过摘要匹配的提权 helper，将已应用节点的名称和别名写入宿主 /etc/hosts 的 Barn 区块。终端先展示变更并询问；非交互或结构化模式默认只预览，显式 --yes 才执行。区块内容未变化时无需提权，up 不会自动发布此文件。

Barn 1.2.0 新增 -f pigsty.yml，可在创建 VM 前发布清单节点及 all.vars.vm_hosts。每次替换整个 Barn 区块，后来不带 -f 执行会移除仅来自清单的服务名，详见本机服务名。

别名：i。

barn hosts install --json
barn hosts install --yes

barn hosts uninstall

barn hosts uninstall [flags]

只移除宿主 /etc/hosts 中 Barn 管理的区块，保留其他条目，不需要清单或部署状态。终端模式展示计划并询问；非交互或结构化模式默认预览，--yes 才执行。移除此区块不删除 VM 或修改客机 DNS 配置。

别名：u。

barn hosts uninstall --json
barn hosts uninstall --yes

实现依据

command_root.go · command_access.go · main.go

发布源码与相对 1.1.0 的变化见版本基线。

1.4 - 镜像命令

更新签名目录、查看和下载镜像、导入本地文件以及清理缓存。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

官方仓库和 HTTP 源必须提供受信任的分离签名。显式选择的自定义 HTTPS 仓库或本地目录可以不签名，但来源必须恰好是该仓库的 catalog.json；只要提供了签名，就必须验签成功。详见目录信任规则。

barn update

barn update [flags]

从所选仓库取得 catalog.json，并按仓库策略获取所需签名，通过信任与 revision 检查后原子激活。普通命令只使用本地元数据，不隐式刷新。本命令更新镜像元数据，不升级 Barn 可执行文件。仓库选择顺序为 --repo > --mirror > BARN_REPO > 全球官方源，详见仓库选择与信任。

barn update
barn update --mirror
barn --json update --repo /srv/barn

barn image list

barn image list [flags]

列出目录中的所有架构和已注册本地镜像，不接受镜像位置参数或架构过滤选项。读取本地活动目录，需要刷新时显式运行 barn update。barn images、barn im 都是镜像命令组的别名。

别名：ls。

barn image list
barn --json image list
barn image list --repo /srv/barn

barn image info

barn image info [image[:channel]|image@version-prefix] [flags]

查看单个镜像的元数据与已验证缓存状态，省略镜像参数时使用目录默认值。可传家族名 u24、通道 u24:stable 或数字版本前缀 el9@9，架构默认原生。--architecture/-a 是 --arch/-A 的兼容写法，不下载镜像制品。别名与精确内置版本见 Linux 镜像。

别名：in。

barn image info
barn image info u24 -A arm64
barn --json image info el9@9

barn image pull

barn image pull [image[:channel]|image@version-prefix] [flags]

下载所选制品，核验 SHA-256、字节大小、qcow2 结构和虚拟容量后激活缓存。省略镜像和架构时使用目录默认镜像与宿主原生架构，已有有效缓存可以复用。目录中的 upstream URL 记录来源，不作为下载失败时的备用地址。仍支持兼容写法 --architecture/-a；下载异架构镜像不会安装对应 QEMU 模拟器。

别名：p。

barn image pull
barn image pull u24 --mirror
barn image pull d13 -A amd64 --repo /srv/barn

barn image import

barn image import <path> [flags]

将本地普通 qcow2 文件复制到私有缓存并校验容器，可选核对预期摘要。接受相对路径、~/ 与指向普通文件的符号链接，需要 qemu-img；导入不启动镜像、不安装 cloud-init，也不修改登录凭据。

指定 local-* 名称可注册不可变的清单引用，必须同时给出启动模式与源镜像登录用户。具名导入可用 -A 记录异架构，qcow2 元数据本身无法识别 CPU 架构；无名称导入不能使用 -A。使用时设置 vm_image 及匹配的 vm_arch。详见导入与缓存规则。

别名：i。

barn image import ./base.qcow2
barn image import ./base.qcow2 --name local-dev --boot uefi --source-user ubuntu -A arm64

barn image sync

barn image sync <url|path> [flags]

从精确 URL 或本地文件激活目录，按上面的信任规则读取旁边的 .minisig 签名，适用于恢复或导入；正常刷新已配置仓库应使用 update。--repo 指定替换哪个仓库的活动元数据。无签名自定义源必须恰好是 <repo>/catalog.json，任意位置的恢复文件则需要受信任签名。

旧 revision 需要 --allow-downgrade；对于允许无签名目录的自定义仓库，从曾签名的目录切换到无签名目录也需要此选项。它不会接受无效签名，也不绕过官方仓库的签名要求和 revision 内容检查。后续回退保护仍记住历史最高 revision。

别名：sy。

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

barn image reset

barn image reset [flags]

为所选仓库重新激活当前二进制内置的镜像目录，保留回退保护使用的历史最高 revision。镜像缓存与 VM 磁盘保留；需要清理缓存时使用 image prune。

barn image reset
barn --json image reset --repo /srv/barn

barn image prune

barn image prune [flags]

默认列出可回收缓存文件，--yes 才删除候选文件，与 --dry-run 互斥。所选仓库的活动目录、已应用节点的基础镜像摘要和本地别名注册表会保护所引用的文件；可识别的过期暂存文件也可清理，隔离的 .corrupt-* 文件保留。

预览和删除时应使用相同的仓库选择。删除按顺序执行，后续文件发生错误不会恢复已经删除的文件。详见清理规则。

别名：pr。

barn image prune --dry-run
barn image prune --repo /srv/barn --dry-run
barn image prune --repo /srv/barn --yes

实现依据

command_image.go · images.go

发布源码与相对 1.1.0 的变化见版本基线。

1.5 - 仓库命令

根据 repo.yaml 与 qcow2 制品扫描、构建和校验静态镜像仓库。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn repo scan

barn repo scan <root> [flags]

扫描包含 repo.yaml 与平铺 images/ 目录的仓库根路径，报告已跟踪、缺失、未跟踪和不安全的 qcow2 文件，不修改文件，也不需要 qemu-img。扫描成功即退出 0，即使发现问题也是如此；自动化必须检查 missing 和 unsafe，不能只看退出码。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn repo scan /srv/barn
barn --json repo scan /srv/barn

barn repo build

barn repo build <root> [flags]

校验 repo.yaml，通过 qemu-img 检查声明的 qcow2 制品，计算最终摘要与大小，并原子生成 catalog.json。缺失或不安全的制品导致构建失败，未跟踪文件不会收录；repo.yaml 与镜像字节保持原样。

本命令不签名或发布目录。内容变化时递增 revision，保持制品文件名不可变，并在发布前使用独立的贡献者签名工具。详见仓库格式。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn repo build /srv/barn
barn --json repo build /srv/barn

barn repo verify

barn repo verify <root> [flags]

根据 repo.yaml 与实际镜像字节在内存中重建预期目录，要求与已有 catalog.json 逐字节一致，需要 qemu-img。本命令检查仓库内容一致性，分离签名由目录激活流程或签名工具验证。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn repo verify /srv/barn
barn --json repo verify /srv/barn

实现依据

command_repo.go

发布源码与相对 1.1.0 的变化见版本基线。

1.6 - 宿主网络命令

检查、安装和移除 Linux 客机使用的固定 IP 网络。

本参考对应 Barn 1.2.0；选项表区分 1.1.0 已有选项 与 1.2.0 新增选项，具体范围见版本基线。所有命令继承全局选项。

barn network status

barn network status [flags]

检查宿主上供 Linux 客机使用的唯一 Barn 网络，包括后端、已安装 CIDR、归属、健康状态和生命周期预检发现。--cidr 指定预期子网，省略时检查已安装子网；本操作只读。每个原生 Mac VM 的独立网络另行管理。

别名：st。

barn network status
barn --json network status --cidr 10.10.10.0/24

barn network install

barn network install [flags]

检查或安装宿主网络后端：macOS 使用 socket_vmnet，Linux 通过活动网络管理器配置 barn0。终端先展示提权计划并询问；结构化或非交互调用默认仅预览，--yes 才执行。新 Mac 建议先用 setup 获取锁定的 socket_vmnet 压缩包。

--archive、--interface-id 仅适用于 macOS，host/shared 是 macOS vmnet 模式，Linux 不接受 shared。已有网络必须匹配所选配置，变更子网或模式前先检查状态。

别名：i。

barn network install --json
barn network install --cidr 10.10.10.0/24 --yes

barn network uninstall

barn network uninstall [flags]

仅移除 Barn 管理的网络配置并恢复已记录的宿主设置，运行中 Linux 客机会阻止卸载，应先停止。终端模式显示计划后询问，结构化或非交互调用默认预览，--yes 才执行。不会删除 VM 磁盘或原生 Mac 网络。

别名：u。

barn stop
barn network uninstall --json
barn network uninstall --yes

实现依据

command_network.go

发布源码与相对 1.1.0 的变化见版本基线。

1.7 - macOS 命令

管理具名原生 macOS VM、桌面访问、恢复镜像与共享基础镜像。

本文对应 Barn 1.2.0；下列选项在 1.1.0 中也已提供。

原生 macOS VM 需要 Apple Silicon、macOS 27+ 与匹配的 Barn.app（宿主上的原生应用包），应由已登录桌面的普通用户运行。状态位于 $BARN_HOME/mac，独立于 Linux 清单。

省略可选名称时，Barn 选择唯一已有 VM 或 mac1；存在多台机器且没有 mac1 时需显式指定。configure、recreate、destroy 始终要求名称，start、stop 可以传多个名称或 --all。宿主各应用合计最多同时运行两台 macOS VM，正在安装的基础镜像也计入限制。详见机器规则、网络、输出与文件。

Mac 容量单位采用二进制，即使写作 GB 也是如此，与 Linux 清单中的十进制 GB 不同；Mac 裸容量数字表示字节。这些命令忽略 Linux 的 BARN_IMAGE/BARN_ARCH/BARN_CPU/BARN_MEM/BARN_SCALE/BARN_DISK 覆盖。

barn mac ls

barn mac ls [flags]

列出每台 VM 的状态、地址、SSH 就绪情况、macOS 版本和资源，读取本地记录并查询运行中机器，不创建、下载或启动 VM。别名为 list、status、st；直接运行 barn mac 也执行此操作。

别名：list, status, st。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac ls
barn --json mac ls

barn mac up

barn mac up [name] [flags]

创建并启动具名 VM，默认名称为 mac1，等待 SSH 和免密 sudo 可用。没有已准备基础镜像时，先确认从 Apple 下载并安装 macOS，后续机器复用基础镜像。

创建参数只用于新 VM，已有 VM 的参数不匹配会报配置冲突；修改 CPU、内存或共享目录用 configure。--no-wait 返回时首次初始化可能尚未完成，随后运行不带该选项的 mac up NAME 完成密钥和 sudo 配置。

barn mac up
barn mac up dev --cpu 8 --memory 16G --share ~/src --open
barn mac up build --yes --no-wait

barn mac start

barn mac start [name...] [flags]

启动已有 VM 并等待 SSH，不创建机器或下载镜像。可传多个名称或 --all，两者不能混用。普通启动要求机器已完成首次初始化；尚未初始化的 VM 用 up 完成，--recovery 则直接打开 macOS Recovery 桌面。

barn mac start mac1
barn mac start --all
barn mac start mac1 --recovery

barn mac stop

barn mac stop [name...] [flags]

通过 macOS 正常关闭所选机器，等待两分钟后仍未停止则断电，并在结果中报告。可传多个名称或 --all；--force 立即断电，会丢失客机中未保存的工作。磁盘和机器配置保留。

barn mac stop dev
barn mac stop --all
barn mac stop dev --force

barn mac restart

barn mac restart [name] [flags]

正常关闭一台 VM 后重新启动并应用配置，省略名称时遵循默认机器选择规则。不接受多个名称或 --all；可用 --open 打开桌面，--no-wait 跳过 SSH 等待。

barn mac restart dev
barn mac restart dev --open

barn mac configure

barn mac configure <name> [flags]

必须显式指定一台已有 VM，修改 CPU、内存、共享目录或子网时需先停止机器；剪贴板设置可以在运行时修改。磁盘和登录账户保持原样，配置在下次启动生效；当前会话的剪贴板同步可在菜单栏即时切换。省略的选项保留原设置，重复 --share 可添加或替换同名共享，--unshare 按名称移除共享。

barn mac stop dev
barn mac configure dev --cpu 8 --memory 16G --share ~/src
barn mac configure dev --unshare src --clipboard off
barn mac start dev

barn mac recreate

barn mac recreate <name> [flags]

必须显式指定机器名。擦除该 VM 磁盘，使用原名称、账户、资源、共享目录和地址重新克隆 macOS，客机文件、应用和设置全部丢失。终端要求输入 recreate，脚本需 --yes 或 --force，没有 -y。--update 使用最新已准备基础镜像，应先执行 mac image update。

barn mac recreate dev
barn mac image update --yes
barn mac recreate dev --update --yes

barn mac destroy

barn mac destroy <name...> [flags]

必须显式指定一个或多个机器名，将机器断电并删除磁盘、密钥、密码和设置，保留共享基础镜像和其他机器。终端要求输入 destroy，脚本需 --yes 或 --force，没有 -y。宿主共享目录不会删除；未使用基础镜像用 mac image prune 清理。

barn mac destroy dev
barn mac destroy mac1 mac2 --yes

barn mac open

barn mac open [name] [flags]

显示 VM 的桌面窗口，机器已停止时会先启动。关闭窗口后 VM 继续在后台运行，剪贴板在窗口聚焦时共享。尚未完成首次初始化且已运行的 VM 可直接打开桌面；未运行时用 mac up NAME --open 继续首次启动。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac open
barn mac open dev

barn mac ssh

barn mac ssh [flags] [name] [-- command...]

使用该 VM 专属 SSH 私钥与固定的宿主密钥连接，省略远程命令时打开交互 shell。-- 前最多传一个已有机器名及 Barn 选项；远程命令必须放在 -- 后，按普通 SSH 方式拼接后交给远程 shell。远程退出码原样返回。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac ssh dev
barn mac ssh dev -- 'sw_vers; id'

barn mac exec

barn mac exec [flags] [name] -- command...

使用 VM 专属 SSH 连接运行远程程序，必须提供 -- 和非空首参数；分开的参数保留边界及后续空值，shell 表达式请显式使用 sh -c。也兼容单个命令字符串。Barn 选项置于 -- 前，远程退出码原样返回，结构化结果包含 stdout、stderr 和 exit_code。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac exec dev -- sw_vers
barn mac exec dev -- printf '<%s>\n' 'a b' ''
barn --json mac exec dev -- sh -c 'echo out; exit 3'

barn mac password

barn mac password [name] [flags]

读取客机登录账户的密码，用于桌面解锁及管理员询问。默认输出密码，--copy 改为复制到宿主剪贴板。密码文件与机器 SSH 私钥采用相同保护；注意选择输出位置。

barn mac password dev
barn mac password dev --copy

barn mac ssh-config

barn mac ssh-config [flags]

打印全部 Mac VM 的 OpenSSH 配置片段，支持 ssh、scp、rsync 和编辑器按名称连接，每台机器使用独立私钥与固定宿主密钥。首台 VM 就绪时自动安装，生命周期命令持续更新。--remove 移除配置并保持停用，直到显式 --install；两选项互斥，也不接受机器选择器。已有 SSH 别名冲突时仅发布 IP 地址条目。

barn mac ssh-config
barn mac ssh-config --install
barn mac ssh-config --remove

barn mac logs

barn mac logs [name] [flags]

读取 VM 的 runner.log 尾部，包含启动、网络、关闭和 Apple Virtualization 错误。--lines/-n 为正整数，默认 100；这里的 -n 表示行数，不是跳过等待。没有跟随选项。

barn mac logs dev
barn mac logs dev --lines 200

barn mac setup

barn mac setup [flags]

提前准备共享 macOS 基础镜像：确认后从 Apple 下载 IPSW，或读取 --ipsw 指定的本地恢复文件，再安装为未启动的基础镜像。后续 VM 从它克隆。此命令不创建具名机器；直接 mac up 也会在需要时自动执行此准备。

barn mac setup --yes
barn mac setup --ipsw ~/Downloads/restore.ipsw --disk 200G

barn mac image ls

barn mac image ls [flags]

列出缓存的 IPSW 恢复文件和已准备基础镜像，包括状态、占用空间及使用它们的 VM；别名为 list。这是本地状态查询，无需调用原生运行器。

别名：list。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac image ls
barn --json mac image ls

barn mac image update

barn mac image update [flags]

从 Apple 查询最新 macOS 27 恢复镜像，经确认后下载并安装为新机器的默认基础镜像；也可通过 --ipsw 指定本地文件。已有 VM 继续使用原基础镜像，显式 mac recreate NAME --update 才替换该 VM 磁盘。

barn mac image update --yes
barn mac image ls

barn mac image prune

barn mac image prune [flags]

默认列出没有机器使用、且不是当前默认基础镜像的清理候选，只有传 --yes 才删除。--installers 同时纳入下载的 IPSW 与未完成下载。VM 的引用关系会保护仍在使用的基础镜像。

barn mac image prune
barn mac image prune --installers --yes

barn mac doctor

barn mac doctor [flags]

只读检查宿主 macOS 与 Apple Silicon 支持、Mac 组件签名、可用磁盘空间、基础镜像以及每台 VM 的文件、密钥、共享目录、网络和 SSH，不修改或启动机器。Linux/QEMU 环境用顶层 barn doctor 检查。

除 --help 外没有局部选项，仍可使用全局输出选项。

barn mac doctor
barn --json mac doctor

实现依据

command_mac.go

发布源码与相对 1.1.0 的变化见版本基线。

2 - 配置

本文对应 Barn 1.2.0，Linux 默认规格为 1 vCPU、2 GiB。升级时如需保留 1.1.0 的默认值，请显式设置 vm_cpu: 2、vm_mem: 4GiB。另见版本基线，并用 barn version 与 --help 核对已安装构建。

发现顺序

Barn 先检查命令行显式传入的 -f 路径；未指定 -f 时，依次在当前工作目录查找 barn.yml、barn.yaml、pigsty.yml 与 pigsty.yaml。四种文件名均使用同一种兼容 Pigsty 的 YAML 主机清单格式。

当前目录没有任何清单文件、但 BARN_HOME（默认 ~/.barn）中已存在部署时，plan、up、reload、recreate 与 resize 会直接使用已应用的部署规格；validate 则始终要求磁盘上存在清单文件。配置文件须解析为不超过 4 MiB 的普通文件，支持符号链接；共享源的相对路径以清单真实文件所在目录为基准。Barn 会采用按顺序找到的第一个候选文件；若该文件存在语法或规则错误，Barn 会直接报错退出，不会继续尝试后续文件名。

已应用的部署状态统一保存在 BARN_HOME 中，重命名清单文件不会改变部署；跨工作目录操作同一套部署时，请将 BARN_HOME 设为绝对路径。

完整配置示例

barn init [meta|dual|trio|full] 分别生成 1、2、3、4 节点的拓扑模板。meta 使用 .10，更大的模板依次增加 .11（node-1）、.12（node-2）与 .13（node-3）；这些模板只定义虚拟机拓扑，上层 Pigsty 服务角色由你的 Ansible 剧本决定。使用 --cidr 可在保留末位主机号的前提下更换 /24 网段；运行 barn init full -o - 可将模板直接打印到标准输出而不落盘。

all:
  vars:
    admin_ip: 10.10.10.10
    vm_image: u24
    vm_cpu: 2
    vm_mem: 4GiB
    vm_disk: 64
  children:
    lab:
      hosts:
        10.10.10.10: { nodename: meta }
        10.10.10.11:
          nodename: worker
          vm_mem: 8GiB
          vm_disks:
            - { path: /data, size: 128, fs: auto, persistent: true }

上面的清单定义了两个托管节点，并以 meta 作为控制节点。将其保存为 barn.yml 后，可在不启动虚拟机的情况下校验配置并预览计划：

barn validate -f barn.yml
barn --json validate -f barn.yml
barn plan -f barn.yml

validate 只检查 YAML 语法、字段规则与镜像目录引用（传入 --repo 可改用其他仓库的目录校验），不会启动虚拟机或下载镜像。JSON 输出包含 valid、source、spec_hash 与 resolved；若本地镜像目录无法读取，结果会附带警告并跳过镜像选择器校验。真正执行 up 时，Barn 会进一步校验 local-* 导入镜像的缓存字节、宿主资源、共享目录、网络与客机 SSH 就绪状态。

Barn 读取什么

清单必须包含顶层 all: 分组，Barn 会遍历其中的 hosts 与嵌套 children 映射。Barn 直接解析静态 YAML，不执行 Ansible 动态清单插件或 Jinja 表达式，也不加载外部 group_vars 或 host_vars 文件。同一个 IPv4 地址出现在多个分组中时，Barn 会合并各组继承的变量，将其视为同一个节点。

Barn 只读取节点 IPv4 键、nodename、admin_ip、pg_cluster、pg_seq、node_admin_username、node_admin_uid 以及下表列出的 vm_* 变量：

• 控制节点：Barn 从 all.vars 读取 admin_ip。未设置或未命中任何托管节点时，Barn 按 YAML 遍历顺序（先读当前组的 hosts，再递归读取 children）选择第一个托管节点。建议显式设置 admin_ip，以免调整分组顺序时改变控制节点。
• 登录账号：所有节点必须使用同一个匹配 [a-z_][a-z0-9_-]{0,31} 的登录用户名。使用默认用户 dba 时，若显式设置 node_admin_uid，其值必须为 88；使用自定义用户名时，Barn 只检查 node_admin_uid 是否为整数，客机内实际 UID 由创建账号时自动分配。
• 上层 Pigsty 字段：pg_role、pg_version、repo_*、node_packages 等不由 Barn 消费的字段会被安全忽略，修改它们不会触发虚拟机配置漂移。
• 继承与严格校验：变量按 all.vars → 嵌套 children.<group>.vars → 节点变量的顺序覆盖。节点上声明的 vm_disks 等列表会整体替换组级列表，不会追加合并。同级分组对同一节点给出不同值时，必须在节点层级显式覆盖以消除冲突。未知的 vm_* 字段、错误类型、Jinja 表达式、重复 YAML 键以及多文档 YAML 流都会直接报错；报错时会指出违反的规则、问题值与行号，并提示拼写相近的 vm_* 字段名。支持 YAML 锚点与 << 合并键（显式键优先，合并序列中排在前面的映射次之）。
• 跳过节点：vm_skip: true 的外部主机可使用主机名或 IPv6 键，不参与推导托管 /24；清单仍须保留一个托管节点。已部署节点被跳过时，plan 会标记为 missing，不会自动销毁。

VM 变量

空节点条目（如 10.10.10.10: {}）即可使用默认参数定义一台完整虚拟机。托管节点须使用同一 /24 内互不重复的可用地址。

裸整数在 vm_mem 中表示 MiB，在磁盘容量中表示 GiB。显式容量字符串接受正整数和不区分大小写的单位，例如 8G、512m、4gib、64GB。K/M/G/T 与 KiB/MiB/GiB/TiB 使用二进制倍率，KB/MB/GB/TB 使用十进制倍率。小数 1.5GiB 和无单位字符串 "8192" 无效。up 会检查根盘不小于基础镜像虚拟大小。

省略 vm_image 时，Barn 始终按二进制内置目录选择 u24（Ubuntu 24.04），自定义仓库中的 defaults.image 不会改写未设置 vm_image 的清单。此外，Barn 在解析清单时会先按内置目录将 ubuntu 等内置别名归一化为 u24；使用自定义仓库时，请在 vm_image 中直接填写规范系列名，不要将内置别名改指其他系列。

需要把镜像系列与版本前缀分开书写时，可配合使用 vm_version：

vm_image: el9
vm_version: "9.8"

若镜像目录中存在完全一致的版本号，Barn 优先精确匹配；否则按点号分段匹配版本前缀，并按整数大小选择匹配的最高版本（9.8 匹配最新的 9.8.* 构建，9 匹配最新的 9.x 版本，且 9.10 排在 9.9 之后）。vm_version 不能与已包含 :channel 或 @version 的 vm_image 同时使用。

1.2.0 的资源缩放

分别解析 vm_cpu、vm_mem 和 vm_scale：主机变量优先于最深层分组，其次是父组和 all.vars。缺省值依次为 1 vCPU、2048 MiB 和倍数 1。继承完成后只乘一次：

CPU  = 解析后的 vm_cpu（默认 1）× 解析后的 vm_scale（默认 1）
内存 = 解析后的 vm_mem（默认 2048 MiB）× 解析后的 vm_scale（默认 1）

主机的 vm_scale: 1 会覆盖分组的 vm_scale: 3，多层倍数不累乘；同层分组冲突需要在主机上覆盖。倍数接受 1–256 的整数，同时受最终 256 vCPU 上限和内存溢出检查约束。带引号的数字、小数、布尔值、null、零和负数均无效。基础内存仍需至少 512 MiB。根盘、数据盘和共享目录不受缩放影响。参数名为 vm_cpu 和 vm_mem，不提供 vm_memory 别名。

先执行 barn plan -f pigsty.yml，再用 barn resize -f pigsty.yml 应用 CPU/内存变更。旧部署若省略了这些字段，新版读取清单后会显示资源减少；升级前显式补上 vm_cpu: 2、vm_mem: 4096 即可保持旧默认规格。没有清单、直接使用已应用状态的命令会保留记录中的资源。

1.2.0 的本机服务域名

Barn 1.2.0 支持从清单发布 hosts。

在 all.vars.vm_hosts 中声明有限的服务映射。显式指定清单发布时，Barn 将它们与节点名、vm_alias 合并：

all:
  vars:
    vm_hosts:
      - {address: 10.10.10.10, names: [i.pigsty, m.pigsty]}
      - {address: 10.10.10.100, names: [pg-dns-service]}
  hosts:
    10.10.10.10: {nodename: meta}

barn hosts install -f pigsty.yml --json  # 预览，VM 创建前也可使用
barn hosts install -f pigsty.yml --yes  # 发布，sudo 可能要求密码
barn hosts uninstall --yes

每条记录必须包含 address 与非空 names 列表。地址必须是清单私网 /24 内的规范 IPv4，范围为 .9–.254；.1–.8 保留给宿主与 DHCP。同名同 IP 去重，名称按大小写不敏感比较；同名不同 IP 报错。Barn 管理块外已有冲突名称时也会停止发布。hosts 记录本身不会在客机上配置 VIP。

这些映射只影响宿主的 /etc/hosts，修改它们不会改变 VM 规格摘要、配置客机 DNS 或产生 VM 漂移。不带 -f 时，hosts install 只发布已应用 VM 状态中的名称和别名，并替换整个 Barn 管理块；需要保留服务域名时应始终显式指定清单。up 不会自动发布此文件。内容不变时无需 sudo，系统 hosts 内容有变时仍需权限。通配符、SRV 记录以及动态主库发现需要 DNS 服务。

Pigsty 1.2.0 的 bin/sandbox-dns 会提取 portal、节点、PostgreSQL、VIP 和 MinIO 名称，再交给此接口。具体范围见 迁移排查。

1.2.0 规格覆盖

Barn 1.2.0 支持六项规格的统一 CLI 与环境变量输入；1.1.0 支持镜像/架构选项，但没有新增的四项资源参数和这些环境变量。

每个字段分别采用 CLI > 非空环境变量 > 主机 > 最深子组 > 父组 > all.vars > 默认值。CPU 和内存始终表示基础值，覆盖完成后各乘一次最终 scale；磁盘容量不参与倍乘。-S 3 替换原来的倍数，指定精确最终 CPU/内存时加 -S 1。CLI 与环境变量覆盖选中节点的主机值；需要保留节点特例的公共默认值写在 all.vars。清单语法、字段类型和继承冲突仍必须有效。

barn init full -C 2 -M 4GiB -S 2 -D 128GiB
barn plan -f barn.yml -S 3
BARN_SCALE=2 barn validate -f barn.yml -S 1

init 和生成模板的 setup 写入全部六项选择，包括默认值；保存 CPU/内存基数和倍数。首次交互式 up 需要生成清单时也保存本次选择。已有文件上的生命周期覆盖仅改变本次期望规格，不回写 YAML；后续读取原文件会报告差异。没有清单、只剩应用状态时，--scale 或 BARN_SCALE 要求提供 -f；CPU/内存可以按隐式倍数 1 设置绝对值。

环境变量只影响接收相应规格的命令。status/start/stop/restart/destroy/purge、独立镜像管理和 barn mac 不读取这六项变量；setup 复用已有清单时也忽略它们。resize 接受 CPU/内存/scale、根盘容量及已有的 I/A 核对接口；BARN_DISK 仅用于根盘增长。空白环境值视为未设置，CLI 已遮蔽的无效环境值不报错，例如 BARN_CPU=bad barn plan -C 2。有效的环境覆盖会保留在后续命令的显式参数中。

--disk 设置系统根盘的绝对容量，必须不小于基础镜像的虚拟大小，计划使用目录元数据检查，创建时再次检查实际镜像。它适用于创建、显式重建，以及 resize -D 的根盘原地增长。扩容只支持末端普通 ext4/XFS 根分区，不支持缩盘；流程与恢复见 根盘扩容。重建会替换根盘和非持久数据盘。当前默认的 128 GiB /data 盘保持独立。

镜像与架构覆盖

镜像与架构遵循相同的规格优先级：命令行参数、非空环境变量、清单值，最后使用默认值。

默认客机架构与宿主一致：Apple Silicon 使用 arm64，Intel/AMD 宿主使用 amd64。可以通过命令行、环境变量或清单选择其他架构。优先级为 --arch/-A → BARN_ARCH → 清单 vm_arch → native（宿主架构）；-A native 可以覆盖环境变量与清单，恢复跟随宿主。

vm_arch 是整套部署共用的属性，请在 all.vars 中统一定义。每个托管节点必须解析为同一架构，不能用节点变量或节点选择器混合架构。

--image/-I 优先于 BARN_IMAGE 和所选节点的 vm_image/vm_version，不改变架构。未传该参数时，非空的 BARN_IMAGE 覆盖清单镜像。镜像目录必须提供目标架构的变体，否则报错；Barn 不会因为镜像缺少该变体而切换架构。

barn plan -I u24                 # 使用 Ubuntu 24.04，架构仍遵循环境变量、清单或宿主默认值
barn up -I u24 -A amd64          # 本次使用 amd64 Ubuntu 24.04
barn plan -A native              # 覆盖清单架构，按宿主架构预览
barn init full -I u24 -A arm64   # 将镜像与架构写入新清单

up、plan、reload、recreate、resize 和 validate 的覆盖只对本次期望配置生效，不改写清单。要长期保留选择，请设置 all.vars.vm_arch、相应节点或组的 vm_image，并移除被替代的 vm_version；init 与生成模板的 setup 会直接写入这些选择。setup 的 -I/-A 不能用于已有清单。

没有清单文件时，生命周期命令沿用已保存的部署规格，再应用显式覆盖。start 和 restart 始终使用已应用状态。已有 VM 的架构不会因省略 -A 或修改清单而自动改变：up 会报告漂移，实际切换架构需要选择全部已有节点执行 recreate。resize 应用 CPU/内存变更并扩大受支持的根盘；镜像和架构变更需要 recreate。

客机与宿主架构不同时使用 QEMU TCG。Linux 宿主的 barn setup 默认只安装本机架构的 QEMU；运行跨架构客机前，需安装对应的 qemu-system-* 与 UEFI 固件。加速方式与镜像例外见运行时策略。

数据盘

vm_disks:
  - path: /data
    size: 128
    fs: auto
    persistent: false

vm_disks 列表中的每一项定义一块附加虚拟块设备：

• path：绝对挂载路径，自动规范化，支持空格、中文和 shell 标点。简单路径保留原有磁盘标识，其他路径生成稳定摘要标识。同一节点内标识须唯一，系统目录和重叠的挂载路径仍会被拒绝。
• size：磁盘容量，默认 128（128 GiB），支持 GiB 整数或显式容量字符串。
• fs：文件系统类型，支持 auto（默认）、xfs 或 ext4。对于空白的 auto 磁盘，客机具备 mkfs.xfs 时格式化为 XFS，否则使用 ext4；显式指定 xfs 或 ext4 时严格使用对应工具，不会降级回退。健康的已有文件系统会直接挂载复用。
• persistent：设为 true 时，普通 barn destroy 与 barn recreate 会在宿主上保留该磁盘镜像；只要磁盘标识与声明保持兼容，重建后的节点会自动重新挂载它。设为 vm_disks: [] 则不挂载任何额外数据盘。

目录共享

vm_shares:
  - host: ./src
    guest: /src
    readonly: true

vm_shares 通过 QEMU Virtio-9p 将 Linux 或 macOS 宿主目录挂载到 Linux 客机，默认 readonly: true。宿主 QEMU 与客机内核须支持 9p，共享数量受后端设备能力约束。原生 macOS 客机使用 barn mac --share 的 VirtioFS。

共享源按当前用户的实际文件系统权限访问：

• host 支持绝对路径、~/、相对清单目录的路径与目录符号链接。guest 须为绝对路径并自动规范化，接受空格、中文和 shell 标点，不接受控制字符。
• 解析后的宿主源须已存在、当前用户可访问且不与 BARN_HOME 重叠，无须归当前用户所有。
• 宿主源可以重叠，多个客机可以同时读写，由用户协调并发写入。同一客机内的挂载目标仍不能重叠。
• guest 路径不能覆盖数据盘挂载点、系统保留目录或登录用户的 .ssh 目录。9p 共享适合挂载开发源码与构建产物，请勿用于存放 PostgreSQL 数据目录。
• 若请求了可写共享（readonly: false）但客机用户无权写入，Barn 会自动降级为只读挂载并报告警告，而不会递归修改宿主文件属主；调整宿主目录权限后重新执行 barn up 即可恢复可写挂载。
• 修改已有节点的 vm_shares 需要执行 barn recreate。up 或 start 期间若某个节点的共享源目录缺失，只会使该节点失败，其余节点照常启动；restart、reload 与 recreate 则会在停止现有虚拟机前预先校验所有共享源目录。

名称与地址

Barn 依次按显式 nodename、<pg_cluster>-<pg_seq>、node-<IP末段> 确定节点名称。节点名称在部署内必须唯一，长度为 1–63 个字符，只能包含小写字母、数字与连字符，且不能以 - 开头或结尾。vm_alias 接受额外的小写 DNS 名称（允许包含点号），且不能与任何节点名或其他别名重复。

同一套部署中的所有托管节点必须位于同一个 RFC1918 /24 私有网段内：.1 固定为宿主网关，.2–.8 保留，节点使用 .9–.254。客机内部由固定 IP 网卡承载清单地址（可通过 ip -br addr 查看）。

漂移

显式节点选择只应用所选节点的改动：plan node-1、up node-1、reload node-1、recreate node-1 和 resize node-1 保留其他节点的已应用配置，即使清单中已修改或省略它们。整份清单仍须通过语法解析，未创建且未选中的节点不要求解析镜像。与已应用节点冲突的地址、别名、控制节点角色或部署公共设置仍会报错。

Barn 为每个解析后的节点计算规格哈希：

• barn up 会创建新增节点、启动已停止节点，并在不重启 QEMU 进程的前提下重试运行中节点尚未完成的客机初始化步骤。
• 修改节点的 CPU 或内存后使用 barn resize <node>，该操作保留虚拟机身份与磁盘。1.2.0 还通过 resize -D 支持根盘增长。修改镜像、数据盘、共享目录或其他虚拟机定义后，需要执行 barn recreate <node> 才能生效。从清单中删去节点（或设为 vm_skip: true）只会在 plan 中将其标记为 missing，Barn 绝不会自动销毁已有节点。
• 修改部署级属性（vm_arch、登录用户名或 /24 子网）需要重建整套部署。
• 由于 plan 与 up 会将镜像通道和版本前缀解析为具体的镜像摘要，执行 barn update 更新镜像目录后，即便 barn.yml 原文未改，也可能产生镜像版本漂移。建议为每个节点显式固定 nodename，避免修改 pg_cluster 时导致旧节点变成 missing 并额外派生出新节点。

3 - CLI 契约

本页说明 Barn 1.2.0 的全局展示、Linux 生命周期语义、结构化输出与退出码；各命令的语法、选项、默认值与示例见命令参考。原生 Mac 运行时契约见 Mac 参考。

barn [--json|--yaml] [-v|--verbose] <command> [flags] [node...]

每条命令都提供内置 --help，用于查看当前二进制支持的参数与示例：

barn --help
barn setup --help
barn image pull --help

不带参数直接运行 barn 会打印与 barn --help 相同的完整帮助并以退出码 0 返回；传入 --json 或 --yaml 时则返回由建议命令组成的 actions[] 数组。只输入命令分组而不带子命令（如 barn image）会以退出码 2 返回（文本模式输出帮助，JSON/YAML 模式输出结构化 usage 错误）。显式传入 --help 始终打印人类可读的帮助文本并以 0 退出。查看构建版本信息请使用 barn --version 或 barn version。

命令

日常命令只读取本地已激活的镜像目录，不会隐式联网刷新。执行 barn update 可拉取、验签并激活所选仓库的最新镜像目录；需要从指定 URL 或本地文件恢复目录时，使用 barn image sync。这两条命令都不会更新 barn 可执行文件本身。

常用命令在各自作用域内支持短别名：

up、ssh、init、start、stop、restart、reload、resize、provision、hosts、purge、update、repo、mac 与 completion 不设顶层短别名（rm 也不是 purge 的别名）。在子命令命名空间内，hosts 与 network 的 install/uninstall 可简写为 i/u，network status 可简写为 st；image 下支持 list=ls、info=in、pull=p、prune=pr、sync=sy 与 import=i。

Barn 在每个 BARN_HOME（默认 ~/.barn，详见配置发现规则）中管理唯一一套部署，只要 BARN_HOME 指向同一位置，操作已应用状态的命令就可在任意工作目录下执行；跨工作目录使用时请设置绝对 BARN_HOME。各条命令按如下规则确定期望配置来源（-f 是命令级参数而非全局参数）：

在终端中，如果宿主缺少依赖或 Barn 网络，up、start、restart 与 reload 会像 barn setup 一样准备宿主：先展示宿主准备计划，在安装软件包或网络前询问一次（涉及特权操作时 sudo 仍会提示输入系统密码）。当前目录没有清单且 BARN_HOME 中也没有已部署环境时，交互式 barn up 还会先生成默认 meta 清单。没有终端时，这些命令只报告缺少的条件。运行 barn setup --dry-run 可查看准备计划，在脚本中请执行 barn setup --yes 准备宿主。

对于全新、未修改的默认模板，若默认 10.10.10.0/24 网段与宿主现有路由冲突，setup 会自动改选另一个空闲的私有 /24 网段，并将原文件备份为 barn.yml.before-network-change。显式传入的 -f 清单、已手动编辑的模板以及已存在的部署始终保留各自配置的网段。

关键参数

各命令支持的局部参数如下表所示：

参数使用说明：

• setup --dry-run 与 setup --yes 互斥。--cidr 仅调整新生成模板的网段，不会改写显式指定的 -f 清单。若要在 validate 时对照中国镜像源校验，请传入 --repo https://repo.pigsty.cc/barn。
• init 与生成模板的 setup 将 -I、-A 写入 all.vars.vm_image、all.vars.vm_arch；setup 遇到已有清单时拒绝这两个生成参数。up、plan、reload、recreate、resize 与 validate 则在内存中覆盖本次期望配置，不改写清单。镜像覆盖作用于所选节点，架构覆盖作用于整套部署；详见覆盖优先级与默认值。
• 独立的 image info/pull/import 默认取宿主架构，不读取清单的 vm_arch；用 -A 显式选择。image import -A 必须与 --name 同用；qcow2 元数据不能识别客机 CPU，所填架构须与实际镜像一致。
• network 与 hosts 的 install/uninstall 会先展示变更计划并在终端请求确认（安装默认同意，卸载默认拒绝）。未传 --yes 时，如果标准输入不是终端或输出为 --json/--yaml，命令只输出计划并退出 0；请检查结构化报告中的 applied，或传入 --yes 执行计划。macOS 首次配置宿主网络请使用 barn setup。有节点运行时 network uninstall 会拒绝卸载网络；停止或销毁虚拟机不会卸载宿主网络。在 Linux 上，若宿主还有其他网络链路，或无法确认 networkd 仅供 Barn 使用，network uninstall 会保留全局 networkd 单元状态；计划中报告 preserve_networkd，执行报告在 checks.networkd 中说明原因。
• 涉及安全确认与仓库选择的开关（--ask、--mirror、--force、--rollback、--remove、--allow-downgrade、--sudo、--delete-persistent、--purge）只提供长参数。在 Linux 命令中，-f 表示 --file（barn logs -f 例外，表示 --follow），-n 表示 --no-wait（而 barn mac logs -n 表示日志行数），-d 表示 --dry-run。
• barn purge 默认立即执行整套清理，删除所有节点、持久盘、密钥、部署状态与默认 SSH 配置片段，保留镜像缓存与宿主网络。只有传入 --ask 时才先展示节点列表与清理范围：输入 y/yes 确认，n/no、空行或 EOF 取消并返回 130；不接受 --yes、-y 或 --force。当环境中尚无部署时，默认 barn purge 与整体 barn destroy 均直接返回成功（purge 还会清理归属元数据完整的残留持久盘）。无法确认残留目录归属时仍会拒绝删除。若部署状态文件已缺失，执行 destroy --force --delete-persistent 或 destroy --force --purge 会报错并提示改用 barn purge。

1.2.0 规格参数与 SPEC 显示

Barn 1.2.0 新增 --cpu/-C、--mem/-M、--scale/-S、--disk/-D，与 --image/-I、--arch/-A 共用规格输入规则，支持范围如下：

参数、单位、环境变量及保存规则见 规格覆盖。up/reload 不会自动应用已有节点的资源变化，仍需 resize 或显式 recreate。

节点表用 SPEC 列表示有效 CPU 与内存，例如 1c2g、2c4g、8c16g。c 表示 vCPU，g 表示 GiB；1536 MiB 精确显示为 1.5g，512 MiB 为 0.5g。不能整除 MiB 的字节容量用 b 精确保留，未知规格显示 -。

status 和完成结果显示已应用规格；plan/validate/setup 显示期望规格。计划中的资源变化显示为 2c4g → 4c8g，根盘在 ROOT 列单独显示。init 摘要、生命周期动态进度及普通终端的完成结果也显示 SPEC。scale 不为 1 时展示基数、倍数、结果及来源；--verbose 也显示倍数为 1 的计算说明。JSON 保留数值 CPU 和字节容量，并在 resources 中提供基数、倍数、有效结果与来源，不要求脚本解析缩写。

1.2.0 根盘原地扩容

barn resize -D 128GiB meta
BARN_DISK=128GiB barn resize meta

-D 是绝对目标容量，重复相同目标不再修改磁盘或重启 VM；缩盘直接报错。首次扩容需要停机，原本运行的节点完成后运行，原本停机的节点临时启动完成检查与扩展后恢复停机。支持 512 字节逻辑扇区、GPT 或主 MBR 分区表中位于末端的普通 ext4/XFS 根分区；LVM、加密设备、后置分区和缺少所需工具会在修改磁盘镜像前报错。根盘与原有数据、VM UUID、SSH 密钥均保留，数据盘不参与扩容。

Barn 持久化恢复阶段，核对镜像容量、客机磁盘、分区及文件系统后才完成操作。失败时 status 显示 root-resize 提示；修复报告的问题后，按提示重复相同 resize -D 目标。根盘已扩展但客机未完成时不会自动缩回。若清单仍保留旧容量，继续运行原清单会报告差异；需要长期保留新容量时更新 vm_disk。实现与测量见 根盘扩容验收。

1.2.0 的生命周期并发

Barn 1.2.0 将 Linux 虚拟机生命周期默认并发设为 max(1, 逻辑 CPU 数 - 2)，CPU 数取 Barn 进程检测到的可用逻辑 CPU 数，各阶段实际并发不超过该阶段所选节点数。已发布的 Barn 1.1.0 最多使用四个工作线程，生命周期命令尚不支持 --parallel。

1.2.0 的 up、start、stop、restart、reload、recreate、destroy 与 purge 接受零或正整数参数 --parallel/-p。省略参数时采用 CPU 默认策略，显式传入 --parallel 0 则让所选节点全部并行；正数指定并发上限，--parallel 1 可将节点操作设为串行。该参数覆盖命令涉及的磁盘准备、启动与停机阶段并发，状态提交与文件删除沿用原有顺序。超过 16 的值也会生效，超过节点数则不会多建工作线程。该选项仅作用于本次命令，失败后建议的重试命令会保留显式传入的值，包括零。

barn up -p 0
barn up --parallel 8
barn start -p 1
barn restart meta node-1 -p 2

启动工作线程在客机启动、等待 SSH 与就绪检查完成期间一直占用并发名额。传入 --no-wait 后，QEMU 启动且进程身份核验通过即可释放名额。磁盘准备阶段全部结束后才进入启动阶段。provision --parallel 保持独立的默认值 1；原生 macOS 客机的运行数量限制见 Mac 命令。

实现与回归测试：concurrency.go、concurrency_test.go 与 lifecycle_parallel_test.go。

2026-11-10 真机验收在具有 18 个逻辑 CPU 的 macOS/arm64 宿主上，通过临时 BARN_HOME 管理六台 Debian 13 客机：自动默认值为 16，实际启动并发峰值为六；显式设为 1 时，启动与停止均为串行；显式设为 32 时，重启并发峰值为六。全部客机通过就绪检查，测试部署已在结束后销毁。

2026-11-11 在同一宿主上另建临时部署，验证显式零值：18 台 Debian 13 客机全部并行启动，并在 39.6 秒内通过就绪检查。选择其中三台执行停止和启动，两阶段并发峰值均为三，其余 15 台虚拟机进程保持不变。测试部署已在结束后销毁，原有六台虚拟机进程保持不变。回归测试另覆盖超过 16 的正数并发上限、修改状态前拒绝负数，以及重试命令保留显式零值。

结构化失败

编写自动化脚本时，请先检查进程退出码，再按所执行的命令解析输出。

在默认文本模式下，耗时满 1 秒的终端操作会在 stderr 动态重绘单张实时状态表（NAME ADDRESS STATE MESSAGE、ITEM STATE MESSAGE 或 IMAGE STATE MESSAGE），并在底部输出以 [DONE]、[FAILED] 或 [CANCELLED] 结尾的汇总行；当 stdout 与 stderr 都是终端且未启用 --verbose 时，完成后的表格会原地固定，stdout 只追加后续操作提示（如 connect:、retry:、next:）。常规错误会在 stderr 打印 error: <消息>；若外部命令调用失败，还会附上其最后几行 stderr 输出，并在有明确恢复步骤时打印 next: 建议命令。SSH 子进程执行远端命令返回非零退出码时，Barn 会直接透传远端输出，不再额外包装 error: 行。

在 --json 或 --yaml 模式下，定义了专属报告结构的命令（doctor、network、provision、生命周期命令以及 ssh/exec）会直接在 stdout 输出各自的报告结构（例如 exec 返回 success、exit_code、stdout 与 stderr）。如果命令在生成专属报告前就失败，Barn 会在 stdout 输出单个通用错误对象：

• error：取自退出码表的固定错误类别（recreate_required 与 nodes_removed 现作为 error: "conflict" 下的 reason 返回，资源冲突统一使用 error: "resource"）。
• message：可读的错误说明。
• 可选上下文字段：reason、next、operation_id，以及记录外部命令失败详情的 command（含 name、argv、exit_status、signal、timed_out、stderr）。

单次结果命令输出一份 JSON 或 YAML 文档；logs --follow 使用 NDJSON 或 YAML 文档流，结构化模式的交互 SSH 将会话输出送往 stderr，最终报告送往 stdout。设计理由见 CLI 契约。

生命周期结果

不传节点名时，生命周期命令默认作用于部署中的全部节点；而 ssh、exec 与单节点 logs 默认作用于已完成准备的控制节点（若控制节点尚未准备就绪，则回退到第一个已准备就绪的节点）。节点选择器必须是解析后的节点名称（如 meta），不接受清单 IP、分组名或 vm_alias 别名。

• restart：不重新读取清单，直接按已应用状态重启节点。
• reload：先校验本次生效的期望规格与启动依赖，通过后再停止所选节点并对这些节点执行 up。该命令可以新增节点；需要替换已有虚拟机的变更仍需使用 recreate。
• resize：应用包含 vm_scale 倍数的有效 CPU/内存规格，并支持根盘增长。支持的增加操作可以热插拔；减少资源、旧虚拟机或后端不支持时会自动停机再启动，同时保留虚拟机身份与磁盘。镜像、数据盘、网络、共享目录、创建、删除及部署级变更会被拒绝。
• recreate：通过替换根盘和非持久数据盘来应用节点定义变更，同时保留兼容的持久数据盘。显式选择节点执行 plan、up、reload、recreate 或 resize 时，其余节点保留已应用定义，即使 YAML 已修改或省略它们；未创建且未选中的节点不要求解析镜像。地址、别名、控制节点角色及部署公共设置的真实冲突仍会在预检时报错；省略选择器时则处理整份清单。
• 当配置漂移需要执行破坏性变更时，up 与 reload 会返回 conflict 错误，并提示先运行 barn plan，再运行 barn recreate <node> 或 barn destroy <node>。在终端上，recreate 与 destroy 会列出将被替换或删除的节点，并要求输入命令名确认，传入 --yes（或 --force）可跳过；没有终端且未传这两个参数时，命令以退出码 2 拒绝执行。不带节点参数时，两者都作用于整套部署。

不带节点参数的 recreate 遇到清单缺少已有节点时，会在任何虚拟机停机前拒绝执行（conflict，reason nodes_removed，退出码 4）。需要删除该节点时请显式执行 barn destroy <node>，否则把它加回清单。Barn 会在销毁锁内再次核对范围；若预检期间已应用状态发生变化，recreate 以 reason deployment_changed 退出，请重新检查计划后重试。

删除控制节点后，剩余的第一个节点接任控制节点。请在清单中把控制角色（admin_ip）改为该节点，再运行 barn up 安装其控制 SSH 访问；--no-wait 会推迟这一步。在此之前，仍把已删除节点设为控制节点的清单属于角色漂移，up 会拒绝执行；如需恢复原节点，请将其作为普通节点重新加入。接任节点存在无法完成的准备记录时，Barn 会在删除任何内容前拒绝删除控制节点，并在错误中指出接任节点。

计划

barn plan 是只读命令，即便计算出的 action 为 resize、recreate 或 blocked-removal，也会以退出码 0 返回；自动化脚本应检查 action、create/resize/recreate/start/missing 数组，以及可选的 blocked 原因字符串。

对于镜像目录中的标准镜像，plan 仅读取本地配置与镜像目录元数据，不依赖 QEMU 或宿主网络；对于已注册的 local-* 本地导入镜像，plan 还会调用 qemu-img 校验缓存文件。plan 不会下载镜像，并会展示精确的镜像版本、CPU/内存/磁盘资源总量、漂移原因以及每块数据盘的处理动作（包括默认的 128 GiB /data 盘）。

启动与 SSH 配置

barn up 会在执行前检查宿主虚拟化能力与地址可用性，依次创建缺失节点、启动已停止节点、检查运行中节点的 SSH 就绪状态，并根据完整的已应用部署重写宿主 SSH 客户端配置片段（~/.ssh/barn_config）以及运行中客机的 /etc/hosts 和控制节点 SSH 配置。recreate 同样会完整刷新上述配置；start 与 restart 也会刷新 SSH 别名；单节点 destroy 会移除对应条目，整体 destroy 则移除整份配置片段。

若虚拟机生命周期操作已成功，但写入 ~/.ssh/config 失败（或者 ~/.ssh/config 是符号链接/硬链接，Barn 从不修改链接文件），Barn 会写好独立的 ~/.ssh/barn_config 片段、提示需手动添加的 Include 行，将告警记入 warnings[] 并以 0 退出（barn ssh 仍可正常连接）。

控制节点上由 Barn 管理的 SSH 条目不会把实验节点的主机密钥锁死在 known_hosts 中，从而保证节点重建后依然可以直接连通；用户在客机中自行添加的 SSH 配置会原样保留。

就绪

管理 SSH 连通后，Barn 即判定 Linux 客机已就绪。非致命的客机初始化问题会记录在 nodes[].warnings 中，已自动完成的恢复动作（例如重置损坏的数据盘）会记录在 nodes[].repairs 中，命令退出码仍为 0。再次运行 barn up 可以在不重启 QEMU 进程的情况下，对运行中的节点重试未完成的初始化步骤。

传入 --no-wait 时，命令在 QEMU 进程启动后立即返回，把客机就绪检查、数据盘恢复与 SSH//etc/hosts 刷新留给下一次 barn up。

哪些数据盘问题会被自动修复（记入 repairs）、哪些只报告（记入 warnings），见数据盘。已有客机会在下一次 barn up 的就绪检查中获得当前的恢复脚本。

节点失败

批处理过程中若出现可隔离的单节点失败，Barn 会保留已成功的节点，以退出码 5 返回，并按 N of M node(s) failed: <node> (<stage>: <error>); ... 格式汇总错误（常见阶段包括 prepare、start、readiness、bootstrap、guest-setup、stop 与 status）。结构化输出在 failures[] 中提供 node、stage、error 及可选的 reason（若传入 --rollback 清理了未提交节点的准备产物，还会包含 rolled_back）。遇到 readiness 或 bootstrap 失败时，请运行 barn logs <node> 查看串口输出，并参考节点未就绪排查。

状态

barn status 默认展示节点名、IP（ADDRESS）、状态（running 表示 QEMU 进程存活，不主动探测客机 SSH）、精确镜像及 CPU/内存，并在使用 TCG 软件模拟时予以标记（在 Apple Silicon 上若存在 Mac 虚拟机，还会附加 mac: <名称>; barn mac ls）。加上 --verbose 可进一步查看 SSH 转发端口、架构、加速器与 QEMU PID。若个别节点异常——包括在线 resize 在热插拔后中断（stage: "resize"、reason: "resize_incomplete"）——status 仍会展示其余正常节点，在 failures[] 中附带节点错误并以 5 退出。

恢复与中断处理

• 故障隔离：执行 up 或 start 时，某个节点的宿主共享目录缺失或新节点准备失败只影响该节点，独立的已停止节点仍会正常启动；命令以 5 退出，并给出保留原 -f、--repo 及参数选项的重试命令。
• 阶段事件日志：宿主 setup 与紧随其后的生命周期重试共用同一个 operation_id。即便首次 setup 在创建部署状态前就失败，也可以运行 barn logs --source events --json 读取定长轮转的阶段事件日志（日志自动脱敏命令参数与凭据；setup --dry-run 不写日志）。
• 遗留持久盘：先前移除节点后保留下来的受管持久盘不会阻塞其余节点的销毁；需要连同这些持久盘一并清理时，请执行 destroy --delete-persistent 或 purge。
• macOS 准备顺序：在 macOS 上安装新网络时，setup 会先完成 Homebrew 查找/安装或下载固定版本的 socket_vmnet 归档，最后再请求管理员授权，避免安装或下载耗时导致先前的 sudo 凭据过期，也不会在下载失败时白白弹出密码框。
• PID 与日志对账：如果记录的 QEMU PID 已被无关进程复用，Barn 会将该节点识别为 stopped；若停止操作中断但虚拟机进程仍在运行，Barn 会将其恢复为 running。若在线 resize 在修改运行中客机后中断，status 会报告 resize_incomplete，可重新运行 barn resize <node> 或执行 barn restart <node>。其他中断状态会提示恢复命令（destroy 会直接完成中断清理）；首次 up 失败后，修改清单再重试时 Barn 会根据事务日志自动回滚未提交的残留产物。
• 取消操作：命令被取消时，Barn 向正在运行的外部程序发送 SIGTERM，sudo 会将其转发给特权命令；Barn 最多等待 10 秒，让该进程及其继承的输出管道结束。忽略 SIGTERM 的后代进程仍需外部监管。

日志与环境变量

barn logs 默认读取客机串口控制台（--source serial）。指定 --source qemu 可读取 QEMU 诊断输出，指定 --source events 可读取部署级的定长事件日志。配合 --follow（-f）时，文本模式流式输出字节，JSON 模式输出 NDJSON 行，YAML 模式输出文档流。Barn 默认将事件日志与 QEMU 日志格式化为简洁记录，仅在传入 --verbose 时展开完整的 QEMU 启动参数。

显式传入的 --json、--yaml 与 -v/--verbose 优先于 BARN_OUTPUT 和 BARN_VERBOSE；即使这两个变量取值无效，--help 仍可正常使用。其他命令在无效取值未被命令行参数覆盖时，以退出码 2（usage）报错。

SSH 透传与命令补全

barn ssh [node] [-- command...]
barn exec [node] -- command...

• barn ssh：不带远端命令时打开交互式登录终端；带上 -- command... 时，将 -- 后的参数用空格拼接后交给远端 shell 解释。
• barn exec：要求提供 -- command...，并将程序名与各个参数分别传递，原样保留参数中的空格、引号、后续空字符串参数以及 shell 元字符。需要使用管道、重定向、变量展开或串行执行多条命令时，请显式调用 sh -c '...'。
• -- 之前的位置参数最多只能包含一个已知节点名（省略时默认选择控制节点）。若 -- 前出现未知节点名或多个选择器，命令会在发起连接前直接以退出码 2（usage）报错，列出已知节点并提示运行 barn status。
• --json、-v、--help 等 Barn 自身参数必须放在 -- 之前；-- 之后的所有内容（包括第二个 --、-V 或 -o...）都归属远端命令，不会修改本地 OpenSSH 客户端选项。

barn ssh meta
barn ssh meta -- 'df -h /data; id'
barn exec meta -- hostname
barn exec meta -- printf '<%s>\n' 'a b' ''
barn exec meta -- sh -c 'id; df -h /data'
barn exec meta --json -- uname -a

执行 barn completion bash|zsh|fish|powershell 可导出对应 shell 的自动补全脚本（升级版本后，Bash 用户可执行 source <(barn completion bash) 重新加载）。补全覆盖命令、短别名、拓扑模板、镜像别名、枚举参数、-f 的 YAML 文件以及当前清单或已应用状态中的节点名，并在输入 -- 后停止提示 Barn 参数。

退出码

镜像目录缺少签名或签名校验失败时返回 reason: "catalog_signature"；目录复用已接受或内置的 revision 号但内容字节不同时返回 reason: "catalog_equivocation"。读取缓存目录签名时遇到的权限或 I/O 错误属于运行时错误（退出码 1）。

若另一个 barn 命令正持有部署锁，修改类命令最多等待 10 分钟并指出持锁命令；等待超时则以退出码 4（reason: "deployment_busy"）退出。只读与访问类命令（status、ssh、exec、ssh-config、hosts）不会阻塞等待锁；其中 status 会展示最近一次提交的节点状态，并在 note 字段中注明正在并发执行的操作。

ssh 与 exec 会原样返回 SSH 子进程的退出码（包括 255，既可能表示 SSH 连接失败，也可能是远端命令自身返回 255），文本输出、JSON exit_code 与进程退出码三者始终保持一致。

4 - Mac 运行时参考

barn [--json|--yaml] [-v|--verbose] mac <command> [flags] [name...]

运行 macOS 客机需要搭载 Apple 芯片且运行 macOS 27 或更高版本的 Mac，并由当前登录桌面用户直接调用。需要调用原生 runner 的命令会以 mac_root 拒绝 root 身份，并以 mac_host_unsupported 拒绝不满足要求的宿主。在 Linux 与 Intel Mac 上，顶层 --help 默认隐藏 mac 命令；而 barn mac image ls 等只读取本地记录的子命令则无需启动原生 runner。不带子命令直接运行 barn mac 等同于 barn mac ls。

本参考说明 Barn 1.2.0 的命令接口与 Barn.app（macOS 宿主上运行虚拟机的原生应用包，runner 协议版本 2）。Apple Silicon 发行包与 Homebrew 安装已包含 App，安装步骤见 macOS 客机指南。

各子命令的完整语法、选项和示例见 macOS 命令参考。本页集中说明机器规则、网络、结果格式和状态文件。

命令

SSH 与 exec

-- 之前除 Barn 参数外，最多接受一个已存在的虚拟机名（省略名称时自动选择唯一虚拟机或 mac1）。ssh 不带命令时打开交互式终端；exec 必须在 -- 后提供非空命令。未知的机器名或语法错误会在发起连接前直接返回退出码 2（usage），并提示运行 barn mac ls 查看现有机器。

ssh 会将 -- 后的参数用空格拼接成命令行交给客机 shell；exec 则将程序名和各个参数分别传入，完整保留空格、引号及后续空字符串参数。需要管道、重定向、变量展开或串行执行多条命令时，请显式使用 sh -c '...'。--json、-v、--help 等 Barn 参数必须放在 -- 前，其后的所有参数（包括第二个 --）都归属客机命令。

为保持兼容，exec 也接受单个命令字符串作为 shell 简写。新脚本请分开传入参数或显式使用 sh -c，明确是否需要 shell 解释。

barn mac ssh dev
barn mac ssh dev -- 'sw_vers; id'
barn mac exec dev -- sw_vers
barn mac exec dev -- printf '<%s>\n' 'a b' ''
barn mac exec dev -- sh -c 'sw_vers; id'
barn --json mac exec dev -- sh -c 'echo out; exit 3'

各命令的参数

对于名称可省略的命令，不传名称时会选中唯一的虚拟机或 mac1；若存在多台虚拟机且没有 mac1，命令会提示你显式指定名称。start 与 stop 支持传入多个名称或 --all。在终端中，destroy 与 recreate 会先列出即将删除的内容，并要求输入命令名称确认；--yes（或 --force）可跳过询问，没有终端时必须传入。这两条命令的 --yes 没有 -y 简写；mac stop --force 表示立即断电。

--no-wait 会在虚拟机进程启动后立即返回；对于新建虚拟机，后续仍需运行一次不带 --no-wait 的 barn mac up NAME 以完成 SSH 密钥写入与 sudo 配置。普通 start 要求虚拟机已完成首次启动——若未完成首次启动的虚拟机已在运行，可执行 barn mac open NAME 查看首次启动画面；若已停止，则执行 barn mac up NAME --open。传入 --recovery 会跳过常规就绪等待，直接启动进入 macOS 恢复模式桌面。

参数取值

对已存在的虚拟机运行 up 时，若传入的创建参数与现有设置不一致，up 会以 mac_configuration_conflict 拒绝执行，并在 next: 行给出对应的 configure 或 recreate 命令：

• 在虚拟机停止状态下使用 barn mac configure 修改 --cpu、--memory、--share/--unshare、--subnet 或 --clipboard（剪贴板配置也可在运行时修改并保存到下次启动生效；当前会话可通过菜单栏图标即时开关剪贴板同步）。共享名称支持空格与中文，须为 1–255 字节的有效 UTF-8，不能是 .、..，也不能包含 / 或 ASCII 控制字符；configure --share 复用已有名称时会更新其路径与读写属性，--unshare 则按名称移除对应共享。
• 管理员账号（--user）与磁盘容量（--disk）在虚拟机整个生命周期内固定不变，recreate 也会保留它们；如需更改账号或磁盘大小，请创建一台新虚拟机。
• 升级虚拟机的 macOS 版本时，先运行 barn mac image update，再执行 barn mac recreate NAME --update。由于 recreate --update 会保留原虚拟机的磁盘容量，若新 macOS 版本下还没有对应自定义容量（如 200G）的基础镜像，请先执行 barn mac setup --disk 200G 准备好该容量的基础镜像。

机器规则

• 名称：1–32 个字符，以小写字母开头，仅含小写字母、数字与中间连字符（例如 mac1、dev、build-2）。
• 单机两台并发上限：受 Apple Virtualization 框架限制，每台 Mac 最多同时运行两台 macOS 虚拟机（跨所有虚拟化应用以及正在执行的 .ipsw 基础镜像安装任务统一计数）。Barn 绝不会为了腾出名额而停止已有虚拟机。ls.running 统计当前 BARN_HOME 内的活跃虚拟机数，宿主全局上限则由 Apple 运行时强制执行。
• 管理员账号：默认配置免密 sudo、Ed25519 SSH 密钥登录、桌面自动登录与“远程登录”（SSH 服务），并关闭 SSH 密码认证；随机生成的本地登录密码保存在虚拟机槽位目录的 password 文件中（权限 0600）。
• 主机名：客机电脑名称（ComputerName）与虚拟机名 <name> 一致，本地主机名（LocalHostName）设为 barn-<name>（可通过 barn-<name>.local 访问）。
• 目录共享：客机内通过单个 VirtioFS 设备挂载到 /Volumes/My Shared Files/<name>。宿主源须解析为已存在的目录，支持符号链接；名称支持空格与中文。
• 剪贴板同步：每当虚拟机桌面窗口获得或失去焦点时，Barn 通过该虚拟机的 SSH 连接双向同步不超过 1 MiB 的纯文本，并自动跳过标记为敏感（concealed）的剪贴板条目。
• 关机行为：barn mac stop 会向客机发送正常关机请求，等待满两分钟仍未退出则强制断电（返回 "forced": true）；传入 --force 则立即断电。

网络

每台虚拟机的 runner 进程在启动时通过 Apple 的共享模式 vmnet API 创建独立的用户态网络，并在退出时自动销毁，全程无需守护进程或 root 权限：

如果宿主新增的路由（如 VPN 路由）占用了虚拟机已保存的网段，start 会以 mac_subnet_in_use 拒绝启动；此时执行 barn mac configure NAME --subnet auto 即可改换到空闲网段。由于 SSH 主机密钥绑定在虚拟机实例标识 barn-mac-<instance_id> 而非 IP 地址上，更换网段不会破坏 SSH 信任链。

macOS 的“本地网络”隐私权限有时会拦截第三方终端或 IDE 访问 vmnet 子网（通常表现为 No route to host），请在 系统设置 → 隐私与安全性 → 本地网络 中为对应应用开启权限。Barn 自身的 Go SSH 连接通过系统内置的 /usr/bin/nc 转发，交互命令则直接调用 /usr/bin/ssh，从而避开第三方二进制直连本地子网时的权限限制。

JSON 输出

除交互式 ssh 外，所有 barn mac 命令均支持通过 --json 与 --yaml 在 stdout 输出结构化结果，同时将进度信息写往 stderr。

ls

{
  "schema_version": 2,
  "root": "/Users/alice/.barn/mac",
  "prepared": true,
  "base": {"version": "27.0", "build": "26A428", "base_id": "26A428-e16af589f4b705ca397f5b21"},
  "machines": [
    {
      "name": "mac1",
      "kind": "macos",
      "state": "running",
      "ready": true,
      "ssh": "ready",
      "address": "10.10.20.10",
      "address_stable": true,
      "ssh_host": "10.10.20.10",
      "ssh_port": 22,
      "user": "alice",
      "image": {"version": "27.0", "build": "26A428", "base_id": "26A428-e16af589f4b705ca397f5b21"},
      "cpus": 4,
      "memory_bytes": 8589934592,
      "disk": {"capacity_bytes": 107374182400, "allocated_bytes": 1202647040},
      "network": {"subnet": "10.10.20.0/24", "gateway": "10.10.20.1", "address": "10.10.20.10"},
      "shares": [{"name": "src", "host": "/Users/alice/src", "guest": "/Volumes/My Shared Files/src", "readonly": false}],
      "clipboard": true,
      "pid": 2545,
      "instance_id": "b1482ffc-2da7-45d9-ace5-c5f3193a9172",
      "warnings": []
    }
  ],
  "running": 1,
  "limit": 2
}

生命周期结果

单机操作（up、restart、open、recreate、configure）返回单个结果对象；批量操作（start、stop、destroy）即使只指定一台虚拟机也始终返回 {"machines": [...]}。多台虚拟机操作部分成功时，结果中会同时保留成功项与失败详情，并以退出码 5 返回。

{"name": "mac1", "action": "created", "state": "running", "ready": true,
 "address": "10.10.20.10", "user": "alice", "version": "27.0", "build": "26A428"}

其他命令的 JSON 输出：

• exec --json：返回与 Linux barn exec --json 相同的结构（node、exit_code、stdout、stderr）。
• password --json：返回明文密码；配合 --copy 时返回 {"name": "mac1", "copied": true}。
• ssh-config --json：默认返回 fragment 字符串；配合 --install 或 --remove 时返回安装状态。
• logs --json：返回 name 与 logs。
• doctor --json：返回 ok 与 checks[]（每项含 name、ok、detail 及可选的 next），任一检查未通过时退出码为 3。

失败原因

退出码遵循 Barn 命令行退出码表，ssh 与 exec 原样透传远端命令退出码。结构化错误对象包含稳定的 reason 标识与 next 修复建议：

文件

其他宿主与客机文件路径：

• 运行时套接字：/tmp/barn-mac-<uid>-<hash>/。
• OpenSSH 配置片段：barn mac ssh-config 负责维护 ~/.ssh/barn-mac_config 以及 ~/.ssh/config 中的 # barn-mac:include 区块（与 Linux 环境使用的 # barn:include 区块互不干扰）。执行 barn mac ssh-config --remove 会在 config.json 中写入 ssh_config_off，此后生命周期命令不会再自动写入 SSH 配置，直到你显式运行 barn mac ssh-config --install。
• 桌面窗口偏好设置：Barn 将窗口位置保存在 ~/Library/Preferences/com.pgsty.barn.plist（0.9.0 使用 ~/Library/Preferences/io.pgsty.barn.mac-runner.plist）。
• Runner 查找机制：CLI 根据解析符号链接后的自身可执行文件路径定位 runner，兼容 Barn.app 应用包（Barn.app/Contents/MacOS/barn-mac-runner）、安装器与 Homebrew libexec 布局；开发调试时可通过环境变量 BARN_MAC_RUNNER 指定绝对路径、相对路径或 ~/ 路径。执行虚拟机操作前 CLI 会校验 runner 协议版本 2；barn mac doctor 还会检查 runner 的本地代码签名。
• 客机内部配置文件：Barn 在客机内写入 ~/.ssh/authorized_keys、/private/etc/sudoers.d/80-barn 与 /etc/ssh/sshd_config.d/000-barn.conf，设置电脑名称与本地主机名，并通过 pmset 禁用休眠。

镜像清理会保留中断的 recreate 仍在引用的基础镜像，直至恢复清理完成。恢复日志损坏时，barn mac image ls、barn mac doctor 的空间估算与镜像清理都会失败，直到日志修复，期间所有镜像原样保留。若某台机器的状态无法读取，barn mac ls 会整体失败，按名称操作其他机器不受影响。

5 - 镜像

Barn 通过静态镜像目录与不可变 qcow2 产物解析 Linux 客机镜像。官方仓库与 HTTP 仓库必须提供 Ed25519/minisign 目录签名，用户显式指定的本地目录仓库与 HTTPS 仓库则允许不签名。日常可通过 barn update 激活新版镜像目录而无需升级 barn 二进制；受信任的签名公钥与 qcow2 安全检查规则则由二进制本身固定。

别名与拉取顺序

Barn 1.2.0 内置镜像目录 2026110502，包含 Debian 13 镜像 20261103.2651.1。目录涵盖 9 个发行版系列，每个系列一个 stable 版本，共 17 个镜像产物：el7 仅提供 amd64，其余系列均同时提供 amd64 与 arm64。缺省请求为宿主原生架构的 u24:stable（Ubuntu 24.04 LTS）。

下表列出内置镜像目录 2026110502 中各系列的 stable 版本快照。运行 barn update 后再执行 barn image list 可查看所选仓库当前的实时目录；宿主平台兼容性详见平台与限制。

发行版说明：

• u22、u24、u26 分别对应 Ubuntu 22.04、24.04、26.04 LTS，d12 与 d13 对应 Debian 12 与 13。它们由 Barn 镜像配方基于发行版官方云镜像构建：镜像内置 dba 用户（UID/GID 88），已带 XFS 用户态工具，并提供 en_US.UTF-8 区域设置，默认区域设置保持为 C.UTF-8。
• el7 为 CentOS Linux 7.9（amd64 BIOS），el8、el9、el10 为 Rocky Linux（amd64 与 arm64 UEFI）。el8 与 el9 同样经过该配方处理（dba，UID/GID 88）；el10 与 el7 直接使用发行版未经修改的云镜像。
• 所有镜像都在首次启动时由 cloud-init 完成账号与网络配置。
• 运行 barn update 只会更新新节点的 :stable 或版本前缀解析结果，已运行的虚拟机和显式锁定 @version 的节点继续使用原有基础镜像。若现有清单使用的通道或版本前缀在新目录中指向了新版本，后续执行 barn plan 或 barn up 会报告镜像漂移，需显式运行 barn recreate 才会替换节点。

barn image list
barn image info d13
barn image info d13:stable
barn image info el9@9.8
barn image pull d13@20261103.2651.1
barn image pull d13 --arch arm64
barn update

barn image list 会列出当前激活目录中的全部版本、架构以及已注册的 local-* 本地别名。barn image info 与 image pull 一样默认采用本机架构；未缓存时无需安装 QEMU 即可查看目录元数据，已缓存时则会调用 qemu-img 校验本地缓存文件。list 与 info 都不会发起镜像下载。

目录中的 status 字段标识支持等级（supported、testing、deprecated 或 unknown）；非 supported 状态的镜像依然可以正常启动，并会在输出中附带状态警告。

拉取镜像时，Barn 依次执行以下四步：

1. 读取本地活动目录 — 为本次命令加载一次所选仓库的本地活动镜像目录（即二进制内置目录，或最近一次通过 barn update / barn image sync 为该仓库激活的目录）。
2. 解析选择器与架构 — 解析 image[:channel] 或 image@version-prefix（官方目录缺省为 u24:stable）及目标架构。独立执行 image pull 默认取宿主架构；生命周期命令遵循 vm_arch，未设置时也取宿主架构。Barn 的 --arch/-A 可覆盖上述选择，优先级见配置参考。
3. 校验本地缓存 — 若本地已存在对应缓存文件，且文件大小、SHA-256 摘要与 qemu-img 结构检查全部通过，则直接复用。
4. 断点续传与落盘校验 — 若未命中缓存，则从所选仓库下载对应产物（支持自动重试与断点续传），待文件大小、SHA-256 与 qcow2 格式全部校验通过后移入缓存。两个官方源（https://repo.pigsty.io/barn 与 https://repo.pigsty.cc/barn）在下载镜像文件时支持自动互备回退，自定义 --repo 仓库则严格只从指定源下载；目录中记录的上游 URL 仅用于构建溯源。

仓库选择优先级依次为 --repo → --mirror（https://repo.pigsty.cc/barn）→ BARN_REPO → 编译期默认源（https://repo.pigsty.io/barn）。两个官方仓库均要求有效的 minisign 镜像目录签名。

由于每个仓库根路径在 $BARN_HOME/images/manifests/ 下独立维护各自的活动目录记录，使用自定义仓库时请始终传入相同的 --repo（或设置 BARN_REPO）；首次切换到带有自定义别名的新仓库时，请先执行 barn update --repo <root> 激活其目录。只要本地已具备激活目录与通过校验的缓存镜像，日常命令即可完全离线运行。

Barn 会自动将通过校验的缓存镜像恢复为只读权限（0444）。如果未被虚拟机引用的缓存文件校验失败，Barn 会先将其重命名为 .corrupt-<timestamp> 留存，再重新下载；若该基础镜像仍被现有虚拟机引用，则保持原文件不动并直接报错。

运行时策略

当客机架构与宿主架构一致时，Barn 默认启用硬件加速虚拟化（macOS 使用 Apple HVF，Linux 使用 KVM），仅有一项内置例外：Rocky Linux 8（el8）的 arm64 原生内核使用 64 KiB 内存页，而 Apple HVF 不支持 64 KiB 页大小，因此 Apple Silicon 宿主运行 el8 时会自动切换为同架构 QEMU TCG 并在状态输出中标注 tcg。跨架构客机（vm_arch 或命令行覆盖后的架构与宿主不同）同样使用 TCG；在 arm64 宿主上模拟 amd64 客机时，Barn 会将 TCG 固定为单翻译线程以保证 x86 内存序正确。

Barn 的 ARM64 TCG 运行时使用 cortex-a72 CPU 模型，避免部分 QEMU/AAVMF 组合在 max 模型下卡住固件。Linux x86-64 宿主运行 ARM64 客机已通过真实 Barn 启动与 SSH 检查。当前 Barn 的目录和运行时只接受 amd64、arm64；发行版或 QEMU 提供其他架构，不代表这些架构已可用于 barn up。

el7 仅支持在 linux/amd64 宿主上原生运行。Linux 宿主的 barn setup 默认只安装本机架构的 QEMU；在通过 up 或 recreate 启动跨架构客机前，请先安装对应架构的 qemu-system-* 模拟器与 UEFI 固件（barn plan 无需安装这些工具即可解析目录镜像，但解析 local-* 导入镜像仍需 qemu-img）。

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

信任与校验

正式发布构建内置了两把生产环境 Ed25519 校验公钥（签名私钥保存在源码仓库之外）。激活镜像目录时，Barn 会拒绝未知签名密钥、格式错误的 JSON、同一修订号下字节不同的内容，以及低于该仓库历史最高已接受修订号的目录（除非在 barn image sync 时显式传入 --allow-downgrade）。缺少签名、签名校验失败或 revision 字节冲突时退出 7（integrity，见退出码）。对相同目录字节的新可信签名会被接受，这也可以修复已损坏的缓存签名。

所有缓存或导入的镜像都必须是文件大小与 SHA-256 严格匹配的独立 qcow2 文件，不得包含后端依赖链（backing file）、外部数据文件、加密或未知的不兼容特性位。通过校验后，Barn 将基础镜像设为只读，并为每个虚拟机节点创建独立的写时复制（CoW）overlay 根盘。

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

• barn update：从 --repo 或 --mirror 拉取、验签并激活最新镜像目录。
• barn image sync：从显式指定的 URL 或本地文件路径恢复镜像目录（对于未签名的自定义仓库，源路径必须指向该仓库根目录下的 catalog.json），支持 --allow-downgrade 显式降级。
• barn image reset：将 --repo（或默认仓库）的活动目录重置回二进制内置版本，同时保留防回滚所需的历史最高修订号水位线。

静态仓库格式

静态 Barn 镜像仓库的目录结构如下：

repo.yaml（schema: 1）负责声明默认配置、别名、通道、精确版本、架构、引导方式、支持状态、source_user（如上游镜像的 rocky 或经 Barn 官方归一化后的 dba）以及可选的上游溯源 URL，无需手写校验和与文件大小。barn repo build 会检查 images/ 下的 qcow2 文件，并自动生成包含文件名、SHA-256、文件大小与虚拟容量的 catalog.json（schema: 3）。

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/<image>-<version>-<arch>.qcow2（例如 images/u24-1-amd64.qcow2 与 images/u24-1-arm64.qcow2）。

静态仓库构建与校验规则（barn repo scan|build|verify /absolute/repo）：

• 仓库根目录接受相对路径、~/ 与目录符号链接，根目录和 images/ 可以共享可写。repo.yaml 可为指向不超过 4 MiB 非空普通文件的符号链接。镜像条目仍须为普通文件，输出 catalog.json 的符号链接不会被覆盖。
• 引导方式按 variant → family → defaults.boot 继承；状态按 variant → version → unknown 继承。每个系列都必须定义指向已有精确版本的默认通道；系列名与别名全局唯一且不能以 local- 开头。由于清单别名归一化会先查二进制内置目录，请勿将 ubuntu、debian、rocky 等内置别名改指其他系列。
• 通道与按点号分段的数值前缀（如 el9@9.8、el9@9）会解析为精确版本或匹配的最高版本，最终落定为不可变的三元组标识 (image, exact version, arch)：

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

• barn repo scan 为只读检查，不依赖 qemu-img；即使存在 missing（缺失）或 unsafe（命名/类型不安全）的文件也会返回退出码 0，自动化脚本需检查输出中的 missing 与 unsafe 数组是否为空。
• barn repo build 与 barn repo verify 依赖本机 qemu-img。build 校验 repo.yaml 并完整检查每个 qcow2 文件后原子替换 catalog.json（存在 missing 或 unsafe 文件时拒绝构建，untracked 未声明文件则仅报告而不写入目录）；verify 要求现有 catalog.json 与重新生成的结果逐字节一致。每次修改目录内容都必须递增 revision，发布时先上传不可变的 .qcow2 文件，最后同步更新 catalog.json 与 catalog.json.minisig。

本地布局与导入

Barn 将目录记录、下载缓存与本地导入文件统一存放在 $BARN_HOME/images（默认 ~/.barn/images）：

将本地 qcow2 文件导入缓存，或注册为 local-* 命名镜像：

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

本地导入规则：

• image import 接受相对路径、~/ 和普通文件的符号链接，并需要 qemu-img。读取以实际本地文件大小或镜像目录声明的大小为界；下载超出声明大小时停止，未声明产物大小的旧协议下载限制在 8 GiB 以内。可选 --sha256 用于核对预期摘要。
• image import 仅复制并校验 qcow2 文件结构，不会清理凭据、安装 cloud-init 或测试启动。
• 源文件名可包含空格或 Unicode，无需特定扩展名；Barn 校验实际 qcow2 内容。新导入使用 local/<sha256>.qcow2，同名不同内容可并存，相同内容复用缓存。重新导入已有别名时保留其原有缓存路径。注册表元数据若超过 1 MiB，会在写入前报错并保留已有别名。
• 命名导入（--name local-<alias>）必须同时指定 --boot bios|uefi 与 --source-user <user>，默认记录宿主架构。可通过 --arch/-A 显式记录 amd64 或 arm64 及其别名；qcow2 元数据不能识别客机 CPU，导入也不会转换架构。使用该镜像时，清单的 vm_arch 或生命周期命令的 -A 须与之匹配。别名一旦注册不可更改，可通过 vm_image: local-mybase 引用；不带 --name 的导入仅预填充缓存，不能传 -A。

清理

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

barn image prune（或 barn image prune --dry-run）只列出可回收的候选文件，传入 --yes 才会实际删除。

prune 会自动保护当前所选仓库活动目录中的全部镜像、已应用节点正在引用的镜像摘要以及已注册的 local-* 别名（因此执行 destroy 或 purge 后基础镜像缓存依然保留）。只有不再受当前目录、节点或本地别名保护的旧镜像及过期暂存文件才会成为清理候选；已隔离的 .corrupt-* 文件会原样保留供排查，未知或不安全的文件则会触发报错。由于 prune --yes 按顺序逐个删除候选文件且在中途出错时不会回滚已删除的文件，清理前请先运行 --dry-run 确认列表（检查自定义仓库时请附上相同的 --repo）。

如需在初始化镜像站时逐字节导出二进制内置的 Schema-3 镜像目录，可在源码仓库下运行 go run ./tools/catalogexport /absolute/new/catalog.json；任何使用内置修订号发布的公开目录都必须与导出的字节完全一致。

6 - 镜像流水线

在 Barn 源码仓库下使用 packaging/image-pipeline/build.sh，可对照已知的 SHA-256 摘要校验或离线归一化已下载的 qcow2 候选镜像。该工具全程在本地运行，不联网、不读取签名密钥、也不修改 Barn 运行时与网络状态，输出状态为 testing 的候选产物包，供后续真机冒烟测试与发布审核使用。

构建宿主环境要求：

• 依赖工具：所有模式均需 Python 3 与 qemu-img；offline 模式还需安装可用的 libguestfs 工具（virt-customize 与 virt-cat）。可通过 --qemu-img、--virt-customize、--virt-cat 参数或 QEMU_IMG、VIRT_CUSTOMIZE、VIRT_CAT 环境变量指定工具路径。
• 工作树外存储：请将源镜像、RPM/DEB 软件包缓存和输出目录放在 Git 工作树之外（源码仓库只跟踪构建配方与锁定清单）。
• 架构匹配：--arch 用于记录候选镜像的目标架构元数据；执行 offline 定制时，构建宿主上的 libguestfs 必须能够运行目标客机架构。

模式与处理方案

• validate（校验模式）：复制源镜像并重算哈希，调用 qemu-img check 强制检查单文件 qcow2 结构，不修改客机文件与凭据，直接生成证据产物包。
• offline（离线归一化模式）：在暂存副本上运行 virt-customize --no-network 与 virt-cat：确认 UID/GID 88 未被其他账号占用后，配置固定的 dba/admin 管理身份，禁用 SSH 密码登录与 root 登录，清理残留密钥、命令历史、机器标识与 cloud-init 缓存，恢复 SELinux 标签，并读回客机内的确定性标记以验证定制结果。

build.sh 默认使用 --profile base。各处理方案（profile）的作用范围如下：

validate 模式仅支持 --profile base。在 offline 模式下使用 el8、d12 或 d13 时，必须同时传入与方案及架构匹配的 --package-lock 和 --package-cache。构建官方镜像时，直接使用下方的 build-official.py 封装脚本即可自动传入锁定的软件包集合。

官方候选镜像矩阵

packaging/image-pipeline/build-official.py 封装了八个官方离线归一化目标——Debian 12/13（d12、d13）与 Rocky Linux 8/9（el8、el9）各自的 amd64 与 arm64 变体，所有上游 qcow2 URL、RPM/DEB 依赖包、发布版本号、SHA-256 摘要与 SOURCE_DATE_EPOCH 均锁定在 official-v1.json 中（目录中的 Ubuntu 制品由 pipeline.py 直接按同一配方构建；Ubuntu 云镜像自带 xfsprogs，无需离线依赖包锁定）。

./packaging/image-pipeline/build-official.py --list

./packaging/image-pipeline/build-official.py \
  --source-cache /absolute/source-cache \
  --package-cache /absolute/package-cache \
  --output /absolute/existing-output-root \
  --target d13/arm64 --fetch

使用说明：

• 运行前请预先创建好 --source-cache、--package-cache 与 --output 目录，并传入规范化的绝对路径。加上 --fetch 时，脚本会从锁定的 HTTPS URL 下载缺失输入并在调用 virt-customize --no-network 前校验 SHA-256；不加 --fetch 时，所有锁定输入必须已存在于两个缓存目录中。
• 省略 --target 会构建全部八个目标，重复指定 --target 可构建指定子集。--list 会列出当前源码锁定的精确版本。

八个目标全部构建完成后，将 包含各产物包目录的父目录 传给 --assemble-from（若分散在多个父目录可重复传入 --assemble-from），即可组装出静态候选仓库：

./packaging/image-pipeline/build-official.py \
  --assemble-from /absolute/existing-output-root \
  --output /absolute/new-candidate-repository

组装操作要求八个目标各有且仅有一个产物包，输出目标路径 --output 必须尚不存在，并会调用 PATH 中的 barn（或 --barn /absolute/path/to/barn）执行 barn repo build 与 barn repo verify。生成的候选仓库默认使用 candidate 通道（例如 d13:candidate）和 testing 状态，便于在提升为 stable / supported 之前执行真机冒烟测试。

校验单个已下载镜像

SOURCE_DATE_EPOCH=1787486400

./packaging/image-pipeline/build.sh \
  --mode validate \
  --source /absolute/source.qcow2 \
  --expected-sha256 <digest> \
  --output /absolute/new/evidence-directory \
  --name u24 --release 20260801.0.0 --arch amd64 \
  --source-user ubuntu --boot uefi \
  --source-uri https://immutable.example/source.qcow2 \
  --artifact-url 'https://images.example/u24/{sha256}.qcow2' \
  --license NOASSERTION \
  --source-date-epoch "$SOURCE_DATE_EPOCH" \
  --manifest-version 2026082903

路径与容量限制：

• --source 必须是规范化绝对路径的普通文件（非符号链接），大小不超过 16 GiB；--output 的父目录必须已存在，而目标目录本身必须尚不存在。
• Barn 按镜像目录声明的大小（或本地导入文件的实际大小，详见本地镜像导入）校验运行时镜像产物；贡献者构建流水线仍遵循构建配方的大小边界。
• 构建器会在输出路径旁创建排他锁，在权限 0700 的临时目录中完成暂存，最后通过原子重命名发布到 --output（失败时仅清理本次构建的暂存目录）。

每个成功生成的产物包包含以下文件：

在输入文件与工具版本固定时，validate 模式可逐字节复现；使用 offline 模式准备发布证据时，请对同一候选镜像构建两次并比对结果。将候选镜像正式发布为 supported 状态时，还需在目标宿主与客机组合上完成真机启动测试、在 repo.yaml 中递增 revision 并更新状态、运行 barn repo build 与 barn repo verify、使用生产密钥签发 catalog.json.minisig 并验证公开仓库端点。