arm32v7/ros 镜像文档

注意： 这是 ros 官方镜像 的 arm32v7 架构构建的 "per-architecture" 仓库——更多信息，请参见官方镜像文档中的 "除 amd64 之外的架构？" 和官方镜像常见问题中的 "镜像源在 Git 中已更改，现在该怎么办？"。

快速参考

• 维护者：
  开源机器人基金会

• 获取帮助：
  Docker 社区 Slack、Server Fault、Unix & Linux 或 Stack Overflow

支持的标签及对应的 Dockerfile 链接

警告： 此镜像在 arm32v7 架构上不受支持

快速参考（续）

• 问题反馈地址：
  [***]

• 支持的架构： (更多信息)
  amd64、arm64v8

• 已发布镜像制品详情：
  repo-info 仓库的 repos/ros/ 目录 (历史记录)
  （镜像元数据、传输大小等）

• 镜像更新：
  official-images 仓库的 library/ros 标签
  official-images 仓库的 library/ros 文件 (历史记录)

• 本描述的来源：
  docs 仓库的 ros/ 目录 (历史记录)

什么是 ROS？

机器人操作系统（ROS）是一组帮助构建机器人应用程序的软件库和工具。从驱动程序到最先进的算法，再到强大的开发工具，ROS 为您的下一个机器人项目提供所需的一切。且全部开源。

***.org/wiki/Robot_Operating_System

