4、编写ROS2 Dockerfile：从基础镜像选择、ROS2安装、依赖安装到环境变量设置的最佳实践

Dockerfile 是构建 ROS2 容器镜像的“施工图纸”，它决定了镜像的体积、构建速度、运行时稳定性以及后续维护的难易程度。在机器人部署场景中，一个设计良好的 Dockerfile 不仅要能成功安装 ROS2，还要兼顾开发调试与生产部署的双重需求。本章将围绕基础镜像选型、ROS2 安装策略、依赖分层缓存、用户与权限处理、环境变量注入等核心环节，给出可落地的工程化实践。

4.1 基础镜像选择：平衡体积、兼容性与维护成本

核心原理：ROS2 对操作系统版本有严格绑定关系，例如 ROS2 Humble 对应 Ubuntu 22.04，ROS2 Jazzy 对应 Ubuntu 24.04。基础镜像的选择直接决定了底层 ABI 兼容性、GLIBC 版本、CUDA/OpenGL 等硬件加速库的可用性。官方 ros 镜像虽然开箱即用，但体积通常超过 2GB，且包含大量桌面工具，不适合部署到资源受限的机器人主控板。

判断方法：按部署目标选择基础镜像策略：

• 开发调试环境：直接使用 ros:jazzy-ros-base-jammy 或 ros:humble-ros-base-focal，减少环境搭建时间。
• 生产部署环境：以 ubuntu:22.04 为底，手动安装 ROS2 核心包，裁剪 GUI 依赖。
• 硬件加速场景：选择 nvidia/cuda:12.1.0-runtime-ubuntu22.04 作为基础镜像，再叠加 ROS2。

4.2 ROS2 安装与依赖分层：构建缓存与可维护性

核心原理：Docker 的层缓存机制决定了 Dockerfile 中指令的顺序直接影响构建效率。将变化频率低的依赖放在前面，变化频繁的工作区代码放在最后，可以最大化利用缓存。ROS2 安装通常涉及 apt 源配置、系统依赖安装、Python 包安装、工作区源码拷贝与编译四个阶段。

操作流程：推荐的分层 Dockerfile 结构如下：

# 阶段1：基础系统 + ROS2 核心
FROM ubuntu:22.04 AS ros2-base
ENV DEBIAN_FRONTEND=noninteractive

# 配置 ROS2 apt 源
RUN apt-get update && apt-get install -y \
    curl gnupg lsb-release \
    && curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
    -o /usr/share/keyrings/ros-archive-keyring.gpg \
    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" \
    > /etc/apt/sources.list.d/ros2.list

