Uni-Lab-OS/docs/developer_guide/networking_overview.md

组网部署与主从模式配置

本文档介绍 Uni-Lab-OS 的组网架构、部署方式和主从模式的详细配置。

目录

• 架构概览
• 节点类型
• 通信机制
• 典型拓扑
• 主从模式配置
• 网络配置
• 示例：多房间部署
• 故障处理
• 监控和维护

---

架构概览

Uni-Lab-OS 支持多种部署模式：

┌──────────────────────────────────────────────┐
│      Cloud Platform/Self-hosted Platform     │
│           uni-lab.bohrium.com                │
│  (Resource Management, Task Scheduling,      │
│              Monitoring)                     │
└────────────────────┬─────────────────────────┘
                     │ WebSocket / HTTP
                     │
          ┌──────────┴──────────┐
          │                     │
     ┌────▼─────┐         ┌────▼─────┐
     │  Master  │◄──ROS2──►│  Slave   │
     │   Node   │         │   Node   │
     │  (Host)  │         │ (Slave)  │
     └────┬─────┘         └────┬─────┘
          │                    │
     ┌────┴────┐          ┌────┴────┐
     │ Device A│          │ Device B│
     │ Device C│          │ Device D│
     └─────────┘          └─────────┘

---

节点类型

主节点（Host Node）

功能:

• 创建和管理全局资源
• 提供 host_node 服务
• 连接云端平台
• 协调多个从节点
• 提供 Web 管理界面

启动命令:

unilab --ak your_ak --sk your_sk -g host_devices.json

从节点（Slave Node）

功能:

• 管理本地设备
• 不连接云端（可选）
• 向主节点注册
• 执行分配的任务

启动命令:

unilab --ak your_ak --sk your_sk -g slave_devices.json --is_slave

---

通信机制

ROS2 通信

用途: 节点间实时通信

通信方式:

• Topic: 状态广播（设备状态、传感器数据）
• Service: 同步请求（资源查询、配置获取）
• Action: 异步任务（设备操作、长时间运行）

示例:

# 查看ROS2节点
ros2 node list

# 查看topic
ros2 topic list

# 查看action
ros2 action list

WebSocket 通信

用途: 主节点与云端通信

特点:

• 实时双向通信
• 自动重连
• 心跳保持

配置:

# local_config.py
BasicConfig.ak = "your_ak"
BasicConfig.sk = "your_sk"

---

典型拓扑

单节点模式

适用场景: 小型实验室、开发测试

┌──────────────────┐
│  Uni-Lab Node    │
│  ┌────────────┐  │
│  │  Device A  │  │
│  │  Device B  │  │
│  │  Device C  │  │
│  └────────────┘  │
└──────────────────┘

优点:

• 配置简单
• 无网络延迟
• 适合快速原型

启动:

unilab --ak your_ak --sk your_sk -g all_devices.json

主从模式

适用场景: 多房间、分布式设备

┌─────────────┐      ┌──────────────┐
│ Master Node │◄────►│ Slave Node 1 │
│ Coordinator │      │   Liquid     │
│ Web UI      │      │  Handling    │
└──────┬──────┘      └──────────────┘
       │
       │             ┌──────────────┐
       └────────────►│ Slave Node 2 │
                     │  Analytical  │
                     │  (NMR/GC)    │
                     └──────────────┘

优点:

• 物理分隔
• 独立故障域
• 易于扩展

适用场景:

• 设备物理位置分散
• 不同房间的设备
• 需要独立故障域
• 分阶段扩展系统

主节点:

unilab --ak your_ak --sk your_sk -g host.json

从节点:

unilab --ak your_ak --sk your_sk -g slave1.json --is_slave
unilab --ak your_ak --sk your_sk -g slave2.json --is_slave --port 8003

云端集成模式

适用场景: 远程监控、多实验室协作

      Cloud Platform
            │
    ┌───────┴────────┐
    │                │
Laboratory A    Laboratory B
(Master Node)   (Master Node)

优点:

• 远程访问
• 数据同步
• 任务调度

启动:

# 实验室A
unilab --ak your_ak --sk your_sk --upload_registry

# 实验室B
unilab --ak your_ak --sk your_sk --upload_registry

---

主从模式配置

主节点配置

1. 创建主节点设备图

host.json:

{
  "nodes": [],
  "links": []
}

2. 启动主节点

# 基本启动
unilab --ak your_ak --sk your_sk -g host.json

# 带云端集成
unilab --ak your_ak --sk your_sk -g host.json --upload_registry

# 指定端口
unilab --ak your_ak --sk your_sk -g host.json --port 8002

3. 验证主节点

# 检查ROS2节点
ros2 node list
# 应该看到 /host_node

# 检查服务
ros2 service list | grep host_node

# Web界面
# 访问 http://localhost:8002

从节点配置

1. 创建从节点设备图

slave1.json:

{
  "nodes": [
    {
      "id": "liquid_handler_1",
      "name": "液体处理工作站",
      "type": "device",
      "class": "liquid_handler",
      "config": {
        "simulation": false
      }
    }
  ],
  "links": []
}

2. 启动从节点

# 基本从节点启动
unilab --ak your_ak --sk your_sk -g slave1.json --is_slave

