Packer builder ARM

镜像概述和主要用途

该插件用于构建或扩展ARM系统镜像，支持以下三种模式：

• new - 创建空磁盘镜像并在其上填充根文件系统
• reuse - 使用现有镜像作为基础
• resize - 使用现有镜像并调整指定分区大小（如根分区）

插件模拟标准镜像创建流程，包括：

• 创建基础空镜像（dd）
• 分区（sgdisk / sfdisk）
• 文件系统创建（mkfs.type）
• 分区映射（losetup）
• 文件系统挂载（mount）
• 填充根文件系统（tar/unzip/xz等）
• 设置qemu + chroot
• 在chroot环境中自定义安装

虚拟化通过binfmt_misc内核功能和qemu实现。

由于不同硬件类型的设置差异较大，每个"开发板"都提供了示例配置。目前支持以下开发板（欢迎添加更多）：

• bananapi-r1（Archlinux ARM）
• beaglebone-black（Archlinux ARM、Debian）
• jetson-nano（Ubuntu）
• odroid-u3（Archlinux ARM）
• odroid-xu4（Archlinux ARM、Ubuntu）
• parallella（Ubuntu）
• raspberry-pi（Archlinux ARM、Raspbian）
• raspberry-pi-3（Archlinux ARM (armv8)）
• raspberry-pi-4（Archlinux ARM (armv7)、Ubuntu 20.04 LTS）
• wandboard（Archlinux ARM）
• armv7通用（Alpine、Archlinux ARM）

核心功能和特性

• 多模式支持：创建新镜像、重用现有镜像或调整现有镜像分区大小
• 完整镜像创建流程：涵盖从空镜像创建到分区、文件系统格式化、根文件系统填充的全流程
• QEMU虚拟化：通过binfmt_misc和qemu实现ARM指令集模拟，支持在x86平台构建ARM镜像
• 多架构容器：提供linux/amd64和linux/arm64多架构Docker容器，支持Intel x86_64、Apple M1及Linux aarch64系统
• 灵活配置：支持远程文件下载、自定义分区方案、QEMU参数配置等
• 广泛的开发板支持：已适配多种主流ARM开发板，可轻松扩展支持新硬件

使用场景和适用范围

适用于需要为ARM设备构建定制系统镜像的开发者，尤其适合：

• 嵌入式系统开发人员构建定制化固件
• ARM开发板用户创建包含特定软件的预制镜像
• CI/CD流程中自动化构建ARM系统镜像
• 为不同ARM硬件（如树莓派、Odroid等）生成标准化系统镜像
• 需要调整现有ARM镜像分区大小或扩展功能的场景

详细使用方法和配置说明

快速开始（非Docker方式）

git clone [***]
cd packer-builder-arm
go mod download
go build

sudo packer build boards/odroid-u3/archlinuxarm.json

在Docker中运行

此方法主要面向macOS用户（无法原生使用qemu-user-static、loop挂载Linux文件系统或安装Linux工具）或不想在本地配置packer及相关工具的Linux用户。

容器为多架构容器（linux/amd64或linux/arm64），可在Intel x86_64、Apple M1及Linux x86_64/aarch64系统上使用。

注意：在Mac上，不要先运行go build .（会生成darwin二进制文件），然后执行下面的docker run命令，这会导致错误error initializing builder 'arm': fork/exec /build/packer-builder-arm: exec format error（Docker内的linux packer进程无法加载darwin二进制文件）。通过rm -r packer-*删除本地二进制文件，仅使用容器内置的二进制文件。

使用Docker Hub上的容器

拉取最新版本容器以确保不使用旧缓存版本：

docker pull mkaczanowski/packer-builder-arm:latest

构建开发板镜像：

docker run --rm --privileged -v /dev:/dev -v ${PWD}:/build mkaczanowski/packer-builder-arm:latest build boards/raspberry-pi/raspbian.json

构建时添加额外系统包（如bmap-tools、zstd）：

docker run --rm --privileged -v /dev:/dev -v ${PWD}:/build mkaczanowski/packer-builder-arm:latest build boards/raspberry-pi/raspbian.json -extra-system-packages=bmap-tools,zstd

注意：上述命令中的latest可替换为特定版本（如1.0.3）以使用指定版本容器。

本地构建容器（支持amd64/aarch64主机）

本地构建容器：

docker build -t packer-builder-arm -f docker/Dockerfile .

通过本地构建的容器运行packer：

docker run --rm --privileged -v /dev:/dev -v ${PWD}:/build packer-builder-arm build boards/raspberry-pi/raspbian.json

依赖项

本地构建需安装以下工具：

• sfdisk / sgdisk（分区工具）
• e2fsprogs（文件系统工具）
• parted（调整分区大小时需要）
• resize2fs（调整分区大小时需要）
• qemu-img（调整分区大小时需要）

