EMQX云端服务器日常使用手册EMQX云端服务器日常使用手册 📖 文档说明本文档适用于已经部署好 EMQX 云端服务

EMQX云端服务器日常使用手册

📖 文档说明

本文档适用于已经部署好 EMQX 云端服务器的用户。

如果你是首次部署，请先查看《基于阿里云ECS与EMQX的无人机-地面站MATT通信系统搭建实战》。

🎯 适用场景

✅ 每次使用系统前的准备工作
✅ 日常启动无人机端和地面站
✅ 长期未使用后重新启动系统
✅ 遇到连接问题时的排查

📋 目录

每次使用前的准备
无人机端连接步骤
地面站连接步骤
使用完毕后
长期未使用后的恢复
常见问题排查
快速参考

1️⃣ 每次使用前的准备

1.1 检查服务器状态（可选）

如果你不确定服务器是否在运行，可以检查：

方法一：访问 Dashboard

打开浏览器，访问：

http://你的服务器公网IP:18083

示例：http://123.45.67.89:18083

✅ 如果能打开登录页面，说明服务器正常运行
❌ 如果无法访问，需要登录服务器检查

方法二：登录阿里云控制台

访问：ecs.console.aliyun.com/
查看服务器状态
如果显示"运行中"，说明服务器正常

1.2 检查 EMQX 服务状态（可选）

如果 Dashboard 无法访问，需要登录服务器检查：

# 登录服务器
ssh root@你的服务器公网IP

# 检查 EMQX 状态
sudo systemctl status emqx

正常输出：

Active: active (running)

如果服务未运行，执行：

sudo systemctl start emqx

1.3 启动 EMQX（如果未运行）

# 启动 EMQX
sudo systemctl start emqx

# 验证启动成功
sudo systemctl status emqx

# 检查端口监听
sudo lsof -i :1883

说明：

如果 EMQX 已配置开机自启（推荐），通常不需要手动启动
只有在服务器重启或 EMQX 异常停止时才需要手动启动

2️⃣ 无人机端连接步骤

2.1 确保 4G 网络连接

检查 4G 模块：
- 确保 4G 模块已插入
- 检查 SIM 卡是否欠费
检查网络连接：
- 右键点击任务栏网络图标
- 确认"移动网络"或"蜂窝网络"已连接

测试网络连通性（可选）：

# 测试到云端 EMQX 的连接
Test-NetConnection -ComputerName 你的服务器公网IP -Port 1883

应该显示：TcpTestSucceeded : True

2.2 启动无人机端程序

运行程序：
查看连接状态：
验证连接成功：

2.3 开始数据采集

连接设备
开始采集

3️⃣ 地面站连接步骤

3.1 启动地面站程序

运行程序
检查连接配置

3.2 连接到云端 EMQX

输入ID
点击 Connect 按钮
验证连接成功

3.3 接收和显示点云数据

等待数据：
- 连接成功后，地面站会自动订阅相关 Topic
- 等待无人机端发送数据
查看点云显示：
- 视图中应该能看到点云数据
- 统计信息更新（Data Rate、Points 等）

4️⃣ 使用完毕后

4.1 断开客户端连接

4.2 是否需要停止 EMQX？

建议：保持 EMQX 服务运行

✅ 优点：下次使用时无需手动启动，即开即用
✅ 成本：云服务器按月计费，停止服务不会节省费用
⚠️ 注意：如果长期不使用（如 1 个月以上），可以考虑停止服务器以节省费用

如果确实需要停止 EMQX：

# 登录服务器
ssh root@你的服务器公网IP

# 停止 EMQX
sudo systemctl stop emqx

5️⃣ 长期未使用后的恢复

5.1 服务器状态检查

如果很久没用系统了（如 1 个月以上），需要检查：

检查服务器是否运行

登录阿里云控制台：
- 访问：ecs.console.aliyun.com/
- 查看服务器状态
如果服务器已停止：
- 点击"启动"按钮
- 等待服务器启动（约 1-2 分钟）

检查公网 IP 是否变化

⚠️ 重要：如果服务器重启或停止后再启动，公网 IP 可能会变化！

在阿里云控制台查看：
- 在实例列表中，查看"IP 地址"列
- 记录当前的公网 IP

或登录服务器查看：

# 登录服务器
ssh root@旧的公网IP  # 如果 IP 变了，这个命令会失败

# 查看当前公网 IP
curl ifconfig.me

如果 IP 变化了：
- 需要修改无人机端和地面站的配置
- 重新编译程序
- 见下文"5.3 客户端重新连接"

5.2 EMQX 服务恢复

登录服务器

ssh root@你的服务器公网IP

检查 EMQX 状态

sudo systemctl status emqx

