Distrobox 搭建 ROS Melodic 环境

目标：在 Ubuntu 26.04 宿主机上，通过 Distrobox 运行 Ubuntu 18.04 容器，并在容器内安装 ROS Melodic。

核心原则：

所有包管理只用 apt，不使用 rosdep
全部使用华为镜像源加速
不装 Docker，只用 Podman + Distrobox（rootless，更安全）

一、宿主机准备（Ubuntu 26.04）

1.1 确认系统版本

BASH

lsb_release -a
uname -r

预期输出：

Distributor ID: Ubuntu
Description:    Ubuntu 26.04 LTS
Release:        26.04
Codename:       resolute
7.0.0-14-generic

1.2 设置华为 Ubuntu 镜像源

Ubuntu 26.04 使用 deb822 格式，配置文件路径为 /etc/apt/sources.list.d/ubuntu.sources。

BASH

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak.$(date +%Y%m%d)

sudo tee /etc/apt/sources.list.d/ubuntu.sources << 'EOF'
Types: deb
URIs: https://mirrors.huaweicloud.com/repository/ubuntu/
Suites: resolute resolute-updates resolute-backports
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

Types: deb
URIs: https://mirrors.huaweicloud.com/repository/ubuntu/
Suites: resolute-security
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
EOF

sudo apt update

1.3 安装 Podman + Distrobox

BASH

sudo apt install -y podman distrobox

验证安装：

BASH

podman --version    # podman version 5.7.0
distrobox --version # distrobox: 1.8.2.4

1.4 用户组配置（串口/摄像头权限）

BASH

sudo usermod -aG dialout $USER   # 串口权限
sudo usermod -aG video $USER     # 摄像头/GPU 权限

注意：添加组后需要完全注销并重新登录才能生效。

二、创建 Ubuntu 18.04 容器

2.1 拉取 Ubuntu 18.04 镜像

由于 docker.io 在国内访问不稳定，使用道客云镜像加速：

BASH

podman pull docker.m.daocloud.io/library/ubuntu:18.04
podman tag docker.m.daocloud.io/library/ubuntu:18.04 ubuntu:18.04

验证镜像：

BASH

podman images | grep ubuntu
# 输出示例：
# localhost/ubuntu                     18.04   f9a80a55f492   3 years ago   65.5 MB

2.2 创建 Distrobox 容器

BASH

yes | distrobox create \
  --image ubuntu:18.04 \
  --name ros-melodic-box \
  --home ~/distrobox-homes/ros-melodic

参数说明：

--image ubuntu:18.04：使用本地已打标签的 18.04 镜像
--name ros-melodic-box：容器名称
--home ~/distrobox-homes/ros-melodic：容器家目录映射到宿主机，数据永久保存

2.3 首次进入容器（关键！等待初始化完成）

重要：Distrobox 首次进入时会自动初始化，安装约 216 个基础包（约 77MB），耗时约 3~5 分钟。

BASH

distrobox enter ros-melodic-box

绝对不要在这个过程中：

按 Ctrl+C 中断
在另一个终端杀掉容器内的 apt 进程
重复执行 distrobox enter

初始化完成后，提示符会变成：

[tm-robot@ros-melodic-box ~]$

如果容器异常退出：是因为初始化被中断了。解决方法是删除重建：
BASH
distrobox stop ros-melodic-box
distrobox rm ros-melodic-box
rm -rf ~/distrobox-homes/ros-melodic
# 然后从 2.2 重新开始

三、容器内环境配置

3.1 设置华为 Ubuntu 镜像源

容器内是 Ubuntu 18.04（bionic），使用传统 sources.list 格式。由于基础镜像缺少 CA 证书，先使用 HTTP 源安装证书，再切换到 HTTPS。

BASH

# 先使用 HTTP 源安装 ca-certificates
sudo tee /etc/apt/sources.list << 'EOF'
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic main restricted universe multiverse
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic-updates main restricted universe multiverse
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic-backports main restricted universe multiverse
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic-security main restricted universe multiverse
EOF

sudo apt update
sudo apt install -y ca-certificates

# 切换到 HTTPS 源
sudo tee /etc/apt/sources.list << 'EOF'
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic main restricted universe multiverse
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic-updates main restricted universe multiverse
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic-backports main restricted universe multiverse
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic-security main restricted universe multiverse
EOF

sudo apt update

3.2 安装基础工具

BASH

sudo apt install -y \
    curl gnupg2 lsb-release software-properties-common \
    git build-essential \
    python-rosdep python-rosinstall \
    python-rosinstall-generator python-wstool \
    mesa-utils

python-catkin-tools 不在默认源中，通过 pip 安装：

BASH

