本地MQTT服务器部署： Mosquitto消息中间件简介与部署

Mosquitto 是一个开源的、轻量级的 MQTT 协议 Broker，由 Eclipse 基金会维护，是目前全球使用最广泛的 MQTT 消息中间件之一。它完全用 C 语言编写，对资源的需求极低，非常适合在边缘设备、工控机或资源受限的嵌入式环境中运行

本地端 Mosquitto Docker（配置与数据统一到 /data/mosquitto）

1. 创建目录结构并设置权限

# 创建所需目录
mkdir -p /data/mosquitto/config
mkdir -p /data/mosquitto/data
mkdir -p /data/mosquitto/log

# 设置权限（容器内 mosquitto 用户 uid=1883）
chown -R 1883:1883 /data/mosquitto
# 如果不想纠结权限，开发环境也可以用 chmod -R 777 /data/mosquitto

2. 编写配置文件

创建 /data/mosquitto/config/mosquitto.conf，内容如下（已针对本地端断网续传优化）：

# ========== 基础监听 ==========
listener 1883 0.0.0.0
# 允许本地内设备匿名接入（生产环境建议改为密码认证）
allow_anonymous true

# ========== 持久化配置 ==========
persistence true
persistence_location /mosquitto/data
autosave_interval 60               # 每60秒自动保存一次持久化状态
max_queued_messages 100000         # 磁盘队列最大消息数（可根据本地端磁盘调整）
max_inflight_bytes 0               # 不限飞行窗口
# 持久会话过期时间（30天），离线客户端重连后仍能收到消息
persistent_client_expiration 30d

# ========== 日志 ==========
log_dest file /mosquitto/log/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information

# ========== 云端桥接（核心：实现断网续传） ==========
connection cloud-bridge
# 云端 EMQX 的地址和端口（请替换为实际 IP 或域名）
address your-cloud-emqx-server:1883
# 需要同步的主题，这里双向同步所有主题，生产环境建议收缩为 vessel/# both 0
topic # both 0 "" ""
try_private false
cleansession false                 # 关键：不清除会话，云端保留离线消息
bridge_qos 2                       # 端到端精确一次确认
notifications true                 # 将桥接状态发布到 $SYS 主题，便于监控
start_type automatic               # Broker 启动时自动连接桥接
restart_timeout 10 30              # 断线后 10 秒开始重试，最大间隔 30 秒
keepalive_interval 60              # 心跳间隔，卫星链路可适当增大
bridge_protocol_version mqttv311

# 如果云端需要身份验证，请设置以下两项
remote_username ocean-dev
remote_password Initpass@word1

说明：

• 路径 /mosquitto/data 和 /mosquitto/log 是容器内部路径，后面通过挂载对应到宿主机的 /data/mosquitto/data 和 /data/mosquitto/log。
• 桥接地址、用户名、密码、同步主题请根据你的云环境修改。

3. 启动容器

使用 eclipse-mosquitto 官方镜像，执行以下命令：

docker run -d \
  --name mosquitto \
  --restart unless-stopped \
  -p 1883:1883 \
  -v /data/mosquitto/config/mosquitto.conf:/mosquitto/config/mosquitto.conf \
  -v /data/mosquitto/data:/mosquitto/data \
  -v /data/mosquitto/log:/mosquitto/log \
  eclipse-mosquitto

若需要 TLS（8883）或 WebSocket（8083），可额外添加端口映射：

-p 8883:8883 -p 8083:8083

并在配置文件中增加对应的 listener 段落。

4. 验证状态

查看日志，确认桥接是否连接成功：

docker logs -f mosquitto

正常时会看到：

Notice: Connecting bridge cloud-bridge (your-cloud-emqx-server:1883)
Notice: Bridge cloud-bridge is connected

监听桥接状态主题（需要本地安装 mosquitto_sub 工具，或在容器内执行）：

docker exec -it mosquitto mosquitto_sub -t '$SYS/broker/connection/cloud-bridge/state' -v

状态值为 1 表示连接正常，0 表示断开。

功能测试：

1. 在本地端发布消息：

   docker exec mosquitto mosquitto_pub -t vessel/test -m "hello from ship" -q 2
   

2. 断开本地网络（或暂停云端 EMQX），继续发布几条消息。
3. 恢复网络，在云端订阅 vessel/test 检查是否收到所有离线消息，无丢失。

5. 目录结构说明

部署完成后，你的 /data/mosquitto 目录结构如下：

/data/mosquitto/
├── config/
│   └── mosquitto.conf      # 配置文件
├── data/
│   └── mosquitto.db        # 持久化数据库文件（自动生成）
└── log/
    └── mosquitto.log       # 运行日志

所有重要数据都集中在 /data/mosquitto，方便备份、迁移和监控。后续如果需要备份本地端 Broker，只需保存该目录即可。