Webots 仿真服务器高级配置指南：Docker 部署、Git 检出与并行容量调优

• 科研
• 自动驾驶
• 物理引擎

本篇指南聚焦 Webots 云端仿真架构中仿真服务器（simulation server）的高级配置场景，覆盖 Docker 容器化运行、GitHub 仓库文件检出协议、以及提升单机并行仿真容量的资源调优手段。读完本文，你将掌握如何安全地用 Docker 运行 Webots 实例、通过 URL 协议远程启动指定世界文件、以及通过 Zram、Swap 与图形质量设置最大化单台服务器可承载的并行仿真数量。

适用前提：本文面向基于 webots-server 与 会话服务器指南。

一、Docker 化运行：安全与开销的权衡

1.1 docker 配置项的作用

仿真服务器配置文件（simulation.json）中的docker选项控制 Webots 实例的启动方式：

• docker: true（推荐）：Webots 在 Docker 容器内启动；
• docker: false（默认）：Webots 直接运行在服务器宿主机（on the metal）上。

容器内运行 Webots 的额外开销非常小，但能保证仿真服务器在运行任意仿真时依然保持安全——恶意或失控的仿真被隔离在容器边界之内。这是官方推荐方案，也是 仿真服务器软件要求 中明确建议的配置。

安全警告：如果你选择不使用 Docker，必须确保配置文件中的allowedRepositories列表不包含任何指向恶意仓库的链接，否则等于将整个仿真服务器暴露在风险之中。

1.2 Dockerfile 的自动生成机制

当docker选项开启后，仿真服务器按以下规则决定容器镜像：

1. 优先使用项目自带 Dockerfile：如果仿真项目根目录存在Dockerfile文件，则使用该文件启动对应的 Webots 实例；
2. 自动生成 Dockerfile：否则，仿真服务器基于 Webots 标准 Docker 镜像自动生成一个Dockerfile。

自动生成的 Dockerfile 以如下指令开头：

FROM docker image cyberbotics/webots.cloud:{{ webots.version.major }}-ubuntu22.04

其中{{ webots.version.major }}（如 R2025a）自动从仿真世界文件的首行解析。Webots 世界文件（.wbt）的头部固定为 VRML 版本声明，例如：

#VRML_SIM {{ webots.version.major }} utf8

这也是 Webots 场景文件的标准格式——通用性说明 中即展示了#VRML_SIM R2025a utf8的实例。通过解析这一行，仿真服务器可以精确地为对应版本的仿真拉取匹配的镜像。

注意：低于 R2022b 的 Webots 版本不支持此机制。

1.3 定制自己的 Docker 镜像

对于已安装 Webots 的仿真服务器，安装流程 给出了拉取官方镜像的方式：

docker pull cyberbotics/webots.cloud:R2025a-ubuntu22.04 docker pull cyberbotics/webots.cloud:R2025a-ubuntu22.04-numpy

官方镜像基于 Ubuntu 22.04，已内置 Xvfb 虚拟帧缓冲，可在无图形界面的情况下以 headless 模式运行：

xvfb-run webots --stdout --stderr --batch --mode=realtime /path/to/your/world/file

二、仿真文件检出：从 GitHub URL 到世界文件

2.1 /client 请求与 URL 协议

仿真服务器收到/client请求（WebSocket）中的start命令后，会从请求携带的url检出仿真文件并启动 Webots。URL 的协议格式如下：

https://github.com/alice/sim/blob/my_own_version/app/worlds/my_world.wbt ^^^^^^^^^ ^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^ repository tag or branch path to world file

各部分含义：

• repository：GitHub 用户名与仓库名（此处为alice用户的sim仓库）；
• tag or branch：要检出的标签或分支（此处为my_own_version）；
• path to world file：仓库内世界文件的相对路径。

以该 URL 为例，仿真服务器会检出alice/sim仓库中my_own_version分支（或标签）下的app目录，并用其中的my_world.wbt世界文件启动 Webots。

限制说明：

• 该协议目前仅支持公共 GitHub 仓库；
• 该协议仍处于实验阶段，尚不支持 robot windows；
• 完整请求负载示例见 仿真服务器指南 中的 JSON 结构（start对象包含url与可选的mode字段，mode可取w3d或mjpeg）。

2.2 只检出单个目录：svn 与 git 探测

仿真项目往往只是大型仓库中的子目录，例如 python 语言示例。整仓克隆既慢又浪费磁盘，而 GitHub 为 SVN 客户端保留了兼容接口，允许只检出特定分支/标签下的单个目录。

在master分支上只检出单个目录：

svn checkout https://github.com/cyberbotics/webots/branches/master/projects/languages/python

在版本标签（如 R2025a）上检出：

svn checkout https://github.com/cyberbotics/webots/tags/R2025a/projects/languages/python

2.3 判断分支或标签是否存在

SVN 方式：

svn ls https://github.com/cyberbotics/webots/branches/master svn ls https://github.com/cyberbotics/webots/tags/R2025a

Git 方式（--quiet抑制输出，返回码即结果）：

git ls-remote --quiet --heads https://github.com/cyberbotics/webots.git master git ls-remote --quiet --tags https://github.com/cyberbotics/webots.git R2025a

若要判定R2025a究竟是分支还是标签：

git ls-remote --quiet https://github.com/cyberbotics/webots.git R2025a

在 仿真服务器软件要求 中，git与subversion正是被列为检出项目代码所必需的依赖（sudo apt-get install git subversion），与本节内容相互印证。

三、降级图形质量：以 GPU 换并行实例数