sudo apt install -y python-pip
sudo pip install catkin_tools

四、安装 ROS Melodic（只用 apt，不用 rosdep）

4.1 添加华为 ROS 镜像源

BASH

sudo tee /etc/apt/sources.list.d/ros-latest.list << 'EOF'
deb https://mirrors.huaweicloud.com/ros/ubuntu/ bionic main
EOF

# 添加 ROS GPG 公钥
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -

sudo apt update

4.2 安装 ROS Melodic 完整版

BASH

sudo DEBIAN_FRONTEND=noninteractive apt install -y ros-melodic-desktop-full

安装时间较长（约 500MB 包，取决于网速），请耐心等待。使用华为源速度约 60 kB/s，预计 10~15 分钟。

4.3 修复依赖冲突（已知问题）

安装完成后，可能会出现 python-rospkg / python-rosdistro 旧包与 -modules 新包的文件冲突。

症状：

dpkg: error processing archive .../python-rospkg-modules_1.5.1-1_all.deb (--unpack):
 trying to overwrite '/usr/lib/python2.7/dist-packages/rospkg/__init__.py',
 which is also in package python-rospkg 1.1.4-1

修复命令：

BASH

sudo apt -o Dpkg::Options::=--force-overwrite install -y \
    python-rospkg-modules python-rosdistro-modules python-catkin-pkg-modules

sudo apt --fix-broken install -y

4.4 验证安装

BASH

# 检查 ROS 包状态
dpkg -l | grep ros-melodic-desktop-full

# 预期输出：
# ii  ros-melodic-desktop-full  1.4.1-0bionic.20230620.175308  amd64  ...

五、环境变量配置

将 ROS 环境变量添加到 .bashrc，这样每次进入容器自动加载：

BASH

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

如果有 catkin 工作空间，也加上：

BASH

# 假设工作空间在 ~/catkin_ws
echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc

立即生效：

BASH

source ~/.bashrc

六、创建工作空间（可选）

BASH

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
# 在这里 git clone 需要的 ROS 包
cd ~/catkin_ws
catkin_make

七、日常使用

7.1 进入容器

BASH

distrobox enter ros-melodic-box

进入后已经是 Ubuntu 18.04 环境，所有 ROS 命令直接使用。

7.2 运行 ROS

BASH

# 启动 roscore
roscore &

# 运行小乌龟（桌面环境下窗口直接弹出）
rosrun turtlesim turtlesim_node

# 运行 RViz
rosrun rviz rviz

# 运行 Gazebo
rosrun gazebo_ros gazebo

7.3 宿主机直接执行容器内命令

不需要先 enter 再执行，可以一行搞定：

BASH

# 编译工作空间
distrobox enter ros-melodic-box -- bash -c "cd ~/catkin_ws && catkin_make"

# 运行 launch 文件
distrobox enter ros-melodic-box -- roslaunch your_package your.launch

7.4 导出应用到宿主机菜单（可选）

在容器内执行：

BASH

distrobox-export --app rviz
distrobox-export --app rqt
distrobox-export --app gazebo

导出后，宿主机的应用菜单里会出现 “RViz (on ros-melodic-box)"，点击直接运行。

7.5 停止/启动容器

BASH

# 停止
distrobox stop ros-melodic-box

# 启动（distrobox enter 会自动启动已停止的容器）
distrobox enter ros-melodic-box

# 完全删除容器和数据
podman stop ros-melodic-box
podman rm ros-melodic-box
rm -rf ~/distrobox-homes/ros-melodic

八、硬件/外设使用

8.1 串口设备

Distrobox 默认共享 /dev 目录，串口设备直接可见：

BASH

ls /dev/ttyUSB*   # USB 转串口
ls /dev/ttyACM*   # Arduino / 某些激光雷达
stty -F /dev/ttyUSB0   # 测试读写权限

权限说明：

只要宿主机用户已加入 dialout 组（见 1.4），容器内自动拥有串口读写权限
如果权限不足，在宿主机执行 newgrp dialout 或重新登录

8.2 摄像头

BASH

ls /dev/video*    # 摄像头设备直接可见

8.3 特殊设备（RealSense、CAN 等）

宿主机：负责安装内核模块和驱动
容器内：只装 ROS 驱动包（如 ros-melodic-realsense2-camera）
udev 规则放在宿主机 /etc/udev/rules.d/，然后执行 sudo udevadm control --reload-rules

九、常见问题速查

