holos v0.6.3

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

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

其原语是虚拟机，而非容器。每个工作负载实例都拥有自己的内核边界、qcow2 覆盖层、cloud-init seed 以及生成的 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

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

安装

预构建的二进制文件附在每个 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] [--locked] [--lockfile path] [--lock-timeout 5m|--no-wait]
                                     启动所有服务
holos run [flags] <image> [-- cmd...] 启动一个一次性虚拟机
holos down <project>                 停止并移除一个项目
holos ps [-f holos.yaml]             列出正在运行的项目
holos start [-f holos.yaml] [svc]    启动一个已停止的服务或所有服务
holos stop [-f holos.yaml] [svc]     停止一个服务或所有服务
holos console <project> [<inst>]     连接串行控制台
holos exec <project> [<inst>] [-- cmd...]
                                     通过 SSH 进入实例
holos logs <project> [<svc|inst>]    显示控制台日志
holos inspect [-f holos.yaml] [project|instance]
                                     以 JSON 格式检查状态
holos validate [-f holos.yaml]       验证 compose 文件（--capacity/--network）
holos pull <image>                   拉取 cloud 镜像
holos verify <image>|--all           验证缓存镜像的校验和
holos images                         列出可用镜像
holos images lock -f holos.yaml [-o holos.images.lock]
                                     写入项目镜像锁文件
holos snapshots {create|list|rm|restore|export} ... 管理根快照
holos volumes [-f holos.yaml] [--json]
                                     列出命名卷
holos volumes rm <project> <volume>  移除已分离的命名卷
holos volumes export <project> <volume> <path>
                                     导出已分离的命名卷
holos volumes snapshot <project> <volume> <snapshot>
                                     为已分离的命名卷创建快照
holos volumes snapshots <project> <volume>
                                     列出卷快照
holos volumes snapshot-rm <project> <volume> <snapshot>
                                     移除卷快照
holos volumes snapshot-restore <project> <volume> <snapshot>
                                     恢复卷快照
holos volumes snapshot-export <project> <volume> <snapshot> <path>
                                     导出卷快照
holos volumes resize [--shrink] <project> <volume> <size>
                                     调整已分离的命名卷大小
holos devices [--gpu]                列出 PCI 设备和 IOMMU 组
holos completion <bash|zsh|fish>      打印 shell 补全脚本
holos doctor [--json]                检查主机依赖
holos install [-f holos.yaml] [--system] [--enable]
                                     安装 systemd 单元
holos uninstall [-f holos.yaml] [--system]
                                     移除 systemd 单元
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
                                     将 virsh 虚拟机转换为 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

示例目录还包括 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。 Cloud 镜像通常不附带控制台密码，holos 也不会添加一个。

`up` 在 macOS 上失败

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

非目标

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

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

许可证

根据 Apache License, Version 2.0 许可。参见 NOTICE 了解署名信息。