根文件系统构建

本文档介绍在 RK3588 Linux SDK 中如何构建根文件系统（Rootfs），包括 Buildroot 和 Debian 两种方案，以及自定义、调试相关操作。

适用范围： 在 PC 上的 RK3588 Linux SDK 环境中构建最终烧录到 C-3588LQ V1.0 + SHIMETAPI-M5-R2A V1.0 底板的根文件系统。 重要： 出厂镜像（已预装在开发板上）的根文件系统是 Debian 12 bookworm，不是 bullseye。本文档描述的是用 SDK 构建镜像的流程（PC 端操作，构建出的版本与出厂镜像相互独立）。

---

1. 概念基础

1.1 根文件系统作用

根文件系统（Rootfs）是 Linux 启动后挂载的第一个文件系统，包含：

• 所有用户空间程序（apps、daemons）
• 共享库（libs）
• 配置文件（/etc）
• 工具与 shell
• 设备树 Overlay 可加载的片段

RK3588 SDK 支持两种方案：

方案	适用场景	特点
Buildroot	存储受限的嵌入式、IoT、工业控制	体积小（~64MB~256MB），启动快，定制强
Debian	桌面级应用、多媒体终端、AI 边缘计算	生态丰富，apt 包管理，调试方便

1.2 构建流程概览

工具链 → 基础系统 → 软件包安装 → 文件系统镜像生成

• Buildroot：Makefile/Kconfig 自动化，下载源码、交叉编译、打包
• Debian：live-build + debootstrap 创建基础 Debian，再叠加 Rockchip 定制 deb 包

---

2. 准备工作

2.1 硬件 / 软件清单

项目	内容
主控板	C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板（用于烧录验证，可选）
开发电脑	Ubuntu 20.04/22.04 LTS（64 位）
磁盘空间	Buildroot 需 ~20GB，Debian 需 ~40GB（推荐 200GB SSD）
SDK	已按 ch01-Linux_SDK编译 准备好

2.2 确认现有系统

设备端（验证用）：

df -h
mount | grep " / "
cat /proc/partitions

出厂镜像：/为 14G ext4（/dev/mmcblk0p6），/oem 124M（mmcblk0p7），/userdata 15G（mmcblk0p8）。

2.3 依赖包

电脑端：

# Buildroot 通用依赖
sudo apt-get install sed make binutils build-essential gcc g++ bash \
  patch gzip bzip2 perl tar cpio unzip rsync file bc wget python3

