ROS2_learn/doc/85-docker.md

85 · Docker 容器化开发(完全指南)

目标:吃透本仓库 Docker 配置,知道每行在做什么,能改能扩,能在 Win/macOS/Linux 一致跑 ROS2。

---

目录

• 1. 为什么用 Docker
• 2. 镜像构建
• 3. 容器编排
• 4. 容器生命周期命令
• 5. 一键启动脚本
• 6. 调试技巧
• 7. 常见坑
• 8. 多机 / 多机器人扩展
• 9. 在本仓库里跑
• 10. 进阶:多阶段构建 + 镜像瘦身

---

1. 为什么用 Docker

痛点	Docker 怎么解
Linux/Windows/macOS 行为差异	镜像固定 Linux,行为一致
ROS2 apt 装一堆,污染系统	容器内隔离
团队协作"在我机器能跑"	镜像统一
升级 ROS 版本代价大	换镜像就行
跨语言/多版本测试	同一镜像多容器

本仓库基于 osrf/ros:humble-desktop(OSRF 官方维护):

• ROS2 Humble 完整运行时
• 默认 RMW: rmw_fastrtps_cpp
• 自带 RViz2 / rqt / colcon / rosdep

---

2. 镜像构建

2.1 Dockerfile

docker/Dockerfile 在 osrf/ros:humble-desktop 之上加:

FROM osrf/ros:humble-desktop

ENV DEBIAN_FRONTEND=noninteractive
ENV ROS_DISTRO=humble
ENV WORKSPACE=/root/ros2_ws

RUN apt-get update && apt-get install -y \
    python3-colcon-common-extensions \
    python3-pip \
    nano \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install -U colcon-argcomplete colcon-common-extensions

RUN echo 'source /opt/ros/humble/setup.bash' >> /root/.bashrc && \
    echo 'source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash' >> /root/.bashrc

WORKDIR ${WORKSPACE}

CMD ["bash"]

2.2 构建

# Windows
docker compose -f D:\xs\ros2\docker\docker-compose.yml build

# Linux
docker compose -f docker/docker-compose.yml build

镜像名:ros2-humble-dev:latest,约 3GB。

2.3 镜像内已装

• ROS2 Humble Desktop
• colcon-common-extensions + colcon-argcomplete
• cv_bridge (openCV ↔ ROS Image)
• ros-humble-tf2-tools (view_frames)
• ros-humble-robot-state-publisher (URDF → TF)

未装(按需补):

• ros-humble-rmw-cyclonedds-cpp(默认 fastdds 够用)
• ros-humble-ros2-control
• ros-humble-moveit
• ros-humble-navigation2

2.4 修改镜像(自定义)

加包:在 apt-get install 加一行:

RUN apt-get install -y ros-humble-ros2-control ros-humble-ros2-controllers

加 Python 包:

RUN pip3 install ultralytics==8.0.0 numpy==1.26

---

3. 容器编排

3.1 docker-compose.yml

docker/docker-compose.yml:

services:
  ros2:
    build: .
    image: ros2-humble-dev:latest
    container_name: ros2_dev

    privileged: true       # 调试用
    stdin_open: true       # docker exec -it
    tty: true

    network_mode: host     # DDS multicast 必须

    environment:
      - ROS_DOMAIN_ID=0
      # 不要设 RMW_IMPLEMENTATION=rmw_cyclonedds_cpp:
      # 镜像没装 cyclone dds,CMake 配置会失败。

    volumes:
      - ..:/root/ros2_ws    # bind mount 本机 D:\xs\ros2

    working_dir: /root/ros2_ws

    command: ["bash", "-lc", "tail -f /dev/null"]   # 容器永不退

3.2 为什么 host network

ROS2 默认用 DDS multicast 在同一网段自动发现节点。多容器或跨主机时,bridge 网络 会拦截 multicast,导致节点看不见彼此。

network_mode: host 让容器用宿主机的网络栈,直接走 multicast。

3.3 为什么 bind mount 整个工程

.. 是 docker-compose.yml 的上一级(D:\xs\ros2)。挂到容器内 /root/ros2_ws,你在 Windows 改代码,容器内 colcon 立即看到(--symlink-install)。

---

4. 容器生命周期命令

# 构建镜像
docker compose -f D:\xs\ros2\docker\docker-compose.yml build

# 启动(后台)
docker compose -f D:\xs\ros2\docker\docker-compose.yml up -d

# 状态
docker compose -f D:\xs\ros2\docker\docker-compose.yml ps

# 进开发终端
docker exec -it ros2_dev bash -lc "source /root/ros2_ws/install/setup.bash && exec bash"

# 一次性跑命令
docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon build --packages-select py_pubsub"

# 关
docker compose -f D:\xs\ros2\docker\docker-compose.yml down

# 重启
docker compose -f D:\xs\ros2\docker\docker-compose.yml restart

# 删容器(保留镜像)
docker compose -f D:\xs\ros2\docker\docker-compose.yml down

# 删镜像
docker rmi ros2-humble-dev:latest

