go-debos/debos

# debos - Debian OS 镜像构建工具 ## 概要 ``` debos [options] debos [--help] ``` 应用选项： ``` -b, --fakemachine-backend= Fakemachine backend to use (default: auto) --artifactdir= Directory for packed archives and ostree repositories (default: current directory) -t, --template-var= Template variables (use -t VARIABLE:VALUE syntax) --debug-shell Fall into interactive shell on error -s, --shell= Redefine interactive shell binary (default: bash) (default: /bin/bash) --scratchsize= Size of disk backed scratch space -c, --cpus= Number of CPUs to use for build VM (default: 2) -m, --memory= Amount of memory for build VM (default: 2048MB) --show-boot Show boot/console messages from the fake machine -e, --environ-var= Environment variables (use -e VARIABLE:VALUE syntax) -v, --verbose Verbose output --print-recipe Print final recipe --dry-run Compose final recipe to build but without any real work started --disable-fakemachine Do not use fakemachine. ``` ## 描述 debos 是一款旨在简化各类基于 Debian 的 OS 镜像创建工作的工具。大多数其他工具都专注于特定的使用场景，而 debos 则被设计为一个工具链，既能轻松处理常见操作，又能为幕后可能所需的任何调整提供足够的灵活性。 debos 接受一个 YAML 文件作为输入。关于 YAML 配方和所用模板引擎的总体概述，可以在 [debos 配方语法文档](https://pkg.go.dev/github.com/go-debos/debos/actions#hdr-Recipe_syntax) 中找到。 debos 按顺序运行配方文件中列出的操作。这些操作应当是自包含的，且彼此独立。 debos 提供的用于定制和生成镜像的部分操作包括： * `apt`: 使用 `apt` 安装软件包及其依赖 * `debootstrap`: 使用 `debootstrap` 构建目标 rootfs * `download`: 从互联网下载单个文件 * `filesystem-deploy`: 将根文件系统部署到先前创建的镜像中 * `image-partition`: 创建镜像文件，进行分区并格式化 * `install-deb`: 从本地 deb 包安装软件包及其依赖 * `ostree-commit`: 从 rootfs 创建一个 OSTree 提交 * `ostree-deploy`: 将一个 OSTree 分支部署到镜像 * `overlay`: 递归复制目录或文件到目标文件系统 * `pack`: 将目标文件系统打包为 tarball * `pacman`: 使用 pacman 安装软件包及其依赖 * `pacstrap`: 使用 pacstrap 构建目标 rootfs * `raw`: 将文件直接写入输出镜像的指定偏移位置 * `recipe`: 包含指定路径下的配方操作 * `run`: 允许在文件系统或主机中运行命令或脚本 * `unpack`: 将文件从压缩包解压到文件系统中 关于所有 debos 操作的完整语法描述，可以在 [debos 操作文档](https://godoc.org/github.com/go-debos/debos/actions) 中找到。 ## 联系我们！ 💬 加入我们的 Matrix 频道 [#debos:matrix.debian.social](https://matrix.to/#/#debos:matrix.debian.social)，聊聊 debos 的使用或开发。 🪲 如需报告 Bug、问题或功能需求，请创建一个新的 [GitHub Issue](https://github.com/go-debos/debos/issues)。 ❓ 请使用 [GitHub Discussion 论坛](https://github.com/go-debos/debos/discussions) 提问关于如何使用 Debos 的问题，或讨论创建配方的最佳方法。 ## 安装 (Docker 容器) 官方提供了 debos 容器： ``` docker pull godebos/debos ``` 用法详见 [docker/README.md](docker/README.md)。 ## 在 GitHub Actions 中使用 debos debos 可以在 GitHub Actions 中使用支持 KVM 的官方容器运行，以实现隔离且可复现的构建。指定 `--fakemachine-backend=kvm` 选项是为了确保按预期使用 KVM： ``` jobs: build: runs-on: ubuntu-latest container: image: ghcr.io/go-debos/debos:main options: --device=/dev/kvm steps: - uses: actions/checkout@v4 - run: debos --fakemachine-backend=kvm --print-recipe recipe.yaml ``` ## 从源码安装 (在 Debian 下) ``` sudo apt install golang git libglib2.0-dev libostree-dev qemu-system-x86 \ qemu-user-static debootstrap systemd-container export GOPATH=/opt/src/gocode # or whatever suits your needs go install -v github.com/go-debos/debos/cmd/debos@latest /opt/src/gocode/bin/debos --help ``` ## 简单示例 以下示例将创建一个 arm64 镜像，在其中安装多个软件包，将文件 `/etc/hostname` 更改为 `debian`，最后打包整个系统为 tarball。 ``` {{- $image := or .image "debian.tgz" -}} architecture: arm64 actions: - action: debootstrap suite: trixie components: - main - non-free-firmware mirror: https://deb.debian.org/debian variant: minbase - action: apt packages: - sudo - openssh-server - adduser - systemd-sysv - firmware-linux - action: run chroot: true command: echo debian > /etc/hostname - action: pack file: {{ $image }} compression: gz ``` 运行此示例，需创建一个名为 `example.yaml` 的文件并执行： ``` debos example.yaml ``` 最终的 tarball 将被命名为 `debian.tgz`。如果你想修改文件名，可以为变量 image 提供一个不同的名称，如下所示： ``` debos -t image:"debian-arm64.tgz" example.yaml ``` ## 其他配方示例 参阅 [bundled example recipes](doc/examples) 获取更详细的配方示例。更多详细的配方示例存储在 [debos-recipes](https://github.com/go-debos/debos-recipes) 中。 ## 环境变量 debos 从主机读取预定义的环境变量列表，并将其传递给 fakemachine 构建环境。该环境变量集合由 `cmd/debos/debos.go` 中的 `environ_vars` 定义。目前，环境变量列表包含以下文档中记录的代理环境变量： https://wiki.archlinux.org/index.php/proxy_settings 当前导出到 fakemachine 的环境变量列表为： ``` http_proxy, https_proxy, ftp_proxy, rsync_proxy, all_proxy, no_proxy ``` 虽然 `environ_vars` 中的元素为小写，但对于每个元素，debos 都会在主机上探测其小写和大写变体，如果找到则传递给 fakemachine。因此，如果主机定义了环境变量 HTTP_PROXY 和 no_proxy，它们都会在保留大小写的情况下传递给 fakemachine。 命令行选项 `--environ-var` 和 `-e` 可用于为 fakemachine 指定、覆盖和取消设置环境变量，语法如下： ``` debos -e ENVIRONVAR:VALUE ... ``` 若要取消设置某个环境变量，或者换句话说，阻止某个环境变量传递给 fakemachine，请使用不带值的相同语法。debos 支持同时接受多个 -e。 ## 代理配置 虽然代理相关的环境变量会从主机导出到 fakemachine，但存在两个已知的问题来源： * 在 fakemachine 中使用 localhost 将无法工作。请使用在你的网络上有效的地址。如果环境变量中包含 localhost，debos 将发出警告。 * 如果你在 fakemachine 内部运行应用程序和/或脚本，可能需要检查它们使用的是哪些代理环境变量。已知不同的应用程序会使用不同的环境变量名称，且大小写也不同。 ## Fakemachine 后端 debos（除非使用 `--disable-fakemachine` 参数运行）会使用 [fakemachine](https://github.com/go-debos/fakemachine) 创建并启动一个虚拟机，并在该虚拟机内执行配方定义的操作。这有助于确保无论主机环境如何，配方都是可复现的。 Fakemachine 可以使用不同的虚拟化后端来启动虚拟机，更多信息请参阅 [fakemachine 文档](https://github.com/go-debos/fakemachine)。 默认情况下，后端将根据主机支持的情况自动选择，但这可以通过 `--fakemachine-backend` / `-b` 选项进行覆盖。如果不支持任何后端，debos 将恢复为在主机上直接运行配方，而不创建 fakemachine。 各后端的性能大致如下：`kvm` 快于 `uml` 快于 `qemu`。使用 `--disable-fakemachine` 比 `kvm` 稍快，但需要 root 权限。 在搭载 SSD 的 Intel Pentium G4560T 上运行 [pine-a64-plus/debian.yaml](https://github.com/go-debos/debos-recipes/blob/9a25b4be6c9136f4a27e542f39ab7e419fc852c9/pine-a64-plus/debian.yaml) 的基准测试时间： | 后端 | 墙上时间 | 前置条件 | | --- | --- | --- | | `--disable-fakemachine` | 8 分钟 | root 权限 | | `-b kvm` | 9 分钟 | 访问 `/dev/kvm` | | `-b uml` | 18 分钟 | 已安装 `user-mode-linux` 包 | | `-b qemu` | 166 分钟 | 无 |

标签：Debian, Debian衍生版, debos, EVTX分析, EVTX分析, Fakemachine, OSTree, YAML, 二进制发布, 安全库, 定制化系统, 嵌入式Linux, 开源工具, 操作系统构建, 日志审计, 磁盘镜像, 系统部署, 自动化运维, 虚拟化, 请求拦截, 身份验证强制, 镜像制作, 镜像烘焙