灵犀 X2 虚拟仿真空间部署（Docker）

1452 字
7 分钟
灵犀 X2 虚拟仿真空间部署（Docker）
2026-10-17
文章
机器人
/
ROS2
/
MuJoCo
/
仿真
灵犀 X2 虚拟仿真空间部署（Docker）

本文记录在一台 x86_64 Ubuntu 机器上，用 Docker 部署灵犀 X2 的 MuJoCo 虚拟仿真空间，从镜像构建到仿真与运动控制器（MC）通信打通的完整过程。

参考#

智元机器人灵犀 X2 AimDK 文档 ROS 2 Humble 文档

1. 环境要求#

项目要求
电脑x86_64，建议 16 GB 或以上内存（实测 8 GB 偏紧，容易卡死）
系统Ubuntu 22.04 或 24.04，带图形桌面
软件Docker（宿主机无需安装 ROS 2）
GPU可选，无独显也能跑（默认走核显/软件渲染）
网络首次部署需下载基础镜像和软件包

先在宿主机确认 X11 转发工具已装：

Terminal window
if ! command -v xhost >/dev/null 2>&1; then
  sudo apt update
  sudo apt install -y x11-xserver-utils
fi

2. 准备软件目录#

把交付文件放到同一工作目录，目录名可自定，下面以 x2_simulation/ 为例：

x2_simulation/
├── aimdk/                  # SDK 源码（aimdk_msgs、py_examples、examples、robotop、ruckig）
├── x2_rl_deploy/           # 官方 MuJoCo 仿真 + 运控扩展包
│   ├── aimdk_msgs/         # 含 ProcessInfo 的完整消息集
│   ├── x2_rl_deploy_controller/   # 运动控制器（MC）
│   ├── x2_rl_deploy_mujoco/       # MuJoCo 仿真（HAL 层）
│   └── third_party/onnxruntime-linux-x64-1.23.2/   # RL 策略推理依赖
├── sim_mujoco/             # 指向 x2_rl_deploy/x2_rl_deploy_mujoco
├── Dockerfile
└── run_docker.sh

控制链路：

SDK(py_examples) ──高层指令──> MC(x2_rl_deploy_controller) ──关节命令──> sim_mujoco
                                  ^                                      │
                                  └────── 关节与 IMU 状态回传 <───────────┘

3. 构建镜像#

工作目录下的 Dockerfile 以 ROS 2 Humble 官方镜像为基础，装齐编译和运行依赖：

FROM osrf/ros:humble-desktop-full


ENV DEBIAN_FRONTEND=noninteractive
ENV RMW_IMPLEMENTATION=rmw_fastrtps_cpp


