luochen570/nixos-pantherx2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3 Commits 1 Branch 0 Tags
main
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE
luochen570 99f24e9a8e 移除f2fs更换为默认的ext4文件系统格式
2026-03-18 10:10:04 +08:00
modules
移除f2fs更换为默认的ext4文件系统格式
2026-03-18 10:10:04 +08:00
pkgs
first commit
2026-03-18 07:25:53 +08:00
.gitignore
更改说明
2026-03-18 10:00:28 +08:00
configuration.nix
first commit
2026-03-18 07:25:53 +08:00
flake.lock
first commit
2026-03-18 07:25:53 +08:00
flake.nix
first commit
2026-03-18 07:25:53 +08:00
PROJECT-GUIDE.md
移除f2fs更换为默认的ext4文件系统格式
2026-03-18 10:10:04 +08:00
README.md
移除f2fs更换为默认的ext4文件系统格式
2026-03-18 10:10:04 +08:00
result
更改说明
2026-03-18 10:00:28 +08:00
U-BOOT-PANTHER-X2.md
first commit
2026-03-18 07:25:53 +08:00

README.md

Panther X2 NixOS 镜像项目

这是一个面向 Panther X2 小盒子（Rockchip RK3566）的 NixOS flake，用来构建可启动的 SD 卡镜像。项目把板级配置、内核、U-Boot 二进制和镜像打包逻辑拆成独立模块，目标是让 Panther X2 的镜像构建过程可复现、可维护，也方便后续继续定制。

项目中的 U-Boot 使用方式，是基于 https://github.com/ophub/amlogic-s9xxx-armbian 项目的 Armbian 成果进行提取和集成；整体文件组织和部分实现思路参考了 https://github.com/gnull/nixos-rk3588。

当前仓库的实现重点如下：

  • 使用 flake.nix 暴露原生构建和交叉构建入口
  • 使用 Armbian 系的 Rockchip vendor kernel
  • 使用 rk3566-panther-x2.dtb
  • 生成 GPT 分区表的 SD 镜像
  • 根分区使用 ext4
  • 通过 extlinux 引导 NixOS
  • 在镜像后处理阶段写入 idbloader.img 和 u-boot.itb

项目结构

nixos-pantherx2/
├── flake.nix                         # 项目入口，定义 NixOS 配置与包输出
├── configuration.nix                # 通用系统配置、用户、SSH、基础软件
├── modules/
│   ├── boards/
│   │   └── pantherx2.nix            # 板级配置：内核、initrd、dtb、内核参数
│   └── sd-image/
│       ├── pantherx2.nix            # Panther X2 镜像参数与 U-Boot 写入逻辑
│       ├── sd-image-rockchip.nix    # 改造后的通用 Rockchip SD 镜像模块
├── pkgs/
│   ├── kernel/
│   │   ├── vendor.nix               # vendor kernel 打包定义
│   │   ├── rk35xx_vendor_config     # 内核 .config
│   │   ├── rk35xx_vendor_config.nix # .config 的 Nix 表达
│   │   └── README.md                # 内核来源与维护说明
│   └── u-boot-radxa/
│       ├── prebuilt.nix             # 预置 U-Boot 二进制打包
│       ├── idbloader.img            # 引导第一阶段
│       ├── u-boot.itb               # U-Boot 主镜像
│       ├── build-from-source.nix    # 源码构建草稿，当前未接通
│       └── panther-x2.nix           # Panther X2 U-Boot 说明
├── U-BOOT-PANTHER-X2.md             # U-Boot 获取说明
└── PROJECT-GUIDE.md                 # 项目结构补充说明

构建链路

镜像构建的入口在 flake.nix：

  • nixosConfigurations.pantherx2 直接以 aarch64-linux 评估系统配置
  • nixosConfigurations.pantherx2-cross 在 x86_64-linux 主机上开启 aarch64-unknown-linux-gnu 交叉构建
  • packages.<system>.sdImage 指向 pantherx2 的 system.build.sdImage
  • packages.<system>.sdImageCross 指向 pantherx2-cross 的 system.build.sdImage

板级和镜像的职责分工如下：

  • configuration.nix 放系统通用项，例如用户、密码、SSH 和基础工具
  • modules/boards/pantherx2.nix 选择 vendor kernel、设置 DTB、initrd 模块和 RK3566 启动参数
  • modules/sd-image/pantherx2.nix 固定根分区 UUID、将根文件系统设为 ext4、启用 generic-extlinux-compatible，并在镜像完成后把 U-Boot 写到固定扇区
  • modules/sd-image/sd-image-rockchip.nix 提供 Rockchip 适配过的 SD 镜像生成逻辑，使用 GPT 分区表，并支持首启自动扩容

