这是本节的多页打印视图。 .

参考

Farrow 读取的 Pigsty Inventory 与命令行的准确契约。

1: 配置
2: 命令行
3: 镜像
4: 镜像流水线

配置：发现顺序、变量、默认值、磁盘、共享、命名与漂移。
命令行：命令、关键参数、输出模式与退出码。
镜像：签名 Catalog、别名、本地缓存、拉取、导入与清理。
镜像流水线：Candidate 校验与离线归一化。

Farrow 不提供受支持的 Go Library API；internal/ 下的包都是实现细节。

1 - 配置

Farrow 读取的 Pigsty Inventory 字段、默认值与节点级漂移行为。

发现顺序

依次查找：显式 -f、当前目录的 farrow.yml、farrow.yaml、pigsty.yml、 pigsty.yaml。所有文件名都使用同一种 Pigsty 兼容 YAML Inventory。

旧的顶层 version:/nodes: 格式会直接报迁移提示。

plan、up、reload、recreate 找不到文件时，如果 deployment 已存在，会回退到已应用规格；validate 不会回退。配置必须是最大 4 MiB 的普通非符号链接文件。

Farrow 读取什么

Farrow 读取主机 IP、nodename、admin_ip、pg_cluster、pg_seq、 node_admin_username、node_admin_uid 与已记录的 vm_* 变量。admin_ip 只从 all.vars 读取，用于选择控制节点；没有匹配时使用第一台托管主机。所有节点必须解析为同一个登录用户名；默认用户 dba 的显式 node_admin_uid 必须为 88。

其余内容完全不读，也不会产生 drift。这里指 pg_role、pg_version、repo_*、 node_packages 等未消费字段，不能泛化为所有 pg_* 或 node_*。

命名空间内严格校验：未知 vm_*、错类型、Jinja 表达式、非法地址、同级分组冲突都会报错。

VM 变量

变量	默认值	含义
`vm_skip`	`false`	不虚拟化这台真实/外部主机
`vm_image`	`u24`	镜像别名
`vm_arch`	`native`	部署级 Guest 架构：`native`、`amd64` 或 `arm64`
`vm_cpu`	`2`	vCPU 数量
`vm_mem`	`4096`	MiB 整数，或 `8GiB` 等尺寸
`vm_disk`	`64`	根盘 GiB
`vm_disks`	`[{path: /data}]`	额外数据盘
`vm_alias`	`[]`	Guest `/etc/hosts`、SSH config 与可选宿主别名
`vm_shares`	`[]`	QEMU 9p 宿主目录共享

空主机条目就是一台完整 VM。每套 deployment 支持 1–20 台托管主机；vm_cpu 范围 1–256，内存至少 512 MiB。

vm_arch 比普通逐主机字段更严格：出现时必须在所有托管主机上解析为同一个值，因此应只在 all.vars 定义一次。修改它属于 deployment envelope 变化，必须整体重建。 Linux setup 只安装宿主原生模拟器；外来架构还需要对应 qemu-system-* 与固件。

数据盘

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

path 同时是磁盘身份与挂载点；fs 为 xfs 或 ext4。persistent: true 在普通 destroy 后保留；vm_disks: [] 表示不要额外盘。

目录共享

vm_shares:
  - host: /absolute/owned/source
    guest: /src
    readonly: true

源目录必须真实、属于调用者且互不重叠。9p 只适合可信开发文件，不能放 PostgreSQL 数据。

名称与地址

节点名依次取 nodename、<pg_cluster>-<pg_seq>、node-<IP末段>，且必须唯一。

所有托管主机必须位于同一个 RFC1918 /24：.1 属于宿主，.2–.8 保留，节点使用 .9–.254。

漂移

Farrow 对每个解析后节点计算哈希。新增主机由 up 创建；选中的已停止节点会启动，运行中同伴不受影响。VM 定义变化需要节点级 recreate；删除主机条目只报告、绝不销毁。 deployment 架构、用户或子网变化需要整体重建。修改用于派生节点名的字段会表现为旧节点 missing 加新节点，建议使用稳定、显式的 nodename。

2 - 命令行

Farrow 命令、关键参数、结构化输出与退出码。

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

