ROS1 Docker 环境管理工具集

一套用于管理ROS1 Noetic Docker开发环境的完整脚本工具集。支持容器创建、启动、备份、迁移和镜像导入导出等全生命周期管理。

📋 目录

• 项目结构
• 功能特性
• 快速开始
• 脚本说明
• 配置说明
• 使用示例
• 常见问题
• 注意事项

📁 项目结构

docker_env/
├── ⭐ config.sh              # 核心配置文件（只需修改这个！）
├── start_docker.sh           # 创建并启动新容器
├── exec_docker.sh            # 启动并进入已有容器
├── stop_docker.sh            # 停止运行中的容器
├── backup_docker.sh          # 备份容器为镜像并迁移
├── docker_save.sh            # 导出镜像为压缩文件
├── docker_load.sh            # 从文件加载镜像
├── install_docker_env.sh     # 配置Docker环境
├── README.md                 # 完整使用文档（本文件）
└── QUICK_START.md            # 快速参考指南

⭐ 重要：所有配置统一在 config.sh 中管理，修改配置只需编辑这一个文件！

✨ 功能特性

• ✅ 完整的GUI支持：支持rviz、gazebo等图形界面工具
• ✅ GPU硬件加速：支持Intel/AMD GPU渲染加速
• ✅ ROS网络通信：使用host网络模式，完美支持ROS节点通信
• ✅ 权限管理：避免容器内文件权限问题
• ✅ 镜像管理：支持镜像导出、导入、备份
• ✅ 容器迁移：支持容器状态保存和迁移
• ✅ 国内镜像加速：配置国内Docker镜像源，加快下载速度

🚀 快速开始

前置要求

• Linux操作系统（Ubuntu推荐）
• 已安装Docker（版本 >= 20.10）
• 已安装X11显示服务器

安装步骤

1. 克隆或下载本项目

   cd /home/realman/docker/docker_env

2. 添加执行权限

   chmod +x *.sh

3. 配置Docker环境（首次安装）

   ./install_docker_env.sh

   此脚本会：

   • 配置Docker镜像加速器
   • 重启Docker服务
   • 下载ROS Noetic基础镜像

4. 修改配置变量（重要）

   所有配置统一在 config.sh 文件中管理，编辑此文件即可修改所有脚本的配置：

   vi config.sh

   主要配置项：

   • 容器名称（CONTAINER_NAME）
   • 镜像名称和版本（IMAGE_NAME, IMAGE_TAG）
   • 工作目录映射路径（HOST_WORKSPACE）
   • GPU组ID（VIDEO_GID, RENDER_GID，使用getent group video和getent group render查看）

5. 启动容器

   ./start_docker.sh

📚 脚本说明

0. config.sh ⭐核心配置文件

功能：集中管理所有脚本的配置变量

重要性：⭐⭐⭐ 所有其他脚本都从这里读取配置

主要配置项：

# 镜像配置
IMAGE_NAME="ros1_noetic_dev"             # Docker镜像名称
IMAGE_TAG="2026-02-02"                   # Docker镜像版本

# 容器配置
CONTAINER_NAME="ros1_test2"              # 当前容器名称
OLD_CONTAINER_NAME="ros1_test"           # 旧容器名称（备份用）

# 目录映射
HOST_WORKSPACE="/home/realman/workspace" # 宿主机工作目录
CONTAINER_WORKSPACE="/workspace"         # 容器内工作目录

# GPU支持
VIDEO_GID=44                             # video组GID
RENDER_GID=110                           # render组GID

查看当前配置：

./config.sh
# 或
source config.sh && check_config

1. install_docker_env.sh

功能：初始化Docker环境，配置镜像加速器并下载ROS镜像

使用场景：

• 新机器首次配置
• 重新配置Docker加速器
• 下载或更新ROS镜像

配置来源：使用config.sh中的BASE_IMAGE_NAME和DOCKER_MIRROR_*

2. start_docker.sh

功能：创建并启动新的ROS Docker容器

使用场景：

• 首次创建容器
• 创建新的开发环境

配置来源：从config.sh读取所有配置 CONTAINER_WORKSPACE="/workspace" # 容器内工作目录 VIDEO_GID=44 # video组GID RENDER_GID=110 # render组GID