RUN apt-get update && apt-get install -y --no-install-recommends \
      build-essential ca-certificates cmake curl \
      libcurl4-openssl-dev libeigen3-dev libgflags-dev \
      libgl1 libgl1-mesa-dri libglx-mesa0 libncurses-dev \
      liboctomap1.9 libopencv-dev libscrypt0 libyaml-cpp-dev \
      mesa-utils pkg-config python3-colcon-common-extensions python3-pip \
      ros-humble-cv-bridge ros-humble-grid-map-msgs ros-humble-grid-map-ros \
      ros-humble-joy ros-humble-rmw-fastrtps-cpp \
    && rm -rf /var/lib/apt/lists/*


RUN printf '%s\n' \
      'source /opt/ros/humble/setup.bash' \
      'export RMW_IMPLEMENTATION=rmw_fastrtps_cpp' \
      'if [ -f /workspace/aimdk/install/local_setup.bash ]; then source /workspace/aimdk/install/local_setup.bash; fi' \
      >> /root/.bashrc


WORKDIR /workspace
CMD ["bash"]

国内网络建议先配 Docker 镜像加速，再拉基础镜像：

Terminal window
sudo mkdir -p /etc/docker
sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null || true
echo '{"registry-mirrors":["https://docker.m.daocloud.io","https://docker.1ms.run"]}' | sudo tee /etc/docker/daemon.json >/dev/null
sudo systemctl restart docker
docker pull osrf/ros:humble-desktop-full
docker build -t x2-simulation:latest .

目标架构是 x86_64，如果镜像文件名带 aarch64 说明是 ARM 包，不能用。编译产物不能跨架构混用。

4. 启动容器#

run_docker.sh 负责挂载工作目录、转发 X11 显示、并把宿主机 /agibot 挂进容器（MC 运行时目录）：

#!/usr/bin/env bash
set -euo pipefail
ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
IMAGE_NAME=x2-simulation:latest
CONTAINER_NAME=x2-sim
xhost +si:localuser:root >/dev/null 2>&1 || true
docker rm -f "${CONTAINER_NAME}" >/dev/null 2>&1 || true
DOCKER_ARGS=(
  run -it
  --name "${CONTAINER_NAME}"
  --network host
  --ipc host
  -e "DISPLAY=${DISPLAY:-:0}"
  -e QT_X11_NO_MITSHM=1
  -e RMW_IMPLEMENTATION=rmw_fastrtps_cpp
  -v "${ROOT_DIR}/aimdk:/workspace/aimdk:rw"
  -v "${ROOT_DIR}/sim_mujoco:/workspace/sim_mujoco:rw"
  -v "${ROOT_DIR}/x2_rl_deploy:/workspace/x2_rl_deploy:rw"
  -v /agibot:/agibot:rw
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw
  -w /workspace
)
if [[ -d /dev/dri ]]; then
  DOCKER_ARGS+=(--device /dev/dri)
fi
docker "${DOCKER_ARGS[@]}" "${IMAGE_NAME}" bash

宿主机准备好 MC 运行时目录，然后执行脚本：

Terminal window
sudo mkdir -p /agibot/data/var/
sudo chown "$USER:$USER" -R /agibot
chmod +x run_docker.sh
./run_docker.sh

执行后进入容器，这个终端作为后续的「终端 1」。要后台常驻（不占用交互终端）可用：

Terminal window
docker exec -d x2-sim bash /workspace/x2_rl_deploy/start_simulation_stack.sh

5. 编译 SDK 与运控栈#

容器内先编译 aimdk：

Terminal window
cd /workspace/aimdk
source /opt/ros/humble/setup.bash
colcon build
source install/local_setup.bash

再编译 x2_rl_deploy（运控 + 消息）。编译前需要给 x2_rl_deploy_controller 准备 onnxruntime（见第 6 节）。

6. 准备 onnxruntime 依赖#

x2_rl_deploy_controller 用 ONNX 推理 RL 策略，CMake 里 find_package(onnxruntime REQUIRED)。容器内没有安装 onnxruntime，也没有 root 权限装到系统目录，解决办法是下载官方预编译包放到 third_party/，并让 CMake 用这个本地路径。

下载并解压（宿主机或容器内均可）：

Terminal window
cd /workspace/x2_rl_deploy
mkdir -p third_party
curl -L https://github.com/microsoft/onnxruntime/releases/download/v1.23.2/onnxruntime-linux-x64-1.23.2.tgz \
  -o third_party/onnxruntime.tgz
tar -xzf third_party/onnxruntime.tgz -C third_party

按 CMake 目标里约定的目录补全 lib64 和头文件布局：

Terminal window
cd third_party/onnxruntime-linux-x64-1.23.2
mkdir -p lib64 include/onnxruntime
cp -a lib/*.so* lib64/
cp -a include/*.h include/onnxruntime/

然后把 x2_rl_deploy_controller/CMakeLists.txt 里的 find_package(onnxruntime REQUIRED) 改成指向本地目录：

set(ONNXRUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../third_party/onnxruntime-linux-x64-1.23.2")
find_package(onnxruntime REQUIRED
  PATHS "${ONNXRUNTIME_DIR}/lib/cmake/onnxruntime"
  NO_DEFAULT_PATH
  HINTS "${ONNXRUNTIME_DIR}")

并在 target_include_directories 里加上 ${ONNXRUNTIME_DIR}/include。

改好后编译：

Terminal window
cd /workspace/x2_rl_deploy
source /opt/ros/humble/setup.bash
source /workspace/aimdk/install/local_setup.bash
colcon build

编译产物：install/x2_rl_deploy_controller/lib/x2_rl_deploy_controller/x2_rl_deploy_controller。

7. 安装 CycloneDDS#

仿真二进制默认用 CycloneDDS 作为 RMW，镜像里只有 Fast DDS，不装会报：

Error getting RMW implementation identifier / RMW implementation not installed
(expected identifier of 'rmw_cyclonedds_cpp')

容器内安装：

Terminal window
apt-get update
apt-get install -y --no-install-recommends ros-humble-rmw-cyclonedds-cpp

之后启动一律设 export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp，让仿真、MC、SDK 三方用同一个 RMW，否则通信不通。

8. 解决 ProcessInfo 符号缺失#

两套 aimdk_msgs 并存时容易踩坑：/workspace/aimdk/install/aimdk_msgs 里没有 ProcessInfo 消息，/workspace/x2_rl_deploy/install/aimdk_msgs 里有。仿真加载 monitor_plugin 时会因为找不到 ProcessInfo 的类型支持而段错误：

undefined symbol: ...get_message_type_support_handle<aimdk_msgs::msg::ProcessInfo...>

解决办法是把带 ProcessInfo 的那套消息库放在 LD_LIBRARY_PATH 最前面：

Terminal window
export LD_LIBRARY_PATH=/workspace/x2_rl_deploy/install/aimdk_msgs/lib:$LD_LIBRARY_PATH

9. 启动仿真与运控#

把上面的环境变量和步骤整合成一键脚本 start_simulation_stack.sh：

#!/bin/bash
set -e
source /opt/ros/humble/setup.bash
source /workspace/x2_rl_deploy/install/local_setup.bash
source /workspace/aimdk/install/local_setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export MUJOCO_GL=egl
export LD_LIBRARY_PATH=/workspace/x2_rl_deploy/install/aimdk_msgs/lib:/workspace/x2_rl_deploy/third_party/onnxruntime-linux-x64-1.23.2/lib:/workspace/sim_mujoco/bin:/workspace/sim_mujoco/lib:/opt/ros/humble/lib:$LD_LIBRARY_PATH


cd /workspace/sim_mujoco/bin
echo lx2501_3_t2d5 > sim_robot_name_cache.txt
echo /workspace/sim_mujoco/configuration > sim_configuration_directory_cache.txt
mkdir -p log/crash
nohup bash ./start_sim.sh > /tmp/sim.log 2>&1 &
echo "sim PID=$!"
sleep 8


cd /workspace/x2_rl_deploy
nohup ./install/x2_rl_deploy_controller/lib/x2_rl_deploy_controller/x2_rl_deploy_controller > /tmp/mc.log 2>&1 &
echo "mc PID=$!"

启动：

Terminal window
docker exec -d x2-sim bash /workspace/x2_rl_deploy/start_simulation_stack.sh

日志分别在容器的 /tmp/sim.log 和 /tmp/mc.log。

10. 验证通信#

查看话题（只 source x2_rl_deploy 的 install，避开两套消息的 Python 类型冲突，见第 8 节）：

Terminal window
docker exec -it x2-sim bash
source /opt/ros/humble/setup.bash
source /workspace/x2_rl_deploy/install/local_setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export LD_LIBRARY_PATH=/workspace/x2_rl_deploy/install/aimdk_msgs/lib:$LD_LIBRARY_PATH


ros2 topic list
ros2 topic echo /aima/hal/joint/arm/state --once
ros2 topic info /aima/hal/joint/leg/command

正常时应看到 Publisher count: 1, Subscription count: 1（MC 发布、仿真订阅），并且 echo 能打印出实时关节数据，说明仿真与运控通信链路已打通。

常见问题#

问题解决办法
基础镜像拉取失败重试 docker pull，或先配镜像加速再拉
MuJoCo 窗口不显示宿主机执行 xhost +si:localuser:root，确认在图形桌面会话
报 rmw_cyclonedds_cpp 未安装第 7 节安装 CycloneDDS，三方统一用同一个 RMW
段错误 + ProcessInfo 符号缺失第 8 节，把带 ProcessInfo 的消息库放 LD_LIBRARY_PATH 最前
start_sim.sh 提示已有实例在跑真没有实例时，是脚本 pgrep 把调用它的命令行自己匹配上了；用独立脚本文件启动，别写在 bash -c "..." 单行里
内存不足导致仿真被杀见下一篇「内存占用优化」，减渲染分辨率、关多余插件

本网站提供的所有教程仅供学习使用，无任何商务用途!#

文章分享

如果这篇文章对你有帮助，欢迎分享给更多人！

灵犀 X2 虚拟仿真空间部署（Docker）
https://blog.levek.top/posts/x2_sim_docker/x2虚拟仿真docker部署/
作者
levek
发布于
2026-10-17
许可协议
CC BY-NC-SA 4.0
VMware 安装 Ubuntu 22.04 教程
VMware 17.6 安装教程（Windows）
相关文章智能推荐
1
灵犀 X2 二次开发指南
文章灵犀 X2 人形机器人二次开发全流程：WSL2 + ROS 2 Humble 环境搭建、代码同步、依赖安装、编译、镜像网络配置、MuJoCo 仿真与故障排查。
2
VMware 安装 Ubuntu 22.04 教程
文章VMware 虚拟机安装 Ubuntu 22.04 LTS 图文教程：ISO 下载、新建虚拟机、系统安装到 VMware Tools 与换源优化全程演示，零基础也能顺利装好 Linux～
3
VMware 17.6 安装教程（Windows）
文章VMware Workstation Pro 17.6 图文安装教程：下载、解压、安装到激活全程截图演示，Win 7/8/10/11 通用，零基础也能轻松装好虚拟机～
4
记账软件
文章一款简洁、无广告的记账软件
5
图片转换工具
文章JPG图片转换工具，JPG-to-PNG JPG-to-ICO PNG-to-JPG,改变照片尺寸等
随机文章随机推荐
Profile Image of the Author
levek
Hello, I'm levek.
BilibiliGitHub
公告
欢迎来到我的博客！
分类
标签
更多
最新动态
站点统计
文章
8
分类
1
标签
14
总字数
6,121
运行时长
0 天
最后活动
0 天前
站点信息
构建平台
Local
博客版本
Firefly v6.16.8
文章许可
CC BY-NC-SA 4.0
文章目录
1
参考
2
1. 环境要求
3
2. 准备软件目录
4
3. 构建镜像
5
4. 启动容器
6
5. 编译 SDK 与运控栈
7
6. 准备 onnxruntime 依赖
8
7. 安装 CycloneDDS
9
8. 解决 ProcessInfo 符号缺失
10
9. 启动仿真与运控
11
10. 验证通信
12
常见问题
本网站提供的所有教程仅供学习使用，无任何商务用途!