企业官网建设流程全解析

Umbrel OS自定义镜像构建教程：把WiFi密码和SSH密钥直接烧进镜像（完整指南）

【免费下载链接】umbrel-osumbrelOS development has moved to https://github.com/getumbrel/umbrel项目地址: https://gitcode.com/gh_mirrors/um/umbrel-os

Umbrel OS 是一款运行在树莓派上的家庭服务器系统，而umbrel-os 项目正是它的官方镜像构建脚本仓库。本教程教你如何使用 Umbrel OS 自定义镜像构建脚本，在打包阶段就把WiFi 密码和SSH 密钥直接烧进系统镜像——开机即连网、开机即免密登录，免去首次启动后连屏幕插键盘配置的烦恼。整个过程只需设置几个环境变量，非常适合想把树莓派藏进电视柜里的新手用户 🎯

🧱 先看懂 Umbrel OS 构建脚本的分层结构

镜像构建被拆成了清晰的三个阶段，每个阶段对应一个目录，执行顺序如下：

全局参数集中在根目录的 config 文件中，例如默认主机名umbrel、默认用户umbrel、是否启用 SSH（ENABLE_SSH=1）等。所有公共函数（chroot 执行、挂载/卸载、镜像压缩等）都封装在 scripts/common 中，构建前会自动通过 scripts/dependencies_check 检查 depends 中声明的工具（quilt、debootstrap、qemu-user-static 等）是否齐全。

💡 新手提示：在 x86 电脑上构建树莓派镜像时，脚本会自动切换为qemu-debootstrap进行交叉编译，无需额外操作。

📶 一键把 WiFi 密码写进 Umbrel OS 镜像

核心逻辑在 stage2/01-net-tweaks/01-run.sh：

• 先安装默认的 wpa_supplicant 框架配置 files/wpa_supplicant.conf（见 01-run.sh#L8-L9）；
• 如果你导入了WPA_ESSID和WPA_PASSWORD两个环境变量，脚本会调用wpa_passphrase自动把SSID + 加密密钥追加进配置文件（见 01-run.sh#L15-L28）；
• 只有WPA_ESSID没有密码时，则写入开放网络配置；
• 默认还通过 rfkill 关闭树莓派自带的 5GHz 无线网卡（01-run.sh#L30-L33）。

所以你的操作非常简单：构建前只需导出环境变量，例如

export WPA_ESSID="我的家庭WiFi" export WPA_PASSWORD="我的WiFi密码"

构建出的镜像开机后就会自动连接该网络。📡

🔑 把 SSH 公钥烧进镜像：开机即可免密登录

SSH 密钥预置逻辑位于 stage2/00-sys-tweaks/01-run.sh：

1. 通过 config 中的ENABLE_SSH=1控制镜像是否默认启动 ssh 服务（见 01-run.sh#L20-L24）；
2. 导出GITHUB_USERNAME环境变量后，脚本会自动创建~/.ssh/authorized_keys，并从https://github.com/<你的用户名>.keys拉取你托管的 SSH 公钥写入镜像（见 01-run.sh#L35-L44）。

也就是说，只要你的 GitHub 账号主页挂有.keys文件，构建时执行export GITHUB_USERNAME="你的用户名"，得到的镜像就能被你的密钥直接免密 SSH 登录，全程无需密码。🚀

⚙️ 其他值得知道的构建参数

构建完成后，脚本还会更新镜像内的版本说明文件（scripts/common#L98-L100），方便你在系统里确认镜像来源与构建时间。

📦 导出成品：NOOBS 安装器与分区自适配

打包阶段位于 export-noobs/：

• export-noobs/00-release/files/partitions.json 定义了镜像的分区布局（boot + rootfs 两个分区）；
• export-noobs/00-release/files/partition_setup.sh 会在NOOBS 首次安装时自动把cmdline.txt和/etc/fstab中的root=指向实际分区号（见 partition_setup.sh#L17-L19），因此你把镜像烧进任意大小 SD 卡、哪怕分区排布不同，也能正常启动；
• 同目录下还有 os.json、release_notes.txt 等发布元数据，用于生成 NOOBS 安装器可识别的系统包。

此外，export-image/ 目录负责把 stage 产物合成最终的裸镜像（清理软件源、设置分区 UUID、收尾压缩），如果你只想产出可直接用dd烧录的 .img 文件，走这条流程即可。

✅ 快速上手清单

1. 准备一台 Debian/树莓派系统，按 depends 安装依赖；
2. 设置WPA_ESSID、WPA_PASSWORD、GITHUB_USERNAME等环境变量；
3. 按 stage0 → stage1 → stage2 → export 的顺序执行各阶段脚本；
4. 得到镜像后烧录到 SD 卡，上电自动连 WiFi、支持 SSH 免密登录——完成！

这样构建出来的 Umbrel OS 镜像，就是"插电即用的家庭服务器"，非常适合批量部署或送朋友使用。

【免费下载链接】umbrel-osumbrelOS development has moved to https://github.com/getumbrel/umbrel项目地址: https://gitcode.com/gh_mirrors/um/umbrel-os