基于Docker与QEMU的树莓派系统镜像自动化构建实战

1. 项目概述：一个基于Docker的树莓派仿真与配置工厂

如果你和我一样，经常需要折腾树莓派——无论是为家庭实验室部署新的服务节点，还是为产品原型准备一批预配置好的开发板，又或者是在CI/CD流水线里自动化测试ARM架构的应用——那你肯定对下面这个流程不陌生：下载系统镜像、烧录到SD卡、启动树莓派、SSH连接、安装依赖、修改配置……一套下来，半小时就过去了。更头疼的是，当需要批量操作或者确保环境完全一致时，手动操作的不可靠性就成了大问题。

今天要聊的ptrsr/pi-ci，就是我最近在项目中发现的“宝藏工具”。它本质上是一个封装好的Docker镜像，但其核心是一个功能完整的树莓派仿真器。它不是为了让你在桌面系统上“玩”树莓派桌面，而是为了解决一个非常实际的工程痛点：如何快速、可重复、自动化地准备和定制树莓派系统镜像。你可以把它理解为一个“树莓派配置工厂”，在容器内虚拟出一个树莓派环境，让你能像操作一台真实Pi一样进行各种配置，最后产出一个可以直接烧录到物理SD卡上的镜像文件。

这个工具的价值在于它将整个流程容器化了。想象一下，你不再需要依赖实体硬件进行前期配置，也不用担心因为SD卡损坏或操作失误导致重头再来。你可以在任何安装了Docker的机器上（无论是x86的笔记本还是ARM的服务器），通过几条命令就启动一个虚拟的树莓派，用Ansible剧本对它进行任意复杂的配置，然后一键导出镜像。这对于需要持续集成（CI）、批量部署和追求环境可重现性的场景来说，效率的提升是颠覆性的。

2. 核心设计思路与工作原理拆解

2.1 为什么选择QEMU仿真而非实体硬件？

pi-ci的核心是QEMU，这是一个开源的硬件虚拟化模拟器。你可能会问，为什么不直接用Docker本身来模拟ARM环境？或者用更轻量的chroot？这里的关键在于指令集架构的差异和系统完整性。

大多数开发者的工作机是x86_64架构，而树莓派是ARM架构。Docker容器虽然提供了隔离的运行环境，但它本质上共享宿主机的内核，并不能跨架构运行不同指令集的二进制文件。因此，直接运行ARM的Docker镜像在x86主机上是不可能的（除非使用Docker Desktop内置的或自己搭建的QEMU用户态模拟，但那通常有性能和兼容性问题）。

pi-ci采用的方案是“套娃”：在Docker容器内部，运行一个完整的QEMU系统模拟器。这个模拟器虚拟出ARMv8（即64位ARM）的CPU、内存、存储设备（虚拟SD卡）甚至网络设备。然后，它在这个虚拟硬件上启动一个真正的、未经修改的树莓派官方Raspberry Pi OS（64位精简版）内核和根文件系统。这样一来，你在容器内通过SSH连接进去的，就是一个几乎与真实树莓派无异的完整操作系统环境。

注意：这种全系统模拟（-machine virt）相比用户态模拟（-cpu cortex-a72等）开销更大，但兼容性最好，能确保所有针对真实树莓派的软件和配置都能无缝运行。

2.2 镜像生命周期管理：从初始化到烧录

pi-ci将树莓派镜像的整个生命周期抽象为几个清晰的命令，每个命令对应容器的一个启动参数。理解这个生命周期是高效使用它的关键。

1. 隐式初始化：当你第一次运行docker run ... start时，如果绑定的/dist目录下没有已有的image.qcow2文件，容器会自动从内置的Raspberry Pi OS Lite镜像初始化一个。这个初始镜像是一个2GB大小的QCOW2格式文件。QCOW2是一种写时复制（Copy-on-Write）的虚拟磁盘格式，它的好处是初始文件很小，只有在写入数据时才会动态增长，非常节省存储空间。

2. 运行与配置：start命令启动QEMU模拟器，运行这个虚拟镜像。你可以通过暴露的SSH端口（2222）连接进去，进行任意操作：apt安装软件、修改配置文件、创建用户、部署代码等等。所有这些改动都被实时写入到image.qcow2文件中。

3. 持久化与复用：通过Docker的-v参数将主机目录挂载到容器的/dist，这个image.qcow2文件就保存在了主机上。下次启动时，只要挂载同一个目录，就会基于上次修改后的状态继续运行，实现了配置的持久化。