可能的情况：

Active: active (running) ✅
- EMQX 正常运行，无需操作
Active: inactive (dead) ⚠️
- EMQX 未运行，需要启动
Active: failed ❌
- EMQX 启动失败，需要排查问题

启动 EMQX（如果未运行）

# 启动 EMQX
sudo systemctl start emqx

# 等待 5 秒
sleep 5

# 检查状态
sudo systemctl status emqx

如果启动失败，查看日志：

sudo journalctl -u emqx -n 50

常见问题见"6.5 EMQX 服务启动失败"。

验证端口监听

# 检查 MQTT 端口
sudo lsof -i :1883

# 检查 Dashboard 端口
sudo lsof -i :18083

正确的输出：

COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
beam.smp 1234 emqx   45u  IPv4  12345      0t0  TCP *:1883 (LISTEN)

5.3 客户端重新连接

如果服务器 IP 没有变化

直接启动无人机端和地面站程序，按照第 2、3 节的步骤连接即可。

如果服务器 IP 变化了

需要修改配置并重新编译：

1. 修改无人机端配置

文件：SPDLiDAR-Drone/src/ui/MainWindow.cpp（第 497 行）

// 修改前
const QString MQTT_BROKER_HOST = "47.100.230.135";  // 旧 IP

// 修改后
const QString MQTT_BROKER_HOST = "新的公网IP";  // 新 IP

2. 修改地面站配置

文件：PointCloudViewer-MQTT/src/MainWindow.cpp（第 54 行）

// 修改前
m_brokerHostEdit = new QLineEdit("47.100.230.135", this);  // 旧 IP

// 修改后
m_brokerHostEdit = new QLineEdit("新的公网IP", this);  // 新 IP

3. 重新编译

在 Qt Creator 中重新构建两个项目
或使用命令行编译

4. 测试连接

按照第 2、3 节的步骤测试连接。

6️⃣ 常见问题排查

6.1 问题：服务器重启后 EMQX 文件消失

症状：

服务器重启后，EMQX 无法启动
提示找不到 EMQX 文件

原因：

使用 tar.gz 解压到临时目录（如 /opt）
临时目录在重启后可能被清空

解决方案：

✅ 使用 APT 包管理器安装 EMQX（推荐）
❌ 不要使用 tar.gz 手动解压安装

正确的安装方法：

curl -s https://assets.emqx.com/scripts/install-emqx-deb.sh | sudo bash
sudo apt-get install emqx -y
sudo systemctl enable emqx

6.2 问题：无人机端连接超时（Connection timeout）

症状：

[WARN] Still in Connecting state after 2000 ms - possible connection issue
[FAULT] Still in Connecting state after 10000 ms - connection timeout
[FAULT] MQTT client error: Connection timeout (10 seconds)

原因：

配置中使用 localhost 而非公网 IP
网络不通
防火墙阻止连接

解决方案：

1. 检查配置

文件：SPDLiDAR-Drone/src/ui/MainWindow.cpp（第 497 行）

// 错误配置
const QString MQTT_BROKER_HOST = "localhost";  // ❌

// 正确配置
const QString MQTT_BROKER_HOST = "47.100.230.135";  // ✅ 使用公网 IP

2. 测试网络连通性

Test-NetConnection -ComputerName 你的服务器公网IP -Port 1883

如果显示 TcpTestSucceeded : False，说明网络不通，检查：

阿里云安全组是否开放 1883 端口
服务器防火墙是否允许 1883 端口
4G 网络是否正常

3. 检查 EMQX 是否运行

ssh root@你的服务器公网IP
sudo systemctl status emqx
sudo lsof -i :1883

6.3 问题：地面站连接失败

症状：

点击 Connect 按钮后无响应
或提示连接失败

原因：

界面输入框中仍是 localhost
Drone ID 输入错误

解决方案：

1. 检查界面输入

Broker Host：必须是服务器公网 IP（如 47.100.230.135）
Port：1883
Drone ID：drone001（必须和无人机端一致）

2. 修改默认值（可选）

文件：PointCloudViewer-MQTT/src/MainWindow.cpp（第 54 行）

m_brokerHostEdit = new QLineEdit("47.100.230.135", this);  // 设置为公网 IP

重新编译后，默认值就是公网 IP 了。

6.4 问题：不知道应该连接哪个 IP

症状：

在服务器上执行 ifconfig，看到多个 IP 地址
不知道应该使用哪个

示例输出：

eth0: inet 172.22.77.100      ← 内网 IP
lo:   inet 127.0.0.1          ← 本地回环

原因：

ifconfig 显示的是内网 IP（如 172.22.77.100）
内网 IP 无法从外部访问

