在不重新下载镜像的情况下为 Raspberry Pi OS 生成 cloud-init 文件

发布: 1周前 (2025年12月24日 GMT+8 18:40)

9 min read

Source: Dev.to

为 Raspberry Pi OS 生成 cloud‑init 文件，而无需重新下载镜像

在 Raspberry Pi 上使用 cloud‑init 可以在首次启动时自动完成系统配置，例如设置用户、网络、SSH 密钥等。
传统做法是先下载完整的 Raspberry Pi OS 镜像，然后再使用 cloud‑localds 或类似工具将 user-data、meta-data 写入镜像中。
本文展示一种更高效的方式：直接生成 cloud‑init ISO（或 seed 文件），并在 Raspberry Pi Imager 中挂载它，从而避免重复下载操作系统镜像。

前置条件

已安装 Raspberry Pi Imager（或其他支持自定义镜像的写卡工具）。
已在本地机器上安装 cloud-image-utils（提供 cloud-localds）：

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install cloud-image-utils

# macOS (Homebrew)
brew install cloud-image-utils

提示：如果你使用的是 Windows，可以通过 WSL 或者在 Linux 虚拟机中完成下面的步骤。

第一步：准备 cloud‑init 配置

创建两个文件：user-data（描述要执行的初始化任务）和 meta-data（提供实例元数据）。

`user-data`

#cloud-config
hostname: raspberrypi
manage_etc_hosts: true

users:
  - name: pi
    sudo: ALL=(ALL) NOPASSWD:ALL
    groups: users, admin, sudo, docker
    shell: /bin/bash
    ssh_authorized_keys:
      - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...

runcmd:
  - apt-get update
  - apt-get install -y docker.io
  - systemctl enable docker
  - systemctl start docker

`meta-data`

instance-id: raspberrypi-01
local-hostname: raspberrypi

注意：ssh_authorized_keys 中请替换为你自己的公钥。

第二步：生成 cloud‑init ISO（seed 文件）

使用 cloud-localds 将上述两个文件打包成一个可供 Raspberry Pi Imager 挂载的 ISO（或 .img）文件：

cloud-localds cloud-init-seed.iso user-data meta-data

生成的 cloud-init-seed.iso 大约只有 2 MB，几乎可以忽略不计。

第三步：在 Raspberry Pi Imager 中使用 seed 文件

打开 Raspberry Pi Imager。
选择你想要的 Raspberry Pi OS（例如 “Raspberry Pi OS (32‑bit)”）。
点击 ⚙️（高级选项）（或在最新版本中点击 “Choose OS” → “Custom” → “Use custom image”）。
在弹出的对话框中，勾选 “Enable SSH”，并在 “Set username and password” 处填写 pi 与你的密码（如果不需要可以留空）。
勾选 “Configure Wi‑Fi”（如果需要无线网络），填写 SSID 与密码。
勾选 “Add custom files”，然后选择刚才生成的 cloud-init-seed.iso（或 .img）。
选择目标 SD 卡，点击 “Write”。

写入完成后，拔出 SD 卡并插入 Raspberry Pi。系统启动时会自动读取 cloud-init-seed.iso，执行 user-data 中的指令。

验证

启动后，你可以通过以下方式检查 cloud‑init 是否成功运行：

cloud-init status --long

如果显示 status: done，说明初始化已经完成。
此外，使用 hostname、docker ps、cat /etc/ssh/sshd_config 等命令可以进一步确认配置是否生效。

常见问题

问题	解决方案
seed 文件未被识别	确认在 Raspberry Pi Imager 的 “Advanced options” 中已经勾选 “Add custom files”。
SSH 仍然不可用	检查 `user-data` 中的 `ssh_authorized_keys` 是否正确，或在 `runcmd` 中添加 `systemctl restart ssh`。
Wi‑Fi 连接失败	确认 `wpa_supplicant.conf`（如果手动编辑）或 `user-data` 中的网络配置与实际 SSID、密码匹配。
Docker 未启动	查看 `journalctl -u docker` 获取错误日志，或手动执行 `systemctl start docker`。

小结

通过 cloud‑localds 直接生成一个极小的 cloud‑init seed 文件，并在 Raspberry Pi Imager 中挂载它，你可以：

省去重复下载完整 OS 镜像的时间和流量。
在一次写卡操作中完成所有初始化配置（用户、SSH、Wi‑Fi、Docker 等）。
保持镜像的原始完整性，因为 seed 文件是独立的附加层。