已安装的二进制是当前版本最准确的参考。每一条可见命令都自带操作边界与可复制样例：

farrow --help
farrow setup --help
farrow image pull --help

文本模式下，直接运行 farrow 或 farrow image 这样的命名空间会展示上下文帮助并成功退出；JSON/YAML 模式下，空命名空间返回结构化用法错误。显式 --help 始终输出供人阅读的帮助文本。

命令

范围	命令
准备	`setup`、`init`、`validate`、`doctor`
生命周期	`plan`、`up`、`start`、`stop`/`halt`、`restart`、`reload`、`recreate`、`status`、`destroy`
访问	`ssh`、`exec`、`logs`、`provision`、`ssh-config`、`ss`、`hosts`
镜像	`image list/info/pull/import/sync/prune/reset-manifest`
宿主网络	`network status/install/uninstall`
其他	`version`、`completion`

使用已应用状态的命令可在任意目录运行。配置来源由命令决定，-f 刻意不做全局参数：

命令	期望状态来源
`setup [template]`	显式 `-f`，否则发现配置，否则生成 `meta`；模板与 `-f` 互斥
`init [template]`	生成新 Inventory，不读取期望状态
`validate`	显式 `-f`，再发现配置；绝不回退到已应用状态
`plan`、`up`、`reload`、`recreate`	显式 `-f`，再发现配置，最后回退到已应用规格
其他生命周期/访问命令	不读取期望配置；按需使用已应用状态或带属主标记的状态

关键参数

参数	含义
`--json`、`--yaml`	stdout 机器可读；进度仍写 stderr
`--verbose`	stderr 有界诊断
`--yes`	应用已展示的宿主/setup 计划
`--force`	跳过 destroy/recreate 交互确认；无终端时必须显式给出
`--no-wait`	QMP/进程身份确认后返回，不等 Guest readiness
`--delete-persistent`	整体销毁时也删持久盘；不能与节点选择器一起使用
`--purge`	整体处置：删除磁盘、密钥与 deployment 状态，保留镜像

如果失败命令尚未输出更丰富的类型化结果，结构化模式会先输出一份包含 error 与 message 的对象，再返回约定的非零退出码；已经携带失败状态的结果后面绝不会追加第二份 JSON/YAML 文档。

plan 是只读操作，即使 action 为 recreate 或 blocked-removal 也返回成功；自动化必须检查 action 与 create、recreate、missing 字段。up 会创建新增节点、启动选中的已停止节点；破坏性 drift 则返回冲突，不会被静默应用。

status 会为每个节点报告持久化的 guest_arch 与 accelerator；文本和结构化输出都会明确显示 TCG。

SSH 透传与命令补全

farrow ssh [node] [--] [command ...] 打开会话或运行可选命令； farrow exec [node] [--] <command ...> 必须给出命令并透传退出码。-- 之前的展示参数属于 Farrow，之后的参数属于 OpenSSH 或远端程序。

加载 farrow completion bash|zsh|fish|powershell 可获得命令与作用域准确的参数补全，同时补全模板、镜像别名、枚举参数，以及从期望/已应用规格只读解析出的节点名。

退出码

代码	含义
0	成功
1	运行时失败
2	用法或配置错误
3	缺少宿主能力
4	状态冲突或需要显式收敛
5	多节点部分完成
6	资源冲突
7	完整性或属主失败

ssh 与 exec 会透传远端程序退出码；但 SSH 保留的传输失败码 255 会被 Farrow 映射为运行时失败 1。

3 - 镜像

签名 Catalog、内置别名、仓库选择、本地缓存校验、导入与清理。

Farrow 使用一份签名静态 Catalog 与不可变 qcow2 工件。更新 Catalog 不需要发布新的 Farrow 二进制，但二进制决定信任哪些签名公钥与镜像安全规则。

警告

EL7 标记为 deprecated；其余内置镜像均为 testing，不是 supported。up 打印的警告是刻意保留的；拉取成功只证明完整性，不代表生产支持承诺。

别名与拉取顺序

内置 Catalog 包含 9 个 Family、17 个工件：el7 只有 amd64；el8、el9、 el10、d12、d13、u22、u24、u26 均有 amd64 与 arm64。默认使用 u24。