![logo]([***]

如何使用此镜像

创建安装 ROS 包的 Dockerfile

要创建自己的 ROS 镜像并安装自定义包，以下是一个简单示例：通过 apt-get 使用官方发布的 Debian 包安装 C++、Python 客户端库演示程序。

FROM arm32v7/ros:rolling-ros-core as aptgetter

# 安装 ROS 包
RUN apt-get update && apt-get install -y \
      ros-${ROS_DISTRO}-demo-nodes-cpp \
      ros-${ROS_DISTRO}-demo-nodes-py && \
    rm -rf /var/lib/apt/lists/*

# 启动 ROS 包
CMD ["ros2", "launch", "demo_nodes_cpp", "talker_listener_launch.py"]

注意：所有 ROS 镜像都包含默认的入口点，在执行配置的命令之前会先加载 ROS 环境设置，此处为演示包的启动文件。然后可以像这样构建和运行 Docker 镜像：

$ docker build -t my/ros:aptgetter .
$ docker run -it --rm my/ros:aptgetter
[INFO] [launch]: process[talker-1]: started with pid [813]
[INFO] [launch]: process[listener-2]: started with pid [814]
[INFO] [talker]: Publishing: 'Hello World: 1'
[INFO] [listener]: I heard: [Hello World: 1]
[INFO] [talker]: Publishing: 'Hello World: 2'
[INFO] [listener]: I heard: [Hello World: 2]
...

创建构建 ROS 包的 Dockerfile

要创建自己的 ROS 镜像并构建自定义包，以下是一个简单示例：安装包的构建依赖项，从源代码编译，并将生成的构建产物安装到最终的多阶段镜像层。

ARG FROM_IMAGE=arm32v7/ros:rolling
ARG OVERLAY_WS=/opt/ros/overlay_ws

# 多阶段缓存
FROM $FROM_IMAGE AS cacher
ARG OVERLAY_WS

# 覆盖默认值以持久化最小缓存
RUN rosdep update --rosdistro $ROS_DISTRO && \
    cat <<EOF > /etc/apt/apt.conf.d/docker-clean && apt-get update
APT::Install-Recommends "false";
APT::Install-Suggests "false";
EOF

# 克隆覆盖层源代码
WORKDIR $OVERLAY_WS/src
RUN cat <<EOF | vcs import .
repositories:
  ros2/demos:
    type: git
    url: [***]
    version: ${ROS_DISTRO}
EOF

# 推导构建/执行依赖项
RUN bash -e <<'EOF'
declare -A types=(
  [exec]="--dependency-types=exec"
  [build]="")
for type in "${!types[@]}"; do
  rosdep install -y \
    --from-paths \
      ros2/demos/demo_nodes_cpp \
      ros2/demos/demo_nodes_py \
    --ignore-src \
    --reinstall \
    --simulate \
    ${types[$type]} \
    | grep 'apt-get install' \
    | awk '{gsub(/'\''/,"",$4); print $4}' \
    | sort -u > /tmp/${type}_debs.txt
done
EOF

# 多阶段构建
FROM $FROM_IMAGE AS builder
ARG OVERLAY_WS

# 安装构建依赖项
COPY --from=cacher /tmp/build_debs.txt /tmp/build_debs.txt
RUN --mount=type=cache,target=/etc/apt/apt.conf.d,from=cacher,source=/etc/apt/apt.conf.d \
    --mount=type=cache,target=/var/lib/apt/lists,from=cacher,source=/var/lib/apt/lists \
    --mount=type=cache,target=/var/cache/apt,sharing=locked \
    < /tmp/build_debs.txt xargs apt-get install -y

# 构建覆盖层源代码
WORKDIR $OVERLAY_WS
COPY --from=cacher $OVERLAY_WS/src ./src
RUN . /opt/ros/$ROS_DISTRO/setup.sh && \
    colcon build \
      --packages-select \
        demo_nodes_cpp \
        demo_nodes_py \
      --mixin release

# 多阶段运行
FROM $FROM_IMAGE-ros-core AS runner
ARG OVERLAY_WS

# 安装执行依赖项
COPY --from=cacher /tmp/exec_debs.txt /tmp/exec_debs.txt
RUN --mount=type=cache,target=/etc/apt/apt.conf.d,from=cacher,source=/etc/apt/apt.conf.d \
    --mount=type=cache,target=/var/lib/apt/lists,from=cacher,source=/var/lib/apt/lists \
    --mount=type=cache,target=/var/cache/apt,sharing=locked \
    < /tmp/exec_debs.txt xargs apt-get install -y

# 设置覆盖层安装
ENV OVERLAY_WS=$OVERLAY_WS
COPY --from=builder $OVERLAY_WS/install $OVERLAY_WS/install
RUN sed --in-place --expression \
      '$isource "$OVERLAY_WS/install/setup.bash"' \
      /ros_entrypoint.sh

# 运行启动文件
CMD ["ros2", "launch", "demo_nodes_cpp", "talker_listener_launch.py"]

上面的示例包含三个连续阶段。cacher 阶段首先更新 apt 列表和 ROS 索引，使用 vcstool 将演示仓库克隆到工作区源代码目录，并使用 rosdep 推导构建和运行时依赖集。builder 阶段安装推导的构建依赖项，加载 ROS 安装底层，并使用 colcon 以发布模式编译源代码。最后，runner 阶段仅安装运行时依赖项，复制编译后的工作区产物，并设置环境以启动演示。注意该示例包含几个细微的优化：

• 多阶段构建

  • 依赖项推导、编译和运行时设置分区
  • 最大化缓存保留，不受包源代码或构建/运行时变化影响
  • 更高并发性，例如 colcon 构建与运行时 apt 安装并行

• 持久缓存传播

  • 使用 --mount 缓存临时数据而不膨胀层
  • 保持并行阶段之间 apt 列表的时间一致性
  • 避免阶段之间或 Docker 重建时不必要的网络 I/O

• 最小镜像大小

  • 最终阶段基于 ros-core 构建，以获得最小运行时镜像
  • 仅构建和安装工作区中的少数选定包
  • 仅将工作区安装产物复制到最终层

作为比较，生成的 runner 镜像大小与前面的 aptgetter 示例相似。这允许您开发和分发自定义 ROS 包，而不会比预构建的 Debian 安装显著增加镜像大小：

$ docker image ls my/ros --format "table {{.Tag}}\t{{.Size}}"
TAG                SIZE
aptgetter          504MB
runner             510MB
builder            941MB
$ docker image ls ros --format "table {{.Tag}}\t{{.Size}}"
TAG                SIZE
rolling-ros-core   489MB
rolling            876MB

有关更高级的示例，例如通过链接多个覆盖工作区来改进 Docker 镜像构建层的缓存、使用 ccache 加速 colcon 编译、或使用 buildkit 在依赖项更改时节省构建时间和带宽，Navigation2 仓库中的项目 Dockerfile 是很好的参考资源。

部署用例

此 ROS 容器化镜像旨在提供一个简化且一致的平台，用于构建和部署分布式机器人应用程序。基于 官方 Ubuntu 镜像 和 ROS 官方 Debian 包构建，包含最新支持的版本，便于快速访问和下载。这为研究和工业领域的机器人专家提供了一种简单的方式来开发、重用和交付用于自主行动与任务规划、控制动力学、定位与地图构建、群体行为以及一般系统集成的软件。

使用新发布算法的前沿实现开发此类复杂系统仍然具有挑战性，因为在创新竞赛中，机器人软件的可重复性和可再现性可能被忽视。加上跨多个工程学科编写、调优和部署多个软件组件的难度，协作方法变得更具吸引力。然而，在多个机器人和平台上共享和维护软件集合的技术困难，长期以来超出了许多小型实验室和企业的时间和精力承受范围。

随着软件容器的发展和标准化，机器人专家已准备好获得一系列改进的开发工具，用于构建和交付软件。为帮助缓解采用新实践的成长痛苦和技术挑战，我们专注于提供将 ROS 与这些新技术结合使用的官方资源。

有关每个 ROS 发行版支持的架构和基础镜像的完整列表，请阅读关于目标平台的官方 REP 此处。

部署建议

可用标签包括支持的发行版以及基于最常见元包依赖项的层次结构标签，旨在具有小 footprint 和简单配置：

• ros-core：最小 ROS 安装
• ros-base：基本工具和库（也使用发行版名称标记，LTS 版本为 latest）

为保持 ros-core 标签的镜像大小最小，rosdep、colcon 和 vcstools 等开发工具未包含在 ros_core 中，而是包含在 ros-base 中。

其他常见元包（如 desktop）托管在 OSRF 的 Docker Hub 个人资料下的仓库中 此处。这些元包包含图形依赖项，并关联许多其他大型包（如 X11、X server 等）。因此，为保持官方镜像精简和安全，桌面包仅托管在 OSRF 的个人资料中。

卷

ROS 使用 ~/.ros/ 目录存储日志和调试信息。如果希望这些文件的生命周期超出生成它们的容器，可以将 ~/.ros/ 文件夹挂载到主机上的外部卷，或者派生镜像可以指定由 Docker 引擎管理的卷。默认情况下，容器以 root 用户运行，因此 /root/.ros/ 是这些文件的完整路径。

例如，如果希望使用本地主目录中已存在的 .ros 文件夹（用户名为 ubuntu），只需使用额外的卷参数启动容器：

$ docker run -v "/home/ubuntu/.ros/:/root/.ros/" arm32v7/ros

设备

某些应用可能需要设备访问，例如从连接的相机获取图像、从人机接口设备获取控制输入，或用于硬件加速的 GPU。这可以使用 --device 运行参数将设备挂载到容器内，为内部进程提供硬件访问。

网络

ROS 允许通过 ROS 通信基础设施松散耦合的进程（可能分布在多台机器上）进行点对点网络通信。ROS 实现了多种通信方式，包括通过服务的同步 RPC 式通信、通过主题的异步类型化数据流、通过动作的请求/回复与状态/反馈组合，以及通过参数的运行时配置。为遵守 每个容器一个进程 的最佳实践，可以使用 Docker 网络将多个运行的 ROS 进程连接起来。详情见下文部署示例。

或者，可以使用更宽松的网络设置，如 host 网络驱动，将所有主机网络接口共享给容器，简化与外部网络参与者的连接。但请注意，这会移除容器之间的网络命名空间隔离，并可能影响 DDS 参与者在容器之间的通信能力，如 此处 所述。

部署示例

Docker Compose

在此示例中，我们将演示使用 docker compose 在共享的软件定义网络中生成一对消息发布者和订阅者节点，分别位于不同的容器中。

创建目录 ~/ros_demos 并添加上面的第一个 Dockerfile 示例。在同一目录中，创建文件 compose.yaml，内容如下，运行 C++ 发布者和 Python 订阅者：

services:
  talker:
    build: ./
    command: ros2 run demo_nodes_cpp talker

  listener:
    build: ./
    environment:
      - "PYTHONUNBUFFERED=1"
    command: ros2 run demo_nodes_py listener

在同一目录中使用 docker compose 启动 ROS 节点。由于创建的容器源自同一个 docker compose 项目，它们将共存于共享的项目网络中：

$ docker compose up -d

注意已创建名为 ros_demos_default 的新网络，可通过以下命令进一步查看：

$ docker network inspect ros_demos_default

可以监控每个容器的日志输出，例如查看 listener 节点：

$ docker compose logs listener

最后，可以从同一目录使用 docker compose 停止并删除所有相关容器：

$ docker compose stop
$ docker compose rm

注意：自动生成的网络 ros_demos_default 将一直存在，直到使用 docker compose down 显式删除。

更多资源

文档：ROS 开发者文档
问答：提问并获取答案
论坛：了解最新讨论
包：发现索引包
[OSRF](