树莓派镜像写入工具的镜像发现机制：JSON存储库详解与自定义镜像发布

对于镜像提供者或希望发布自定义树莓派系统镜像的爱好者而言，理解树莓派镜像写入工具（Raspberry Pi Imager）如何发现和列出操作系统镜像至关重要。本文将深入探讨其背后的工作原理，重点解析存储库JSON格式的内部机制。

自树莓派镜像写入工具升级至2.0版本后，其用户界面、写入流程及内部配置处理均得到了显著优化（更多细节可查阅2.0版本发布公告）。

其中一项重要更新是用于定义可用操作系统镜像的JSON架构发生了变化。此次更新与树莓派操作系统引入对云初始化（cloud-init）的支持密切相关，新增的cc_raspberry_pi模块能够自动启用SPI等配置功能。

镜像写入工具如何识别镜像？

树莓派镜像写入工具与树莓派操作系统的发布周期并不同步。操作系统可能在镜像写入工具发布新版本前经历多次更新。若为每次系统更新都发布新版的镜像写入工具，效率低下且给用户带来不便。

为解决此问题，镜像写入工具并未内置固定的操作系统镜像列表。相反，它会从一个远程JSON文件（称为“存储库JSON”）中动态获取这些信息。这使得“受支持的设备列表”和“可用操作系统镜像列表”的更新可以独立于镜像写入工具本身的发布周期。用户无需重新安装或更新应用，即可自动获得最新的选项。

当前版本（镜像写入工具2.0及以上使用）的格式被正式定义为存储库JSON V4。

为何采用独立存储库？

外部托管镜像元数据方案提供了强大的灵活性。例如，你可以维护多个存储库：一个用于官方稳定版本，另一个用于每日构建或测试镜像，甚至可以为内部部署或教学环境维护一个私有存储库。

为了让此功能更易用，镜像写入工具2.0在应用设置中引入了一个新选项，允许用户在官方存储库和自定义JSON文件之间切换，自定义JSON可以从本地文件或URL加载。

更改此设置后，镜像写入工具将重置当前会话，并使用所选存储库JSON的内容重新加载界面。此功能面向高级用户和维护者，普通用户通常无需调整。

对于高级用户或自动化场景，经典方法仍然有效：你可以使用 --repo 命令行选项传递自定义存储库路径。此选项可指向URL或本地JSON文件，非常适合脚本化工作流程或预设配置。

解析存储库JSON结构

树莓派镜像写入工具的存储库文件遵循可预测的结构，围绕四个主要配置元素构建：

• 最新镜像写入工具版本
• 用户可下载更新的URL
• 受支持的设备配置文件列表
• 可用操作系统条目列表

基本结构如下：

{
  "imager": {
    "latest_version": "2.0.0",
    "url": "https://www.raspberrypi.com/software/",
    "devices": [
      /* 设备对象放在这里 */
    ]
  },
  "os_list": [
    /* 操作系统对象放在这里 */
  ]
}

imager.latest_version 和 url

镜像写入工具使用 latest_version 字段来检查是否有新版本可用。启动应用时，它会将自身版本与此字段比较。若存储库指示有更新版本，工具将显示更新提示，并链接到 url 字段提供的地址。

devices 列表

devices 数组包含受支持的硬件配置文件列表。这些配置文件允许镜像写入工具根据所选树莓派型号筛选操作系统条目。例如，某个镜像可能仅限于树莓派5使用，或标记为与所有型号兼容。

你会看到一个名为“无过滤”的特殊条目。选择此项时，将显示所有操作系统镜像，不应用任何设备兼容性过滤器。此模式通常用于测试或使用通用镜像，它就像一个支持所有功能的虚拟设备配置文件，确保即使未选择特定型号，所有配置选项也可用。

os_list

这是核心部分。os_list 包含了镜像写入工具向用户展示的所有操作系统条目。每个条目可以代表一个完整的操作系统、一个包含多个变体的子组，甚至可以引用嵌套的JSON文件以实现模块化的存储库管理。

如果你正在构建自己的自定义存储库，os_list 通常是你唯一需要编辑的部分。顶级的 imager 块（包含设备元数据和更新信息）由树莓派官方管理，并与官方应用紧密集成。

JSON设备对象：定义硬件配置文件

在镜像写入工具决定为特定设备显示哪些操作系统之前，它需要了解每个树莓派型号的身份和功能。这正是设备对象的作用。

devices 数组中的每个条目代表一个设备配置文件（通常是兼容型号的组，而非单一块卡）。例如，可能仅用一个配置文件代表“树莓派4/400”。

设备对象可包含以下属性：

• name (string): 在镜像写入工具中显示的名称（如“树莓派5”）。
• tags (string[]): 一组标识符。操作系统对象可以引用这些标识符来声明兼容性。
• default (boolean, 默认 true): 只有一个设备应设置此值为 true；当未手动应用过滤器时，镜像写入工具会自动选择它。
• icon (string, URL): 设备选择对话框中名称旁显示的小图标（PNG格式）。
• description (string): 可选文本，用于列出支持的型号或提供额外上下文。
• matching_type ("inclusive" | "exclusive"): 定义未声明设备标签的操作系统条目应如何表现：
  • inclusive → 无论如何都显示它们。
  • exclusive → 隐藏它们，除非明确为此设备标记。
