开始使用

• 1: 安装
• 2: 教程
• 3: 日常操作
• 4: 故障排查

1 - 安装

当前可用的安装方式

从当前工作区构建：

cd /path/to/farrow
make build
export PATH="$PWD/bin:$PATH"
farrow version
farrow doctor

目前没有公开的 v1 软件包。不要用来源不明的二进制替换同一次构建产生的 farrow 与 farrow-hosts-helper。

源码构建需要 Go 1.27.x。macOS 还需要已经安装好的 Homebrew；Farrow 可以通过 Homebrew 安装 QEMU，但不会自行引导安装 Homebrew。当前编译默认镜像仓库是开发宿主 https://m0/farrow；需要其他可达镜像时使用 FARROW_REPO 或 --repo。

宿主要求与带日期的证据

HVF/KVM 原生加速是正常路径。任意原生失败绝不会被静默改成模拟重试；只有显式外来 vm_arch，或 Catalog 已知的 EL8 arm64/Apple Silicon 不兼容规则，才会选择 TCG。 TCG 结果只可作为兼容性证据，不能作为性能证据。

macOS 需要 Homebrew。Linux 需要 systemd，以及 NetworkManager 或 systemd-networkd 之一。farrow setup 会通过 Homebrew、APT 或 DNF 安装缺失依赖。

setup 会改什么

可以先看 dry-run：

farrow setup --dry-run
farrow setup --yes

setup 可能安装 QEMU 依赖、准备固定 IP 网络、安装权限很窄的 hosts publisher。 所有宿主变更与 sudo 原因都会先打印。

自动化环境使用 --yes。非交互 sudo 可以来自已缓存凭据或合适的 NOPASSWD 策略； 每一条真实特权命令仍使用明确的绝对路径 argv。

setup 是幂等的：健康的重复执行只会复用网络与 helper。 源码测试与这份带日期的真机矩阵是不同门禁：重新构建更新的工作树不会自动刷新上表。

2 - 教程

1. 创建实验环境

mkdir -p ~/lab
cd ~/lab
export FARROW_REPO=https://m0/farrow   # 离开开发网络后替换为可达镜像
farrow setup --dry-run
farrow setup --yes
farrow up

目录中没有配置时，setup 会写入单节点 farrow.yml：

all:
  vars:
    admin_ip: 10.10.10.10
  children:
    nodes:
      hosts:
        10.10.10.10: { nodename: meta }

up 下载并校验镜像，创建磁盘与 cloud-init seed，启动 QEMU，并等待 Guest 的 readiness 记录。

2. 验证节点

farrow status
farrow ssh meta
farrow exec meta -- hostname
ping 10.10.10.10

默认节点有 2 vCPU、4 GiB 内存、64 GiB 根盘，以及挂载到 /data 的 128 GiB XFS 数据盘。

farrow status 还会显示实际 Guest 架构与加速器。默认 EL9/EL10 使用原生 HVF/KVM。 Apple Silicon 上设置 vm_image: el8 时，Stock 64K Granule Kernel 会自动使用同架构 TCG。显式设置部署级 vm_arch: amd64 可运行 amd64 Guest，但会使用单线程 TCG，速度 明显更慢。EL7 仅作为 deprecated 的 Linux/amd64 原生 BIOS/KVM Guest 提供。

3. 扩到四节点

在同一个 hosts: 映射下增加三行：

        10.10.10.11: { nodename: node-1 }
        10.10.10.12: { nodename: node-2 }
        10.10.10.13: { nodename: node-3 }

然后收敛：

farrow plan       # create: node-1, node-2, node-3
farrow up
farrow status

只会创建新增节点，meta 的进程与 uptime 不变。控制节点第一次启动时就获得了 deployment 密钥，因此可以立即 SSH 到新节点：

farrow exec meta -- ssh [email protected] hostname

4. 与 Pigsty 共用同一份文件

如果 Pigsty 已生成 pigsty.yml，无需转换：

./configure -c meta
farrow setup
farrow up
./install.yml

Farrow 读取已记录的 VM 字段，以及用于命名、控制节点和登录身份的原生字段。 pg_role、pg_version、repo_*、node_packages 等未消费参数不会产生 VM drift； pg_cluster/pg_seq 与 node-admin 字段会被消费。

5. 停止或移除

farrow stop
farrow start
farrow destroy --force

普通 destroy 保留已校验镜像缓存、deployment 密钥与持久盘。只有明确需要时才使用 --delete-persistent 或 --purge。

3 - 日常操作

检查与访问

farrow status
farrow ssh meta
farrow exec node-1 -- hostname
farrow logs meta --source serial
farrow ss                         # 安装 SSH 别名，之后可直接 ssh meta

