实战：从后端 MQTT(1883) 配置到三端联调全流程

关键词：Mosquitto、FastAPI、PuppyPi、Vue、MQTT 1883、设备在线状态

场景：云服务器 122.51.12.83，后端 puppyfit，终端 puppyfit-terminal，前端 puppyfit-frontend

一、目标

本文从 后端 MQTT 配置到 1883 端口 开始，完成以下最小闭环：

PuppyPi 能连上云端 MQTT
FastAPI 能收到 PuppyPi 消息
Vue 能调用 FastAPI
设备在线状态可见（online_status）

二、环境说明

MQTT Broker：Mosquitto（云端）
MQTT 端口：1883
后端：FastAPI
终端：ROS2 工作空间
前端：Vue3

三、配置 Mosquitto（1883 + 账号密码）

1）确认主配置

/etc/mosquitto/mosquitto.conf 示例（核心项）：

conf 复制代码

listener 1883 0.0.0.0
protocol mqtt
allow_anonymous false
password_file /etc/mosquitto/passwd

说明：

allow_anonymous false：必须用户名密码登录
password_file：账号来源文件

2）创建/重置 MQTT 用户密码

bash 复制代码

sudo mosquitto_passwd /etc/mosquitto/passwd puppy_server

会交互输入两次密码（输入不回显）。

3）修复密码文件权限（关键）

如果这里不对，systemctl restart mosquitto 很容易失败。

bash 复制代码

sudo chown root:mosquitto /etc/mosquitto/passwd
sudo chmod 640 /etc/mosquitto/passwd
sudo systemctl restart mosquitto
sudo systemctl status mosquitto --no-pager -l

成功标志：

Active: active (running)

4）确认当前用户列表

bash 复制代码

sudo awk -F: '{print $1}' /etc/mosquitto/passwd

示例输出：

text 复制代码

puppy_server

四、后端接入 MQTT（puppyfit）

在后端配置中，确保 MQTT 指向云端 1883，并与 Broker 账号一致。

puppyfit/config.py 关键项（示意）：

python 复制代码

MQTT_BROKER = "122.51.*.*"
MQTT_PORT = 1883
MQTT_USERNAME = "puppy_server"
MQTT_PASSWORD = "你设置的密码"
MQTT_USE_TLS = False

建议把账号密码写入 .env，避免明文硬编码到仓库。

启动后端

bash 复制代码

cd /home/ubuntu/puppyfit
python main.py
# 或
uvicorn main:app --host 0.0.0.0 --port 8000

检查健康状态：

bash 复制代码

curl http://127.0.0.1:8000/health

关注字段：

services.mqtt 应为 connected

五、终端（PuppyPi）配置 MQTT 环境变量

终端代码读取的是环境变量：

PUPPY_MQTT_USER
PUPPY_MQTT_PASS

建议先临时导出：

bash 复制代码

export PUPPY_MQTT_USER=puppy_server
export PUPPY_MQTT_PASS='你设置的密码'

如需持久化，写入 ~/.bashrc：

bash 复制代码

cat >> ~/.bashrc <<'EOF'
export PUPPY_MQTT_USER=puppy_server
export PUPPY_MQTT_PASS='你设置的密码'
EOF
source ~/.bashrc

启动终端遥测节点

bash 复制代码

cd /home/ubuntu/puppyfit-terminal/puppyfit_v2_ws
# source ROS2 环境后启动
ros2 launch bridge_pkg mqtt_telemetry.launch.py

六、连通性验证（强烈建议）

1）用 mosquitto_sub 验证账号是否可用

bash 复制代码

mosquitto_sub -h 122.51.*.* -p 1883 \
  -u "puppy_server" -P "你设置的密码" \
  -t "puppy/event/+" -C 1 -v

能收到消息：认证与链路 OK
报 not authorised：用户名或密码错误

2）后端日志验证是否收到终端消息

关注主题：

puppy/data/{device_id}
puppy/event/{device_id}

七、前端对接 FastAPI（Vue）

puppyfit-frontend 使用 Vite 代理，开发时设置：

bash 复制代码

export VITE_API_TARGET=http://122.51.*.*:8800
npm run dev -- --host

前端接口通过 /api/... 访问后端。

八、设备在线状态判断逻辑

当前项目中，设备在线常见依赖：

devices.last_heartbeat 最近更新时间
或 online_status 字段

实践建议：

终端持续上报心跳/状态
后端把心跳落库到设备表
前端读取 /api/device/my-devices 展示在线状态

九、常见坑位总结

坑 1：Mosquitto 重启失败

常见原因：/etc/mosquitto/passwd 权限错误
正确权限：root:mosquitto + 640

坑 2：1883 通但认证失败

原因：账号密码不匹配
处理：mosquitto_passwd 重置并统一后端/终端配置

坑 3：只改了后端没改终端

终端仍用旧密码会持续 not authorised

坑 4：前端显示离线

并不一定是前端问题，通常是后端未刷新 last_heartbeat

十、结语

这套链路的核心就三件事：

Broker 认证配置正确且服务可用
后端与终端使用同一套 MQTT 凭证
心跳要能真正落库并被前端读取