# 安装 ROS2 核心（利用缓存）
RUN apt-get update && apt-get install -y \
    ros-humble-ros-base \
    python3-colcon-common-extensions \
    python3-rosdep \
    && rm -rf /var/lib/apt/lists/*

# 阶段2：项目依赖
FROM ros2-base AS project-deps
# 安装项目特定系统依赖
RUN apt-get update && apt-get install -y \
    libserial-dev \
    libusb-1.0-0-dev \
    && rm -rf /var/lib/apt/lists/*

# 阶段3：工作区构建
FROM project-deps AS workspace
WORKDIR /ros2_ws
COPY src/ ./src/
RUN . /opt/ros/humble/setup.sh && \
    rosdep install --from-paths src --ignore-src -y && \
    colcon build --symlink-install

案例拆解：某移动机器人项目需要同时使用激光雷达驱动、IMU 驱动和导航栈。初始 Dockerfile 将所有依赖写在一个 RUN 指令中，每次修改源码后都需要重新下载所有 apt 包，构建时间长达 25 分钟。重构为上述分层结构后，apt 依赖层被缓存，仅源码变更时只需重新编译工作区，构建时间缩短至 6 分钟。关键改进点在于：

1. 将 rosdep install 与 colcon build 分离，避免每次源码变更都触发依赖解析。
2. 使用 --symlink-install 允许开发模式下无需重新构建即可生效 Python 代码变更。
3. 将 apt-get clean 与安装指令合并，减少镜像层数。

4.3 环境变量与用户权限：运行时一致性的关键

核心原理：ROS2 的运行时行为高度依赖环境变量，包括 ROS_DOMAIN_ID（用于多机通信隔离）、RMW_IMPLEMENTATION（选择中间件实现）、LD_LIBRARY_PATH（动态库搜索路径）以及 AMENT_PREFIX_PATH（功能包定位）。此外，容器内默认以 root 用户运行会导致生成的日志文件、rosbag 记录文件归属混乱，且存在安全风险。

操作流程：环境变量设置应遵循以下原则：

• 使用 ENV 设置固定值，如 ENV ROS_DOMAIN_ID=42。
• 使用 ARG 允许构建时传入可变值，如 ARG RMW_IMPLEMENTATION=rmw_fastrtps_cpp。
• 在 entrypoint.sh 中动态 source ROS2 环境，而非在 Dockerfile 中硬编码 source 路径。

# entrypoint.sh 示例
#!/bin/bash
set -e

# 加载 ROS2 环境
source /opt/ros/humble/setup.bash
source /ros2_ws/install/setup.bash

# 允许外部传入 ROS_DOMAIN_ID
if [ -n "$ROS_DOMAIN_ID" ]; then
    export ROS_DOMAIN_ID=$ROS_DOMAIN_ID
fi

# 执行用户命令
exec "$@"

用户权限处理：推荐在 Dockerfile 中创建非 root 用户，并使用 USER 指令切换：

RUN groupadd -r robot && useradd -r -g robot robot \
    && mkdir -p /home/robot && chown -R robot:robot /home/robot
USER robot
WORKDIR /home/robot

对于需要访问串口、USB 摄像头等设备的场景，需要在运行时通过 --device 参数映射设备，并在容器内将用户加入 dialout 组：

RUN usermod -aG dialout robot

4.4 镜像体积优化与多阶段构建

核心原理：机器人部署场景常面临存储空间限制，尤其是使用 SD 卡或 eMMC 的嵌入式平台。多阶段构建允许在构建阶段使用完整工具链，而最终运行镜像仅包含运行时所需文件。

操作流程：多阶段构建的关键在于区分“构建依赖”和“运行依赖”：

# 构建阶段
FROM ros2-base AS builder
WORKDIR /ros2_ws
COPY src/ ./src/
RUN . /opt/ros/humble/setup.sh && \
    colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

# 运行阶段
FROM ubuntu:22.04 AS runtime
# 仅安装运行时依赖
RUN apt-get update && apt-get install -y \
    libserial0 libusb-1.0-0 \
    && rm -rf /var/lib/apt/lists/*
# 从构建阶段拷贝编译产物
COPY --from=builder /ros2_ws/install/ /ros2_ws/install/
COPY --from=builder /opt/ros/humble/ /opt/ros/humble/
# 配置环境变量
ENV AMENT_PREFIX_PATH=/ros2_ws/install:/opt/ros/humble
ENV LD_LIBRARY_PATH=/ros2_ws/install/lib:/opt/ros/humble/lib

案例拆解：某视觉导航机器人项目，初始镜像体积为 3.2GB。通过多阶段构建，将编译工具链（gcc、cmake、colcon）留在构建阶段，运行镜像仅保留动态库和 Python 包，最终体积降至 1.1GB。同时，使用 --no-install-recommends 避免安装不必要的推荐包，并清理 /var/lib/apt/lists 缓存，进一步节省约 200MB 空间。

4.5 启动脚本与 CMD/ENTRYPOINT 设计

核心原理：容器启动时，ENTRYPOINT 定义固定入口，CMD 提供默认参数。对于 ROS2 应用，推荐将 entrypoint.sh 作为 ENTRYPOINT，负责 source 环境，而 CMD 指定实际启动的 ROS2 节点或 launch 文件。这样既保证了环境加载，又允许运行时通过 docker run 覆盖启动命令。

操作流程：标准启动脚本设计如下：

#!/bin/bash
set -e
source /opt/ros/humble/setup.bash
source /ros2_ws/install/setup.bash
exec "$@"

Dockerfile 中设置：

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["ros2", "launch", "my_robot_bringup", "robot.launch.py"]

常见误区：直接在 Dockerfile 中使用 RUN source /opt/ros/humble/setup.bash 是无效的，因为每个 RUN 指令都在新的 shell 中执行，环境变量不会持久化。正确做法是使用 ENV 显式设置关键变量，或在 ENTRYPOINT 中动态 source。

总结复盘：编写 ROS2 Dockerfile 的核心原则可归纳为：

1. 基础镜像选型：优先 ubuntu LTS + 官方 apt 源，按需叠加 CUDA 等专用镜像。
2. 分层缓存：将系统依赖、ROS2 核心、项目依赖、工作区代码按变更频率从低到高排列。
3. 环境变量：使用 ENV 设置固定值，ARG 支持构建时参数，运行时通过 -e 覆盖。
4. 用户权限：创建非 root 用户，加入 dialout 组以访问串口设备。
5. 体积控制：多阶段构建 + 清理 apt 缓存 + 裁剪无用包。
6. 启动设计：ENTRYPOINT 负责环境加载，CMD 定义默认启动命令，保持灵活性。