holos v0.6.2

用于 KVM 的 Docker compose。在一个 YAML 文件中定义多虚拟机栈。无需 libvirt，无需 XML，无需分布式控制平面。

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

基本单元是虚拟机，而不是容器。每个工作负载实例都拥有自己的内核边界、qcow2 覆盖层、cloud-init 种子以及生成的 SSH 访问。

快速开始

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

一个一次性虚拟机，无需 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

那是一个真实的虚拟机，正在启动云镜像、安装软件包、写入配置，并转发主机端口。

日常使用

在项目目录内：

holos exec web       # open a guest shell
holos logs           # read project boot logs
holos stop web       # keep its disk
holos start web
holos up --dry-run   # preview configuration changes
holos help exec      # command syntax and options

当服务有多个副本时，请使用诸如 web-0 之类的实例名称。

安装

每个 GitHub release 都附带了预构建的二进制文件：

TAG=v0.6.3
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] [--dry-run] [--recreate] [--strict] [--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] [--strict]
                                     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 指南：临时虚拟机、exec、systemd 安装、virsh 导入，以及 doctor。
Compose 文件：服务、卷、健康检查、网络、PCI 直通、Dockerfile 配置，以及默认值。
JSON Schema：为 holos.yaml 提供编辑器补全和校验。
示例：可运行和模板化的堆栈，附带 README 风格的说明。
缺失功能：按优先级排列的差距，符合 holos 单主机 KVM compose 目标。
开发：构建、测试、主机要求，以及发布流程。
安全策略：支持的版本和私密报告。
威胁模型 / 加固：镜像验证、状态权限、锁，以及操作指南。
贡献：构建、测试、风格，以及 PR 约定。

示例

从小的 nginx 示例开始：

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

examples 目录还包含 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 检查主机。

故障排查

打开 /dev/kvm 时权限被拒绝

检查 id -nG 和 ls -l /dev/kvm。在设备属于 kvm 组的主机上，使用 sudo usermod -aG kvm "$USER" 将你的用户加入该组，然后注销并重新连接。已有的 shell 会保留旧的组成员身份。从新会话中再次运行 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 也不会添加密码。

在 macOS 上 `up` 失败

KVM 是 Linux 内核特性。macOS 二进制文件可用于编写配置和离线命令，但 holos up 和 holos run 必须在 Linux KVM 主机上执行。

非目标

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

其目标是让 KVM 在单主机栈中可用，而不引入 Kubernetes 的运维形态。

许可证

依据 Apache License, Version 2.0 授权。署名信息见 NOTICE。