主题模式
环境、容器与地面站
本页对应原始操作手册第 4～8 章，依次完成 Docker 镜像检查、宿主机 X11 授权、项目容器启动、ROS 2 工作空间编译以及 AISWARMLAB 地面站 UI 启动。
除特别标注为“容器内执行”的命令外，本页其他命令均在 Ubuntu 22.04 宿主机的桌面终端中执行。
1. 准备 Docker 镜像
1.1 进入项目根目录
本文使用 <AISWARMLAB_ROOT> 表示 AISWARMLAB 仓库根目录。实际路径应根据宿主机用户名和项目存放位置确定，例如：
bash
cd /home/user_name/aiswarmlab/aiswarmlab执行前请将 user_name 替换为实际用户名。后文出现 <AISWARMLAB_ROOT> 时，也应替换为该项目根目录的真实绝对路径。
1.2 检查 Docker 与 Compose
bash
docker --version
docker compose version两个命令都应正常输出版本信息。
Docker 权限
如果出现权限错误，先确认当前用户是否属于 docker 用户组。不要在不了解影响的情况下随意修改 Docker 权限，也不要为了绕过问题而给无关目录添加宽泛权限。
1.3 加载项目镜像
假设收到的镜像文件名为 <镜像文件>.tar：
bash
docker load -i /path/to/<镜像文件>.tar加载完成后，检查项目要求的镜像标签：
bash
docker image inspect aiswarmlab_control:ros2_cmdvel_bridge_v2也可以查看所有相关镜像：
bash
docker images | grep aiswarmlab_control如果镜像已经存在，但标签不是 aiswarmlab_control:ros2_cmdvel_bridge_v2，根据实际镜像 ID 或已有名称补充标签：
bash
docker tag <镜像ID或已有镜像名:标签> aiswarmlab_control:ros2_cmdvel_bridge_v2成功判据： docker image inspect 能输出镜像的详细信息，而不是 No such image。
2. 配置宿主机图形显示
AISWARMLAB 地面站和 RViz 都是图形程序，Docker 容器需要访问宿主机的 X11 显示服务。
2.1 开放 X11 权限
在 Ubuntu 宿主机的桌面终端执行：
bash
xhost +local:docker2.2 检查 DISPLAY
bash
echo "$DISPLAY"正常情况下会输出 :0、:1 或类似值。如果结果为空，应在 Ubuntu 图形桌面会话的终端中执行本教程，而不是纯 SSH、TTY 或无桌面终端。
实验结束后收回权限
xhost +local:docker 会允许本机 Docker 容器访问 X Server。全部实验结束后运行以下命令收回权限：
bash
xhost -local:docker3. 启动并进入 Docker 容器
3.1 启动容器
仓库中的实际启动脚本是位于 sh 目录下的 start_swarm_control_srv.sh 文件，即：
text
sh/start_swarm_control_srv.sh可以在项目根目录执行：
bash
cd <AISWARMLAB_ROOT>
bash sh/start_swarm_control_srv.sh也可以先进入 sh 目录再运行：
bash
cd <AISWARMLAB_ROOT>/sh
bash start_swarm_control_srv.sh该脚本实际执行 docker compose up，使用的 Compose 文件为：
text
docker/service/swarm_control_service/docker-compose.yml当前 Compose 配置会：
- 使用镜像
aiswarmlab_control:ros2_cmdvel_bridge_v2； - 创建名为
aiswarmlab_vrpn的容器； - 使用宿主机网络和 IPC；
- 将宿主机
source/swarmlab_simulator_ws挂载到容器/home/linuxbrew/swarmlab_simulator_ws； - 挂载
/dev，使容器能够访问飞控串口等设备； - 挂载
/tmp/.X11-unix，使地面站和 RViz 能显示在宿主机桌面。
终端 A 不会进入容器
启动脚本会占用终端 A 并持续显示 Compose 日志，它本身不执行 docker exec。终端没有出现容器提示符属于正常现象。请保持终端 A 运行，另开终端进入容器。
3.2 检查容器状态
在另一个 Ubuntu 宿主机终端执行：
bash
docker ps --filter name=aiswarmlab_vrpn成功判据： 输出中容器 aiswarmlab_vrpn 的状态为 Up。
3.3 进入容器
bash
docker exec -it aiswarmlab_vrpn /bin/bash进入容器后，检查当前用户和挂载的工作空间：
bash
whoami
ls /home/linuxbrew/swarmlab_simulator_ws后续所有标注为“容器内执行”的命令，都应在通过 docker exec 打开的容器终端中运行。建议将该窗口作为终端 B。
4. 编译 ROS 2 工作空间
4.1 执行项目编译脚本
在终端 B 的容器内执行：
bash
source /opt/ros/humble/setup.bash
cd /home/linuxbrew/swarmlab_simulator_ws/sh
bash start_compliler.sh脚本名称说明
如下图所示，仓库中的实际脚本名称是 start_compliler.sh。虽然 compliler 疑似是开发人员将“编译”一词的英文拼错了，但执行命令时必须与仓库中的真实文件名完全一致，不要下意识改成 start_compiler.sh。
4.2 脚本都做了什么操作？
start_compliler.sh 会依次：
- 进入
src/fcu_core_ros2_ws； - 单独编译
quadrotor_msgs； - 加载 FCU 子工作空间环境，并完整编译 FCU 子工作空间；
- 返回
/home/linuxbrew/swarmlab_simulator_ws主工作空间； - 加载 FCU 子工作空间环境，并执行主工作空间的
colcon build。
首次编译可能需要较长时间。编译期间不要关闭终端，也不要在其他终端同时重复执行 colcon build。
4.3 编译后检查关键包
bash
cd /home/linuxbrew/swarmlab_simulator_ws
source /opt/ros/humble/setup.bash
source install/setup.bash
ros2 pkg prefix vrpn_client_ros
ros2 pkg prefix fcu_core
ros2 pkg prefix rviz2_custom_panel成功判据： 以上三个命令都能输出对应包的安装路径。
4.4 编译失败时检查
应查看终端中最先出现的 Failed 包，而不是只看最后一行。后续包的 Aborted 往往只是上游依赖失败的结果。
需要显示更完整的构建过程时执行：
bash
cd /home/linuxbrew/swarmlab_simulator_ws
colcon build --event-handlers console_direct+5. 启动 AI SWARMLAB 地面站 UI
保持终端 B 位于容器内。
5.1 加载 ROS 2 与工作空间环境
bash
source /opt/ros/humble/setup.bash
source /home/linuxbrew/swarmlab_simulator_ws/install/setup.bash每个新打开的容器终端都需要重新执行以上两条 source 命令；一个终端中的环境不会自动传递给另一个终端。
5.2 检查容器显示变量
bash
echo "$DISPLAY"容器内应能看到宿主机传入的显示变量。如果为空，先返回本页“配置宿主机图形显示”部分检查 X11 和 Compose 挂载。
5.3 启动指定版本地面站
bash
cd /home/linuxbrew/swarmlab_simulator_ws/ground_deploy_2026_07_08/ground
python3 main.py成功判据： Ubuntu 宿主机桌面出现 AISWARMLAB 地面站窗口，终端中没有持续出现 Python 异常。
5.4 使用诊断启动脚本
同一目录还提供带环境检查的启动方式。直接运行 python3 main.py 失败时，可以执行：
bash
cd /home/linuxbrew/swarmlab_simulator_ws/ground_deploy_2026_07_08/ground
bash start.sh地面站启动后不要关闭终端 B。
6. 本页完成检查
继续下一章前，应确认：
docker image inspect aiswarmlab_control:ros2_cmdvel_bridge_v2能找到镜像；aiswarmlab_vrpn容器状态为Up；- 容器内存在
/home/linuxbrew/swarmlab_simulator_ws； vrpn_client_ros、fcu_core、rviz2_custom_panel三个包均可被 ROS 2 找到；- Ubuntu 桌面已经显示 AI SWARMLAB 地面站窗口；
- 终端 A 和终端 B 保持运行且没有持续错误。
全部通过后，进入下一章：动捕与 VRPN 定位。