holos v0.6.2

Docker compose 的 KVM 版本。在一个 YAML 文件中定义多 VM 堆栈。没有 libvirt，没有 XML，没有分布式控制平面。

网站和文档：https://zeroecco.github.io/holos/

原语是 VM，而不是容器。每个工作负载实例都有自己的内核边界、qcow2 覆盖层、cloud-init 种子和生成的 SSH 访问。

快速开始

需要 Linux + /dev/kvm。macOS 构建可以运行离线命令，如 validate、import、images 和 pull，但 up 和 run 需要 KVM 主机。

一个一次性 VM，无需 compose 文件：

holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>

一个单服务堆栈，您可以使用 curl。保存为 holos.yaml：

name: hello

services:
  web:
    image: ubuntu:noble
    ports:
      - "8080:80"
    cloud_init:
      packages:
        - nginx
      write_files:
        - path: /var/www/html/index.html
          content: "hello from holos\n"
      runcmd:
        - systemctl restart nginx

holos up
curl localhost:8080
holos down hello

这是一个真实的 VM，启动云镜像，安装包，写入配置，并转发主机端口。

安装

预构建的二进制文件附加到每个 GitHub 版本：

TAG=v0.6.1
ASSET=holos_${TAG#v}_Linux_x86_64.tar.gz
BASE=https://github.com/zeroecco/holos/releases/download/$TAG
curl -LO $BASE/$ASSET
curl -LO $BASE/checksums.txt
grep " $ASSET$" checksums.txt | sha256sum -c -
gh attestation verify $ASSET --repo zeroecco/holos
sudo tar -xz -C /usr/local/bin -f $ASSET holos
holos version
holos doctor

发布页面包含 SHA-256 校验和以及用于签名来源的 GitHub 工件认证。在生产主机上安装二进制文件之前，请验证两者。

或从源代码构建：

go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor

CLI

holos up [-f holos.yaml] [--locked] [--lockfile path] [--lock-timeout 5m|--no-wait]
                                     start all services
holos run [flags] <image> [-- cmd...] launch a one-off VM
holos down <project>                 stop and remove a project
holos ps [-f holos.yaml]             list running projects
holos start [-f holos.yaml] [svc]    start a stopped service or all services
holos stop [-f holos.yaml] [svc]     stop a service or all services
holos console <project> [<inst>]     attach serial console
holos exec <project> [<inst>] [-- cmd...]
                                     SSH into an instance
holos logs <project> [<svc|inst>]    show console logs
holos inspect [-f holos.yaml] [project|instance]
                                     inspect state as JSON
holos validate [-f holos.yaml]       validate compose file (--capacity/--network)
holos pull <image>                   pull a cloud image
holos verify <image>|--all           verify cached image checksums
holos images                         list available images
holos images lock -f holos.yaml [-o holos.images.lock]
                                     write project image lockfile
holos snapshots {create|list|rm|restore|export} ... manage root snapshots
holos volumes [-f holos.yaml] [--json]
                                     list named volumes
holos volumes rm <project> <volume>  remove a detached named volume
holos volumes export <project> <volume> <path>
                                     export a detached named volume
holos volumes snapshot <project> <volume> <snapshot>
                                     snapshot a detached named volume
holos volumes snapshots <project> <volume>
                                     list volume snapshots
holos volumes snapshot-rm <project> <volume> <snapshot>
                                     remove a volume snapshot
holos volumes snapshot-restore <project> <volume> <snapshot>
                                     restore a volume snapshot
holos volumes snapshot-export <project> <volume> <snapshot> <path>
                                     export a volume snapshot
holos volumes resize [--shrink] <project> <volume> <size>
                                     resize a detached named volume
holos devices [--gpu]                list PCI devices and IOMMU groups
holos completion <bash|zsh|fish>      print shell completion script
holos doctor [--json]                check host dependencies
holos install [-f holos.yaml] [--system] [--enable]
                                     install a systemd unit
holos uninstall [-f holos.yaml] [--system]
                                     remove the systemd unit
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
                                     convert virsh VMs into holos.yaml

文档

网站：登录页面和渲染文档。
CLI 指南：ad hoc VM、exec、systemd 安装、virsh 导入和 doctor。
Compose 文件：服务、卷、健康检查、网络、PCI 直通、Dockerfile 配置和默认值。
JSON 模式：holos.yaml 的编辑器补全和验证。
示例：可运行和模板堆栈，附带 README 风格的说明。
缺失功能：优先处理的差距，符合 holos 的单主机 KVM compose 目标。
开发：构建、测试、主机要求和发布流程。
安全策略：支持的版本和私下报告。
威胁模型/加固：镜像验证、状态权限、锁和操作指导。
贡献：构建、测试、样式和 PR 约定。

示例

从小型 nginx 示例开始：

holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx

示例目录还包含 Dockerfile 配置、GPU 直通以及一个多服务堆栈，展示了 depends_on、生成的配置和副本。

主机要求

具有 /dev/kvm 的 Linux
qemu-system-x86_64
qemu-img
以下之一：cloud-localds、genisoimage、mkisofs 或 xorriso
用于 UEFI 或 PCI 直通的 OVMF / edk2-ovmf 固件
用于 holos exec 和健康检查的 ssh

运行 holos doctor 检查主机。

故障排除

首次引导时 SSH 重置

kex_exchange_identification: read: Connection reset by peer 通常意味着 cloud-init 仍在重新生成主机密钥并重启 sshd。默认情况下 holos exec 最多等待 60 秒，但非常慢的首次引导可能需要再次重试或使用 holos exec -w 5m <project>。

控制台显示 `Login incorrect`

串行控制台可能在 cloud-init 创建用户之前尝试自动登录。等待控制台日志中出现 cloud-init ... finished，然后使用 holos exec。云镜像通常不附带控制台密码，holos 也不会添加密码。

`up` 在 macOS 上失败

KVM 是 Linux 内核功能。macOS 二进制文件对于编写和离线命令很有用，但 holos up 和 holos run 必须在 Linux KVM 主机上执行。

非目标

holos 不是 Kubernetes。它不尝试解决多主机集群、实时迁移、服务网格、覆盖网络、调度器、CRD 或控制平面仲裁问题。

目标是在不引入 Kubernetes 操作模式的情况下，使 KVM 可用于单主机堆栈。

许可证

根据 Apache 许可证 2.0 版授权。归属声明见 NOTICE。