应用状态位于 ~/.farrow，这些命令可在任意目录执行。 Status 会显示持久化的 Guest 架构与加速器，因此 TCG 永远不是不可见回退。 plan、up、reload、recreate 依次优先使用 -f、当前目录发现的 Inventory， 两者都没有时才回退到已应用规格；validate 始终需要文件。

停止与启动

farrow stop                       # 别名：halt
farrow start
farrow restart node-1
farrow reload -f farrow.yml       # 停止、重新读配置、收敛

restart 使用已应用状态；reload 会重新读取 Inventory。

变更 deployment

farrow plan
farrow up                         # 创建新增节点，并启动选中的已停止节点
farrow recreate node-1 --force    # 应用某个节点的 VM 定义变化

删除 YAML 永远不会删除 VM。未消费的 Pigsty 变更得到 action:none；命名与 node-admin 字段虽然不以 vm_ 开头，仍会被消费。

销毁

farrow destroy node-3 --force
farrow destroy --force
farrow destroy --force --delete-persistent
farrow destroy --force --purge

--delete-persistent 与 --purge 只适用于整体销毁，不能和节点选择器一起使用。 --purge 删除持久盘、密钥和 deployment 状态，但保留镜像。宿主网络单独卸载，仍有 VM 挂接时会拒绝：

farrow network uninstall --yes

镜像

farrow image list
farrow image info u24
farrow image pull u24
farrow image prune --dry-run

镜像必须来自签名 Catalog，并在使用前通过 SHA-256 校验。当前镜像均为 testing， 只有 EOL EL7 是 deprecated，因此每次启动都会打印相应警告。

4 - 故障排查

先做只读检查：

farrow doctor --json
farrow network status --json
farrow status --json

找不到配置

第一次部署时，在 farrow.yml/pigsty.yml 所在目录运行 plan、up、validate， 或传入 -f /path/to/file。状态存在后，plan、up、reload、recreate 可回退到 已应用规格；status、start、stop、SSH 与 destroy 始终使用已应用状态。如果 status 也打印同样消息，所选 FARROW_HOME 中没有已应用状态。

setup 需要 sudo

提示前一行会说明具体宿主变更；特权步骤开始时 Farrow 会直接把交互终端交给 sudo。 自动化环境需要已有凭据或合适的 NOPASSWD，再使用 --yes。

原生加速或兼容运行时不可用

原生路径需要 macOS HVF 或 Linux KVM。只有显式外来 vm_arch 或内置镜像/宿主兼容规则 才会选择 TCG；任意原生失败绝不会静默回退。Homebrew QEMU 包含两个 System Emulator； Linux setup 只安装宿主原生家族，因此外来 Guest 还需要对应 qemu-system-* 与固件。

plan、up、recreate 会在任何破坏性修改前验证所选模拟器与固件。TCG 性能结果没有 参考意义。

网络是 partial 或 invalid

不要手工删宿主文件，先查看受控清理计划：

farrow network status --json --verbose
farrow network uninstall

确认只包含 Farrow 自有路径后再加 --yes。Linux bridge smoke 失败会自动按 manifest 回滚；只有出现 automatic rollback failed 才表示必须人工检查。

Linux bridge helper 失败

id
stat -c '%U:%G %a %n' /usr/lib/qemu/qemu-bridge-helper
dpkg-statoverride --list /usr/lib/qemu/qemu-bridge-helper

Debian/Ubuntu 使用 root:<调用者可用组> 4750。桌面系统通过 ACL 获得 /dev/kvm 权限时，调用者不必静态加入 kvm 组。

plan 报 recreate 或 missing

recreate 需要 farrow recreate <node> --force。missing 只是报告：恢复主机条目， 或运行 farrow destroy <node> --force。

SSH 失败

检查 farrow status、farrow ssh-config 与串口日志。Farrow 自身 SSH 使用回环管理端口； Ansible 直连固定 IP。

Catalog 或镜像校验失败

当前二进制已内置 active 与 standby Catalog 公钥。未知签名者、版本回滚/同版本异内容、 工件尺寸/SHA 不符、qcow2 结构不安全属于不同完整性错误。使用正确签名仓库，或通过 farrow image import --sha256 ... 导入；不要直接向 ~/.farrow/images 复制字节。

命令被中断

运行 farrow status。可证明存活或死亡的运行时会按完整进程身份收敛；歧义进程继续阻塞。 不要只凭状态文件里的 PID 就杀进程。

如果记录的 QEMU 进程仍存在，但 QMP Socket 缺失，应先保留证据并查看串口/QEMU 日志， 再决定是否用 stop 收敛。不要手工删除运行时 Socket 或状态文件。

提交问题时请包含准确命令与退出码、farrow version、上面三份 JSON、宿主系统/架构与 QEMU 版本。