安装
选择适合操作系统的安装方式。表格中的链接会跳转到本页对应的操作步骤。
选择安装包
| 操作系统 | 安装方式 | 仿真引擎 |
|---|---|---|
| Apple Silicon · macOS 27及以上 | 通过DMG安装 · 通过Homebrew安装 | 原生ROS 2、Gazebo · Metal |
| Ubuntu 26.04 · x86-64 | APT软件源 · 通过DEB安装 | Docker中的Linux引擎 |
| Windows · x86-64 | 在Windows上安装 | Docker Desktop · WSL2 |
在Windows上安装
配置WSL2
如果尚未安装WSL,从开始菜单以管理员身份打开终端或PowerShell,执行:
wsl --install --no-distribution
按提示重启电脑,再打开一个新终端执行:
wsl --update
wsl --set-default-version 2
wsl --status
确认默认版本为2。如果出现虚拟化错误,请检查固件中的硬件虚拟化设置,并参阅Microsoft的WSL安装指南。Docker Desktop使用自己的WSL2环境,因此应用不需要单独安装Ubuntu发行版。只有准备独立的ROS环境时才需要另行安装。
安装Docker Desktop和应用
- 安装Docker Desktop,配置WSL2后端,并按要求重启。
- 打开Docker Desktop,等待引擎运行。
- 下载Windows安装程序,按提示安装。如果出现Windows已保护你的电脑,对官方WWW-POSIM下载选择更多信息 → 仍要运行。当前安装包没有Authenticode签名,可使用公开的SHA-256校验和确认文件。
- 从开始菜单打开WWW-POSIM。如果再次出现相同警告,再次确认。登录后选择启动仿真器。
- 浏览器会打开本地仿真器。继续阅读熟悉工作区。
使用期间请保持Docker Desktop运行。应用会自动下载与自身版本匹配的镜像。
通过DMG安装
需要搭载Apple Silicon的Mac,系统为macOS 27或更新版本。可在苹果菜单 → 关于本机中确认。
- 下载Mac版DMG。
- 打开DMG,将WWW-POSIM拖入应用程序。
- 尝试打开应用。该应用使用临时签名,未经过Apple公证。
- 如果首次启动被阻止,打开系统设置 → 隐私与安全性 → 安全性,点击WWW-POSIM旁的仍要打开。在确认窗口中选择打开,并按要求完成身份验证。参阅Apple说明。
- 登录并选择启动仿真器。首次启动会下载、验证并解压引擎文件,窗口中会显示进度。
- 浏览器打开后,继续阅读熟悉工作区。
下载支持断点续传,文件按512 MiB分块。每个安装程序和分块文件均小于2 GiB。ROS环境和准备好的引擎缓存在应用目录之外,供后续启动复用。原生引擎通过Metal使用GPU。
如果启动受阻,参阅恢复Mac应用启动。
通过Homebrew安装
如果尚未安装Homebrew,先按照其官方安装说明完成安装。然后执行以下命令安装同一应用:
brew tap ioes-lab/www-posim
brew trust --cask ioes-lab/www-posim/www-posim
brew install --cask ioes-lab/www-posim/www-posim
brew trust --cask允许加载指定仓库中该应用的Cask。参阅Tap Trust。
如果Homebrew请求packages.arm64_dunno.jws.json时收到HTTP 404,说明其系统版本表尚未识别macOS 27。可以绕过软件包API更新Homebrew,再安装应用:
HOMEBREW_NO_INSTALL_FROM_API=1 brew update
HOMEBREW_NO_AUTO_UPDATE=1 brew tap ioes-lab/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew trust --cask ioes-lab/www-posim/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew install --cask ioes-lab/www-posim/www-posim
这些环境变量仅对紧随其后的命令有效,详见Homebrew环境选项。如果仍然失败,请使用通过DMG安装。
打开WWW-POSIM,使用与网站相同的账号登录。应用会自动连接账号服务器。首次启动会验证文件并将引擎解压到Library中,显示已解压大小、百分比、预计剩余时间和服务启动状态。Gazebo、ROS 2和Autopilot均在Mac上运行。更新提示不会中断正在运行的仿真。
要在已有终端中加载随应用提供的环境,执行:
eval "$(/Applications/WWW-POSIM.app/Contents/MacOS/WWW-POSIM --ros-env)"
应用已包含连接器、标准ROS消息和RViz2。打开ROS终端和打开RViz会使用该环境。算法所需的其他依赖请安装到兼容环境中。参阅ROS 终端与连接和控制桌面版工作区。
在Ubuntu上准备Docker
安装Docker和curl。将账号加入Docker用户组后,退出Ubuntu会话并重新登录。
sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
APT软件源
先完成在Ubuntu上准备Docker,再添加签名APT软件源并安装应用:
SERVER=https://www-posim.vercel.app
curl -fSL "$SERVER/guide/packages/apt/www-posim-archive-keyring.gpg" | \
sudo tee /usr/share/keyrings/www-posim-archive-keyring.gpg >/dev/null
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/www-posim-archive-keyring.gpg] $SERVER/guide/packages/apt stable main" | \
sudo tee /etc/apt/sources.list.d/www-posim.list
sudo apt update
sudo apt install www-posim
www-posim
应用会按自身版本选择引擎镜像。当前账号必须能够访问Docker。GPU渲染还需要兼容的驱动和容器运行环境。
通过DEB安装
此安装包面向x86-64架构的Ubuntu 26.04。按Ctrl+Alt+T打开终端并执行:
sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
mkdir -p ~/Downloads
cd ~/Downloads
curl -fL -o www-posim.deb https://www-posim.vercel.app/guide/packages/latest/linux-amd64.deb
sudo apt install ./www-posim.deb
sudo提示时输入电脑密码,输入过程中不会显示字符。- 退出Ubuntu会话并重新登录,使Docker访问权限生效。
- 从应用菜单打开WWW-POSIM,或运行
www-posim。 - 登录,选择启动仿真器,再阅读熟悉工作区。
使用Docker也必须是Ubuntu 26.04吗?
Docker Engine也支持Ubuntu 24.04和22.04。容器内的Ubuntu与ROS版本不必与宿主机一致。不过,WWW-POSIM发布的DEB和安装脚本面向Ubuntu 26.04,启动程序本身也依赖宿主机的系统库。因此,此DEB的支持环境是26.04。旧版宿主机能够运行Docker,并不能证明WWW-POSIM安装程序也兼容。参阅Docker支持的Ubuntu版本。
验证账号并开始使用
在安装注册账号,打开验证邮件并选择验证邮箱。如果没有收到,请检查垃圾邮件。验证成功并登录后,应用可以将密码保存在操作系统的凭据存储中。
登录和定期更新使用权限需要互联网连接。请为引擎、地形和模型预留磁盘空间。账号存储配额与电脑的可用空间是两回事。参阅账号与使用时长。
创建Python项目会向已保存的工作目录添加示例,初始目录为Documents/WWW-POSIM。打开ROS终端、打开工作目录和在VS Code中打开均使用该目录。VS Code会打开ros_vehicle_command.py。继续阅读控制桌面版工作区。
选择图形设备
本地设置中的图形 → 自动(推荐)会在引擎容器内实际检测EGL图形设备。Windows的NVIDIA环境使用WSL D3D12。如果没有可用的硬件渲染器,应用会改用CPU并说明原因。
必须使用GPU会在GPU检测失败时停止启动。软件(CPU)选择CPU渲染。Linux的NVIDIA环境需要兼容的驱动和NVIDIA Container Toolkit。Windows用户应在Windows侧安装NVIDIA驱动,引擎使用WSL2后端。Mac原生引擎使用Metal。
应用中的ROS终端和RViz已经配置好环境。只有按照ROS 终端与连接手动搭建独立环境时,才需要额外安装Ubuntu和ROS。
本地场景由Gazebo Ogre2渲染。拖动可绕场景旋转观察相机,滚轮用于缩放。没有收到画面或画面停止更新时,视图会显示等待状态。
更新
红色提示条会显示已安装版本和可用版本。立即更新在仿真器中打开安装说明,在启动程序中开始经过验证的下载。点击×可在当前标签页隐藏提示,直到出现更新版本。
请先结束仿真,再选择一种方式更新:
- 应用:更新到VERSION。
- Homebrew:
brew upgrade --cask www-posim。 - APT:
sudo apt update && sudo apt upgrade。 - 直接安装:下载并安装当前版本的安装包。
Mac更新程序会在替换应用前验证下载和签名。如果现有引擎已匹配,只下载应用文件。保存在应用目录之外的项目、模型和地形缓存会保留。
对于另一台ROS工作站,请下载连接器安装包,并按ROS 终端与连接准备兼容的ROS环境。
引擎镜像
应用会自动从Docker Hub下载匹配版本的引擎和工作空间镜像。这些镜像公开可用,无需登录镜像仓库或手动输入镜像地址。Mac原生安装包使用经过验证的分块发布文件,不使用Docker镜像。
docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker.io/ioeslab/www-posim-web:0.6.15-amd64
也可以提前下载:
docker pull docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker pull docker.io/ioeslab/www-posim-web:0.6.15-amd64
恢复Mac应用启动
此发行版未经Apple公证,因此下载或替换应用后可能再次出现警告。请先尝试仍要打开。如果按钮无响应,或应用停留在Dock中却没有窗口,可能需要重启macOS的应用验证服务。
先退出WWW-POSIM。只有启动程序无响应且没有仿真运行时,才使用苹果菜单 → 强制退出。重启Mac后重新打开应用是最简单的恢复方法。
如果希望不重启电脑,请先确认DMG来自官方下载,且与公布的SHA-256校验和一致。执行shasum -a 256并在后面加上DMG路径。临时签名只能验证文件完整性,不能证明发布者身份。
将Mac启动恢复工具保存到下载目录,然后执行:
bash "$HOME/Downloads/recover_macos_launch.command"
默认检查会验证应用身份和签名,并报告下载隔离属性。要修复启动阻止,执行:
bash "$HOME/Downloads/recover_macos_launch.command" --repair --restart-validation
阅读提示后,输入TRUST WWW-POSIM,表示允许该应用在Apple警告下运行。工具只移除所选应用的隔离属性,重启验证服务并请求打开应用。sudo要求时,请在本机终端输入Mac密码。Gatekeeper仍保持启用。请确认应用窗口确实出现;发出打开请求本身不代表启动成功。
如果仍要打开正常响应,无需重启验证服务,则只使用--repair。Dev版应用需添加--app "/Applications/WWW-POSIM Dev.app"。DMG的README旁也包含同一工具,可将其路径传给bash执行。
若手动执行同样的恢复,请先退出应用并验证官方DMG的校验和。只有下面的完整性检查成功、且你信任该应用时,才继续:
codesign --verify --deep --strict "/Applications/WWW-POSIM.app"
xattr -dr com.apple.quarantine "/Applications/WWW-POSIM.app"
sudo /usr/bin/killall -TERM syspolicyd
open -a "/Applications/WWW-POSIM.app"
重启验证服务会影响其他应用尚未完成的安全检查,可能需要重新打开这些应用。如果恢复失败,请重启Mac。如果签名验证失败,请重新下载官方安装程序。