4. 调整与输出：resize命令可以扩容虚拟磁盘（比如从2G扩到16G），以容纳更多软件或数据。export命令则将动态的QCOW2格式转换为静态的、线性的RAW（.img）格式，这是大多数SD卡烧录工具（如Balena Etcher、dd命令）能直接识别的格式。

5. 最终交付：flash命令是最便捷的一步，它直接将最终的.img文件写入到你通过--device参数传入的物理SD卡设备（如/dev/mmcblk0）中。写入后，这张SD卡插入真实的树莓派即可启动，并且系统会在首次启动时自动扩展根分区以填满整个SD卡空间。

这种设计将复杂的仿真、镜像处理流程封装成了简单的Docker命令，开发者只需关注“配置什么”，而无需操心“如何配置”。

3. 从零开始实战：搭建你的第一个自动化Pi镜像

理论说得再多，不如动手试一遍。下面我将带你完整走一遍流程，从拉取镜像到产出一个预装了Nginx和自定义服务的树莓派镜像。

3.1 环境准备与镜像获取

首先，确保你的开发机上已经安装了Docker Engine。对于Linux系统，建议使用官方仓库安装；对于macOS或Windows，使用Docker Desktop即可。pi-ci对Docker版本要求不高（≥19.03.6），现代版本都兼容。

第一步，拉取pi-ci镜像。这可能需要一些时间，因为它包含了完整的QEMU和基础系统。

docker pull ptrsr/pi-ci

拉取完成后，可以创建一个专门的工作目录来管理你的镜像文件，这样更清晰。

mkdir -p ~/pi-ci-workspace && cd ~/pi-ci-workspace mkdir dist

这个dist目录就是我们用来持久化树莓派虚拟镜像的地方。

3.2 启动虚拟机并进行初次配置

现在，启动你的第一个虚拟树莓派。我们同时启用持久化存储和SSH访问。

docker run --rm -it \ -v $(pwd)/dist:/dist \ -p 2222:2222 \ ptrsr/pi-ci start

运行后，终端会卡住，并显示一些QEMU的启动日志。这是正常的，虚拟树莓派正在启动。等待十几秒后，你就可以打开另一个终端窗口，通过SSH登录了。

ssh root@localhost -p 2222

默认密码为空，直接回车即可进入。你应该会看到熟悉的树莓派终端提示符：root@raspberrypi:~#。

首次登录必须做的几件事：

1. 修改root密码：输入passwd，按提示设置一个强密码。这是安全的基础。
2. 更新系统：虽然镜像较新，但最好更新一下包列表和已安装的包。

   apt update && apt upgrade -y

3. 安装你的基础软件：例如，我想预装Nginx和Python3。

   apt install -y nginx python3-pip systemctl enable nginx

3.3 使用Ansible实现配置自动化

手动SSH进去配置对于单个镜像还行，但无法复现，更无法集成到CI中。pi-ci的精髓在于与Ansible的搭配。Ansible可以通过Docker API直接控制容器内的虚拟机，实现全自动化配置。

首先，在宿主机（不是容器内）安装Ansible和必要的Python Docker库。

# 在Ubuntu/Debian宿主机上 sudo apt install -y ansible python3-pip pip3 install docker-py

注意：这里安装的是docker-py，这是一个旧的但广泛兼容的库。你也可以安装更现代的dockerPython包，但可能需要调整Ansible的配置。

接下来，为你的项目创建一个Ansible剧本目录结构。

mkdir -p ~/pi-ci-ansible && cd ~/pi-ci-ansible mkdir -p roles/common/tasks

创建一个清单文件hosts.yml，告诉Ansible我们的“主机”就是这个Docker容器。

# hosts.yml all: hosts: pi-ci-vm: ansible_connection: community.docker.docker ansible_host: pi-ci-container ansible_user: root

这里的关键是ansible_connection: community.docker.docker，它指定使用Docker连接插件。ansible_host的名字需要与后面启动容器时赋予的名称一致。

然后，创建一个主剧本文件main.yml。

# main.yml - name: Configure Raspberry Pi CI Image hosts: pi-ci-vm gather_facts: no # 初始镜像可能没有Python，暂时不收集信息 pre_tasks: - name: Install python3 for Ansible raw: apt-get update && apt-get install -y python3 roles: - role: common