3.1 为什么降级本地渲染不影响浏览器画质

即使 Webots 以--no-rendering模式启动（该参数在 启动命令参考 中被描述为"禁用主 3D 视图的渲染"），服务器端的图形场景仍然会被计算——因为 Camera 等设备需要"看见"场景才能成像。

但 Docker 内 Webots 实例的图形质量，通常不会影响浏览器端显示的仿真画质，仅有两个例外：

• 仿真中使用了Camera设备；
• 仿真使用了本地纹理：即 proto/world 中通过textures/my_images.jpg这类相对路径引用图片，而非https://the_address_of_my_picture.jpg这类远程 URL。

因此，在服务器端主动降低图形质量，是提高单机并行 Webots 实例数量的有效手段。

3.2 通过配置文件降低 OpenGL 质量

Webots 的图形设置位于Preferences → OpenGL标签页，偏好设置文档 中列出了可调项及其性能影响，例如：

• Ambient Occlusion：环境光遮蔽（GTAO），默认medium，对性能开销明显；
• Texture Quality：纹理分辨率，high使用原始分辨率，medium将 ≥1024 的图片分辨率减半，low将 ≥512 的图片分辨率降至 1/4，用于节省 GPU 显存；
• Max Texture Filtering：最大纹理过滤级别，降低可减少 GPU 占用；
• Disable shadows：禁用阴影（3D 视图与 Camera 渲染均生效）；
• Disable anti-aliasing：禁用 SMAA 抗锯齿。

将这些设置从最高质量调至最低，当 GPU 是瓶颈时，可将并行实例数提升3～4 倍。具体做法是修改 Webots 配置文件（位于/$Home/.config/Cyberbotics/Webots-R202??.conf），然后基于修改后的配置重建 Docker 镜像：

FROM my_name/my_webots_repo:previous_webots_tag COPY /path_to_the_configuation_file/Webots-R202??.conf /root/.config/Cyberbotics/Webots-R202??.conf

说明：此优化已在 Cyberbotics 官方提供的 Docker 镜像中实现，自建镜像时才需要手动处理。

四、资源优化：缩短加载时间与提升并行容量

4.1 将资产直接放入 Docker

Webots 启动时需加载世界文件及其资产（纹理、网格、声音）。资产默认按需从网络下载并缓存（详见 安装流程 的 Asset Cache 说明），而在 Docker 场景下，可以把资产预置进镜像，省去启动时的网络下载：

FROM my_name/my_webots_repo:previous_webots_tag COPY path_to_your_assets_folder/assets /root/.cache/Cyberbotics/Webots/assets

两个关键约束：

• 资产文件夹中的内容必须与 Docker 内 Webots 的版本对应（资产缓存与版本强相关，Linux 下默认缓存路径为~/.cache/Cyberbotics/Webots，目录结构为按内容哈希命名的文件，见 安装流程）；
• 该优化同样已内置在 Cyberbotics 官方 Docker 镜像中。

4.2 服务器饱和的演进路径

服务器的并行容量受限于 CPU 与 GPU 显存，饱和过程通常是：

1. GPU 显存最先被占满（多数场景）；
2. GPU 占满后，CPU 内存开始承担渲染压力，迅速填满；
3. 内存填满后，Swap 开始接管；
4. Swap 填满后，再尝试开启更多仿真将导致服务器崩溃。

因此，扩容并行容量的核心思路是：压缩内存占用（Zram）与扩大交换空间（Swap）。

4.3 启用 Zram 压缩内存

Zram 是 Linux 内核模块，将内存中极少使用的部分压缩存放，作用类似 Swap 但通常更快。启用步骤：

sudo apt-get install zram-config sudo service zram-config start

验证安装：

cat /proc/swaps

正常输出类似（/dev/zram0至/dev/zram3即为压缩设备）：

Filename Type Size Used Priority /dev/sda3 partition 9215996 0 -1 /dev/zram0 partition 755740 8104 5 /dev/zram1 partition 755740 8004 5 /dev/zram2 partition 755740 8120 5 /dev/zram3 partition 755740 8064 5

4.4 扩大 Swap 空间

增大 Swap 可让服务器支撑更多并行仿真，但需要注意：Swap 填充过程中会观察到明显的性能下降。Linux 下调整 Swap 大小的通用步骤包括关闭现有 swap 文件、创建新的 swap 文件（fallocate/mkswap）、挂载并写入/etc/fstab，可参考公开的 Ubuntu swap 扩容教程。

五、配套实践与验证依据

本节梳理上文涉及的配套配置，方便对照落地：

• 仿真服务器完整配置项：docker、allowedRepositories、projectsDir、webotsHome、maxConnections、timeout等参数清单见 仿真服务器指南；
• 与仿真服务器相关的网络架构：仿真服务器机器的/load（返回机器负载）与/monitor（状态页）HTTP 处理器，以及 Apache 反向代理对 2000-2999 / 3000-3999 端口段的 WebSocket 与 HTTP 重写规则，见 仿真服务器指南；
• 启动参数佐证：--no-rendering与--batch等参数的语义见 启动命令参考；xvfb-run --auto-servernum webots --mode=fast --no-rendering ...的无界面运行方式见 安装流程；
• 世界文件版本头解析：.wbt文件首行#VRML_SIM <version> utf8的规范见 通用性说明。

综上，Docker 隔离 + 单目录检出 + 图形降质 + Zram/Swap 扩容，构成了 Webots 仿真服务器"安全、快速启动、高并行"三个维度的完整高级配置方案。

• 科研
• 自动驾驶
• 物理引擎