# Robot

**Repository Path**: lft1011/robot

## Basic Information

- **Project Name**: Robot
- **Description**: 机器人仿真
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Robot Test Platform 2.0

面向多人协作和 ROS 2 机器人算法验证的平台。当前唯一运行架构位于 `apps/`、`ros2_ws/` 和 `deploy/`，平台数据统一使用 PostgreSQL 持久化。

## 分层

- `apps/api`：FastAPI API、PostgreSQL 持久化、SSE 运行事件。
- `apps/worker`：Redis 队列消费者，负责异步执行测试任务。
- `apps/agent`：Ubuntu 24.04 本地 Agent，通过出站 HTTPS 领取绑定任务并调用 ROS 2。
- `apps/web`：Vue 3 + TypeScript 前端控制台。
- `ros2_ws/src/robot_test_simulation`：`rclpy` 仿真适配器，发布 `/odom`、`/scan` 并订阅 `/cmd_vel`。
- `ros2_ws/src/robot_test_control_cpp`：C++ 安全控制节点，限制速度后发布 `/safe_cmd_vel`。
- `ros2_ws/src/robot_test_interfaces`：ROS 2 `NavigateToPose` Action 接口。

## 启动

```powershell
docker compose up -d --build
```

多人平台启动后访问 `http://127.0.0.1:8080`。首次启动会自动执行 Alembic 数据库迁移。开发前端可在 `apps/web` 目录执行 `npm install` 和 `npm run dev`。

云服务器使用 `docker compose -f compose.production.yaml up -d --build`。生产编排由 Caddy 在 `80/443` 端口提供域名访问并自动续期 HTTPS 证书，Web、PostgreSQL、Redis 和 FastAPI 仅在 Compose 内部网络中访问；启动前必须在 `.env` 设置 `POSTGRES_PASSWORD`、`REDIS_PASSWORD`、`AUTH_SECRET` 和 `PUBLIC_ORIGIN`。

后续发布可在服务器执行 `bash ops/deploy-production.sh`，脚本会快进同步 `master`、执行生产数据库迁移、重建服务并等待 `/api/ready` 通过；它不会删除 PostgreSQL 或 Redis 数据卷。

## 接口文档

平台接口由 FastAPI 自动生成 OpenAPI 文档，字段说明、约束、请求/响应示例与代码中的 Pydantic 模型同步：

- `/docs`：面向平台开发者和测试人员的 Swagger UI，可使用用户令牌在线调试。
- `/redoc`：面向外部集成方的阅读版。
- `/openapi/v1.json`：版本化公开 OpenAPI 规范；`/openapi.json` 是兼容别名。
- `/agent/docs`、`/agent/redoc` 和 `/openapi/agent-v1.json`：本机 Ubuntu Agent、Windows 桥接和 Gazebo 注入服务的内部文档。内部 Swagger 禁用在线提交。

登录后在 Swagger 的 **Authorize** 输入原始 `access_token`；页面会自动加上 Bearer 前缀。用户令牌与机器人 Agent Token 不可互换，Agent Token 不得写入浏览器或第三方客户端。当前路由仍为 `/api/...`，本次只版本化文档契约，不把已有路由改成 `/api/v1/...`，以免破坏正在运行的前端和机器人。将来若有不兼容变更，应新增路径版本并保留兼容期。

文档中导航坐标统一按当前地图的 `map` 坐标系说明：`x/y` 单位米，`yaw` 单位弧度。接口实际错误格式为 FastAPI 的 `{"detail": ...}`；不要假设尚未实现的统一业务错误码。首次对外集成建议依次调用登录、机器人列表、地图列表、创建导航任务、查询执行记录与遥测日志。

Worker 默认使用本地确定性执行器。部署到已安装 ROS 2 工作区的 Worker 后，可在运行配置中设置 `execution_mode: "ros2"`，任务会调用 `navigate_to_pose` Action；仿真节点提供对应的 Action Server。

项目所有者可以创建多个本地 Robot Agent。绑定 Agent 的任务不会进入云端 Worker 队列，而是由 Agent 主动领取；Agent 通过 `ROBOT_PLATFORM_URL` 和一次性生成的 `ROBOT_AGENT_TOKEN` 连接云端。详细的 Ubuntu 24.04 安装、模拟验收和 systemd 示例见 `apps/agent/README.md`。

登录后的默认页面显示真实机器人上传的地图、位姿、运动轨迹和传感器频率。导航实验室通过本地 ROS 2 Agent 向真实 Nav2 发送单点和多航点任务，任务状态与结果统一展示在“执行记录”中。

## 历史数据导入

已有 SQLite 测试资产可导入任意 PostgreSQL 工作区。导入会保留测试用例及版本、运行报告、逐步控制指令、测试批次和导航地图，并通过 `legacy_id` 保证重复执行不会产生副本：

```bash
python ops/import_legacy_sqlite.py /path/to/robot-test.db --project robot-test-platform
```

迁移后的历史数据仍保存在 PostgreSQL 中；当前 TypeScript 控制台聚焦地图管理、导航实验室和 Nav2 执行记录。原始 SQLite 文件仅作为迁移来源，不再作为生产数据库。

运行任务支持项目级取消和重试：编辑者可以取消排队中或执行中的任务，失败任务可以重新排队；创建任务时可设置 `max_attempts`（1-5），Worker 会记录当前尝试次数并对执行异常进行指数退避重试。任务状态包括 `queued`、`running`、`cancel_requested`、`cancelled`、`completed`、`failed` 和 `error`。

共享环境启动前应在 `.env` 中设置独立的 `POSTGRES_PASSWORD`、`REDIS_PASSWORD` 和 `AUTH_SECRET`。ROS 2 工作区需要在已安装 ROS 2 的 Linux/WSL 环境中执行 `colcon build`。