最后，创建角色任务文件roles/common/tasks/main.yml，定义你要自动化的所有配置。

# roles/common/tasks/main.yml - name: Update and upgrade system packages apt: update_cache: yes upgrade: dist cache_valid_time: 3600 - name: Install necessary packages apt: name: - nginx - python3-pip - git - vim state: present - name: Ensure nginx is enabled and started systemd: name: nginx enabled: yes state: started - name: Deploy a custom index.html copy: content: "<h1>Hello from Auto-Configured Pi-CI!</h1><p>This page was deployed by Ansible.</p>" dest: /var/www/html/index.html owner: www-data group: www-data mode: '0644' - name: Create a deploy user user: name: deployer shell: /bin/bash groups: sudo append: yes - name: Set authorized key for deploy user authorized_key: user: deployer key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"

现在，我们需要一个脚本来协调整个过程：启动容器、运行Ansible、停止容器。创建一个run_playbook.sh脚本。

#!/bin/bash # run_playbook.sh set -e WORK_DIR=$(pwd) DIST_DIR="$WORK_DIR/dist" # 1. 启动pi-ci容器，并命名为`pi-ci-container`，以便Ansible连接 echo "Starting PI-CI container..." docker run -d --rm \ --name pi-ci-container \ -v "$DIST_DIR:/dist" \ ptrsr/pi-ci start # 给虚拟机一点启动时间 sleep 20 # 2. 运行Ansible剧本 echo "Running Ansible playbook..." ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook -i hosts.yml main.yml # 3. 停止容器（这会优雅关闭虚拟机） echo "Stopping container..." docker stop pi-ci-container echo "Configuration complete! Image saved to $DIST_DIR/image.qcow2"

给脚本执行权限并运行：chmod +x run_playbook.sh && ./run_playbook.sh。如果一切顺利，你将看到Ansible任务一条条执行。完成后，一个预装了Nginx、创建了用户、并部署了网页的树莓派镜像就已经安静地躺在./dist/image.qcow2文件里了。

4. 镜像处理进阶操作：扩容、导出与烧录

经过Ansible的洗礼，我们得到了一个定制化的镜像。但在把它放入真实的SD卡前，通常还需要一些处理。

4.1 安全地扩容虚拟磁盘

初始的2GB镜像对于安装了较多软件的系统可能不够用。pi-ci的resize命令可以安全地扩容虚拟磁盘。请务必记住：这个操作只能增大，不能缩小。

方法一：按目标设备大小扩容（推荐）这是最安全的方法，确保生成的镜像大小小于等于你的物理SD卡容量。假设你的SD卡在Linux系统中识别为/dev/sdb。

# 首先，确保dist目录下有我们之前生成的image.qcow2 ls -lh dist/image.qcow2 # 运行resize命令，并传入设备路径 docker run --rm -it \ -v $(pwd)/dist:/dist \ --device=/dev/sdb \ ptrsr/pi-ci resize /dev/sdb

容器会读取/dev/sdb的实际容量（注意，标称16GB的卡，实际可用容量可能只有14.9GiB左右），然后将image.qcow2扩容到与之相同的大小。

重要警告：在操作物理设备前，请务必先用lsblk命令确认设备标识符，误操作可能导致数据丢失。同时，强烈建议在扩容前备份image.qcow2文件。

方法二：指定具体大小扩容如果你确知需要的大小，也可以直接指定。

# 扩容到8GB docker run --rm -it -v $(pwd)/dist:/dist ptrsr/pi-ci resize 8G # 或者使用MB单位 docker run --rm -it -v $(pwd)/dist:/dist ptrsr/pi-ci resize 8192M

扩容操作只是扩大了虚拟磁盘的“盒子”，里面的分区表（主要是根分区）还没有变化。别担心，pi-ci使用的Raspberry Pi OS镜像包含一个init-resize.sh脚本，在镜像首次被烧录到物理卡并启动时，会自动扩展根分区以填满所有可用空间。

4.2 导出为通用IMG格式

QCOW2格式虽然节省空间，但并非所有烧录工具都支持。为了获得最大的兼容性，我们需要将其导出为原始的.img文件。

docker run --rm -it \ -v $(pwd)/dist:/dist \ ptrsr/pi-ci export \ --input /dist/image.qcow2 \ --output /dist/my-pi-image.img

