校园智巡 Nav Console — 部署与启动手册
适用环境：Xavier NX（Ubuntu 22.04 + ROS 2 Humble）+ 开发/上位机电脑（Windows/macOS/Linux）
目录
1. 系统架构
┌─────────────────────────────┐ 局域网 / 直连
│ 上位机（电脑/平板） │ ←──────────────────────→ Xavier NX
│ │ WebSocket :9090
│ 浏览器 │ ┌─────────────────────┐
│ └── Nav Console (React) │ │ rosbridge_websocket │
│ ├── 高德地图 │ │ Nav2 导航栈 │
│ ├── 机器人状态显示 │ │ robot_localization │
│ ├── 航点规划 & 发送 │ │ UM982 GPS 驱动 │
│ └── 手动控制 │ │ LiDAR 驱动 │
└─────────────────────────────┘ └─────────────────────┘2. 前置条件
上位机（开发电脑）
| 依赖 | 版本要求 | 验证命令 |
|------|---------|---------|
| Node.js | ≥ 18 | node -v |
| npm | ≥ 9 | npm -v |
| Git | 任意 | git --version |
# 克隆项目
git clone https://github.com/ana52070/carplannning-web.git
cd carplannning-web
# 安装依赖
npm installXavier NX
Ubuntu 22.04
ROS 2 Humble（已 source）
与上位机在同一局域网或直连
3. 配置文件说明
所有需要修改的参数集中在 src/config/index.ts：
export const CONFIG = {
// 高德地图 Web JS API Key
// 申请地址：https://console.amap.com/
AMAP_KEY: '你的_API_Key',
// JS API 2.0 安全密钥（与 Key 配套，缺少则地图瓦片被静默拦截）
// 在高德控制台「应用管理 → 设置 → JS API 安全密钥」获取
AMAP_SECURITY_CODE: '你的_Security_Code',
// rosbridge WebSocket 地址（填 Xavier NX 的实际 IP）
ROSBRIDGE_URL: 'ws://192.168.1.100:9090',
// 地图默认中心点（天津理工大学中环信息学院）
MAP_CENTER: {
lng: 117.3246,
lat: 39.1078,
},
MAP_ZOOM: 18,
TOPICS: {
ODOM: '/odometry/filtered', // robot_localization 输出
GOAL_POSE: '/goal_pose', // Nav2 目标点输入
CMD_VEL: '/cmd_vel', // 速度控制
GPS_FIX: '/gps/fix', // UM982 GPS（按实际话题名修改）
LIDAR: '/livox/lidar',
NAV_STATUS: '/navigate_to_pose/_action/status',
},
};注意：
AMAP_KEY和AMAP_SECURITY_CODE不要提交到公开仓库。建议将真实密钥写在本地.env.local（已在.gitignore中）并通过import.meta.env读取，config 文件只保留占位符。
4. Web 控制台 — 开发模式
适用于日常开发调试，热更新，实时看改动效果。
# 在项目根目录执行
npm run dev启动成功后输出：
VITE v8.x.x ready in xxx ms
➜ Local: http://localhost:5173/
➜ Network: http://192.168.x.x:5173/用浏览器打开 http://localhost:5173，或在同一局域网的其他设备访问 Network 那个地址。
开发常用命令：
npm run dev # 启动开发服务器（HMR 热更新）
npm run build # 类型检查 + 构建生产包 → dist/
npm run lint # ESLint 检查
npm run preview # 本地预览 dist/ 构建产物5. Web 控制台 — 生产部署到 Xavier NX
将控制台作为静态网站部署在 Xavier NX 上，机器人上电后用局域网内任意浏览器访问。
5.1 在开发电脑上构建
npm run build产物在 dist/ 目录，整个目录传到 Xavier NX：
# 替换 xavier-ip 为实际地址，替换 your-user 为 Xavier NX 用户名
scp -r dist/ your-user@xavier-ip:/home/your-user/nav-console-dist/5.2 在 Xavier NX 上安装 nginx
sudo apt update
sudo apt install nginx -y5.3 配置 nginx
sudo nano /etc/nginx/sites-available/nav-console写入以下内容（按实际路径修改 root）：
server {
listen 8080;
server_name _;
root /home/your-user/nav-console-dist;
index index.html;
# SPA 路由支持
location / {
try_files $uri $uri/ /index.html;
}
# 允许局域网访问
allow 192.168.0.0/16;
deny all;
}
# 启用站点
sudo ln -s /etc/nginx/sites-available/nav-console /etc/nginx/sites-enabled/
sudo nginx -t # 检查配置语法
sudo systemctl restart nginx
sudo systemctl enable nginx # 开机自启5.4 访问
在局域网内任意设备浏览器打开：
http://192.168.1.100:8080（192.168.1.100 替换为 Xavier NX 实际 IP）
6. Xavier NX：安装并启动 rosbridge
6.1 安装
sudo apt update
sudo apt install ros-humble-rosbridge-server -y6.2 单次启动（调试用）
source /opt/ros/humble/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml启动成功输出：
[INFO] [rosbridge_websocket]: Rosbridge WebSocket server started on port 9090如需指定端口或关闭 SSL：
ros2 launch rosbridge_server rosbridge_websocket_launch.xml \
port:=9090 \
ssl:=false6.3 开机自启（systemd 服务）
sudo nano /etc/systemd/system/rosbridge.service写入：
[Unit]
Description=ROS 2 rosbridge WebSocket Server
After=network.target
[Service]
Type=simple
User=your-user
Environment="HOME=/home/your-user"
ExecStartPre=/bin/bash -c 'source /opt/ros/humble/setup.bash'
ExecStart=/bin/bash -c 'source /opt/ros/humble/setup.bash && \
ros2 launch rosbridge_server rosbridge_websocket_launch.xml'
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable rosbridge
sudo systemctl start rosbridge
# 查看状态
sudo systemctl status rosbridge
# 查看实时日志
journalctl -u rosbridge -f6.4 防火墙放行 9090 端口
sudo ufw allow 9090/tcp
sudo ufw status7. 连接验证
7.1 确认 rosbridge 在监听
在 Xavier NX 上：
ss -tlnp | grep 9090输出应包含：
LISTEN 0 5 0.0.0.0:9090 ...7.2 从上位机 ping Xavier NX
ping 192.168.1.100确保网络通畅。
7.3 用浏览器 WebSocket 测试（可选）
在浏览器控制台（F12 → Console）执行：
const ws = new WebSocket('ws://192.168.1.100:9090');
ws.onopen = () => console.log('✅ rosbridge 连接成功');
ws.onerror = (e) => console.error('❌ 连接失败', e);7.4 在控制台界面操作
打开 Nav Console
右侧面板「连接」区域确认地址为
ws://192.168.1.100:9090点击「连接」
顶部状态栏变绿显示「已连接」
8. 话题速查表
连接后可在 Xavier NX 上用以下命令确认话题实际名称：
source /opt/ros/humble/setup.bash
ros2 topic list| 控制台功能 | 话题 | 消息类型 | 方向 |
|-----------|------|---------|------|
| 里程计（位置/速度/朝向） | /odometry/filtered | nav_msgs/Odometry | 订阅 |
| GPS 定位（RTK 状态） | /gps/fix | sensor_msgs/NavSatFix | 订阅 |
| 局部代价地图 | /local_costmap/costmap | nav_msgs/OccupancyGrid | 订阅 |
| 发送导航目标 | /goal_pose | geometry_msgs/PoseStamped | 发布 |
| 手动控制速度 | /cmd_vel | geometry_msgs/Twist | 发布 |
如果 GPS 话题名不是
/gps/fix，修改src/config/index.ts中的TOPICS.GPS_FIX即可，无需改其他代码。
9. 常见问题
Q1：控制台连接后立刻断开 / 状态一直是「连接中」
# 检查 rosbridge 进程是否在跑
ros2 node list | grep rosbridge
# 检查端口
ss -tlnp | grep 9090
# 检查防火墙
sudo ufw statusQ2：地图显示黑屏
原因按概率排序：
缺少安全密钥：
AMAP_SECURITY_CODE为空。高德 2021 年后的 Key 必须配套安全密钥，缺少时瓦片请求被静默拦截，无 JS 报错。API Key 无效或域名未白名单：检查高德控制台应用设置中允许的域名（开发时填
localhost，生产时填 Xavier NX IP）。网络问题：确认能访问
webst01.is.autonavi.com（高德瓦片服务器）。
Q3：机器人标记位置偏差数百米
控制台已内置 WGS84 → GCJ02 坐标转换，机器人 GPS（UM982 输出 WGS84）会自动修正后显示在高德地图上。
如果仍有偏差，确认 UM982 驱动发布的是原始 WGS84 坐标，未经任何预处理。
Q4：发送导航目标后机器人走到错误位置
当前 sendGoal 将地图点击的 GCJ02 经纬度直接作为 map frame 的 x/y 传给 Nav2，这是占位实现。
正确做法取决于导航栈坐标系设置：
robot_localization+navsat_transform（最常见）：
```
目标 x = (目标WGS84_lng - 地图原点_lng) × 111320 × cos(原点纬度)
目标 y = (目标WGS84_lat - 地图原点_lat) × 111320
```
地图原点可从话题 /navsat_transform/gps_origin 获取。
- 纯 GPS 导航：消息类型需改为
geographic_msgs/GeoPose，话题也需对应修改。
Q5：手动控制按钮无响应
手动控制需要 rosbridge 已连接，且 /cmd_vel 话题有节点订阅（底盘驱动在跑）。
检查：
ros2 topic echo /cmd_vel # 按按钮时应该有输出
ros2 node list # 确认底盘驱动节点在线Q6：代价地图没有显示
代价地图叠加层在 rosbridge 连接后自动生效，依赖 /local_costmap/costmap 话题。
确认话题存在且有数据：
ros2 topic hz /local_costmap/costmap # 应该有持续更新频率如话题名不同，修改 src/hooks/useROS.ts 中 costmapSub 的 name 字段。
文档最后更新：2026-06