# roboflow_studio

**Repository Path**: xiaobairisk/roboflow_studio

## Basic Information

- **Project Name**: roboflow_studio
- **Description**: 基于 Web 的机器人管理平台，支持 3D 可视化、远程遥控、实时监控。技术栈：Vue 3 + Three.js + Foxglove WebSocket。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-01-06
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 RoboFlow Studio

<p align="center">
  <img src="assets/picture/首页.png" alt="RoboFlow Studio" width="100%">
</p>

<p align="center">
  <strong>开源的 Web 端机器人管理与可视化平台</strong>
</p>

<p align="center">
  <a href="#-核心特性">核心特性</a> •
  <a href="#-技术架构">技术架构</a> •
  <a href="#-快速开始">快速开始</a> •
  <a href="#-项目结构">项目结构</a> •
  <a href="#-贡献指南">贡献指南</a>
</p>

<p align="center">
  <a href="https://github.com/xiaobairisk/roboflow_studio/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
  </a>
  <img src="https://img.shields.io/badge/Vue-3.4-brightgreen.svg" alt="Vue 3">
  <img src="https://img.shields.io/badge/TypeScript-5.3-blue.svg" alt="TypeScript">
  <img src="https://img.shields.io/badge/Three.js-0.182-black.svg" alt="Three.js">
  <img src="https://img.shields.io/badge/ROS2-Humble%2FIron-orange.svg" alt="ROS2">
</p>

---

## 🎯 项目简介

RoboFlow Studio 是一个**完全开源**的 Web 端机器人管理平台，专为 ROS/ROS2 机器人设计。它提供了从单机器人远程控制到多机器人调度的完整解决方案，让你可以通过浏览器随时随地监控和操作你的机器人。

