📚 课程目录第4章搭建镜像构建环境

4. 搭建镜像构建环境

SONiC 镜像构建本质上是在一个受控的 Linux 环境中，把大量上游源码、Debian 包、Docker 镜像和平台适配补丁编译、打包成可刷写的交换机镜像。构建环境一旦不稳定，后续出现的编译失败、依赖缺失、镜像体积异常等问题往往很难定位。因此，这一节的重点不是“装一个 Ubuntu”，而是把版本、容器运行时、依赖、磁盘、网络和构建用户这六个要素一次性配置到位。

一、Ubuntu 版本选择

SONiC 社区构建长期以 Ubuntu 20.04 LTS（Focal）为主力环境，较新的分支逐步向 Ubuntu 22.04 LTS（Jammy）迁移。选择原则可以归纳为三点：优先使用 SONiC 分支官方文档声明的版本；优先使用 LTS 版本以获得稳定的工具链和软件源；构建机与目标分支的 Python、GCC、Debian 打包工具版本要匹配。示例中我们以 Ubuntu 20.04 LTS 作为构建宿主，内核建议 5.4 及以上，内存不低于 16 GB，推荐 32 GB。

需要特别注意的是，SONiC 构建过程中会启动多个 Docker 容器（如 sonic-slave、sonic-buildimage 相关容器），宿主 Ubuntu 的版本主要影响 Docker 与内核行为，而真正的编译工具链由容器内的 slave 镜像提供。因此宿主版本不必追求最新，稳定和可复现更重要。

二、Docker 安装与验证

Docker 是 SONiC 构建的核心依赖，社区脚本通过 Docker 拉起构建容器。推荐使用 Docker 官方 apt 源安装，而不是 Ubuntu 自带的旧版本。示例命令如下：

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
https://download.docker.com/linux/ubuntu focal stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker
sudo docker run --rm hello-world

看到 Hello from Docker! 说明 Docker 安装成功。随后把构建用户加入 docker 组，避免每次使用 sudo：

sudo usermod -aG docker $USER
newgrp docker
docker info | grep -E "Server Version|Storage Driver"

建议存储驱动使用 overlay2，并确认 docker info 中 Cgroup 版本与宿主一致。若构建机同时运行 Kubernetes 或其他容器平台，需避免 Docker 与它们争抢同一存储目录。

三、依赖包与磁盘空间

宿主侧需要的基础依赖包括：git、make、python3、python3-pip、jq、quilt、dos2unix、rsync、bc、libssl-dev、libncurses-dev、flex、bison、build-essential、uuid-runtime、pigz、aria2 等。一次性安装：

sudo apt install -y git make python3 python3-pip jq quilt dos2unix rsync bc \
  libssl-dev libncurses-dev flex bison build-essential uuid-runtime pigz aria2

磁盘空间是构建环境中最容易被低估的一项。SONiC 全量构建会拉取大量源码、Debian 包和 Docker 层，建议为构建目录预留 至少 120 GB，推荐 200 GB 以上 SSD。可以用下面的方式检查：

df -h /data
# 示例输出：/dev/nvme0n1p1  400G  60G  320G  16% /data

如果空间不足，构建会在 make 阶段报 “No space left on device”，此时清理 target/ 与 Docker 悬空镜像通常能回收数十 GB：

docker system df
docker image prune -a
make clean

四、网络代理与构建用户配置

SONiC 构建需要访问 GitHub、Debian 源、Docker Hub 等外部资源。若构建机处于受限网络，需要同时为 shell、apt、git 和 Docker 配置代理，否则会出现“部分包能拉、部分包超时”的隐蔽问题。示例配置：

export http_proxy=http://10.0.0.1:3128
export https_proxy=http://10.0.0.1:3128
export no_proxy=localhost,127.0.0.1,10.0.0.0/8

sudo tee /etc/apt/apt.conf.d/95proxy <<'EOF'
Acquire::http::Proxy "http://10.0.0.1:3128";
Acquire::https::Proxy "http://10.0.0.1:3128";
EOF

git config --global http.proxy http://10.0.0.1:3128
git config --global https.proxy http://10.0.0.1:3128

Docker 守护进程的代理需要单独配置，写入 /etc/systemd/system/docker.service.d/http-proxy.conf 后执行 systemctl daemon-reload && systemctl restart docker。构建用户方面，建议创建专用账号 builder，加入 docker 组，并为其配置 SSH key 与 git 身份，避免使用 root 直接构建：

sudo useradd -m -s /bin/bash builder
sudo usermod -aG docker builder
sudo -iu builder
git config --global user.name "sonic-builder"
git config --global user.email "builder@example.com"
ssh-keygen -t ed25519 -C "builder@example.com"

下面这张图把本节六个要素与它们之间的依赖关系整理在一起，便于对照检查：

五、环境自检清单

在正式执行 make init 之前，建议按下面的顺序做一次自检，任何一项不通过都不要继续：

检查项	命令	通过标准
Ubuntu 版本	`lsb_release -a`	20.04 或 22.04 LTS
Docker 可用	`docker run --rm hello-world`	输出 Hello from Docker!
存储驱动	`docker info \| grep Storage`	overlay2
磁盘空间	`df -h /data`	可用 ≥ 120 GB
代理连通	`curl -I https://github.com`	返回 200/301
构建用户	`id builder`	包含 docker 组

如果构建机位于内网且无法直连外网，可以提前在可联网机器上执行 make init 拉取源码与 slave 镜像，再把 target/ 与 Docker 镜像导出后拷贝到构建机，减少对代理的依赖。

不要用 root 直接执行构建脚本。SONiC 构建过程中会生成大量文件，root 构建会导致后续 make clean 和权限修复非常麻烦；同时 Docker 组本身等价于 root 权限，构建用户应仅用于构建，不要在该账号下存放敏感凭据。

完成以上配置后，构建环境就具备了可复现的基础。接下来进入源码拉取与 make init 阶段时，如果出现网络超时、依赖缺失或空间不足，都可以回到本节对应的检查项快速定位，而不必在编译日志里反复排查。