使用Docker在Ubuntu上搭建OrangePi5 SDK编译环境与问题解决

官方推荐的是直接在 Host 机器上使用 SDK 构建相关镜像，但使用 Docker 可以方便地隔离编译环境，避免污染主机系统。

以下是在 Docker 中成功构建 OrangePi5 系统镜像的完整步骤以及常见问题的解决方案。

测试通过的 Host 环境

• Ubuntu 24.04 物理主机。
• Windows 下的 WSL2 子系统。

操作步骤

1. 拉取 Docker 镜像
   官方推荐使用 Ubuntu 22.04 版本的基础镜像。

   docker pull ubuntu:22.04

2. 创建并进入容器
   使用以下命令创建具备特权并映射了必要目录的容器。

   docker run --name dev-orangepi -it --privileged=true --net=host -v /lib/modules:/lib/modules -v /dev:/dev -v $HOME/workspace:$HOME/workspace ubuntu:22.04 /bin/bash

   关键参数说明：

   • --privileged=true: 赋予容器 root 权限，解决后续可能出现的挂载等问题。
   • -v /lib/modules:/lib/modules 和 -v /dev:/dev: 映射内核模块和设备目录，这对构建系统镜像至关重要。
   • -v $HOME/workspace:$HOME/workspace: 将宿主机的工作目录映射到容器内，方便共享文件。

3. 更换软件源
   为了加速软件包下载，建议将容器内的 APT 源更换为国内镜像源，例如清华源。

4. 安装基本依赖工具
   进入容器后，首先更新软件包列表并安装一些编译和系统管理所需的基础工具。如果你对 计算机基础 环境配置不熟悉，可以先执行此步骤，或按需安装。

   apt-get update
   apt-get upgrade -y
   apt-get install -y vim
   apt-get install -y libncurses5-dev build-essential bison flex libssl-dev git fdisk

5. 拉取 OrangePi 官方 SDK
   在映射的工作目录下拉取构建脚本仓库。

   cd ~/workspace
   git clone https://github.com/orangepi-xunlong/orangepi-build.git -b next

6. 启动构建过程
   运行构建脚本，并通过交互式菜单选择要构建的板型（如 OrangePi 5 Plus）和系统版本（如 Ubuntu 20.04 Focal Server）。

   ./build.sh

常见问题与解决方案

在 Docker 环境中构建时，你可能会遇到一些在宿主机上不会出现的问题。

1. chroot 报错

错误信息:

[ o.k. ] Installing base system [ Stage 2/2 ]
chroot: failed to run command ‘/bin/bash’: No such file or directory
[ error ] ERROR in function create_rootfs_cache ...

分析与解决:
此错误可能由构建环境的状态引起。一种可行的解决方法是，先在宿主机上成功构建一次，之后再在 Docker 容器内构建。社区中也有类似问题的讨论可供参考。

2. 挂载 binfmt_misc 问题

错误信息:

mount: /proc/sys/fs/binfmt_misc: permission denied.
update-binfmts: warning: Couldn't mount the binfmt_misc filesystem...

分析与解决:
这是因为需要注册 QEMU 静态解释器来运行跨架构（如 ARM）的二进制文件。创建容器时已使用 --privileged 参数。
你可以在容器内执行以下命令来测试和启用所需支持：

sudo apt-get update && sudo apt install -y qemu-user-binfmt
sudo update-binfmts --enable qemu-aarch64
update-binfmts --display | grep qemu-aarch64
# 状态显示为 `enabled` 即正常
qemu-aarch64 (enabled):

3. sfdisk 工具未安装

错误信息:
在构建日志 install.log 中看到：

~/workspace/orangepi-build/scripts/debootstrap.sh: line 629: sfdisk: command not found

解决:
安装 fdisk 工具包，其中包含了 sfdisk 命令。

sudo apt install fdisk

4. check_loop_device 函数报错

错误信息:

[ error ] ERROR in function check_loop_device ...
[ error ] Device node /dev/loop3p2 does not exist

分析与解决:
这个错误通常是因为容器内部无法正确访问宿主机的设备节点和内核模块。
解决方案：在创建 Docker 容器时，必须添加以下两个卷映射参数：

-v /lib/modules:/lib/modules -v /dev:/dev

排查思路:

1. 起初怀疑是内核 loop 模块的问题。但在 Linux 系统中，loop 驱动通常是内建（built-in）的，lsmod | grep loop 可能无输出。
2. 尝试在容器内执行 modprobe loop，在宿主机成功但在容器内报错，这提示了容器缺少宿主机 /lib/modules 目录下的内核模块信息。
3. 参考相关文档，首先映射了 /lib/modules 目录，但问题依旧。
4. 最终，同时映射 /lib/modules 和 /dev 目录后，问题得以解决。这类设备映射和内核访问问题，在 运维/DevOps/SRE 实践中经常需要处理。

构建成功

解决上述问题后，构建过程将顺利完成，输出类似如下信息：

[ o.k. ] SHA256 calculating [ Orangepi5plus_1.2.0_ubuntu_focal_server_linux6.1.43.img ]
[ o.k. ] Done building [ ~/workspace/orangepi-build/output/images/Orangepi5plus_1.2.0_ubuntu_focal_server_linux6.1.43.img ]
[ o.k. ] Runtime [ 20 min ]

生成的 .img 文件即可用于烧录到 OrangePi 5 Plus 开发板。

通过 Docker 容器化编译环境，不仅能保证环境的一致性与纯净性，也便于团队共享和版本管理。如果在实践中遇到更多系统构建或环境配置的挑战，欢迎到 云栈社区 的相关板块与开发者们交流探讨。