运行后，你会在dist目录下得到一个my-pi-image.img文件。这个文件的大小就是你之前扩容后的虚拟磁盘大小（例如8GB），即使里面实际数据只有3GB，它也是一个8GB的二进制文件。你可以用Balena Etcher、Raspberry Pi Imager或者经典的dd命令来烧录它。

4.3 一键烧录到物理SD卡

如果你在Linux环境下，并且追求极致的命令行效率，pi-ci的flash命令是最直接的选择。它本质上是一个封装好的dd命令，但包含了进度显示和一些安全检查。

# 再次确认你的SD卡设备路径，例如 /dev/sdb sudo lsblk # 执行烧录，确保dist目录下有image.qcow2或导出的.img文件 docker run --rm -it \ -v $(pwd)/dist:/dist \ --device=/dev/sdb \ ptrsr/pi-ci flash /dev/sdb

命令会提示你确认设备信息，防止误操作。烧录过程会有进度条显示。完成后，将SD卡插入树莓派，上电启动。你会看到系统首次启动时会进行分区扩展，之后便自动登录或等待你通过SSH连接（取决于你的配置）。

5. 集成到CI/CD流水线：让镜像构建自动化

pi-ci的真正威力在于与持续集成/持续部署（CI/CD）系统的结合。你可以将上述所有步骤编写成一个脚本，由GitHub Actions、GitLab CI或Jenkins在每次代码推送时自动执行，生成最新的系统镜像。

下面是一个GitHub Actions工作流的示例（.github/workflows/build-pi-image.yml），它会在每次向main分支推送时，构建一个包含最新代码的树莓派镜像。

name: Build Raspberry Pi Image on: push: branches: [ main ] # 你也可以添加手动触发 workflow_dispatch: jobs: build-image: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Docker run: | sudo apt-get update sudo apt-get install -y docker.io - name: Pull PI-CI image run: docker pull ptrsr/pi-ci - name: Create working directory run: mkdir -p ${{ github.workspace }}/dist - name: Start PI-CI VM run: | docker run -d --rm \ --name pi-ci-builder \ -v ${{ github.workspace }}/dist:/dist \ ptrsr/pi-ci start # 等待VM完全启动 sleep 30 - name: Configure with Ansible run: | pip3 install ansible docker-py # 这里使用一个内联的Ansible剧本，也可以引用仓库里的playbook文件 cat > hosts.yml << EOF all: hosts: pi-ci-vm: ansible_connection: community.docker.docker ansible_host: pi-ci-builder ansible_user: root EOF cat > playbook.yml << EOF - name: Deploy application hosts: pi-ci-vm gather_facts: no pre_tasks: - name: Install python3 raw: apt-get update && apt-get install -y python3 tasks: - name: Clone the latest application code git: repo: https://github.com/your-username/your-app-repo.git dest: /opt/myapp version: main - name: Install app dependencies pip: requirements: /opt/myapp/requirements.txt - name: Set up systemd service copy: src: ./deploy/myapp.service dest: /etc/systemd/system/myapp.service notify: reload systemd handlers: - name: reload systemd systemd: daemon_reload: yes EOF ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook -i hosts.yml playbook.yml - name: Stop and export image run: | docker stop pi-ci-builder docker run --rm -it \ -v ${{ github.workspace }}/dist:/dist \ ptrsr/pi-ci export \ --input /dist/image.qcow2 \ --output /dist/pi-app-{{ github.sha }}.img - name: Upload image as artifact uses: actions/upload-artifact@v4 with: name: raspberry-pi-image path: ${{ github.workspace }}/dist/*.img retention-days: 7

这个工作流完成了自动化闭环：拉取代码、启动虚拟Pi、部署应用、导出镜像，并将最终镜像文件作为构建产物提供下载。团队的任何成员都可以随时获得一个与最新代码同步的、可立即烧录的系统镜像。

6. 常见问题、排查技巧与实战心得

在实际使用pi-ci的过程中，我踩过一些坑，也总结了一些技巧，希望能帮你绕开弯路。

6.1 网络连接问题

问题描述：虚拟机启动后，无法从内部访问外网（apt update失败），或者宿主机无法SSH连接到虚拟机。

排查思路：

