ESP32 / ESP8266 MQTT 实战：Docker 部署与设备远程控制

IoT 入门 · MQTT · ESP32实战｜FastBee 技术团队｜一篇可复现的 IoT 开发实战：用 Docker 启动 FastBee 开源版，配置 MQTT 产品和物模型，再让 ESP32 或 ESP8266 上报数据并接收远程控制指令。

简要回答：以FastBee开源平台为例，先用 Docker 部署 FastBee 开源版，创建并发布 MQTT 产品及其物模型，再用设备编号、产品 ID、用户 ID 和 MQTT 凭据连接开发板。ESP32 可按 FastBee-Arduino 官方文档选择受支持的固件；ESP8266 则需要自行编写 MQTT 客户端，按 FastBee 文档实现认证、主题和消息格式。

适合读者：熟悉基本网络和 Arduino 开发、第一次搭建 IoT 平台的开发者。 目标：让一块开发板从“连上 Wi-Fi”走到“平台看见数据、下发命令、设备执行后回报状态”。 版本说明：FastBee-Arduino 官方零代码固件面向 ESP32 系列；ESP8266 可按文中的 MQTT 协议自行编写固件适配，不应直接套用 ESP32 固件。

完成后你会得到什么

• 一套通过 Docker Compose 运行的 FastBee 开源版测试环境。
• 一个 MQTT 产品、一个温度属性和一个可写开关属性。
• 一块 ESP32 或 ESP8266 完成上线、属性上报和远程指令闭环。

设备与平台之间的链路如下：

传感器/继电器 ↔ ESP32 或 ESP8266 ↔ MQTT Broker ↔ FastBee 平台 ↔ 浏览器控制台

1. 准备环境

硬件与软件

• 服务器或本地虚拟机。FastBee 当前 Docker 文档列出的最低配置为 2 核 CPU、4 GB 内存；这是部署最低要求，不等同于生产容量规划。
• Docker 20.10+ 和 Docker Compose 2.0+。
• ESP32 开发板；ESP8266 开发板也可用于自行编写 MQTT 客户端的路径。
• USB 数据线、Wi-Fi 网络。可选：温度传感器、低压 LED 或隔离继电器模块。
• 浏览器；可选 MQTTX，用于先验证 Broker 和主题。

部署机、开发板和浏览器需要网络互通。后文用 SERVER_IP 表示部署 FastBee 的主机地址，用 PRODUCT_ID、DEVICE_NUM 等占位符表示你在控制台创建的值。设备端 MQTT 地址必须填写设备实际可访问的服务器 IP 或域名；localhost 指设备自身，不能用来访问另一台服务器。

2. 用 Docker 部署 FastBee

FastBee 开源版内置 MQTT Broker（消息代理，负责接收并转发 MQTT 消息），初次测试无需另行部署 EMQX。FastBee 当前 Docker 文档列出的环境要求为 Docker 20.10+、Docker Compose 2.0+，以及至少 2 核 CPU、4 GB 内存。该数值是官方文档给出的最低部署要求；生产环境容量应结合设备数、消息频率和业务负载评估。

在 Linux 主机终端执行官方安装命令，按提示选择“开源版本”：

sudo wget -c https://hub.fastbee.cn/resource/install.sh && bash ./install.sh

等待服务启动后，查看容器状态：

docker ps

浏览器打开 http://SERVER_IP:80。官方初始登录凭据为 admin / admin123；首次登录后立即修改密码。测试时只向需要接入的网段开放 Web 端口和 MQTT TCP 1883；不要把数据库、Redis 等内部服务直接暴露到公网。

官方部署文档：FastBee 开源版 Docker 一键部署

3. 建立 MQTT 产品和设备

在控制台进入产品管理，创建通信方式为 MQTT 的产品，然后添加以下物模型属性。物模型是产品对设备属性、功能和事件的统一描述；本例用温度属性接收遥测，用可写开关属性接收控制并回报实际状态：

标识符	类型	权限	用途
temperature	数值	只读	展示传感器温度
switch	布尔/开关	可读写	接收开关控制并上报实际状态

保存后发布产品，再创建一个设备。记录产品详情页的产品 ID（不是产品编号）、设备编号、MQTT 用户名和密码，以及当前登录用户 ID。如果产品启用了设备授权码，也要一并记录。

测试阶段的 MQTT 连接参数格式为：

Host: mqtt://SERVER_IP
Port: 1883
Protocol: MQTT 3.1.1
Client ID: S&DEVICE_NUM&PRODUCT_ID&USER_ID
Username: MQTT 用户名
Password: MQTT 密码

如果产品启用了设备授权码，密码格式为 MQTT密码&设备授权码。正式环境请按官方说明使用加密认证，不要把真实凭据提交到公开代码仓库。

4. 先用 MQTTX 验证链路

建议先用 MQTTX 排除固件和接线问题。按上面的参数新建连接，连接成功后订阅平台下行主题：

/{PRODUCT_ID}/{DEVICE_NUM}/function/get

向设备信息主题发布以下 JSON：

{
  "rssi": -48,
  "firmwareVersion": 1.0,
  "status": 3,
  "userId": USER_ID
}

随后向属性主题发布一组属性：

Topic: /{PRODUCT_ID}/{DEVICE_NUM}/property/post

[
  {"id":"temperature","value":"23.6","remark":"bench test"},
  {"id":"switch","value":"0","remark":"relay off"}
]

在平台设备详情中确认设备在线且温度、开关值出现。属性 id 必须和物模型标识符完全一致；布尔值按字符串 "0" / "1" 传递。设备首次连接时，先发布 /info/post，再发布属性或事件。

5. 接入 ESP32 和 ESP8266

路径 A：ESP32 使用 FastBee-Arduino