问题	解决
`docker.io` 拉镜像超时	用 `docker.m.daocloud.io/library/ubuntu:18.04` 代替
容器创建后第一次进入就退出	等待初始化完成（~3-5 分钟），不要中断
容器内 `apt update` 报证书错误	先换 HTTP 源安装 `ca-certificates`，再切 HTTPS
`python-rospkg-modules` 文件冲突	`sudo apt -o Dpkg::Options::=--force-overwrite install -y python-rospkg-modules python-rosdistro-modules`
串口 `/dev/ttyUSB0` 权限 denied	宿主机执行 `sudo usermod -aG dialout $USER`，注销重新登录
GUI 窗口不弹出	确认在桌面环境运行，不是纯 SSH；或尝试 `export DISPLAY=:0`
Gazebo 黑屏/闪退	容器内执行 `export LIBGL_ALWAYS_SOFTWARE=1` 强制软渲染测试

十、为什么不用 rosdep？

本教程选择只用 apt 管理依赖，不使用 rosdep。原因是 rosdep 在国内网络环境下经常初始化失败或更新超时，且本方案的所有依赖均可通过 apt 直接安装，无需引入额外的依赖管理工具。

场景	做法
ROS 基础依赖	`sudo apt install -y ros-melodic-desktop-full`
额外的 ROS 包	`sudo apt install -y ros-melodic-<package-name>`
系统级依赖	`sudo apt install -y <system-package>`
Python 包	`sudo pip install <python-package>`（少数情况）

这种简化方案适用于：

项目所有依赖都可以通过 apt 安装（ROS 官方包或系统包）
不需要跨平台构建（rosdep 的主要价值是统一不同发行版的依赖名，如果只固定在 Ubuntu 18.04 上使用，这个价值不大）

如果未来确实需要 rosdep，可以按以下步骤安装：

BASH

sudo apt install -y python-rosdep
sudo rosdep init
rosdep update

十一、数据备份

所有代码和配置都在宿主机的 ~/distrobox-homes/ros-melodic/ 下：

BASH

# 查看容器内文件（在宿主机上）
ls ~/distrobox-homes/ros-melodic/

# 备份整个环境
tar czvf ros-melodic-backup.tar.gz ~/distrobox-homes/ros-melodic/

即使容器被删除，~/distrobox-homes/ros-melodic/ 里的数据仍然保留。重建容器时指定同一个 --home 即可恢复。

一、宿主机准备（Ubuntu 26.04）#

1.1 确认系统版本#

1.2 设置华为 Ubuntu 镜像源#

1.3 安装 Podman + Distrobox#

1.4 用户组配置（串口/摄像头权限）#

二、创建 Ubuntu 18.04 容器#

2.1 拉取 Ubuntu 18.04 镜像#

2.2 创建 Distrobox 容器#

2.3 首次进入容器（关键！等待初始化完成）#

三、容器内环境配置#

3.1 设置华为 Ubuntu 镜像源#

3.2 安装基础工具#

四、安装 ROS Melodic（只用 apt，不用 rosdep）#

4.1 添加华为 ROS 镜像源#

4.2 安装 ROS Melodic 完整版#

4.3 修复依赖冲突（已知问题）#

4.4 验证安装#

五、环境变量配置#

六、创建工作空间（可选）#

七、日常使用#

7.1 进入容器#

7.2 运行 ROS#

7.3 宿主机直接执行容器内命令#

7.4 导出应用到宿主机菜单（可选）#

7.5 停止/启动容器#

八、硬件/外设使用#

8.1 串口设备#

8.2 摄像头#

8.3 特殊设备（RealSense、CAN 等）#

九、常见问题速查#

十、为什么不用 rosdep？#

十一、数据备份#

一、宿主机准备（Ubuntu 26.04）

1.1 确认系统版本

1.2 设置华为 Ubuntu 镜像源

1.3 安装 Podman + Distrobox

1.4 用户组配置（串口/摄像头权限）

二、创建 Ubuntu 18.04 容器

2.1 拉取 Ubuntu 18.04 镜像

2.2 创建 Distrobox 容器

2.3 首次进入容器（关键！等待初始化完成）

三、容器内环境配置

3.1 设置华为 Ubuntu 镜像源

3.2 安装基础工具

四、安装 ROS Melodic（只用 apt，不用 rosdep）

4.1 添加华为 ROS 镜像源

4.2 安装 ROS Melodic 完整版

4.3 修复依赖冲突（已知问题）

4.4 验证安装

五、环境变量配置

六、创建工作空间（可选）

七、日常使用

7.1 进入容器

7.2 运行 ROS

7.3 宿主机直接执行容器内命令

7.4 导出应用到宿主机菜单（可选）

7.5 停止/启动容器

八、硬件/外设使用

8.1 串口设备

8.2 摄像头

8.3 特殊设备（RealSense、CAN 等）

九、常见问题速查

十、为什么不用 rosdep？

十一、数据备份