启动与镜像布局

当前镜像方案的关键点：

  • 分区表类型：GPT
  • 固件分区偏移：32 MiB
  • 固件分区：vfat，默认只保留占位，不写板级启动文件
  • 根分区：ext4
  • /boot 内容放在根分区内，由 extlinux 管理
  • 根分区标签：NIXOS_SD
  • 根分区 UUID：e3361446-4d2f-4d21-954c-9ca6d76029ea

镜像生成完成后，会执行：

dd if=idbloader.img of=$img seek=64 conv=notrunc
dd if=u-boot.itb of=$img seek=16384 conv=notrunc

也就是：

  • idbloader.img 写入 LBA 64
  • u-boot.itb 写入 LBA 16384

这套布局是当前仓库为 Panther X2 约定的启动方式。

前置准备

1. 准备 U-Boot 二进制

仓库当前默认走预置二进制方案，直接读取：

  • pkgs/u-boot-radxa/idbloader.img
  • pkgs/u-boot-radxa/u-boot.itb

这两个文件的来源约定为从 ophub/amlogic-s9xxx-armbian 项目的 Panther X2 Armbian 系统或镜像中提取，再放入仓库对应目录。

如果需要重新提取或替换，请参考 U-BOOT-PANTHER-X2.md。

2. 确认 Nix 环境

需要启用：

  • nix-command
  • flakes

仓库自身已经在目标系统配置里启用了这两个实验特性，但构建机本身也需要可用的 flake 环境。

构建方法

在仓库根目录执行：

nix flake show

原生构建

适合直接在 aarch64-linux 主机上构建：

nix build .#sdImage

交叉构建

适合在 x86_64-linux 主机上为 Panther X2 生成镜像：

nix build .#sdImageCross

默认包输出指向交叉构建版本，因此也可以直接执行：

nix build

构建产物

当前配置里 sdImage.compressImage = true，所以产物默认是压缩后的镜像：

result/sd-image/pantherx2-sd-image-<label>-<system>.img.zst

如果要写入 SD 卡，可以先解压：

zstd -d result/sd-image/*.img.zst -o pantherx2.img

再写卡：

sudo dd if=pantherx2.img of=/dev/sdX bs=4M conv=fsync,status=progress

也可以直接流式写入：

zstdcat result/sd-image/*.img.zst | sudo dd of=/dev/sdX bs=4M conv=fsync,status=progress

请先用 lsblk 确认目标设备，避免写错盘。

首次启动行为

镜像默认启用了首启扩容逻辑，第一次启动时会：

  • 扩展根分区到整张卡
  • 注册初始 Nix store
  • 建立 system profile
  • 移除 /nix-path-registration，避免后续重复执行

当前默认根分区已经使用 ext4，因此通用 Rockchip SD 镜像模块里的首启扩容逻辑与当前配置是匹配的。

当前系统默认配置

这些内容直接来自当前的 configuration.nix：

  • 普通用户：luochen570
  • root 密码：Luochen570
  • 普通用户初始密码：Luochen570
  • openssh：默认启用
  • PasswordAuthentication：默认启用
  • PermitRootLogin：yes
  • 预装工具：git、fastfetch、htop

如果这个镜像会在真实网络环境里使用，建议在构建前先修改默认密码和 SSH 策略。

常用定制点

修改系统软件与服务

编辑 configuration.nix。

修改板级启动参数、DTB、initrd

编辑 modules/boards/pantherx2.nix。

修改镜像布局和写入逻辑

编辑 modules/sd-image/pantherx2.nix 和 modules/sd-image/sd-image-rockchip.nix。

更新内核版本或内核配置

编辑 pkgs/kernel/vendor.nix 与 pkgs/kernel/rk35xx_vendor_config。

已知现状

  • U-Boot 当前依赖仓库中的预置二进制，而不是源码构建
  • pkgs/u-boot-radxa/build-from-source.nix 仍标注为 TODO not working yet
  • PROJECT-GUIDE.md 和 U-BOOT-PANTHER-X2.md 里部分内容比当前代码更旧，后续可以继续同步

相关文档

致谢

感谢以下项目和维护者的工作，为本仓库提供了非常重要的基础：

  • ophub/amlogic-s9xxx-armbian 本项目当前使用的 Panther X2 U-Boot 二进制提取流程，建立在他们提供的 Armbian 适配成果之上。
  • gnull/nixos-rk3588 本项目的文件结构划分、Rockchip 镜像构建思路和部分实现方式参考了这个项目。
Description
在Panther X2上安装nixos
Readme 915 KiB
Languages
Nix 100%