配置说明

配置分为三部分：远程文件配置、镜像配置和QEMU配置。

远程文件配置

描述用作基础镜像或根文件系统归档的远程文件（取决于image_build_method）：

"file_urls": ["[***]"],
"file_checksum_url": "[***]",
"file_checksum_type": "md5",
"file_unarchive_cmd": ["bsdtar", "-xpf", "$ARCHIVE_PATH", "-C", "$MOUNTPOINT"],
"file_target_extension": "tar.gz"

file_urls的下载通过github.com/hashicorp/go-getter实现，支持本地文件、http(s)等多种协议（详见支持的协议）。如需使用其他协议，可在运行packer前通过curl、wget等工具下载文件，然后在file_urls中引用本地文件。

file_unarchive_cmd为可选配置，当标准golang归档器无法处理归档格式时使用。

可通过定义file_target_extension使用原始镜像格式（.img或.iso）。

镜像配置

基础镜像描述（大小、分区、挂载点等）：

"image_build_method": "new",
"image_path": "odroid-xu4.img",
"image_size": "2G",
"image_type": "dos",
"image_partitions": [
    {
        "name": "root",
        "type": "8300",
        "start_sector": "4096",
        "filesystem": "ext4",
        "size": "0",
        "mountpoint": "/"
    }
]

插件不会尝试检测镜像分区（因差异较大），完全依赖image_partitions配置，即使使用reuse模式也需设置此项。

QEMU配置

QEMU相关配置：

"qemu_binary_source_path": "/usr/bin/qemu-arm-static",
"qemu_binary_destination_path": "/usr/bin/qemu-arm-static"

可通过QEMU_CPU变量定义要模拟的ARM指令集（默认为qemu-arm-static的armv7l）。要切换到armv6l（可通过uname -m验证），可通过以下方式运行packer：

• QEMU_CPU=arm1176 packer build ...
• docker run -e QEMU_CPU=arm1176 ...

Chroot provisioner

要在chroot环境中执行命令，需使用chroot通信器：

"provisioners": [
    {
        "type": "shell",
        "inline": [
            "pacman-key --init",
            "pacman-key --populate archlinuxarm"
        ]
    }
]

插件不会调整基础镜像的分区大小，但可通过systemd服务在启动时扩展分区。此处提供了树莓派根文件系统扩展至SD卡全部空间的实际示例。

镜像烧录

可使用自定义后处理器（dd的封装，包含一些安全检查）将镜像写入设备：

"post-processors": [
    {
        "type": "flasher",
        "device": "/dev/sdX",
        "block_size": "4096",
        "interactive": true
    }
]

其他功能

生成rootfs归档

虽然.img格式适用于大多数情况，但有时可能需要rootfs用于其他目的（如导出到Docker）。通过以下方式生成rootfs归档而非镜像：

"image_path": "odroid-xu4.img"  // 生成镜像
"image_path": "odroid-xu4.img.tar.gz"  // 生成rootfs归档

调整镜像大小

目前仅支持使用resize2fs扩展单个ext{2,3,4}分区。这是一个常见需求：使用现有镜像并扩展主分区以容纳 provisioner 步骤中安装的软件包。

要调整分区大小，需将image_build_method设置为resize模式，并将目标分区大小设为0：

"builders": [
    {
        "type": "arm",
        "image_build_method": "resize",
        "image_partitions": [
            {
                "name": "boot",
                ...
            },
            {
                "name": "root",
                "size": "0",
                ...
            }
        ],
        ...
    }
]

完整示例：

• boards/raspberry-pi/raspbian-resize.json
• boards/beaglebone-black/ubuntu.pkr.hcl

Docker集成

通过artifice插件可将rootfs归档传递给Docker插件：

"post-processors": [
    [
        {
            "type": "artifice",
            "files": ["rootfs.tar.gz"]
        },
        {
            "type": "docker-import",
            "repository": "mkaczanowski/archlinuxarm",
            "tag": "latest"
        }
    ],
    ...
]

CI/CD

以下是使用GitHub Actions将镜像推送到Docker镜像仓库的示例：

cat .github/workflows/archlinuxarm-armv7-docker.yml

示例

更多示例请查看：

tree boards/

仓库还包含一些ARM常用脚本，如首次启动时调整分区大小或更复杂的provision脚本：

tree scripts/

Packer provision脚本的丰富资源可参考GitHub Actions runner images仓库。

故障排除

许多报告的问题是平台/OS特定的。如遇到问题，首先应确认：

是我的设置有问题？还是确实存在问题？

建议在VM中重现错误以排查：

cd packer-builder-arm
vagrant up
vagrant provision

注意：需要安装disksize插件（如未安装）vagrant plugin install vagrant-disksize

演示

![asciicast]([***]