RK3588 Docker 启动失败排查与修复

摘要在 RK3588 或其他 Linux 开发板上Docker 常见启动失败。本文给出两种可落地方案方案一按瑞芯微文档做下 iptables 选择切换legacy/nft方案二补齐内核 Docker 依赖能力check-config menuconfig 重编译 模块替换文中所有命令已按实际流程整理适合直接照做。项目地址GitHub本文对应项目已同步发布在 GitHub可直接参考仓库中的最新文档、脚本与配图https://github.com/ShengTong1/rk3588-docker-kernel-guide一、问题背景在开发板上系统基础功能通常正常但 Docker 无法直接可用常见现象包括Docker 服务启动失败提示缺少 cgroups、namespace、overlayfs 等内核能力容器创建失败或网络初始化失败典型报错Couldn’t load match ‘addrtype’:No such file or directory根因通常是内核配置不完整或用户态 iptables 路径与当前内核能力不匹配导致 Docker 网络规则下发失败。二、适用范围本思路不仅适用于 RK3588。凡是 Linux 开发板在 Docker 启动时出现内核能力缺失、网络初始化失败、addrtype 相关报错都可参考。本文仅以笔者手中的飞凌嵌入式的 ELF2RK3588为例其他Linux开发板同理迁移。三、方案一优先尝试切换 iptables参考资料Rockchip_Developer_Guide_Linux_Docker_Deploy_CN.pdf5.3 Debian 配置。切换到 legacysudo update-alternatives --set iptables /usr/sbin/iptables-legacysudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy切回 nftsudo update-alternatives --set iptables /usr/sbin/iptables-nftsudo update-alternatives --set ip6tables /usr/sbin/ip6tables-nft验证docker infodocker run --rm hello-worldjournalctl -u docker -n 200 --no-pager说明此方案属于用户态配置改动小、见效快建议先试。四、方案二主线补齐内核能力步骤1获取并执行 check-config 脚本cd /home/elf/work/ELF2-linux-source/kernelcurl -fL https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh -o ./check-config.shchmod x ./check-config.sh./check-config.sh .config处理原则Generally Necessary 中 missing 项要补齐。步骤2menuconfig 补配置cd /home/elf/work/ELF2-linux-source/kernelmake menuconfig建议用 / 检索 missing 项再用数字跳转定位。配置建议仅为笔者经验Generally Necessary 中 missing 必补与 IPv6 无关能力优先编译进内核IPv6 相关能力编译为模块步骤3保存配置并复查保存 .config 后再跑一次./check-config.sh .config步骤4导出并固化 defconfigcd /home/elf/work/ELF2-linux-source/kernelmake ARCHarm64 CROSS_COMPILE/home/elf/work/ELF2-linux-source/prebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu- savedefconfigcp defconfig arch/arm64/configs/elf2_kernel_defconfig步骤5重新编译内核cd /home/elf/work/ELF2-linux-source./build kenerl步骤6导出模块cd /home/elf/work/ELF2-linux-sourcemkdir -p /home/elf/work/installsudo make -C /home/elf/work/ELF2-linux-source/kernel/ CROSS_COMPILEprebuilts/gcc/linux-x86/aarch64/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu- ARCHarm64 modules_install INSTALL_MOD_PATH/home/elf/work/install步骤7板端替换 /lib/modulesSRC/home/elf/work/install/lib/modules/5.10.209DST/lib/modules/5.10.209test -d “$SRC” || { echo “源目录不存在:KaTeX parse error: Expected EOF, got } at position 15: SRC; exit 1; }̲ uname -r sudo …DST” “DST.baksudorm−rf{DST}.bak sudo rm -rf DST.baksudorm−rfDST”sudo mkdir -p /lib/modulessudo cp -a “SRC/lib/modules/sudochown−Rroot:rootSRC /lib/modules/ sudo chown -R root:root SRC/lib/modules/sudochown−Rroot:rootDST”sudo depmod -a 5.10.209ls -la “$DST” | headsudo modprobe -n -v vethsudo modprobe -n -v br_netfilter步骤8烧录 boot.img按你的 SDK/产线流程打包并烧录 boot.img。步骤9启动后验证docker infodocker run --rm hello-worldjournalctl -u docker -n 200 --no-pager通过标准Docker 服务正常启动hello-world 运行成功五、补充说明大陆网络环境建议先配置 Docker 镜像加速否则可能无法正常拉取镜像。若步骤1下载失败可直接使用仓库内 check-config.sh。若 uname -r 与脚本中的版本号不同请按实际版本替换。六、结语如果方案一无法解决就进入方案二按步骤补齐内核能力。整体流程可复用到多数 Linux 开发板只需按你的平台路径和版本替换命令参数。