• capabilities (镜像写入工具2.0新增, string[]，如 "usb_otg"): 作为功能标志，用于根据所选设备是否支持来隐藏或启用用户界面选项。

设备功能特别有用，它们允许镜像写入工具仅显示有意义的配置选项。例如，仅当所选设备和所选操作系统在其功能列表中均列出 usb_otg 时，才会显示USB外设模式切换开关。这避免了向用户展示在其硬件上无法工作的选项。

os_list 中的对象：类别与操作系统

os_list 部分可包含两种不同类型的对象，各司其职：

1. 类别对象

类别是一个容器，用于组织多个操作系统条目甚至子类别。它不能被选择下载，也不包含 url 或镜像元数据。
类别对象仅支持以下键：

• name (string): 用户界面中显示的类别标题。
• description (string): 名称下方显示的可选文本。
• icon (string, URL): 类别名称旁显示的图标。
• random (boolean, 可选): 若为 true，则随机排列 subitems 中条目的顺序。
• subitems (array): 包含操作系统对象和/或嵌套的类别对象。
  可以将类别视为用户界面中的一个文件夹——点击它以显示其中的内容。

2. 操作系统对象

操作系统对象定义了一个可选择安装的镜像。这些是可安装的条目，它们不包含 random 或 subitems。
操作系统条目支持以下键：

• name (string): 操作系统的显示名称。
• description (string): 简短说明或变体信息。
• icon (string, URL): 条目旁边显示的图标。
• url (string, URL): 压缩镜像文件的直接链接（如 .img.xz、.img.zip 等）。
• extract_size (int): 未压缩镜像的大小（用于用户界面空间估算）。
• extract_sha256 (string): 提取后镜像的SHA256哈希值。
• image_download_size (int): 压缩下载包的大小。
• image_download_sha256 (string): 压缩文件的SHA256哈希值。
• release_date (string, 日期格式): 用于版本/构建标识的显示日期。
• init_format ("none" | "systemd" | "cloudinit" | "cloudinit-rpi"): 声明镜像写入工具可提供何种类型的自定义设置；cloudinit-rpi 启用树莓派特定的 cc_raspberry_pi 模块。
• devices (string[]): 此操作系统支持的设备标签（来自设备对象）列表。
• capabilities (string[]): 指示此操作系统镜像支持的功能（如 usb_otg 或 rpi_connect）。

提示：对于开发或内部测试，可以省略校验和及大小字段。但对于公共存储库，提供这些信息有助于镜像写入工具提供准确的进度提示，并允许进行完整性验证。

经验法则：

• 如果对象包含 subitems → 它是类别对象。
• 如果对象包含 url → 它是操作系统对象。

功能匹配详解

以下是适用于设备和操作系统对象的功能说明：

• usb_otg: （设备和操作系统）仅当所选设备和操作系统均支持USB外设功能时，相关选项才会显示（要求操作系统中包含 rpi-usb-gadget 且硬件支持OTG）。
• rpi_connect: （仅操作系统镜像）指示在用户界面中支持树莓派连接（Raspberry Pi Connect）功能。

镜像技术要求

若希望你的镜像在树莓派镜像写入工具中提供自定义选项（特别是利用新的云初始化集成），必须满足一些技术要求。

支持云初始化自定义

要启用基于云初始化的配置（如在首次启动时设置主机名、Wi-Fi凭证或SSH密钥），你的镜像必须：

• 支持云初始化的网络配置版本2——通常通过Netplan实现，并使用正确的网络渲染器。
• 包含云初始化，并通过 bootfs 分区支持 NoCloud 数据源（镜像写入工具会将配置文件写入 bootfs，操作系统必须在首次启动时检测到它们）。

cloudinit-rpi：高级树莓派集成

如果在操作系统条目中声明 init_format: "cloudinit-rpi"，镜像写入工具还将暴露树莓派特定的选项，例如自动启用SPI或I2C。要支持此模式，你的镜像必须：

• 启用 cc_raspberry_pi 云初始化模块。
• 包含 raspi-config-vendor 软件包（针对你的发行版修改），该包在首次启动时为云初始化模块提供集成钩子。
  更多细节及模板设置，请参见相关GitHub仓库。

其他初始化模式

init_format 值	镜像写入工具行为
"none"	不向用户提供自定义选项——简单的下载和写入流程。
"systemd"	启用基于 bootfs 的传统 firstrun.sh 自定义机制。
"cloud-init"	启用标准云初始化（NoCloud）和通用选项。
"cloud-init-rpi"	通过 cc_raspberry_pi 启用扩展的、树莓派特定的选项。

如果你的镜像不支持任何自定义机制，请使用 init_format: "none" 以在用户界面中明确禁用自定义步骤。

加入官方镜像列表

如果你正在维护高质量的镜像，并希望其出现在树莓派镜像写入工具的官方镜像旁边（例如在某个社区类别下），可以填写官方申请表提交审核。

审核团队将评估你的提交，验证其兼容性，并在需要调整时与你联系。一旦获得批准，你的镜像将通过主要存储库基础设施分发给全球成千上万的用户。