# Debian 构建额外依赖
sudo apt-get install binfmt-support qemu-user-static live-build
sudo dpkg -i debian/ubuntu-build-service/packages/*
sudo apt-get install -f

2.4 SDK 目录结构（根文件系统相关）

<SDK>/
├── buildroot/                 # Buildroot 构建系统
│   ├── configs/               # 默认配置
│   │   └── rockchip_rk3588_defconfig
│   ├── output/                # 编译输出
│   ├── package/               # 软件包定义
│   └── dl/                    # 下载的源码包
├── debian/                    # Debian 构建脚本
│   ├── mk-base-debian.sh      # 基础 Debian 系统构建
│   ├── mk-rootfs.sh           # 根文件系统构建（基于当前 RELEASE）
│   ├── mk-image.sh            # Ext4 镜像生成
│   ├── overlay/               # 板级覆盖文件
│   ├── packages/              # Rockchip 定制 deb 包
│   └── ubuntu-build-service/  # 构建服务工具

RK3588 SDK 同时支持 Debian 11（bullseye）和 Debian 12（bookworm），两种发行版的构建命令基本一致，区别在于脚本中的 RELEASE= 参数。

---

3. Buildroot 根文件系统构建

3.1 完整编译

电脑端：

cd <SDK_PATH>

# 选择板级配置
./build.sh device/rockchip/rk3588/BoardConfig-rk3588-evb1-ddr4-v10.mk

# 编译完整系统（含 Buildroot 根文件系统）
./build.sh all

# 或单独编译根文件系统
./build.sh rootfs

输出镜像：

buildroot/output/rockchip_rk3588/images/rootfs.ext4

3.2 配置 Buildroot

电脑端：

cd <SDK_PATH>
source envsetup.sh rockchip_rk3588
make menuconfig

常用菜单项：

配置路径	说明
Target options → Target Architecture	目标架构（AArch64）
Build options → Download dir	源码下载目录
Toolchain → Toolchain type	工具链类型
System configuration → Root password	root 用户密码
System configuration → /dev management	设备节点管理
Filesystem images → ext2/3/4 rootfs	根文件系统镜像格式
Target packages →	选择要包含的软件包

3.3 选择软件包（menuconfig）

通过路径勾选需要的包（示例）：

Target packages →
    [*] Audio and video applications
    [*]   gstreamer1
    [*]     gst1-plugins-base
    [*]     gst1-plugins-good
    [*]     gst1-plugins-bad
    [*] Debugging tools
    [*]   strace
    [*]   gdb
    [*] Development tools
    [*]   git
    [*] Networking applications
    [*]   openssh
    [*]   dhcpcd

3.4 使用配置片段

电脑端：

ls buildroot/configs/rockchip/
# adbd.config  audio.config  base.config  benchmark.config  bt.config
# camera.config  chromium.config  debug.config  display.config

构建时这些片段会自动合并到配置中。

3.5 单独编译 / 重新编译包

电脑端：

source envsetup.sh rockchip_rk3588

make <package>            # 编译
make <package>-rebuild    # 重新编译
make <package>-reconfigure    # 重新配置
make <package>-dirclean    # 完全清理

3.6 自定义根文件系统

方法一：覆盖文件

将文件放入 buildroot/board/rockchip/rk3588/overlay/，编译时会自动复制进根文件系统。

电脑端：

mkdir -p buildroot/board/rockchip/rk3588/overlay/etc
mkdir -p buildroot/board/rockchip/rk3588/overlay/opt/myapp

# 自定义配置
echo "my_custom_config" > buildroot/board/rockchip/rk3588/overlay/etc/my_config.conf

# 自定义启动脚本
cat > buildroot/board/rockchip/rk3588/overlay/etc/init.d/S99myapp << 'EOF'
#!/bin/sh
case "$1" in
    start)
        echo "Starting myapp..."
        /opt/myapp/myapp &
        ;;
    stop)
        killall myapp
        ;;
    *)
        exit 1
        ;;
esac
EOF
chmod +x buildroot/board/rockchip/rk3588/overlay/etc/init.d/S99myapp

方法二：post-build 脚本

电脑端（编辑 buildroot/board/rockchip/rk3588/post-build.sh）：

#!/bin/sh
# post-build.sh: 在构建完成后执行的自定义操作

# 设置 root 密码
echo "root:myrootpassword" | chpasswd -r $TARGET_DIR

# 修改 motd 消息
echo "Welcome to shimetapi RK3588" > $TARGET_DIR/etc/motd

# 移除不需要的文件
rm -rf $TARGET_DIR/usr/share/man
rm -rf $TARGET_DIR/usr/share/doc

---

4. Debian 根文件系统构建

Debian 12 (bookworm) 是当前最新默认；如需 Debian 11 (bullseye) 请调整脚本参数。

4.1 一键编译

电脑端：

cd <SDK_PATH>

# 选择 Debian 作为根文件系统（RK SDK 通过 RK_ROOTFS_SYSTEM 切换）
export RK_ROOTFS_SYSTEM=debian

# 编译完整系统
./build.sh all

4.2 分步构建

电脑端：

cd <SDK_PATH>/debian

# 1. 构建基础 Debian 系统（先确保脚本可执行）
chmod +x mk-base-debian.sh mk-rootfs.sh mk-image.sh

# 2. 安装依赖
sudo apt-get install binfmt-support qemu-user-static live-build
sudo dpkg -i ubuntu-build-service/packages/*
sudo apt-get install -f

# 3. 64 位 Debian 12 (bookworm, 默认)
RELEASE=bookworm TARGET=desktop ARCH=arm64 ./mk-base-debian.sh

# 或 Debian 11 (bullseye, 备选)
RELEASE=bullseye TARGET=desktop ARCH=arm64 ./mk-base-debian.sh

# 4. 构建 RK 定制根文件系统
VERSION=debug ARCH=arm64 ./mk-rootfs.sh

# 5. 生成 ext4 镜像
./mk-image.sh

输出文件：debian/linaro-rootfs.img

4.3 配置 Debian 镜像源

编辑 debian/ubuntu-build-service/bookworm-desktop-arm64/configure（或 bullseye-desktop-arm64，视选用版本而定），添加国内镜像源：

--mirror-bootstrap "http://mirrors.ustc.edu.cn/debian" \
--mirror-chroot "http://mirrors.ustc.edu.cn/debian" \
--mirror-chroot-security "http://mirrors.ustc.edu.cn/debian-security" \
--mirror-binary "http://mirrors.ustc.edu.cn/debian" \
--mirror-binary-security "http://mirrors.ustc.edu.cn/debian-security"

如使用阿里云：mirrors.aliyun.com/debian；如使用清华：mirrors.tuna.tsinghua.edu.cn/debian。

4.4 自定义 Debian 根文件系统

自定义方式	方法
添加软件包	编辑 configure 的 --packages / --package-lists
添加覆盖文件	放入 debian/overlay/ 目录，构建时自动复制
添加启动脚本	编辑 debian/overlay/etc/rc.local 或创建 systemd 服务
预装应用	在 debian/packages/ 放入自定义 .deb，脚本会安装

---

5. 自定义根文件系统（手动制作）

5.1 使用 debootstrap 手动制作

电脑端：

sudo apt-get install debootstrap qemu-user-static

mkdir rootfs
# Debian 12 (bookworm)
sudo debootstrap --arch=arm64 --foreign bookworm rootfs http://mirrors.ustc.edu.cn/debian
# 或 Debian 11 (bullseye)
# sudo debootstrap --arch=arm64 --foreign bullseye rootfs http://mirrors.ustc.edu.cn/debian

sudo cp /usr/bin/qemu-aarch64-static rootfs/usr/bin/

# 完成第二阶段安装
sudo chroot rootfs /debootstrap/debootstrap --second-stage

# 挂载伪文件系统
sudo mount --bind /dev rootfs/dev
sudo mount --bind /proc rootfs/proc
sudo mount --bind /sys rootfs/sys

# 配置网络
echo "nameserver 8.8.8.8" | sudo tee rootfs/etc/resolv.conf

# 安装系统组件
sudo chroot rootfs apt-get update
sudo chroot rootfs apt-get install -y openssh-server network-manager

# 打包为 ext4 镜像
dd if=/dev/zero of=rootfs.img bs=1M count=2048
mkfs.ext4 rootfs.img
sudo mount rootfs.img /mnt
sudo cp -a rootfs/* /mnt/
sudo umount /mnt

5.2 使用 BusyBox 制作最小根文件系统

电脑端：

wget https://busybox.net/downloads/busybox-1.35.0.tar.bz2
tar xf busybox-1.35.0.tar.bz2
cd busybox-1.35.0

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- defconfig
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- menuconfig
# 确保 "Build BusyBox as a static binary (no shared libs)" 已勾选

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -j$(nproc)
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- install

# 创建最小根文件系统
mkdir -p _install/{dev,proc,sys,etc,etc/init.d,lib,usr,var,root,tmp}

cat > _install/etc/inittab << 'EOF'
::sysinit:/etc/init.d/rcS
::respawn:-/bin/sh
::ctrlaltdel:/bin/umount -a -r
EOF

cat > _install/etc/init.d/rcS << 'EOF'
#!/bin/sh
mount -t proc none /proc
mount -t sysfs none /sys
mount -t tmpfs none /tmp
mdev -s
EOF
chmod +x _install/etc/init.d/rcS

---

6. Buildroot/Debian 包定义（参考）

6.1 Buildroot 软件包三件套

每个 Buildroot 包由三个文件定义：

Config.in（Kconfig 选项）：

config BR2_PACKAGE_MYAPP
    bool "myapp"
    help
      My custom application for RK3588.

myapp.mk（构建规则）：

MYAPP_VERSION = 1.0
MYAPP_SITE = /path/to/source
MYAPP_SITE_METHOD = local

define MYAPP_BUILD_CMDS
    $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D)
endef

define MYAPP_INSTALL_TARGET_CMDS
    $(INSTALL) -D -m 0755 $(@D)/myapp $(TARGET_DIR)/usr/bin/myapp
endef

$(eval $(generic-package))

6.2 Buildroot 构建流程

1. 下载源码包到 dl/ 目录
2. 解压到 output/build/<package>-<version>/
3. 配置（configure）
4. 编译（make）
5. 安装到 output/target/ 目录
6. 生成文件系统镜像（rootfs.ext4/rootfs.squashfs 等）

6.3 Debian 构建流程

1. mk-base-debian.sh: 使用 debootstrap + live-build 创建基础 Debian 系统
2. mk-rootfs.sh: 叠加 Rockchip 定制包（mpp、libmali、gstreamer-rockchip 等）
3. mk-image.sh: 打包为 ext4 镜像（输出 linaro-rootfs.img）

---

7. 故障排除

7.1 Buildroot 编译下载失败

现象： 构建过程长时间停在下载软件包这一步，提示超时或连接失败。

解决方案：

电脑端：

# 配置 BR2_PRIMARY_SITE 使用国内镜像
export BR2_PRIMARY_SITE="https://mirrors.ustc.edu.cn/buildroot"
# 或: https://mirror.sjtu.edu.cn/buildroot

# 或手动下载缺失的包到 dl/ 目录
ls buildroot/dl/    # 检查已下载

7.2 Debian 构建报 "noexec or nodev"

现象： Debian 构建时出现 Cannot install into target '.../chroot' mounted with noexec or nodev。

解决方案：

电脑端：

# 重新挂载构建目录，移除 noexec/nodev 限制
mount -o remount,exec,dev /path/to/sdk

确认构建所在的文件系统为 ext2/ext4 或已正确挂载。

7.3 Debian 镜像过大

现象： linaro-rootfs.img 超过 2GB（嵌入式固件常见容量上限）。

解决方案：

电脑端：

# 使用 minimal 变体而非 desktop
RELEASE=bookworm TARGET=minimal ARCH=arm64 ./mk-base-debian.sh
# 或 bullseye:
# RELEASE=bullseye TARGET=minimal ARCH=arm64 ./mk-base-debian.sh

清理不必要的包和文档可显著减小体积。

7.4 根文件系统无法挂载

现象： 内核启动提示 VFS: Cannot open root device。

解决方案：

电脑端：确保内核配置包含：

CONFIG_EXT4_FS=y    # ext4 支持
CONFIG_MMC_BLOCK=y  # eMMC/SD 块设备支持

---

相关文档

• 01_Linux_SDK编译 — SDK 编译流程
• 02_内核配置与裁剪 — 内核配置
• 05_hardware-reference/00_硬件事实基线 — 硬件事实清单