别名	发行版	架构	启动	状态
`el7`	CentOS Linux 7.9 / 2211	amd64	BIOS	deprecated
`el8`	Rocky Linux 8.10	amd64、arm64	UEFI	testing
`el9`、`el10`	Rocky Linux	amd64、arm64	UEFI	testing
`d12`、`d13`	Debian	amd64、arm64	UEFI	testing
`u22`、`u24`、`u26`	Ubuntu	amd64、arm64	UEFI	testing

farrow image list
farrow image info u24
farrow image pull u24

拉取时 Farrow 会：

按 --repo、FARROW_REPO、编译期默认仓库的顺序刷新 catalog.json 与相邻 .minisig；
使用内置 active 或 standby 公钥验证签名；
选择 Catalog 默认 Release；独立 image pull 使用本机架构，生命周期解析遵循 vm_arch；
只有尺寸、SHA-256、qcow2 结构全部匹配时才复用本地文件；
否则下载仓库工件，仓库缺失时回退到 Catalog 中不可变的 HTTPS Upstream URL。

当前编译默认值仍是开发仓库 https://m0/farrow，尚未声称存在公开镜像服务。显式仓库失败会报错；无法访问编译默认仓库时则回退到内置 Catalog。

运行时策略

匹配架构正常使用原生 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 固件，plan、up、recreate 才会继续。

farrow image pull --repo https://mirror.example/farrow u24
FARROW_REPO=/absolute/local/repository farrow up

仓库 URL 可以是 HTTP 或 HTTPS，因为 Catalog 签名与镜像摘要才是完整性权威；Catalog 中的不可变 Upstream 工件 URL 必须使用 HTTPS。

信任与校验

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

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

farrow image sync https://repo.example/farrow/catalog.json
farrow image sync --allow-downgrade /absolute/repo/catalog.json
farrow image reset-manifest

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

本地布局与导入

镜像位于 FARROW_HOME/images（默认 ~/.farrow/images）：各 Family 目录保存下载工件， manifests/ 保存 Catalog 状态，local/ 与 local-images.json 保存导入镜像。已经没有旧的 ~/.farrow/cache 或按摘要组织的 sha256/ 层级。

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

命名的本地别名必须以 local- 开头，因此未来的签名 Catalog 无法覆盖它。使用 --name 时必须同时给出 --boot 与 --source-user；Farrow 不猜 Guest Bootstrap 契约。

清理

farrow image prune --dry-run
farrow image prune --yes

Prune 会先列出准确的未引用镜像与遗留 Staging 文件。已应用 deployment 引用的镜像永远不是候选；destroy（包括 destroy --purge）后镜像仍保留缓存。

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

4 - 镜像流水线

不下载、不上传、不签名地校验或离线归一化显式 qcow2 Candidate。

packaging/image-pipeline/ 接受一份已下载的不可变 qcow2 与独立获得的 SHA-256。它绝不下载、上传、修改 Farrow 运行时/网络状态、读取签名密钥，也不会把镜像标成 supported。

模式

validate：复制并重哈希，强制 qcow2 检查，校验单元素 Backing Chain，运行 qemu-img check，输出明确不可发布的证据 Bundle；不会修改 Guest 凭据。
offline：额外在 Staged Copy 上使用 libguestfs virt-customize --no-network 与 virt-cat。它拒绝无关 UID/GID 88 占用，归一化锁定的 dba/admin 身份，关闭密码与 Root SSH，清理密钥/历史/Host Identity/cloud-init Cache，恢复定向 SELinux Label，并回读确定性 Marker。

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 2026082801

Source/Output 必须是绝对路径；Source 必须 Canonical、普通、非符号链接、复制期间稳定，且不超过 16 GiB；Output 必须不存在。Builder 使用相邻排它锁、0700 Staging 与一次最终 Rename；失败只删除受保护的 Staging。

成功 Bundle 包含只读 qcow2、Recipe、SLSA Provenance、SPDX Boundary SBOM、状态为 testing 的 manifest-candidate.json、Validation Evidence 与 Checksums。签名刻意位于流水线之外。固定输入/工具下 validate 模式逐字节可复现；offline Mutation 必须构建两次并比较，才能成为 Release Evidence。