**重要说明**：
- 运行前需查看系统的video和render组ID：
  ```bash
  getent group video    # 输出如：video:x:44:...
  getent group render   # 输出如：render:x:110:...

• 将输出中的GID（冒号后的数字）更新到config.sh中

3. exec_docker.sh

功能：启动并进入已存在的容器

使用场景：

• 日常开发，进入已创建的容器
• 容器停止后重新启动

配置来源：从config.sh读取CONTAINER_NAME

4. stop_docker.sh

功能：停止运行中的容器

使用场景：

• 临时停止容器但保留数据
• 系统维护前停止容器

配置来源：从config.sh读取CONTAINER_NAME

5. backup_docker.sh

功能：备份当前容器为镜像并创建新容器

使用场景：

• 容器版本升级
• 容器重命名/迁移
• 重要修改前备份

配置来源：从config.sh读取OLD_CONTAINER_NAME、BACKUP_IMAGE_NAME等

6. docker_save.sh

功能：将Docker镜像导出为压缩文件

使用场景：

• 镜像离线备份
• 跨机器部署
• 创建安装包

配置来源：从config.sh读取IMAGE_NAME、IMAGE_TAG、SAVE_OUTPUT_DIR等

输出：生成 镜像名_版本.tar.gz 文件

7. docker_load.sh

功能：从压缩文件加载Docker镜像

使用场景：

• 导入备份的镜像
• 离线环境部署
• 从其他机器迁移镜像

配置来源：从config.sh读取IMAGE_NAME、IMAGE_TAG、LOAD_IMAGE_DIR

⚙️ 配置说明

统一配置管理 - config.sh

所有配置都集中在 config.sh 文件中，这是项目的核心配置文件。

修改配置的步骤：

1. 编辑 config.sh 文件
2. 修改需要的变量
3. 保存文件
4. 运行任何脚本时会自动使用新配置

优点：

• ✅ 只需编辑一个文件
• ✅ 所有脚本配置保持一致
• ✅ 避免配置不同步的问题
• ✅ 便于版本控制

查看当前配置：

./config.sh
# 或
source config.sh && check_config

工作目录映射

容器会将宿主机目录映射到容器内：

• 宿主机路径：/home/realman/workspace
• 容器内路径：/workspace
• 映射特性：双向同步，容器内外修改实时可见

GPU支持配置

容器支持Intel/AMD GPU硬件加速：

1. 查看系统组ID：

   getent group video    # 查看video组ID
   getent group render   # 查看render组ID

2. 更新配置： 将查到的ID更新到 config.sh 中的VIDEO_GID和RENDER_GID

   vi config.sh
   # 修改 VIDEO_GID 和 RENDER_GID 的值

📖 使用示例

示例1：首次创建容器

# 1. 配置Docker环境（仅首次需要）
./install_docker_env.sh

# 2. 编辑config.sh，修改配置变量
vi config.sh
# 重点检查：
# - CONTAINER_NAME（容器名称）
# - HOST_WORKSPACE（工作目录）
# - VIDEO_GID 和 RENDER_GID（GPU组ID）

# 3. 创建并启动容器
./start_docker.sh

# 4. 容器内配置ROS环境（仅首次需要）
mkdir -p /workspace
touch /workspace/.bashrc
echo "source /opt/ros/noetic/setup.bash" >> /workspace/.bashrc

示例2：日常使用

# 启动并进入容器
./exec_docker.sh

# 在容器内工作...

# 退出容器
exit

# 停止容器
./stop_docker.sh

示例3：容器备份与迁移

# 1. 备份当前容器为新镜像
./backup_docker.sh

# 2. 将镜像导出为文件
./docker_save.sh

# 3. 将文件传输到目标机器
scp ros1_noetic_dev_2026-01-21.tar.gz user@target:/tmp/

# 4. 在目标机器上加载镜像
./docker_load.sh

# 5. 创建容器
./start_docker.sh

示例4：容器内ROS开发

# 进入容器
./exec_docker.sh

# 在容器内
cd /workspace

# 创建catkin工作空间
mkdir -p catkin_ws/src
cd catkin_ws
catkin_make

# 设置环境变量
source devel/setup.bash
echo "source /workspace/catkin_ws/devel/setup.bash" >> ~/.bashrc

# 启动ROS
roscore

# 测试GUI（新终端）
rviz

❓ 常见问题

Q1: GUI程序无法显示

原因：X11权限问题

解决：

# 在宿主机执行
xhost +local:docker

# 或在脚本中已自动执行

Q2: 容器内文件权限错误

原因：UID/GID不匹配

解决：脚本已通过-u $(id -u):$(id -g)参数解决，无需额外配置

Q3: ROS节点无法通信

原因：网络配置问题

解决：脚本已使用--network host，确保容器使用宿主机网络

Q4: GPU加速不工作

原因：组ID配置错误

解决：

# 查看正确的组ID
getent group video
getent group render

# 更新脚本中的VIDEO_GID和RENDER_GID

Q5: 镜像下载缓慢

原因：未配置镜像加速器

解决：运行./install_docker_env.sh配置国内镜像源

Q6: 容器已存在无法创建

错误：The container name "/ros1_test2" is already in use

解决：

# 方案1：使用已有容器
./exec_docker.sh

# 方案2：删除旧容器
docker rm ros1_test2
./start_docker.sh

# 方案3：修改容器名称
# 编辑start_docker.sh中的CONTAINER_NAME

⚠️ 注意事项

数据安全

1. 持久化数据：

   • 容器内/workspace目录的数据保存在宿主机
   • 容器删除不影响工作目录数据
   • 建议将重要代码放在/workspace下

2. 容器数据：

   • 容器内其他目录的数据在容器删除后会丢失
   • 重要修改（如软件安装）应通过backup_docker.sh备份

性能优化

1. 镜像大小：

   • 定期清理不用的镜像：docker image prune
   • 使用压缩级别1-2导出镜像，平衡速度和大小

2. 容器性能：

   • 使用host网络模式确保最佳网络性能
   • GPU加速需正确配置组权限

安全建议

1. 用户权限：

   • 容器默认使用当前用户权限运行
   • 如需root权限：docker exec -it -u 0 容器名 bash

2. 网络安全：

   • host网络模式会暴露所有端口
   • 生产环境建议使用桥接网络

版本管理

1. 镜像版本：

   • 使用日期作为标签便于管理
   • 重要版本应导出备份

2. 脚本版本：

   • 建议使用Git管理脚本
   • 修改前先备份配置

� 参考链接

• ROS Noetic官方文档
• Docker官方文档
• Docker Hub ROS镜像

📄 许可证

MIT License - 详见LICENSE文件

🤝 贡献

欢迎提交Issue和Pull Request！

---

维护者: realman-luca
最后更新: 2026-02-02