1. 检查容器网络模式：pi-ci默认使用Docker的bridge网络。确保没有特殊的防火墙规则阻止容器访问外网。可以尝试在启动容器时使用--network host（仅限Linux宿主机）来使用主机网络，排除桥接网络问题。
2. 检查QEMU内部网络：pi-ci使用-netdev user为QEMU配置了用户模式网络栈。这种模式默认提供了NAT网络，可以访问外网，并将宿主机的2222端口转发到虚拟机的22端口。如果SSH连不上，首先确认启动命令是否包含了-p 2222:2222。
3. 查看容器日志：启动容器时加上-v参数（docker run ... ptrsr/pi-ci -v start）可以显示更详细的QEMU启动日志，观察是否有网络初始化错误。

6.2 镜像文件损坏

问题描述：再次启动容器时，虚拟机无法启动，提示磁盘错误或QCOW2文件损坏。

原因与预防： 这是最严重的问题，根本原因是非正常关闭。绝对不要在虚拟机运行时直接使用docker kill或Ctrl+C强制停止容器。QEMU进程需要时间将缓存数据写入磁盘，强行中断会导致文件系统不一致。

正确操作：

1. 在虚拟机内部，执行shutdown -h now或poweroff命令。
2. 或者在宿主机，对运行中的容器执行docker stop <container_name>。Docker会先发送SIGTERM信号，让QEMU优雅关闭，等待一段时间后再强制终止。

补救措施： 如果镜像已经损坏，可以尝试用QEMU自带的工具修复（前提是你有备份的好习惯）。

# 在宿主机安装qemu-utils sudo apt install qemu-utils # 尝试修复qcow2文件 qemu-img check -r all dist/image.qcow2

但修复不一定总能成功。因此，定期备份dist/image.qcow2文件是至关重要的。在执行resize等危险操作前，务必先复制一份。

6.3 性能与资源考量

磁盘I/O慢：QEMU全系统模拟，加上QCOW2格式的动态分配和宿主机文件系统的多层叠加，磁盘I/O性能远低于物理机。建议：

• 将工作目录（dist）放在宿主机SSD硬盘上。
• 在虚拟机内进行大量文件操作（如apt upgrade）时保持耐心。
• 可以考虑在启动QEMU时使用-drive cache=writeback选项来提升写入性能（但这需要你修改pi-ci的Dockerfile并自行构建镜像）。

内存占用：默认分配给虚拟机的内存可能不够（尤其是Pi 4/5模拟）。虽然pi-ci文档未明确说明，但你可以通过修改Dockerfile中QEMU的-m参数（例如-m 2G）并重新构建镜像，来为虚拟机分配更多内存。

6.4 安全最佳实践

1. 禁用Root SSH登录：在通过Ansible完成初始配置后，务必在虚拟机内修改/etc/ssh/sshd_config，设置PermitRootLogin no，并创建一个具有sudo权限的普通用户用于日常登录。
2. 使用密钥认证：如之前的Ansible示例所示，部署公钥认证，完全禁用密码登录，是提升安全性的有效手段。
3. 镜像最小化：只安装必要的软件包。每多一个服务，就多一个潜在的攻击面。使用Raspberry Pi OS Lite版本作为起点是很好的选择。
4. 定期更新：在自动化剧本中，加入apt upgrade任务，确保构建出的镜像包含最新的安全补丁。

6.5 对Windows/WSL用户的特别提示

在Windows的WSL（Windows Subsystem for Linux）环境下使用pi-ci，直接访问物理SD卡设备（/dev/sdX）通常很困难。这时，export命令生成的.img文件就是你的救星。

1. 在WSL中完成所有配置和export操作，得到.img文件。
2. 将该.img文件移动到Windows能访问的目录（例如/mnt/c/Users/YourName/Downloads/）。
3. 在Windows系统下，使用图形化工具Balena Etcher或Raspberry Pi Imager来烧录这个.img文件到SD卡。这是最稳定可靠的方式。

pi-ci这个项目将树莓派的系统准备从一种依赖物理硬件、手动操作的“手艺活”，变成了一种可版本化、可自动化、在云端也能进行的“软件流程”。它特别适合需要在多个树莓派上部署相同环境、频繁迭代应用版本，或者希望将基础设施也纳入代码管理（IaC）的开发者。虽然全虚拟化带来了一定的性能开销，但用它来准备系统镜像，其带来的效率提升和一致性保证，远超过那点额外的构建时间。下次当你需要为你的树莓派集群准备系统时，不妨试试这个“容器里的树莓派工厂”，它可能会彻底改变你的工作流。