一、安装 Docker 引擎

1.下载必要的软件

sudo apt update

sudo apt install apt-transport-https ca-certificates curl gnupg lsb-release

2.添加Docker的官方GPG密钥

（1）创建 keyrings 目录

sudo install -m 0755 -d /etc/apt/keyrings

（2）下载Docker的公钥

使用gpg --dearmor命令将其转换为适用于apt的格式，存储在/usr/share/keyrings目录下

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

（3）给目录权限

sudo chmod a+r /etc/apt/keyrings/docker.gpg

3.设置Docker稳定版仓库

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4.安装 Docker 引擎

sudo apt update

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

5.配置 Docker 用户组

为了避免每次运行 Docker 都要输入 sudo，将当前用户加入 docker 组。

sudo usermod -aG docker $USER

配置完后重启系统

6.配置图形化支持 (GUI 转发)

ROS 2 经常需要使用 Rviz2 或 Gazebo 等图形界面工具。为了让 Docker 容器内的窗口显示在 Debian 桌面系统上，需要配置 X11 访问权限。

安装 xhost：

sudo apt install -y x11-xserver-utils

允许本地连接：

xhost +local:root

二、启动 ROS 2 Galactic 容器

1.我们使用官方维护的 osrf/ros:galactic-desktop 镜像，它包含了完整的桌面开发工具。

运行以下命令启动容器：

docker run -it \
  --name galactic_container \
  --env="DISPLAY" \
  --env="QT_X11_NO_MITSHM=1" \
  --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
  --network host \
  ros:galactic-ros-base

2.在拉取镜像过程中出现，网络无法直接到达的问题，解决方法

编辑 Docker 配置文件：
如果文件不存在，会自动创建。

sudo vim /etc/docker/daemon.json

/etc/docker/daemon.json 完整内容：
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.anyhub.us.kg",
    "https://dockerhub.jobcher.com",
    "https://docker.ckyl.me",
    "https://docker.awsl9527.cn",
    "https://mirror.baidubce.com"
  ]
}

然后重启

sudo systemctl daemon-reload

sudo systemctl restart docker

此时出现新问题：我的系统根目录本身就是overlayroot ，而Docker 默认的 overlay2 存储驱动无法在另一个 Overlay 文件系统之上运行。

解决办法一：

（1）完全清理失败的残留（非常重要）

由于之前的解压失败占用了空间且产生了错误的文件碎片，先执行清理：

sudo docker system prune -a

（2）修改 /etc/docker/daemon.json

我们需要强制 Docker 使用 vfs 驱动（兼容性最强，专门解决底层是 Overlay 的情况），同时保留镜像加速器。

执行：

sudo nano /etc/docker/daemon.json

将内容完整替换为：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.anyhub.us.kg",
    "https://dockerhub.jobcher.com",
    "https://mirror.baidubce.com"
  ],
  "storage-driver": "vfs"
}

重启 Docker 服务

解决方法二：

（1）创建新的镜像存储目录：（我的开发板userdata不是overlatroot）

sudo mkdir -p /userdata/docker

   (2)修改 /etc/docker/daemon.json：
不要使用 vfs，而是指定数据目录（data-root）并保留加速器。

sudo vim /etc/docker/daemon.json

替换为以下内容：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.anyhub.us.kg",
    "https://dockerhub.jobcher.com",
    "https://mirror.baidubce.com"
  ],
  "data-root": "/userdata/docker",
  "storage-driver": "overlay2"
}

重启 Docker：

sudo systemctl daemon-reload
sudo systemctl start docker

再重新拉取即可

docker run -it \
  --name galactic_container \
  --env="DISPLAY" \
  --env="QT_X11_NO_MITSHM=1" \
  --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
  --network host \
  ros:galactic-ros-base

三、进入容器后手动安装桌面工具 (Desktop Components)

当你成功进入容器（看到 root@firefly:/#）后，运行以下命令来安装 Rviz2 等桌面工具：

# 更新软件源
apt update

# 安装桌面全家桶（注意：这可能需要一段时间，取决于网速）
apt install ros-galactic-desktop -y

1.验证 ROS 2 环境

在当前的容器终端中，执行以下命令来确认 ROS 2 是否可以正常工作：

(1)加载环境变量：

source /opt/ros/galactic/setup.bash

(2)运行一个 Demo 测试（Talker）：

ros2 run demo_nodes_cpp talker

屏幕开始循环打印 Publishing: "Hello World: 1"，说明核心组件已经安装成功！

2.持久化保存镜像

注意： Docker 容器默认是“临时”的。如果你现在直接关闭这个终端或退出容器，你刚才安装的几个 GB 的 ROS 桌面组件将会全堆丢失。

(1)保持当前的容器终端不要关闭。

(2)在开发板上重新打开一个新的终端。

（3）执行以下命令，将这个容器保存为一个新的镜像：

# 1. 查看容器 ID（找到名为 galactic_container 的那一行）
docker ps

# 2. 提交并保存镜像
# 语法：docker commit [容器名/ID] [新镜像名]:[标签]
docker commit galactic_container my_ros_galactic_desktop:v1

3.配置自动加载环境

为了以后进入容器不用每次都手动敲 source 命令，我们将它写入容器的配置文件中：

在容器内部终端执行：

echo "source /opt/ros/galactic/setup.bash" >> ~/.bashrc
source ~/.bashrc

4.测试图形化工具 (Rviz2)

（1）在宿主机 (Firefly 终端) 执行：
允许 Docker 访问宿主机的显示服务：

xhost +local:docker

在容器内部终端执行：
尝试打开 Rviz2：

rviz2