网关快速开始
页面导读
开发预览与当前阻塞
本页不是已验证成功的端到端教程。内容依据提交 b1a16cbc 的静态源码审计整理，未在本页执行 Docker、浏览器、MQTT Broker 或物理设备验收。
当前阻塞包括：应用不会创建并注册配置的驱动到 TagEngine；生产代码没有调用 subscribeFunction；默认 Compose 的 Broker 地址与网关配置不一致，配置目录只读却又需要写入密钥和保存配置。下面的设备、Tag、上报和反向控制部分只能作为开发配置清单与联调参考。
1. 环境要求
- 操作系统：Linux（Debian 12 推荐）/ macOS / Windows（开发调试，WSL2 亦可）
- Docker 方式：Docker ≥ 20.10、Docker Compose ≥ 2.0
- 源码方式：GCC 9+ / Clang 10+ / MSVC 2019+、CMake 3.16+、pkg-config、OpenSSL；真实 Modbus 需要 libmodbus，真实 GPIO 需要 libgpiod
2. 检查 Docker 启动资产
在 fastbee-gateway 源码根目录操作。镜像采用 Alpine 3.19 多阶段构建，默认关闭测试、GPIO、OPC UA 和 BACnet，构建 Modbus 驱动并复制 web-src。
启动前先检查并处理以下问题，不要直接假设原 Compose 是自包含演示：
docker-compose.yml的 Broker 服务名是mosquitto，但config/gateway.json默认指向192.168.1.100:1883。./config以只读方式挂载，启动可能创建.secret.key，MQTT 配置接口也会尝试保存文件；只读挂载会使这些写入无法持久化。- 配置中的
ENC(...)密文依赖匹配的密钥，不能当作可移植的默认凭据。应替换为本环境的开发配置，并妥善保管密钥。 - 默认
drivers是空数组，也没有预置设备或 Tag。
源码提供的开发启动命令为：
git clone https://gitee.com/beecue/fastbee-gateway.git
cd fastbee-gateway
docker compose up -d --build
docker compose logs -f gateway另开终端检查进程与健康接口：
curl -fsS http://localhost:8080/api/health停止开发环境：
docker compose down这些命令用于检查当前源码，不构成采集链路已经可用的声明。健康接口只反映进程和模块状态，不能证明物理设备通信成功。
3. 打开 Web 并处理默认凭据
Web UI/API 地址为 http://localhost:8080。当前代码使用明文 HTTP；虽然 Docker 暴露了 8443，但没有配置对应的 HTTPS 服务，不要把 https://localhost:8443 当作可用入口。
首次启动会创建默认用户 admin/admin123，登录页还可能预填该凭据。仅在隔离开发环境中使用，并立即通过用户管理/API 修改密码；不要把 8080 直接暴露到不受信任网络。 当前认证中间件主要检查 Token 是否存在和有效，不能据此宣称角色权限已在所有路由强制执行。
Web 管理界面的主要页面：
| 页面 | 功能描述 |
|---|---|
| 概览仪表盘 | 系统资源使用率、设备在线统计、流量图表、报警列表 |
| 设备管理 | 子设备增删改查、Tag 配置、协议参数设置 |
| GPIO 管理 | DI 实时状态、DO 手动控制、AI 工程值显示、LED 配置 |
| MQTT 配置 | Broker 地址/端口/认证、TLS 证书、连接状态 |
| 在线调试 | 实时 Tag 数据查看、手动读写测试、MQTT 消息监控 |
| 系统管理 | 用户管理、日志查看、配置导入导出、OTA 升级、时间设置 |
注意：Web 的设备页当前支持设备添加/删除和只读 Tag 列表，没有可靠的"新增 Tag"表单；设备字段和 MQTT 保存行为也存在 UI/API 差异。因此下面的设备与 Tag JSON 以运行时解析器为准，不以界面字段为准。
4. 配置开发 MQTT 连接
编辑 config/gateway.json 中的 mqtt 段。自包含 Compose 开发环境至少需要把 Broker 主机改为服务名，并清理不可用的密文占位：
{
"mqtt": {
"broker": "mosquitto",
"port": 1883,
"clientId": "fastbee-gw-dev-001",
"productId": "fastbee-gateway",
"deviceNum": "gw001",
"username": "",
"password": "",
"keepAliveSec": 60,
"qos": 1,
"tls": false
}
}该示例只适用于受控开发环境。随附 docker/mosquitto.conf 在 1883 和 8883 监听器上均设置了 allow_anonymous true，且 8883 没有配置 TLS 证书；匿名 MQTT 和无 TLS 端口不得暴露到生产或不受信任网络。 生产部署应另行配置认证、加密、访问控制和可写秘密存储。
可用以下命令观察属性主题；将占位值替换为实际配置，并按 Broker 认证要求补充参数：
mosquitto_sub -h <broker-host> -t '/<productId>/<deviceNum>/property/post' -v在当前阻塞未解决前，没有属性消息是预期风险之一，不应把该观察命令描述为成功验收。
5. 开发预览：一个 Modbus TCP 设备与 Tag
5.1 驱动配置
运行时读取顶层 drivers 数组，而不是旧文档中的顶层 devices 数组。下面是单个 Modbus TCP 驱动配置示例；192.0.2.10 是文档保留地址，必须替换为受控设备或模拟器地址：
{
"drivers": [
{
"protocolName": "modbus",
"connectionType": "tcp",
"host": "192.0.2.10",
"port": 502,
"timeoutMs": 3000,
"retryCount": 3,
"pollIntervalMs": 1000
}
]
}Modbus 驱动本身包含真实 libmodbus 读写代码，但当前 GatewayApp::initDrivers() 只记录配置数量。这就是设备接入的当前阻塞：仅写入上述 JSON 不会创建并注册驱动。
5.2 用 Modbus 模拟器代替真实设备
开发机上没有 PLC 时，可用 pymodbus 启动一个 Modbus TCP 模拟器，把驱动配置的 host/port 指向它：
pip install pymodbus
# 启动 Modbus TCP 模拟器（监听 5020 端口）
python -c "
from pymodbus.server import StartTcpServer
from pymodbus.datastore import ModbusSlaveContext, ModbusServerContext
store = ModbusSlaveContext()
context = ModbusServerContext(slaves=store, single=True)
StartTcpServer(context, address=('0.0.0.0', 5020))
"驱动配置中写 "host": "127.0.0.1", "port": 5020 即可连接模拟器。该方式只验证链路行为，不产生真实物理量。
5.3 一个子设备
运行时设备解析器使用 deviceId 和 protocolType。以下是要发送到 POST /api/devices 的开发示例，不是 Web 表单兼容性承诺：
{
"deviceId": "modbus-dev-001",
"productId": "demo-product",
"deviceNum": "modbus-001",
"deviceName": "Modbus development device 001",
"protocolType": "modbus"
}调用受保护接口前需先登录并携带 Bearer Token，详见 API。不要复用旧示例中的 id、protocol 或 slaveAddress 来推断当前设备模型。
5.4 一个 Tag
以下是发送到 POST /api/devices/modbus-dev-001/tags 的单个 Modbus Tag 示例：
{
"id": "holding-0",
"name": "Holding register 0",
"sourceType": 0,
"slaveAddr": 1,
"registerAddr": 0,
"registerCount": 1,
"scale": 1,
"offset": 0,
"pollIntervalMs": 1000,
"reportOnChange": false,
"enabled": true
}其中 sourceType: 0 表示 Modbus，registerAddr 直接传给 libmodbus，采用零基地址：第一个保持寄存器用 0，不要直接写 40001。当前解析器不读取旧示例中的 dataType、functionCode、字节序或 pollInterval 字段；应使用运行时实际读取的字段，不能把未解析字段当作已生效配置。
即使 API 接受设备或 Tag，驱动未注册仍会使真实读取/写入无法形成闭环。
6. 开发预览：属性上报
当前活动回调使用的属性主题是：
/{productId}/{deviceNum}/property/post其活动 JSON 结构为网关级配置的产品/设备主题加内部 deviceId 和 tags 数组：
{
"deviceId": "modbus-dev-001",
"timestamp": 1700000000000,
"tags": [
{ "id": "holding-0", "value": 25.5, "quality": 0 }
]
}源码另有 TagMapper::buildPropertyPost() 可生成 FastBee 风格 params，但活动回调没有使用它；不要把两套格式混写。MQTT 断开时，活动回调会记录并跳过本批数据，当前没有生产可用的离线缓存补报保证。
7. 开发预览：反向控制
MQTT 客户端实现了 /{productId}/{deviceNum}/function/# 订阅原语，但生产代码没有调用 subscribeFunction。因此不能通过发布一条 MQTT function 消息来宣称云端反向控制已经实现。
当前另有手工调试写接口 POST /api/debug/write：
{
"tagId": "holding-0",
"value": 1
}它调用 TagEngine::writeTag()，仍要求有效 Tag 和已注册驱动。Stub 返回 success: true 可能只是模拟结果，不能证明物理继电器或寄存器已改变。调试接口应限制在受控网络与受信任用户内，尤其不要把 /api/debug/ping 暴露给不可信调用者。
8. 联调前必须解除的当前阻塞
- 在应用层创建、初始化并把真实驱动注册到 TagEngine，且为 Stub 结果保留明确标识。
- 统一 Web、API 与运行时设备/Tag/MQTT 字段，并补齐可靠的 Tag 配置入口。
- 修正 Compose 的 Broker、配置写入和秘密管理，关闭匿名访问并配置真实 TLS。
- 明确唯一活动上报格式，接通生产 function 订阅与命令处理。
- 分别实现并验证断网数据处理、配置重连、恢复出厂和 OTA；在完成前不要作生产承诺。