# 指定不同端口（如果多个从节点在同一台机器）
unilab --ak your_ak --sk your_sk -g slave1.json --is_slave --port 8003

# 跳过等待主节点（独立测试）
unilab --ak your_ak --sk your_sk -g slave1.json --is_slave --slave_no_host

3. 验证从节点

# 检查节点连接
ros2 node list

# 检查设备状态
ros2 topic echo /liquid_handler_1/status

跨节点通信

资源访问

主节点可以访问从节点的资源：

# 在主节点或其他节点调用从节点设备
ros2 action send_goal /liquid_handler_1/transfer_liquid \
  unilabos_msgs/action/TransferLiquid \
  "{source: {...}, target: {...}, volume: 100.0}"

状态监控

主节点监控所有从节点状态：

# 订阅从节点状态
ros2 topic echo /liquid_handler_1/status

# 查看所有设备状态
ros2 topic list | grep status

---

网络配置

ROS2 DDS 配置

确保主从节点在同一网络：

# 检查网络可达性
ping <slave_node_ip>

# 设置ROS_DOMAIN_ID（可选，用于隔离）
export ROS_DOMAIN_ID=42

防火墙配置

建议做法：

为了确保 ROS2 DDS 通信正常，建议直接关闭防火墙，而不是配置特定端口。ROS2 使用动态端口范围，配置特定端口可能导致通信问题。

Linux:

# 关闭防火墙
sudo ufw disable

# 或者临时停止防火墙
sudo systemctl stop ufw

Windows:

# 在Windows安全中心关闭防火墙
# 控制面板 -> 系统和安全 -> Windows Defender 防火墙 -> 启用或关闭Windows Defender防火墙

验证网络连通性

在配置完成后，使用 ROS2 自带的 demo 节点来验证跨节点通信是否正常：

在主节点机器上（激活 unilab 环境后）：

# 启动talker
ros2 run demo_nodes_cpp talker

# 同时在另一个终端启动listener
ros2 run demo_nodes_cpp listener

在从节点机器上（激活 unilab 环境后）：

# 启动talker
ros2 run demo_nodes_cpp talker

# 同时在另一个终端启动listener
ros2 run demo_nodes_cpp listener

注意：必须在两台机器上互相启动 talker 和 listener，否则可能出现只能收不能发的单向通信问题。

预期结果：

• 每台机器的 listener 应该能同时接收到本地和远程 talker 发送的消息
• 如果只能看到本地消息，说明网络配置有问题
• 如果两台机器都能互相收发消息，则组网配置正确

本地网络要求

ROS2 通信:

• 同一局域网或 VPN
• 端口：默认 DDS 端口（7400-7500）
• 组播支持（或配置 unicast）

检查连通性:

# Ping测试
ping <target_ip>

# ROS2节点发现
ros2 node list
ros2 daemon stop && ros2 daemon start

云端连接

要求:

• HTTPS (443)
• WebSocket 支持
• 稳定的互联网连接

测试连接:

# 测试云端连接
curl https://uni-lab.bohrium.com/api/v1/health

# 测试WebSocket
# 启动Uni-Lab后查看日志

---

示例：多房间部署

场景描述

• 房间 A: 主控室，有 Web 界面
• 房间 B: 液体处理室
• 房间 C: 分析仪器室

房间 A - 主节点

# host.json
unilab --ak your_ak --sk your_sk -g host.json --port 8002

房间 B - 从节点 1

# liquid_handler.json
unilab --ak your_ak --sk your_sk -g liquid_handler.json --is_slave --port 8003

房间 C - 从节点 2

# analytical.json
unilab --ak your_ak --sk your_sk -g analytical.json --is_slave --port 8004

---

故障处理

节点离线

检测:

ros2 node list  # 查看在线节点

处理:

1. 检查网络连接
2. 重启节点
3. 检查日志

从节点无法连接主节点

1. 检查网络：

   ping <host_ip>
   

2. 检查 ROS_DOMAIN_ID：

   echo $ROS_DOMAIN_ID
   

3. 使用--slave_no_host测试：

   unilab --ak your_ak --sk your_sk -g slave.json --is_slave --slave_no_host
   

通信延迟

排查:

# 网络延迟
ping <node_ip>

# ROS2话题延迟
ros2 topic hz /device_status
ros2 topic bw /device_status

优化:

• 减少发布频率
• 使用 QoS 配置
• 优化网络带宽

数据同步失败

检查:

# 查看日志
tail -f unilabos_data/logs/unilab.log | grep sync

解决:

• 检查云端连接
• 验证 AK/SK
• 手动触发同步

资源不可见

检查资源注册：

ros2 service call /host_node/resource_list \
  unilabos_msgs/srv/ResourceList

---

监控和维护

节点状态监控

# 查看所有节点
ros2 node list

# 查看话题
ros2 topic list

---

相关文档

• 最佳实践指南 - 完整的实验室搭建流程
• 安装指南 - 环境安装步骤
• 启动参数详解 - 启动参数说明
• 添加设备驱动 - 自定义设备开发
• 工作站架构 - 复杂工作站搭建

---

参考资料

• ROS2 网络配置
• DDS 配置
• Uni-Lab 云平台文档