解决方案：

使用以下命令获取公网 IP：

curl ifconfig.me

输出示例：

47.100.230.135  ← 这才是公网 IP

或在阿里云控制台查看：

进入 ECS 控制台
在实例列表的"IP 地址"列查看公网 IP

6.5 问题：EMQX 服务启动失败（exit-code）

症状：

Active: failed (Result: exit-code)

原因：

端口被占用
进程冲突

解决方案：

1. 杀死冲突进程

# 杀死所有 EMQX 相关进程
sudo pkill -9 beam.smp

# 等待 2 秒
sleep 2

# 重启 EMQX
sudo systemctl start emqx

2. 检查端口占用

# 检查 1883 端口是否被占用
sudo lsof -i :1883

# 如果有其他进程占用，杀死它
sudo kill -9 <PID>

3. 查看详细日志

sudo journalctl -u emqx -n 100

根据日志提示进一步排查。

6.6 问题：防火墙配置问题

症状：

本地测试连接成功（localhost）
远程连接失败（公网 IP）

原因：

阿里云安全组未开放端口
服务器防火墙阻止连接

解决方案：

1. 检查阿里云安全组

登录阿里云控制台
进入"网络与安全" → "安全组"
检查入方向规则是否包含：
- 1883/1883 - TCP - 0.0.0.0/0

2. 检查服务器防火墙

# 检查防火墙状态
sudo ufw status

# 如果防火墙开启，允许 1883 端口
sudo ufw allow 1883

# 重新加载防火墙
sudo ufw reload

6.7 问题：带宽不足，数据传输卡顿

症状：

地面站接收数据延迟严重
点云显示卡顿
Dashboard 显示大量消息积压

原因：

服务器带宽不足（1M 带宽 = 125 KB/s）
点云数据量过大（未优化时约 1.5 MB/s）

解决方案：

方案一：升级带宽（推荐）

在阿里云控制台升级带宽到 3M 或 5M
立即生效，无需重启服务器

方案二：数据优化

实施数据降采样和压缩：

降采样：10,000 点 → 5,000 点
压缩：qCompress 压缩率 70%
预期带宽：1.5 MB/s → 220 KB/s

详见《agent20251121.md》中的"数据优化"章节。

7️⃣ 快速参考

7.1 配置信息速查表

服务器信息

项目	值	说明
公网 IP	`123.45.67.89`	替换为你的实际 IP
MQTT 端口	`1883`	标准 MQTT 端口
MQTT SSL 端口	`8883`	加密连接端口（可选）
Dashboard 端口	`18083`	Web 管理界面
Dashboard 账号	`admin`	默认用户名
Dashboard 密码	`你修改后的密码`	建议修改默认密码

无人机端配置

项目	值	文件位置
Broker Host	`123.45.67.89`	`SPDLiDAR-Drone/src/ui/MainWindow.cpp:497`
Broker Port	`1883`	`SPDLiDAR-Drone/src/ui/MainWindow.cpp:498`
Client ID	`drone001`	`SPDLiDAR-Drone/src/ui/MainWindow.cpp:499`

地面站配置

项目	值	文件位置
Broker Host	`123.45.67.89`	`PointCloudViewer-MQTT/src/MainWindow.cpp:54`
Broker Port	`1883`	界面输入
Drone ID	`drone001`	界面输入（必须和无人机端一致）

Topic 结构

Topic	用途	发布者	订阅者
`lidar/drone001/pointcloud`	点云数据	无人机端	地面站
`lidar/drone001/frame_end`	帧结束标记	无人机端	地面站
`lidar/drone001/coord_range`	坐标范围	无人机端	地面站
`lidar/drone001/status`	状态信息	无人机端	地面站

7.2 常用命令速查表

EMQX 服务管理

# 启动 EMQX
sudo systemctl start emqx

# 停止 EMQX
sudo systemctl stop emqx

# 重启 EMQX
sudo systemctl restart emqx

# 查看状态
sudo systemctl status emqx

# 查看日志（实时）
sudo journalctl -u emqx -f

# 查看日志（最近 100 行）
sudo journalctl -u emqx -n 100

# 启用开机自启
sudo systemctl enable emqx

# 禁用开机自启
sudo systemctl disable emqx

# 检查是否已启用开机自启
sudo systemctl is-enabled emqx

网络检查

# 查看公网 IP（在服务器上执行）
curl ifconfig.me

# 检查端口监听
sudo lsof -i :1883
sudo lsof -i :18083

# 检查防火墙状态
sudo ufw status

# 允许端口
sudo ufw allow 1883
sudo ufw allow 18083

# 测试端口连通性（在客户端执行）
# PowerShell:
Test-NetConnection -ComputerName 123.45.67.89 -Port 1883

