# Barn 0.3.0：显式 Catalog 与可操作的就绪诊断

> 显式镜像目录更新、逐节点初始化诊断、发行版原生客机网卡名与精简的 CLI。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

> [!NOTE]
> 本文为 `0.3.0` 历史发布记录。旧版发行附件已下线，安装当前版本请参见[安装指南](/zh/docs/start/installation/)。

Barn 0.3.0 取消了隐式后台刷新镜像目录的行为，支持按节点报告客机初始化失败阶段与排查命令，并在保留 Pigsty 清单与固定 IP 部署模型的前提下精简了 CLI 命令集。

## 主要变化 {#what-changed}

- **显式更新镜像目录。** `up`、`plan` 与日常 `image` 子命令固定读取当前激活的本地镜像目录快照，不再后台拉取远端目录元数据。使用 `barn update` 可显式从配置仓库拉取最新签名目录，使用 `barn image sync` 可激活指定 URL 或本地目录文件。
- **逐节点报告初始化故障。** 客机引导过程以原子方式记录当前所处阶段；操作部分失败时会逐一列出失败节点、所处阶段与错误信息，就绪超时直接提示执行 `barn logs <node>` 查看串口与引导日志。
- **运行中客机免重启复检。** 已在运行的客机无需重启 QEMU 即可重新执行就绪检查；部分节点失败后，Barn 仍会根据全部已提交节点更新宿主机 SSH 客户端配置。
- **保留发行版原生网卡名。** Netplan 直接按确定性 MAC 地址匹配网卡，不再重命名客机网络接口；`vm_disks[].fs: auto` 优先使用 XFS，缺失工具时自动回退至 ext4。
- **精简命令与参数。** 移除冗余的 `ss` 子命令及易混淆的短参数别名，`barn image reset` 取代 `reset-manifest`（旧命令保留为兼容别名）。

## 验证范围 {#validation}

源码提交 `da6d02426da93c677c94c67fec4eb4fcecf4766a` 已通过完整本地源码门禁与 GoReleaser 全量快照构建（涵盖单元测试、竞态测试、`go vet`、Staticcheck、`govulncheck`、四目标交叉构建、镜像流水线与安装器测试、归档与软件包一致性、依赖许可证、SBOM 及 Linux 原生软件包校验），标签工作流在发布前完整复跑了上述检查。各阶段的 macOS `arm64`/HVF 与 Ubuntu `amd64`/KVM 实测记录见[验证历史](../../../docs/about/history/)。

## 安装或升级 {#install-or-upgrade}

从 [Barn 0.3.0 GitHub 发布页](https://github.com/pgsty/barn/releases/tag/v0.3.0)下载安装脚本与发行资产：

```bash
curl -fLO https://github.com/pgsty/barn/releases/download/v0.3.0/install.sh
chmod +x install.sh
BARN_VERSION=0.3.0 ./install.sh
barn version
barn doctor
```

同一预发布页附带 Homebrew 配方与 `amd64`/`arm64` DEB/RPM 软件包，直接兼容 0.1.0 与 0.2.0 的部署与镜像目录状态。