CustomPiOS

CustomPiOS 是一个用于构建 Raspberry Pi <[]> 和其他 ARM 设备发行版的工具。它可以打开现有镜像、修改并重新打包，以便分发使用。本仓库包含从现有 Raspbian <[]> 发行版镜像或 Armbian 设备生成自定义发行版的源脚本。

***

CustomPiOS 是 100% 免费开源软件，由 Guy Sheffer 维护。如果它对您的生活、组织有帮助或让您满意，请考虑***。任何金额都将帮助开发者更专注于代码开发。感谢所有代码贡献者。

|***|

.. || image:: [] :target: [***]

获取方式

通过 克隆本仓库 <[***]>_ 获取。然后按照说明构建现有发行版或创建自己的发行版。

使用方法

1. 克隆仓库：git clone [***]
2. 在仓库中运行 src/make_custom_pi_os -g <发行版文件夹>，发行版文件夹不应存在且不含空格。此命令将创建用于构建新发行版的文件夹，并下载最新的 Raspbian Lite 镜像。初始发行版包含一个与发行版同名的模块，位于 <发行版文件夹>/src/modules/<发行版名称>（模块文件夹中应只有一个模块）。
3. 进入 <发行版文件夹>/src
4. 编辑 <发行版文件夹>/src/config，也可编辑位于 modules/<发行版名称> 的起始模块（更多信息见开发部分）。
5. 运行 <发行版文件夹>/src/build_dist 构建镜像。若失败，可使用 Vagrant 构建方法（确保 sfdisk 等工具正常工作）。

特性

• 模块系统：编写一个模块可用于多个发行版
• 精简开发：只需编写发行版所需代码，无需维护内核构建等复杂功能（除非需要）
• 标准模块：开箱即提供额外功能
• 多设备支持：通过 Armbian 和 Raspbian 支持超过 40 种嵌入式设备
• 64 位支持：支持 Raspberry Pi OS arm64 位，使用 raspios_lite_arm64 变体

开发

要求

1. qemu-arm-static <[***]>_
2. 已下载的 Raspbian <[***]>_ 镜像
3. chroot 所需的 root 权限
4. Bash
5. git
6. realpath
7. sudo（脚本会调用 sudo，直接以 root 运行可能无法工作）
8. p7zip-full
9. Python 3.2+

已知可用的构建配置

1. 使用 CustomPiOS Docker 镜像 <[***]>_
2. Linux（Ubuntu / Debian 等）
3. OS X - 参考此讨论 <[***]>_

模块

参见 wiki 中的模块条目 <[***]>_

chroot_script

用于编写在发行版内执行的代码。在 start_chroot_script 中编写主代码，可使用 end_chroot_script 编写清理函数，在模块命名空间结束时运行。

common.sh 中的实用命令

CustomPiOS 提供 common.sh 脚本，包含可在 chroot_script 中使用的实用函数。通过 source /common.sh 引入。

• unpack [from_filesystem] [destination] [owner]：将 filesystem 文件夹中的文件解压到指定目标路径，并设置所有者。例如：unpack /filesystem/home/pi /home/pi pi
• gitclone <MODULE_NAME>_<REPO_NAME>_REPO destination：克隆 Git 仓库，配置预设在 config 文件中。示例：在 chroot_script 中使用 gitclone OCTOPI_OCTOPRINT_REPO OctoPrint，在 config 中设置 [ -n "$OCTOPI_OCTOPRINT_REPO_SHIP" ] || OCTOPI_OCTOPRINT_REPO_SHIP=[***]

从镜像导出文件

CustomPiOS 支持将 chroot 中创建的文件导出为 tar.gz 归档。在 chroot_script 中运行：

• custompios_export [归档名称] [chroot 中的文件路径]
• copy_and_export [归档名称] [源路径] [目标路径]
• copy_and_export_folder [归档名称] [文件夹] [目标路径] 结果保存在 workspace 文件夹中。

filesystem

用于添加文件到发行版并保存到仓库，可通过 common.sh 中的 unpack 命令解压。

config

用于创建模块特定设置，可在发行版或变体中覆盖。命名约定为模块名称前缀。

构建方法

从 Raspbian / Debian / Ubuntu / CustomPiOS 发行版构建

参见 wiki 中的构建条目 <[***]>_

构建发行版变体

参见 wiki 中的构建条目 <[***]>_

使用 Docker 构建（部署方案示例）

1. 拉取 CustomPiOS Docker 镜像：docker pull guysoft/custompios
2. 克隆 CustomPiOS 仓库：git clone [***]
3. 运行 Docker 容器并挂载仓库目录：docker run -it -v $(pwd)/CustomPiOS:/CustomPiOS guysoft/custompios
4. 在容器内创建发行版文件夹并构建： cd /CustomPiOS src/make_custom_pi_os -g my_distro （创建发行版文件夹并下载基础镜像） cd my_distro/src ./build_dist （执行构建，生成镜像）

使用 Vagrant 构建

参见 wiki 中的 Vagrant 构建条目 <[***]>_

使用 CI/CD 构建

可通过云持续集成系统构建 CustomPiOS 镜像。GitHub Actions 示例配置见 此 YAML 文件 <[***]>_

使用

1. 如需覆盖现有配置，创建 src/config.local 文件，可覆盖 src/config 中的所有设置。若需指定用于构建的 Raspbian 镜像路径，覆盖基础模块中的 BASE_ZIP_IMG（默认使用 src/image 中最新的 *-raspbian.zip 文件）。
2. 以 root 身份运行 src/build。
3. 最终镜像生成在 src/workspace 目录。

使用 CustomPiOS 的发行版列表

• OctoPi <[***]>_ - 预安装 OctoPrint 的 Raspberry Pi 镜像
• FarmPi <[***]>_ - 运行 OctoFarm 的 Ubuntu ARM 64 位 Raspberry Pi 镜像
• FullPageOS <[***]>_ - 启动时显示全屏浏览器的 Raspberry Pi 发行版
• Zynthian <[***]>_ - 开源合成器平台
• ElectricSheepPi <[***]>_ - 运行 Electric Sheep 数字艺术的 Raspberry Pi 发行版
• AlarmPi <[***]>_ - 物联网 *** 控制闹钟的 Raspberry Pi 发行版
• RealtimePi <[***]>_ - 预配置实时内核的 Raspbian 发行版
• RMS Pi <[***]>_ - Winlink RMS 的 Raspberry Pi 发行版
• V1PI <[***]>_ - 控制 V1Engineering 机器的 Raspberry Pi 发行版
• HotSpotOS <[***]>_ - 未找到 WiFi 时自动创建热点的 Raspberry Pi 发行版
• MtigOS <[***]>_ - 接收、存储和图表化 ESP8266 传感器数据的发行版，使用 MTIG 栈（Mosquitto、Telegraf、InfluxDB、Grafana）
• Tilti-Pi <[***]>_ - 通过 tilty 包提交 Tilt 比重计 BLE 数据的发行版
• MainsailOS <[***]>_ - 集成 Mainsail Web UI、Moonraker API 和 Klipper 3D 打印机固件的发行版
• UbuntuDockerPi <[***]>_ - 预装 Ubuntu ARM 64 位 Docker 和 docker-compose 的发行版
• FluiddPi <[***]>_ - 集成 Fluidd、Moonraker 和 Klipper 的 3D 打印机固件发行版
• My Naturewatch Camera <[***]>_ - 用于通过网站流式传输 Pi 摄像头内容的 Python/OpenCV 服务器

欢迎代码贡献！