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

Umbrel OS自定义镜像构建教程把WiFi密码和SSH密钥直接烧进镜像完整指南【免费下载链接】umbrel-osumbrelOS development has moved to https://github.com/getumbrel/umbrel项目地址: https://gitcode.com/gh_mirrors/um/umbrel-osUmbrel OS 是一款运行在树莓派上的家庭服务器系统而umbrel-os 项目正是它的官方镜像构建脚本仓库。本教程教你如何使用 Umbrel OS 自定义镜像构建脚本在打包阶段就把WiFi 密码和SSH 密钥直接烧进系统镜像——开机即连网、开机即免密登录免去首次启动后连屏幕插键盘配置的烦恼。整个过程只需设置几个环境变量非常适合想把树莓派藏进电视柜里的新手用户 先看懂 Umbrel OS 构建脚本的分层结构镜像构建被拆成了清晰的三个阶段每个阶段对应一个目录执行顺序如下阶段目录作用stage0stage0/用 debootstrap 引导出基础 Debian 系统、配置软件源stage1stage1/写入 boot 启动文件、系统参数微调、安装基础包stage2stage2/网络配置WiFi、时区、安装 Umbrel 核心、写入版本信息全局参数集中在根目录的 config 文件中例如默认主机名umbrel、默认用户umbrel、是否启用 SSHENABLE_SSH1等。所有公共函数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通过 config 中的ENABLE_SSH1控制镜像是否默认启动 ssh 服务见 01-run.sh#L20-L24导出GITHUB_USERNAME环境变量后脚本会自动创建~/.ssh/authorized_keys并从https://github.com/你的用户名.keys拉取你托管的 SSH 公钥写入镜像见 01-run.sh#L35-L44。也就是说只要你的 GitHub 账号主页挂有.keys文件构建时执行export GITHUB_USERNAME你的用户名得到的镜像就能被你的密钥直接免密 SSH 登录全程无需密码。⚙️ 其他值得知道的构建参数环境变量默认值说明WPA_ESSID/WPA_PASSWORD无预置 WiFi 名称与密码GITHUB_USERNAME无预置 SSH 公钥从 .keys 拉取FIRST_USER_NAMEumbrel镜像内的初始用户名FIRST_USER_PASS见 config初始用户密码可自定义ENABLE_SSH1是否默认开启 SSH 服务TIMEZONE_DEFAULTEtc/UTC默认时区构建完成后脚本还会更新镜像内的版本说明文件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 文件走这条流程即可。✅ 快速上手清单准备一台 Debian/树莓派系统按 depends 安装依赖设置WPA_ESSID、WPA_PASSWORD、GITHUB_USERNAME等环境变量按 stage0 → stage1 → stage2 → export 的顺序执行各阶段脚本得到镜像后烧录到 SD 卡上电自动连 WiFi、支持 SSH 免密登录——完成这样构建出来的 Umbrel OS 镜像就是插电即用的家庭服务器非常适合批量部署或送朋友使用。【免费下载链接】umbrel-osumbrelOS development has moved to https://github.com/getumbrel/umbrel项目地址: https://gitcode.com/gh_mirrors/um/umbrel-os创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考