这种方法特别适合批量部署或在网络受限的环境中快速准备 Raspberry Pi。祝你玩得开心！

介绍

Raspberry Pi 最近在其官方 Raspberry Pi OS 镜像中引入了 cloud-init 支持。这使用户能够在首次启动前预先配置设备，包括 Wi‑Fi 凭据、用户、SSH 访问、地区设置等。

然而，官方 Raspberry Pi Imager 提供的当前工作流程存在一个实际限制：只有在映像器内部的官方操作系统列表中选择 Raspberry Pi OS 时，才会出现高级自定义选项。如果使用 Custom Image 选项刷写本地下载的镜像，这些配置选项将不再出现。

对于带宽受限、网络慢或经常清理缓存的用户来说，这会很快变得令人沮丧。本文将详细说明该问题，并提供一种使用 cloud‑init 文件生成器的简洁、节省带宽的解决方案。

Raspberry Pi Imager 定制的问题

定制仅在官方 OS 下载时有效

Raspberry Pi Imager 允许您配置：

Wi‑Fi（SSID、密码、国家/地区）
用户名和密码
SSH 访问
地区设置、时区和键盘布局

这些选项仅在以下情况下启用：

您直接在 Imager 中选择 Raspberry Pi OS，并且
镜像由 Imager 本身下载。

如果您：

手动下载 Raspberry Pi OS 镜像，并且
使用 Custom Image 选项进行写入，

则所有定制选项均被禁用。

重新下载浪费带宽

Raspberry Pi OS 镜像体积很大。
清除缓存会强制完整重新下载。
多次重新下载相同镜像会浪费流量。
在网络受限或费用高昂的地区尤为痛苦。

许多用户已经拥有所需的镜像，但仍需要在首次启动前配置 Wi‑Fi 和用户。

cloud‑init 在 Raspberry Pi OS 上的工作原理

最近的 Raspberry Pi OS 镜像通过在首次启动时读取 boot 分区 中的配置文件来支持 cloud‑init。关键文件包括：

meta-data
network-config
user-data

如果这些文件存在于 boot 分区，Raspberry Pi OS 会在首次启动时自动应用这些配置。这意味着：

无需使用 Raspberry Pi Imager 进行自定义。
无需重新下载 OS 镜像。
适用于任何刷写工具。

只需要提供有效的 cloud‑init 文件。

解决方案：Raspberry Pi cloud‑init 生成器

项目概览

GitHub repository:
Hosted website:

该工具生成：

meta-data
network-config
user-data

可直接复制到 Raspberry Pi 的 boot 分区。

旧工作流（存在问题）

打开 Raspberry Pi Imager。
从官方列表中选择 Raspberry Pi OS。
再次下载镜像。
添加自定义设置。
刷写 SD 卡。

问题：重复下载、流量消耗大、自定义镜像选项不可用。

新工作流（高效）

仅下载一次 Raspberry Pi OS 镜像。
使用 Raspberry Pi Imager 中的 Custom Image 或其他工具刷写。
打开 cloud‑init 生成器网站。
填写 Wi‑Fi、用户和 SSH 信息。
生成 meta-data、network-config 和 user-data。
将这些文件复制到 SD 卡的 boot partition。
启动 Raspberry Pi。

结果：无需重新下载，完整的 cloud‑init 自定义，下载镜像后即可离线使用。

主要优势

节省带宽。
避免不必要的重新下载。
可使用缓存或归档的镜像。
使用官方 Raspberry Pi OS cloud‑init 支持。
简单且适合初学者。

此方法特别适用于：

为多块 Raspberry Pi 开发板刷写镜像的开发者。
网络访问受限的用户。
自动化或可重复的 Raspberry Pi 部署。

Conclusion

Raspberry Pi OS 的 cloud‑init 支持功能强大，但当前的 Raspberry Pi Imager 工作流不必要地迫使用户重新下载镜像才能使用基本的自定义功能。

通过手动生成 cloud‑init 文件并将其放置在 boot 分区中，您可以在不依赖 Imager 官方 OS 下载流程的情况下完整配置 Raspberry Pi OS。Raspberry Pi cloud‑init 生成器使此过程变得简单、易用且节省带宽。

如果您经常使用 Raspberry Pi 开发板，这种方法可以节省时间和流量，同时让您对系统配置拥有完全的控制权。