教程

启动网关，
并接受一条事件。

本教程启动 netbaiot-server，上传一条设备事件，再用 netbaiot-client 消费。标准 MQTT 3.1.1 客户端不依赖可选设备 SDK。MSRV 1.88.0。协议 v1。

你将完成

在回环地址上启动开发监听
POST 一条 heartbeat 并看到 HTTP 202
在业务客户端中订阅并 ACK 该投递

1. 运行开发服务器

开发监听绑定回环地址。HTTP 202 表示 EventAccepted。调用管理 API 前需设置 64 字符的 NETBAIOT_ADMIN_SECRET。生产配置必须指定确认型 webhook 或分帧 TCP/RPC 业务 sink。

cargo run -p netbaiot-server -- configs/development.json

2. 上传设备事件

设备 bearer 格式为 credential_id:secret。JSON schema 为 DeviceUplink。重试与重启重放可能重复投递；业务 sink 必须按 event_id 去重。

curl --noproxy '*' -i http://127.0.0.1:8080/v1/device/data \
  -H 'Authorization: Bearer demo-device:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f' \
  --data '{"schema_version":1,"source_message_id":"demo:1","kind":"heartbeat","data":{"sequence":1}}'

3. 用业务客户端消费事件

AckMode 默认为 Manual。在应用处理之后 ACK。每个订阅同时只有一条服务器确认投递。丢弃未确认投递会关闭流，以便服务器重投。

use futures_util::StreamExt;
use netbaiot_client::NetbaIoTClient;
use netbaiot_protocol::EventFilter;

let client = NetbaIoTClient::builder()
    .endpoint(endpoint)
    .token(token)
    .event_address(event_address)
    .connect()
    .await?;
let mut events = client.events().subscribe(EventFilter::default()).await?;
while let Some(delivery) = events.next().await {
    let delivery = delivery?;
    handle(delivery.event()).await?;
    delivery.ack().await?;
}

4. 可选设备 SDK

netbaiot-device-sdk 是便利层，不是硬性要求。标准 MQTT 3.1.1 客户端仍为一等公民。断线发布会被拒绝；SDK 不会累积离线 RAM 队列。

cargo check -p netbaiot-device-sdk --examples

5. 运维 CLI

netbaiot 仅通过 netbaiot-client 实现。令牌不会被打印。drain 需要 --yes。退出码 5 表示设备离线。

netbaiot server status
netbaiot events subscribe
netbaiot command send DEVICE --json JSON
netbaiot server drain --yes

运行约束

运行时没有数据库、持久 outbox 或持久命令状态。
EventAccepted 不是业务持久化。消费者必须对 event_id 幂等。
不会为离线设备存储命令。
计划内重启可以 spool 必达工作；突然崩溃可能丢失内存中已接受的事件。
当前 broker 不包含 MQTT 5、WebSockets、共享订阅与 $SYS。

许可

NetbaIoT 以 AGPL-3.0-or-later 授权。如果修改程序并让用户通过网络与之交互，必须提供对应源代码。

启动网关，并接受一条事件。