# Linux/Mac:
telnet 123.45.67.89 1883
nc -zv 123.45.67.89 1883

系统信息

# 查看 EMQX 版本
emqx version

# 查看系统资源使用
top
htop

# 查看磁盘使用
df -h

# 查看内存使用
free -h

# 查看网络连接
netstat -tunlp | grep 1883

7.3 重要文件路径

无人机端

文件	路径	说明
MQTT 配置	`SPDLiDAR-Drone/src/ui/MainWindow.cpp`	第 497-499 行
MQTT 客户端实现	`SPDLiDAR-Drone/src/network/MQTTClient.cpp`	MQTT 发布逻辑
可执行文件	`SPDLiDAR-Drone/bin/SPD-LiDAR-Drone.exe`	编译后的程序
日志文件	`SPDLiDAR-Drone/log8.txt`	运行日志

地面站

文件	路径	说明
MQTT 配置	`PointCloudViewer-MQTT/src/MainWindow.cpp`	第 54 行
MQTT 订阅者实现	`PointCloudViewer-MQTT/src/MQTTSubscriber.cpp`	MQTT 订阅逻辑
可执行文件	`PointCloudViewer-MQTT/bin/PointCloudViewer.exe`	编译后的程序

服务器端（EMQX）

文件/目录	路径	说明
EMQX 配置文件	`/etc/emqx/emqx.conf`	主配置文件
EMQX 数据目录	`/var/lib/emqx/`	数据存储
EMQX 日志目录	`/var/log/emqx/`	日志文件
EMQX 安装目录	`/usr/lib/emqx/`	程序文件
Systemd 服务文件	`/lib/systemd/system/emqx.service`	服务配置

7.4 快速诊断流程

问题：无法连接到 EMQX

1. 检查服务器是否运行
   ↓
2. 检查 EMQX 服务是否运行
   ↓
3. 检查端口是否监听
   ↓
4. 检查防火墙配置
   ↓
5. 检查客户端配置（IP、端口）
   ↓
6. 测试网络连通性

快速检查命令：

# 在服务器上执行
sudo systemctl status emqx          # 检查服务状态
sudo lsof -i :1883                  # 检查端口监听
sudo ufw status                     # 检查防火墙
curl ifconfig.me                    # 获取公网 IP

# 在客户端执行
Test-NetConnection -ComputerName 你的服务器IP -Port 1883

7.5 Dashboard 常用功能

访问 Dashboard

http://你的服务器公网IP:18083

主要功能

客户端管理（左侧菜单 → 客户端 → 连接管理）
- 查看当前连接的客户端
- 查看客户端 IP、连接时间
- 强制断开客户端
订阅管理（左侧菜单 → 客户端 → 订阅管理）
- 查看客户端订阅的 Topic
- 查看订阅的 QoS 级别
消息统计（左侧菜单 → 监控 → 统计）
- 查看消息发送/接收速率
- 查看连接数统计
用户管理（右上角用户图标 → 用户管理）
- 修改密码
- 添加新用户

7.6 联系方式和资源

官方文档

EMQX 官方文档：www.emqx.io/docs/zh/v5.…
Qt MQTT 文档：doc.qt.io/qt-6/qtmqtt…
阿里云帮助中心：help.aliyun.com/

项目文档

首次部署指南：SPDLiDAR-Drone/doc/EMQX云端部署完整指南.md
工作总结：SPDLiDAR-Drone/doc/agent20251121.md
客户部署指南：SPDLiDAR-Drone/doc/操作步骤.md

📝 使用检查清单

每次使用前

服务器正常运行
EMQX 服务正常运行
无人机端 4G 网络连接正常
无人机端程序成功连接到云端
地面站程序成功连接到云端
Dashboard 中能看到两个客户端连接

使用过程中

点云数据正常传输
地面站显示正常
无明显延迟或卡顿
无错误日志

使用完毕后

无人机端程序已关闭
地面站程序已关闭
EMQX 服务保持运行（推荐）

🎯 总结

日常使用流程

1. 检查服务器和 EMQX 状态（可选）
   ↓
2. 启动无人机端程序（自动连接）
   ↓
3. 启动地面站程序并连接
   ↓
4. 开始数据采集和传输
   ↓
5. 使用完毕后关闭程序

长期未用后恢复流程

1. 检查服务器状态和公网 IP
   ↓
2. 检查并启动 EMQX 服务
   ↓
3. 如果 IP 变化，修改配置并重新编译
   ↓
4. 测试连接

文档版本：v1.0 创建日期：2025-11-21 适用版本：EMQX 5.8.8、Ubuntu 22.04/24.04

祝使用愉快！ 🚀