若希望先跑通设备侧，可依照官方快速开始文档为受支持的 ESP32 开发板选择匹配的合并固件，通过在线烧录工具写入，再配置 Wi-Fi、外设和联网参数。Flash/PSRAM 规格要与开发板匹配；具体芯片与固件型号以目标版本官方硬件文档为准。

把平台地址配置为部署主机的可达 IP 或域名，并按平台产品配置填写设备身份和 MQTT 凭据。局域网测试通常使用 SERVER_IP:1883。在 FastBee-Arduino 中配置温度传感器与开关输出后，确认它们关联到 temperature 和 switch 标识符；再回到平台设备详情观察上线和属性变化。

官方步骤：FastBee-Arduino 快速开始 · 硬件与环境说明

路径 B：ESP8266 自行实现 MQTT 客户端

ESP8266 可以作为通用 MQTT 设备接入，但要由你维护 Arduino 固件适配：连接 Wi-Fi 与 MQTT 3.1.1 Broker，使用上面的认证参数，发布设备信息和属性，并订阅 /function/get。FastBee-Arduino 的官方零代码固件不是 ESP8266 固件。

固件主循环的逻辑应类似下面的伪代码。将 mqttPublish、mqttSubscribe、JSON 解析和 GPIO 操作替换为你所用 MQTT 库的实际 API：

连接 Wi-Fi
连接 MQTT，clientId = "S&" + DEVICE_NUM + "&" + PRODUCT_ID + "&" + USER_ID
订阅 /{PRODUCT_ID}/{DEVICE_NUM}/function/get
发布 /{PRODUCT_ID}/{DEVICE_NUM}/info/post

循环：
  读取温度
  发布 /{PRODUCT_ID}/{DEVICE_NUM}/property/post
    [{"id":"temperature","value":"23.6","remark":"sample"},
     {"id":"switch","value":"0","remark":"actual state"}]
  收到 function/get 后解析 id 和 value
  若 id 为 switch：先按硬件安全逻辑更新输出，再读取实际状态
  将实际 switch 状态发布到 property/post

使用 ESP8266 时，确保开发板 GPIO 电平、启动绑带引脚、供电和继电器模块匹配；不要照搬其他板子的引脚编号。官方协议格式和主题清单见 MQTT 接入文档。

6. 从平台下发远程控制

在控制台设备详情或设备控制页面，对 switch 属性发起设置。平台会把类似下面的 JSON 发到设备订阅主题：

Topic: /{PRODUCT_ID}/{DEVICE_NUM}/function/get

[{"id":"switch","value":"1","remark":"platform command"}]

设备固件应解析标识符和值，执行相应输出，再从 /property/post 回报实际状态：

[{"id":"switch","value":"1","remark":"output confirmed"}]

不要只把期望值直接回报为设备状态：如果 GPIO 写入失败、继电器未动作或状态读取不一致，平台应收到真实结果，便于诊断。仅在隔离低压电路上验证；不要把开发板直接接入市电负载。继电器模块的有效电平因型号而异，首次上电先确认接线图和默认断开状态。

7. 验收清单与常见故障

• 设备离线：确认 Docker 容器运行、1883 端口可达、设备没有把服务器地址填成 localhost。
• 认证失败：逐项核对 clientId 中的设备编号、产品 ID、用户 ID；若开启授权码，检查密码是否追加授权码。
• 在线但没数据：确认产品已发布，主题中的产品 ID 和设备编号无误，先发 /info/post，属性 ID 与物模型完全一致，且负载是 JSON 数组。
• 平台命令收不到：设备须在线并订阅 /{PRODUCT_ID}/{DEVICE_NUM}/function/get；检查控制台指令日志和 MQTT 客户端订阅主题。
• 平台显示已控制但硬件没变化：检查属性是否配置为可写、固件是否处理了该 ID、GPIO 与模块有效电平是否匹配，并确认设备回报的是执行后的状态。

最小闭环的验收标准是：设备显示在线，温度值能刷新；平台下发 switch=1 后设备执行输出，并将实际开关值回报到平台。

常见问题

FastBee-Arduino 零代码固件能直接用于 ESP8266 吗？

不能。FastBee-Arduino 官方零代码固件面向其文档列出的 ESP32 开发板。ESP8266 可以按 FastBee MQTT 协议接入，但需要自行实现和维护固件客户端，并正确处理认证、主题和报文格式。

设备显示在线，但平台没有温度数据，先检查什么？

先确认产品已发布，主题中的产品 ID 和设备编号准确，已先发布 /info/post，属性主题使用 /{PRODUCT_ID}/{DEVICE_NUM}/property/post，JSON 负载为数组，且每个 id 与物模型标识符完全一致。属性值应符合对应数据类型；FastBee MQTT 文档规定属性值以字符串传递。

官方的 2 核 CPU、4 GB 内存足以支撑生产环境吗？

这只是 FastBee 当前 Docker 文档列出的最低部署要求，不能据此推断生产环境容量。生产配置应根据设备数量、上报频率、数据保留、规则负载和并发访问评估，并通过目标部署的负载测试验证。

MQTT 命令发出后，如何确认继电器确实动作？

设备端应执行命令、检查实际输出状态，再将结果上报到 /property/post。平台下发成功或 MQTT 消息送达，都不能单独证明继电器已动作；还需按具体模块设计状态读取和安全默认状态。

官方资料

• FastBee 开源版 Docker 一键部署
• FastBee 开源版 MQTT 接入
• FastBee-Arduino 快速开始
• FastBee-Arduino 硬件与环境
• FastBee 开源版文档首页
• 开源许可与授权说明

部署和二次开发前请阅读许可说明；FastBee 官方授权页面列出开源版采用 AGPL-3.0，并说明其用途边界。