x86 架构下运行 ARM-ROS2 Docker 镜像操作指南

ps: 这篇文章只涉及到操作流程，具体的容器没有办法分享给大家（公司内部文件）。😟

1. Docker 安装与环境配置

1.1 清理旧版本

为了防止版本冲突，优先清理系统中可能存在的旧版本 Docker：

复制代码

sudo apt-get remove docker docker-engine docker.io containerd runc

1.2 安装基础工具

复制代码

sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg

1.3 配置阿里云软件源

添加 GPG 密钥并写入软件源列表（提升国内安装速度）：

复制代码

# 添加 GPG Key 
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg 

# 写入源列表 
echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

1.4 安装 Docker Engine

复制代码

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

1.5 配置镜像加速器（关键步骤）

注意：为了解决 dial tcp ... i/o timeout 网络超时问题，必须配置国内镜像源。

复制代码

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://docker.nju.edu.cn",
    "https://mirror.baidubce.com"
  ]
}
EOF

# 重启 Docker 使配置生效
sudo systemctl daemon-reload
sudo systemctl restart docker

1.6 设置用户权限（免 sudo）

将当前用户加入 docker 组，避免每次都要输 sudo：

复制代码

sudo usermod -aG docker $USER
newgrp docker

(验证：输入 docker version 若无报错则配置成功)

2. ARM 跨架构环境配置与镜像运行

2.1 安装 QEMU 模拟器支持

在宿主机安装基础支持工具：

复制代码

sudo apt-get install -y qemu-user-static binfmt-support

2.2 注册 QEMU 到内核（核心魔法步骤）

这一步至关重要。它通知内核遇到 ARM 程序时自动调用 QEMU 翻译。

复制代码

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

注：执行成功后会下载一个小镜像并退出，无报错即为成功。

2.3 加载本地 ARM 镜像

将 .tar.gz 镜像文件导入本地仓库：

复制代码

docker load -i arm-ros2-humble-20260108.tar.gz

导入后使用 docker images 确认镜像名称（例如：arm-ros2-humble）和标签（20260108）。

2.4 启动容器

使用以下命令启动并进入容器：

复制代码

docker run --platform linux/arm64 -it arm-ros2-humble:20260108 /bin/bash

2.5 验证运行结果

进入容器后，输入以下命令查看架构：

复制代码

uname -m

若输出 aarch64：恭喜，环境运行成功！
若输出 x86_64：说明模拟未生效，请重新执行步骤 2.2。

⚠️ PS / 常见问题提示（必读）

1. 关于平台警告（WARNING）

现象：启动容器时可能会看到提示 WARNING: The requested image's platform (linux/arm64/v8) does not match the detected host platform...
解释：这是 Docker 在善意提醒你"你在 x86 电脑上跑 ARM 镜像"。
对策：只要你执行了步骤 2.2，请忽略此警告 ，它不会影响运行。在启动命令中添加 --platform linux/arm64 参数可以消除此警告。

2. 关于镜像拉取超时

如果在执行 2.2 时提示 dial tcp ... i/o timeout，说明无法连接 Docker Hub。请务必检查 1.5 章节 的镜像加速器是否配置正确并重启了 Docker 服务。

3. Exec format error 报错

如果启动容器时直接报错 exec format error，说明 QEMU 注册失败。请重新执行步骤 2.2。