# 看日志
docker logs -f ros2_dev

---

5. 一键启动脚本

5.1 start.ps1 (Windows)

powershell D:\xs\ros2\start.ps1

等价于:

docker compose build     # 首次 5-10min
docker compose up -d
docker exec ros2_dev bash -lc "cd /root/ros2_ws && bash build.sh"
docker exec -it ros2_dev bash -lc "source install/setup.bash && exec bash"

5.2 start.sh (Linux/macOS)

./start.sh

5.3 build.sh (容器内)

bash build.sh
# 1) source /opt/ros/humble/setup.bash
# 2) colcon build --symlink-install --packages-select <all>
# 3) ls install/
# 4) 打印运行命令速查

---

6. 调试技巧

6.1 看容器日志

docker logs ros2_dev
docker logs -f ros2_dev       # 持续

6.2 进容器交互 shell

docker exec -it ros2_dev bash
# 进入后:
source /opt/ros/humble/setup.bash
cd /root/ros2_ws
source install/setup.bash

6.3 在容器内单次跑命令

docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && ros2 node list"

6.4 看 DDS 流量

docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && ros2 doctor --report"

6.5 看网络

docker exec ros2_dev bash -lc "ip addr; ip route"

6.6 容器与宿主机共享 GPU(可选)

services:
  ros2:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

---

7. 常见坑

7.1 容器启动后找不到 ros2 命令

容器里 /opt/ros/humble/setup.bash 没 source。每个 shell 都要 source, 或者写进 ~/.bashrc(已加,新 bash 自动 source)。

7.2 改了源码但 colcon 看不到

确认 --symlink-install(默认配置里加上了)。否则需要重 build。

7.3 跨容器看不到节点

• 同一 ROS Domain(ROS_DOMAIN_ID)
• host network(本仓库用了)
• multicast 没被拦截

7.4 Windows bind mount 文件锁

有时 LSP / IDE 持文件锁,导致容器内 colcon 失败。关掉 IDE 或在容器内编辑。

7.5 容器启动很慢

• Docker Desktop 未运行
• WSL2 后端未启用
• 镜像太大(本仓库 ~3GB 正常)

7.6 容器 OOM

Docker Desktop → Settings → Resources → Memory 调到 ≥ 4GB。

---

8. 多机 / 多机器人扩展

# docker-compose.yml 改成:
services:
  robot1:
    image: ros2-humble-dev:latest
    container_name: ros2_robot1
    network_mode: host
    environment:
      - ROS_DOMAIN_ID=42
      - ROS_NAMESPACE=robot1
    volumes:
      - ./robot1_conf:/root/ros2_ws

  robot2:
    image: ros2-humble-dev:latest
    container_name: ros2_robot2
    network_mode: host
    environment:
      - ROS_DOMAIN_ID=42
      - ROS_NAMESPACE=robot2
    volumes:
      - ./robot2_conf:/root/ros2_ws

  central:
    image: ros2-humble-dev:latest
    container_name: ros2_central
    network_mode: host
    environment:
      - ROS_DOMAIN_ID=42
    command: ["bash", "-lc", "ros2 launch bringup multi_robot_launch.py"]

每个 container 各跑一组节点,ROS_NAMESPACE 隔离命名空间, ROS_DOMAIN_ID 共享同一总线 → 跨容器通讯。

详见 doc/100-embedded-deployment.md。

---

9. 在本仓库里跑

9.1 一键启

powershell D:\xs\ros2\start.ps1

9.2 进入后跑测试

docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && cd /root/ros2_ws && colcon test --packages-select py_pubsub cpp_pubsub py_srv py_action_demo cpp_robot_tf2 py_vision_demo bringup"

9.3 跑 demo

docker exec ros2_dev bash -lc "source /root/ros2_ws/install/setup.bash && ros2 launch bringup full_demo_launch.py"

---

10. 进阶:多阶段构建 + 镜像瘦身

10.1 当前镜像大小

docker images ros2-humble-dev
# SIZE: 3.4GB

来源:

• osrf/ros:humble-desktop: ~2.1GB(包含 RViz / rqt / Gazebo)
• 我们的 apt 包 + colcon: ~1.3GB

10.2 改用 osrf/ros:humble-ros-base

基础镜像改成 humble-ros-base(无 RViz / rqt):

FROM osrf/ros:humble-ros-base

SIZE 减少 ~1.5GB。但少了 RViz / rqt / Gazebo,如果需要这些再加 apt。

10.3 多阶段构建(进一步瘦身)

# Stage 1: build
FROM osrf/ros:humble-ros-base AS builder
# ... 装 build 工具,build 我们的包 ...

# Stage 2: runtime
FROM osrf/ros:humble-ros-base
COPY --from=builder /root/ros2_ws/install /root/ros2_ws/install
# 不带 build 工具,更小

适合 CI 流水线 + 生产环境。

---

接下来读

主题	文档
venv 工作流	02-virtualenv.md
测试策略	90-testing.md
三机部署	100-embedded-deployment.md
项目总览	00-overview.md