什么是 rpi-image-gen?

rpi-image-gen是一个轻量级、可编写脚本的框架，用于生成基于 Raspberry Pi OS-的框架。它采用基础根文件系统（Raspberry Pi OS精简版或完整版），并进行分层定制，生成可随时闪存的 .img 文件。

从本质上讲，它是一个可重现的 dd 工作流程--自动化、版本控制和高度可配置。

为什么要使用它？

不同 Yocto或 Buildroot, rpi-image-gen不从源代码重建软件包。相反，它利用 Debian 的二进制软件包和现有的 Raspberry Pi基础设施。您可以

  • 添加配置文件、服务和用户
  • 启用或禁用 systemd 单元
  • 预装应用程序和依赖项
  • 嵌入 SSH 密钥、Wi-Fi 证书和设备 ID

这是从原型到生产的最快方法，同时还能保持对系统设置的完全控制。

核心概念

一个典型的 rpi-image-gen项目由以下部分组成：

  • 基础镜像 - 官方 Raspberry Pi OS精简版
  • 覆盖目录 - 附加文件、服务和脚本
  • 自定义钩子--文件系统注入前和注入后脚本
  • 构建配置--定义 rootfs、启动分区、布局和版本标签

rpi-image-gen阴谋

这些元素结合在一起，就能生成一个一致的、可启动的映像，并为配置做好准备。

安装

请按照 https://github.com/raspberrypi/rpi-image-gen.

示例

一个典型的项目可能是这样的

deb12-cm5-min-desktop
├── README.md
├── config
│   └── deb12-cm5-min-desktop.yaml
├── device
│   ├── cm5-device.yaml
│   └── rootfs-overlay
│       ├── etc
│       │   ├── lightdm
│       │   └── skel
│       └── usr
│           └── local
└── layer
    ├── image
    │   └── simple-dual-nosparse
    │       ├── bdebstrap
    │       ├── device
    │       ├── genimage.cfg.in.btrfs
    │       ├── genimage.cfg.in.ext4
    │       ├── image.yaml
    │       ├── mke2fs.conf
    │       ├── pre-image.sh
    │       └── setup.sh
    └── packages.yaml

最重要的文件是 YAML 配置文件，这些文件定义了生成的映像中包含哪些软件包、文件和设置。

配置示例

config/deb12-cm5-min-desktop.yaml - 定义主机名、用户凭证、分区大小和 SSH 密钥等全局参数：

device:
  layer: cm5-device
  hostname: cm5-dev
  user1: pi
  user1pass: StrongPass!1

image:
  layer: image-rpios-nosparse
  rootfs_type: ext4
  boot_part_size: 512M
  root_part_size: 4G
  compression: zstd
  name: deb12-cm5-min-desktop

layer:
  custom: base-packages

ssh:
  pubkey_user1: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB"   # your custom public key
  pubkey_only: y

layer/packages.yaml - 列出软件包、配置文件和自定义添加内容（如 Qt 应用程序）：

# METABEGIN
# X-Env-Layer-Name: base-packages
# X-Env-Layer-Desc: Installs base packages
#  for sw development.
# X-Env-Layer-Version: 1.0.0
# X-Env-Layer-Requires: debian-bookworm-arm64-multi,
#  rpi-debian-bookworm,
#  rpi-misc-utils,
#  rpi-essential-base,
#  rpi-misc-skel,
#  rpi-user-credentials,
#  systemd-net-min,
#  fake-hwclock,
#  openssh-server
# METAEND
---
mmdebstrap:
  setup-hooks:
    - echo "hello - no setup-hooks in base-packages"
  packages:
    # Firmware to enable SHIFT boot manager and EEPROM maintenance
    - raspberrypi-bootloader
    - rpi-eeprom
    - raspberrypi-ui-mods
    - lightdm
    - lightdm-gtk-greeter
    - labwc
    - wf-panel-pi
    - lxsession
    - lxpanel
    - pcmanfm
    - lxterminal
    - gvfs
    - xserver-xorg
    - xwayland
    - wayland-utils
    - wlr-randr
    - x11-xserver-utils
    - xdg-user-dirs
    - xdg-utils
    - policykit-1
    # helper and utilities
    - bash
    - sudo
    - vim-tiny
    - less
    - nano
    - network-manager
    - bash-completion
    # library manager
    - libinput10
    - libinput-bin
    - libinput-dev
    # sqlite
    - sqlite3
    - libsqlite3-0
    - libsqlite3-dev
  customize-hooks:
    - echo "hello - customize-hooks in base-packages"
    - $BDEBSTRAP_HOOKS/enable-units "$1" lightdm
    - sed "s|alias ls='ls --color=auto'|alias ll='ls -al --color=auto'|" /home/$IGconf_device_user1/.bashrc > $1/home/$IGconf_device_user1/.bashrc
    - uchroot $1 'mkdir -m 0700 -p ${HOME}/.config/labwc'
    - cp "${IGconf_device_assetdir}/rootfs-overlay/etc/skel/.config/labwc/autostart" "$1/home/$IGconf_device_user1/.config/labwc/autostart"
    - cp "${IGconf_device_assetdir}/rootfs-overlay/etc/skel/.config/labwc/environment" "$1/home/$IGconf_device_user1/.config/labwc/environment"
    - cp "${IGconf_device_assetdir}/rootfs-overlay/etc/skel/.config/labwc/rc.xml" "$1/home/$IGconf_device_user1/.config/labwc/rc.xml"
    - chown "${IGconf_device_user1}:${IGconf_device_user1}" "$1/home/$IGconf_device_user1/.config/labwc/autostart"
    - chown "${IGconf_device_user1}:${IGconf_device_user1}" "$1/home/$IGconf_device_user1/.config/labwc/environment"
    - chown "${IGconf_device_user1}:${IGconf_device_user1}" "$1/home/$IGconf_device_user1/.config/labwc/rc.xml"

有关完整的工作示例，请参阅 https://github.com/interelectronix/rpi-image-gen-projects/tree/main/deb12-cm5-min-desktop

构建命令

要创建映像，请运行

rpi-image-gen build -S path-to-project-folder -c deb12-cm5-min-desktop.yaml

CI/CD 和可重复性

一旦您的构建脚本具有确定性，您就可以将其集成到 rpi-image-gen到 CI/CD 管道中（例如GitHub Actions,GitLab CI,Jenkins ）。

每次构建都会产生一个可跟踪的版本化工件，从而实现可靠的更新和更简便的调试--这是向生产级部署迈出的关键一步。

本系列文章

资料来源