**🌐 在线演示**: [http://39.106.224.176](http://39.106.224.176) (账号: admin / admin123)

### 为什么选择 RoboFlow Studio？

| 痛点 | RoboFlow 的解决方案 |
|------|---------------------|
| RViz 只能本地使用 | 基于 Web，任何设备都能访问 |
| 多机器人管理困难 | 统一的车队管理界面 |
| 远程调试不便 | 内置 Web 终端，远程 SSH |
| 数据可视化单一 | 3D 点云、激光雷达、相机多维展示 |
| 部署复杂 | Docker 一键部署，开箱即用 |

---

## ✨ 核心特性

### 🗺️ 3D 可视化引擎
- **点云地图** - 实时渲染 PCD/PointCloud2 数据，支持大文件（1GB+）
- **栅格地图** - OccupancyGrid 地图显示与编辑，支持 ROS YAML 配置
- **激光扫描** - LaserScan 数据实时可视化
- **TF 坐标系** - 完整的坐标变换树展示
- **导航路径** - 规划路径与历史轨迹回放

### 🎮 远程遥控
- **虚拟摇杆** - 触屏友好的遥控界面
- **键盘控制** - WASD 快捷键操控
- **速度调节** - 线速度/角速度实时可调
- **紧急停止** - 一键急停保障安全

### 📊 实时监控
- **状态追踪** - 电池、CPU、内存实时监控
- **心跳检测** - 自动识别在线/离线状态
- **话题订阅** - 任意 ROS 话题实时查看
- **相机视频** - 多路视频流同时显示

### 🧭 导航功能
- **目标点导航** - 点击地图设置导航目标
- **初始位姿** - 2D Pose Estimate 位姿校准
- **路径规划** - Nav2 路径规划可视化
- **多点巡航** - 预设巡航路线自动执行

### 📋 任务调度
- **任务创建** - 可视化任务编排
- **队列管理** - 任务优先级与依赖
- **执行监控** - 实时任务状态追踪
- **历史记录** - 完整的执行日志

### 🤖 AI 智能助手
- **告警分析** - 智能诊断异常原因
- **操作指导** - 自然语言交互问答
- **知识库** - 内置机器人运维知识

### 🖥️ 远程终端
- **Web SSH** - 浏览器内直接访问机器人终端
- **多会话** - 同时管理多个终端
- **命令历史** - 完整的操作记录

### 🎮 MuJoCo 物理仿真
- **Web 端仿真** - 基于 MuJoCo WASM (v3.3.8)，浏览器内运行物理仿真
- **Livelybot Pi** - 内置小派双足机器人模型 (12 DOF)
- **ONNX 策略推理** - 支持 ONNX Runtime Web，运行真正的 RL 策略
- **模型上传** - 用户可上传自定义 .onnx 策略文件
- **交互控制** - 键盘控制机器人前进、转向 (WASD/方向键)
- **可扩展架构** - 支持添加新的机器人模型和配置

---

## 🏗️ 技术架构

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           RoboFlow Studio                                │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        Frontend (Vue 3)                          │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │   │
│  │  │ Three.js │ │ Element  │ │  Pinia   │ │ xterm.js │           │   │
│  │  │ 3D渲染   │ │  Plus    │ │ 状态管理  │ │ 终端模拟  │           │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│                          WebSocket / REST API                            │
│                                    │                                     │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                     Backend (Node.js + Express)                  │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │   │
│  │  │ Gateway  │ │ Auth/JWT │ │ SQL.js   │ │ WebSocket│           │   │
│  │  │ 网关服务  │ │ 认证授权  │ │ 数据存储  │ │ 实时通信  │           │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                          Foxglove WebSocket Protocol
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                          Robot Side (Python)                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐      │
│  │  ros2_bridge.py  │  │ foxglove_tunnel  │  │ terminal_server  │      │
│  │  ROS2 自动桥接    │  │  Foxglove 隧道   │  │   远程终端服务    │      │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘      │
│                                    │                                     │
│                              ROS2 / ROS1                                 │
└─────────────────────────────────────────────────────────────────────────┘
```

### 技术栈

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| **前端框架** | Vue 3 + TypeScript | 组合式 API，类型安全 |
| **UI 组件** | Element Plus | 企业级 UI 组件库 |
| **3D 渲染** | Three.js | WebGL 3D 图形库 |
| **状态管理** | Pinia | Vue 官方状态管理 |
| **构建工具** | Vite | 极速开发体验 |
| **后端框架** | Express + TypeScript | 轻量高效 |
| **数据库** | SQL.js (SQLite) | 零配置嵌入式数据库 |
| **通信协议** | Foxglove WebSocket | ROS 生态标准协议 |
| **机器人端** | Python + rclpy | ROS2 原生支持 |

---

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0
- Python >= 3.8 (机器人端)
- ROS2 Humble/Iron (机器人端)

### 方式一：本地开发

```bash
# 1. 克隆仓库
git clone https://github.com/xiaobairisk/roboflow_studio.git
cd roboflow_studio

# 2. 安装前端依赖
npm install

# 3. 安装后端依赖
cd server && npm install && cd ..

# 4. (可选) 如需 MuJoCo 仿真功能
# Windows: scripts\setup-mujoco.bat
# Linux/Mac: bash scripts/setup-mujoco.sh

# 5. 启动后端 (新终端)
cd server && npm run dev

# 6. 启动前端 (新终端)
npm run dev

# 7. 访问 http://localhost:5173
```

### 方式二：Docker 部署

```bash
# 使用 docker-compose 一键启动
docker-compose -f docker-compose.prod.yml up -d

# 访问 http://localhost
```

### 方式三：生产部署

详见 [DEPLOY.md](./DEPLOY.md) 完整部署指南。

### 连接机器人

机器人端客户端独立维护：[robot-client](https://gitee.com/xiaobairisk/robot-client)

```bash
# 安装
git clone https://gitee.com/xiaobairisk/robot-client.git
cd robot-client
pip install -r requirements.txt

# 启动 ROS2 桥接
python3 ros2_bridge.py -s ws://服务器地址/ws/robot -r robot-001
```

---

## 📁 项目结构

```
roboflow-studio/
├── src/                          # 前端源码
│   ├── components/               # Vue 组件
│   ├── services/                 # 服务层
│   ├── stores/                   # Pinia 状态管理
│   ├── views/                    # 页面视图
│   └── types/                    # TypeScript 类型
│
├── server/                       # 后端源码
│   ├── src/
│   │   ├── routes/               # API 路由
│   │   ├── services/             # 业务服务
│   │   ├── websocket/            # WebSocket 处理
│   │   └── db/                   # 数据库
│   └── package.json
│
├── robot-client/                 # 机器人端客户端 (git submodule)
│
├── assets/                       # 静态资源
│   ├── docs/                     # 文档
│   └── picture/                  # 截图
│
├── nginx/                        # Nginx 配置
├── deploy-full.sh                # 首次部署脚本
├── deploy-update.sh              # 更新部署脚本
├── docker-compose.prod.yml       # Docker 生产环境
└── DEPLOY.md                     # 部署指南
```

---

## ⚙️ 配置说明

### 环境变量

复制 `.env.example` 为 `.env` 并修改：

```bash
# JWT 配置
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=24h

# 服务器配置
PORT=3001
NODE_ENV=production

# AI 助手配置 (可选)
QWEN_API_KEY=your-qwen-api-key
```

### 文件上传限制

系统支持上传大型点云文件（最大 1GB），相关配置：

| 配置项 | 位置 | 默认值 |
|--------|------|--------|
| Nginx body size | nginx/nginx.conf | 1024m |
| Multer file size | server/src/routes/maps.ts | 1GB |
| 前端超时 | src/services/MapService.ts | 30分钟 |

---

## 📸 界面预览

### 监控大屏 - 多机器人状态总览
<p align="center">
  <img src="assets/picture/监控大屏.png" alt="监控大屏" width="100%">
</p>

### AI 智能助手
<p align="center">
  <img src="assets/picture/AI助手.png" alt="AI助手" width="100%">
</p>

---

## 🤝 贡献指南

我们欢迎任何形式的贡献！

### 如何贡献

1. **Fork** 本仓库
2. 创建特性分支 `git checkout -b feature/amazing-feature`
3. 提交更改 `git commit -m 'feat: add amazing feature'`
4. 推送分支 `git push origin feature/amazing-feature`
5. 提交 **Pull Request**

### 开发规范

- 使用 TypeScript 编写代码
- 遵循 Vue 3 组合式 API 风格
- 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)

---

## 📄 许可证

本项目基于 [Apache License 2.0](LICENSE) 开源。

---

## 🙏 致谢

- [Foxglove](https://foxglove.dev/) - 机器人可视化工具与 WebSocket 协议
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Three.js](https://threejs.org/) - 3D 图形库
- [ROS2](https://ros.org/) - 机器人操作系统
- [Element Plus](https://element-plus.org/) - Vue 3 UI 组件库

---

## 📬 联系我们

- 邮箱: 1245953651@qq.com
---

<p align="center">
  如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！
</p>

<p align="center">
  Made with ❤️ by the RoboFlow Community
</p>