olorobotics/olo-appliance

OLO Appliance - Docker镜像

该镜像运行OLO Appliance。本指南仅专注于如何运行镜像及可配置的选项。

---

支持的标签

• olorobotics/olo-appliance:humble-latest
• olorobotics/olo-appliance:jazzy-latest

---

快速启动（单容器 - Humble，推荐使用主机网络）

bash
docker pull olorobotics/olo-appliance:humble-latest

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_AUTH_USERNAME="you@example.com" \
  -e OLO_APL_AUTH_PASSWORD="your-password" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

此命令使用olo-data Docker卷启动设备，实现持久化存储。

---

最小化Docker Compose示例（Humble）

yaml
services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    container_name: olo-appliance
    network_mode: host
    environment:
      OLO_APL_AUTH_USERNAME: "you@example.com"
      OLO_APL_AUTH_PASSWORD: "your-password"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
    volumes:
      - olo-data:/data
    restart: unless-stopped

volumes:
  olo-data:
    driver: local

---

必要配置

设备启动需要以下环境变量：

• OLO_APL_AUTH_USERNAME - OLO账户用户名/***
• OLO_APL_AUTH_PASSWORD - OLO账户密码
• OLO_APL_APPLIANCE_NAME - 设备实例名称（例如：My Appliance）

如果任何变量缺失或无效，设备将在启动时失败并退出，同时显示错误信息。

---

可选配置

ROS桥接

默认情况下，设备在localhost:9090启动内置rosbridge服务器。可配置为使用外部rosbridge服务器：

• OLO_APL_ROSBRIDGE_HOST - Rosbridge服务器主机名（默认：localhost）
• OLO_APL_ROSBRIDGE_PORT - Rosbridge服务器端口（默认：9090）
• OLO_APL_DISABLE_LOCAL_ROSBRIDGE - 设置为true以禁用内置rosbridge服务器

注意：也可通过OLO UI的维护窗口配置rosbridge设置。但通过UI修改rosbridge主机/端口时需谨慎 - 设置必须从容器视角有效。例如，使用主机网络时，localhost指主机；使用桥接网络并端口映射时，可能需要使用容器内部网络地址或host.docker.internal（Docker Desktop）访问主机服务。

连接外部rosbridge示例：

bash
docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_AUTH_USERNAME="you@example.com" \
  -e OLO_APL_AUTH_PASSWORD="your-password" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -e OLO_APL_ROSBRIDGE_HOST="192.168.1.100" \
  -e OLO_APL_ROSBRIDGE_PORT="9090" \
  -e OLO_APL_DISABLE_LOCAL_ROSBRIDGE="true" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

仿真时间

• OLO_APL_USE_SIM_TIME - 设置为true以使用仿真时间（默认：false）

ROS Domain ID

• ROS_DOMAIN_ID - 用于DDS通信的ROS 2域ID（默认：0）

主题限流

控制主题发布速率以管理带宽：

• OLO_APL_TOPIC_DEFAULT_THROTTLE_HZ - 所有主题的默认限流频率（Hz）（未设置或0表示禁用）
• OLO_APL_TOPIC_HANDLING_JSON - 完整的主题处理配置（JSON格式）

主题处理配置示例：

bash
docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_AUTH_USERNAME="you@example.com" \
  -e OLO_APL_AUTH_PASSWORD="your-password" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -e OLO_APL_TOPIC_HANDLING_JSON='{"defaultThrottleFrequency": 20, "throttleTopics": {"/odom": 10, "/camera/image_raw": 5}, "throttleDataTypes": {"sensor_msgs/msg/PointCloud2": 2}}' \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

主题处理选项：

• defaultThrottleFrequency - 所有主题的默认限流频率（Hz）
• throttleTopics - 按主题限流（优先级最高）
• throttleDataTypes - 按消息类型限流（优先级次之）

配置优先级：throttleTopics > throttleDataTypes > defaultThrottleFrequency

---

外部ROS2工作区集成

设备可加载外部ROS2工作区，使其能够识别机器人的自定义消息类型、服务和包。当机器人使用设备需要理解的自定义接口时，这一点至关重要。

工作原理

设置ROS2_WS_PATH环境变量指向容器内的ROS2工作区。设备启动时，会在加载基础ROS发行版后，加载$ROS2_WS_PATH/install/setup.bash。

容器间共享工作区

推荐方法是使用包含已构建ROS2工作区的共享Docker卷。机器人驱动容器可导出其工作区，设备可只读导入：

yaml
services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    network_mode: host
    environment:
      OLO_APL_AUTH_USERNAME: "you@example.com"
      OLO_APL_AUTH_PASSWORD: "your-password"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
      ROS2_WS_PATH: /shared/workspace
    volumes:
      - olo-data:/data
      - ros-workspace:/shared/workspace:ro  # 只读访问共享工作区

  my-robot-driver:
    image: my-robot-driver:humble-latest
    network_mode: host
    environment:
      EXPORT_WORKSPACE: "1"  # 驱动启动时导出工作区
    volumes:
      - ros-workspace:/shared/workspace:rw  # 读写权限以填充工作区

volumes:
  olo-data:
    driver: local
  ros-workspace:
    driver: local

关键点：

• 机器人驱动以读写（rw）方式挂载共享卷并导出已构建工作区
• 设备以只读（ro）方式挂载同一卷，并通过ROS2_WS_PATH加载
• 使设备能够理解机器人的自定义消息类型、动作定义和服务接口

---

与Docker化机器人驱动一起运行

常见部署模式是OLO Appliance与一个或多个容器化机器人驱动一起运行。所有容器共享主机网络，以确保ROS 2 DDS发现正常工作。

多容器示例

以下示例展示设备与机器人驱动一起运行，使用共享ROS工作区卷：

yaml
services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    init: true
    restart: unless-stopped
    stop_signal: SIGINT
    stop_grace_period: 40s
    network_mode: host
    environment:
      OLO_APL_AUTH_USERNAME: "you@example.com"
      OLO_APL_AUTH_PASSWORD: "your-password"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
      ROS_DOMAIN_ID: 55
      ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET
      FASTDDS_BUILTIN_TRANSPORTS: UDPv4
      ROS_LOCALHOST_ONLY: 0
      ROS2_WS_PATH: /shared/workspace
    volumes:
      - olo-appliance-data:/data
      - ros-workspace:/shared/workspace:ro

  my-robot-driver:
    image: your-robot-driver:humble-latest
    init: true
    restart: unless-stopped
    stop_signal: SIGINT
    stop_grace_period: 40s
    network_mode: host
    environment:
      ROS_DOMAIN_ID: 55
      ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET
      FASTDDS_BUILTIN_TRANSPORTS: UDPv4
      ROS_LOCALHOST_ONLY: 0
    volumes:
      - ros-workspace:/shared/workspace:rw
    # 如果驱动需要硬件访问：
    # devices:
    #   - "/dev/ttyUSB0:/dev/ttyUSB0"

volumes:
  ros-workspace:
    driver: local
  olo-appliance-data:
    driver: local

关键配置点

• network_mode: host - ROS 2 DDS发现需要，确保容器间及与主机/LAN节点通信
• ROS_DOMAIN_ID - 所有容器和外部ROS节点必须匹配
• ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET - 允许在本地子网内发现节点
• FASTDDS_BUILTIN_TRANSPORTS: UDPv4 - 强制使用UDP传输（见故障排除）
• ros-workspace卷 - 用于自定义消息类型的共享工作区
• init: true - 正确处理信号以实现优雅关闭

启动服务

bash
# 启动所有服务
docker compose up -d

# 仅启动设备
docker compose up -d olo-appliance

# 查看日志
docker compose logs -f

---

网络与端口

• 推荐：主机网络
  大多数设置中，使用主机网络（--net=host或network_mode: host）运行设备。当机器人位于同一网络的另一台计算机上时，这是ROS 2 DDS发现正常工作所必需的，因为容器需要接收多播数据包以进行节点发现。
  在此模式下不使用-p端口映射；容器直接共享主机的网络栈。

• 可选：诊断/健康API（仅桥接网络）
  如果选择不使用主机网络（Docker桥接模式），设备在容器内的8443端口公开内部HTTP端点。

  要在桥接模式下从容器外部访问（用于基本健康检查），可发布端口：

  bash
  docker run -d \
    --name olo-appliance \
    -e OLO_APL_AUTH_USERNAME="you@example.com" \
    -e OLO_APL_AUTH_PASSWORD="your-password" \
    -e OLO_APL_APPLIANCE_NAME="My Appliance" \
    -v olo-data:/data \
    -p 9443:8443 \
    olorobotics/olo-appliance:humble-latest
  

  然后例如：

  bash
  curl http://localhost:9443/health
  

  发布此端口是可选的，正常运行不需要。

• ROS 2 / DDS网络（重要）
  Docker默认桥接网络阻止多播流量，而ROS 2 DDS依赖多播进行节点发现。如果机器人运行在同一网络的另一台计算机上，不使用主机网络时设备将无法发现机器人。

  使用主机网络时，不使用-p端口映射（容器直接共享主机端口）。

---

数据持久化

设备将所有持久数据存储在容器内的/data目录下。此统一目录包含：

• /data/recordings/rosbags - ROS bag记录
• /data/script-logs - 脚本执行日志
• /data/cached-scripts - 缓存的脚本
• /data/scheduled-scripts - 计划脚本数据
• /data/cache/olo-client - OLO客户端缓存

推荐：使用命名卷实现重启间的数据持久化：

bash
docker volume create olo-data

docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_AUTH_USERNAME="you@example.com" \
  -e OLO_APL_AUTH_PASSWORD="your-password" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

或使用Docker Compose：

yaml
services:
  olo-appliance:
    image: olorobotics/olo-appliance:humble-latest
    network_mode: host
    environment:
      OLO_APL_AUTH_USERNAME: "you@example.com"
      OLO_APL_AUTH_PASSWORD: "your-password"
      OLO_APL_APPLIANCE_NAME: "My Appliance"
    volumes:
      - olo-data:/data

volumes:
  olo-data:
    driver: local

---

故障排除

ROS 2 DDS发现问题

如果ROS 2节点无法相互发现（主题不可见、服务未找到），尝试强制DDS传输为UDPv4：

yaml
environment:
  FASTDDS_BUILTIN_TRANSPORTS: UDPv4

或通过命令行：

bash
docker run -d \
  --net=host \
  --name olo-appliance \
  -e OLO_APL_AUTH_USERNAME="you@example.com" \
  -e OLO_APL_AUTH_PASSWORD="your-password" \
  -e OLO_APL_APPLIANCE_NAME="My Appliance" \
  -e FASTDDS_BUILTIN_TRANSPORTS="UDPv4" \
  -v olo-data:/data \
  olorobotics/olo-appliance:humble-latest

这在以下情况特别有用：

• 同一主机上运行多个容器
• 容器无法看到其他容器或主机的主题
• 使用特定网络配置或***

其他DDS配置

如需更多ROS 2发现控制：

yaml
environment:
  ROS_DOMAIN_ID: 55                          # 所有节点保持一致
  ROS_AUTOMATIC_DISCOVERY_RANGE: SUBNET      # 发现本地子网节点
  ROS_LOCALHOST_ONLY: 0                      # 允许非本地主机通信
  FASTDDS_BUILTIN_TRANSPORTS: UDPv4          # 强制UDP传输

认证问题

• 验证环境变量或.env文件中的凭据
• 检查与OLO后端的网络连接
• 查看日志：docker logs olo-appliance

端口冲突

• 如果8443端口被占用，更改主机端口映射：-p 9443:8443
• 使用主机网络时，确保没有其他服务使用8443端口