POSIM v1.0.1Platform for Ocean Simulation · 文档
文档菜单
POSIM / 开始使用

Linux:使用Docker安装

如果桌面系统使用其他 Ubuntu 版本或其他 Linux 发行版,可以直接使用已发布的 POSIM 镜像。本指南面向 x86-64 桌面上的 AMD64 镜像,通过 X11 或 XWayland 显示 Gazebo。Ubuntu 26.04 用户建议选择原生安装。

1. 准备 Docker 和显示环境

按发行版安装 Docker Engine。Ubuntu 用户可使用专门的安装说明。如果当前账户无法运行 docker,请完成安装后的配置。

在当前桌面会话中打开终端并安装 xauth。Ubuntu 命令如下:

sudo apt update
sudo apt install -y xauth

检查显示地址和 Docker 服务端版本:

printf '%s\n' "$DISPLAY"
docker version --format '{{.Server.Version}}'

2. 下载 POSIM

docker pull ioeslab/posim:latest

Docker 环境介绍了版本选择和源码构建。首次运行采用软件渲染,速度可能低于使用 GPU 的原生安装。

3. 授权容器访问显示服务

将当前会话的 X11 认证信息复制到仅当前账户可读的文件:

mkdir -p "$HOME/.cache/posim"
export POSIM_XAUTH="$HOME/.cache/posim/xauthority"
touch "$POSIM_XAUTH"
chmod 600 "$POSIM_XAUTH"
xauth nlist "$DISPLAY" | sed -e 's/^..../ffff/' | xauth -f "$POSIM_XAUTH" nmerge -
test -s "$POSIM_XAUTH"

最后一条命令检查文件是否包含数据。如果失败,请确认终端属于当前图形会话,且 XWayland 可用。完成认证配置后再继续。

4. 创建容器

docker run -d --name posim --init --shm-size=1g \
  -e DISPLAY -e QT_QPA_PLATFORM=xcb -e LIBGL_ALWAYS_SOFTWARE=1 \
  -e XAUTHORITY=/tmp/posim.xauth \
  --mount type=bind,source=/tmp/.X11-unix,target=/tmp/.X11-unix,readonly \
  --mount "type=bind,source=$POSIM_XAUTH,target=/tmp/posim.xauth,readonly" \
  --mount type=volume,source=posim-data,target=/work \
  --entrypoint bash ioeslab/posim:latest -lc 'exec sleep infinity'

将自己的模型和录制数据保存在 /work 的 posim-data 数据卷中。使用 docker stop posim 停止容器,使用 docker start posim 恢复。如果重新登录 Linux 后无法显示窗口,请更新认证文件。

运行示例前,先准备两个终端,并让它们连接同一个容器。启用硬件加速或 CUDA 声呐之前,请阅读 GPU 配置。

5. 运行演示世界

进入容器:

docker exec -it posim bash

在容器内完成最后的安装验证:

source /opt/ros/lyrical/setup.bash
source /opt/posim_ws/install/setup.bash
ros2 launch posim_demos posim_world.launch.py \
  world_name:=posim_ocean_waves headless:=false

Gazebo 应打开海洋世界。运行期间请保持终端打开,按 Ctrl+C 停止。然后继续第一次仿真。