教程

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

先运行独立的 MQTT 演示，再初始化自己的网关。Rust 最低版本 1.88.0；设备协议 v1。

你将完成

运行本地 MQTT 演示
初始化并校验网关配置
连接设备和确认型业务 sink

1. 运行演示

在源码目录运行以下命令。演示会认证真实 MQTT 设备、发布 heartbeat、等待业务 sink ACK，然后排空并退出。去掉 --once 可进入交互式演示。演示凭据仅用于本地开发。

cargo run --locked -p netbaiot-cli -- demo --once

使用解压后的发布包时，运行：

./netbaiot demo --once

2. 初始化网关

从解压后的发布包运行以下命令，初始化目录、校验配置并启动网关。CLI 默认读取当前目录的 netbaiot.json。

./netbaiot init my-gateway
cd my-gateway
../netbaiot config check --config netbaiot.json
../netbaiot serve

3. 连接业务 sink

配置确认型 HTTP webhook 或 Business RPC V4 sink。Business RPC V5 事件窗口需显式启用。应用处理完成后再 ACK，并按 event_id 保证幂等。下方示例从环境变量读取管理与事件连接凭据。

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

#[netbaiot_driver::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = NetbaIoTClient::builder()
        .endpoint(std::env::var("NETBAIOT_ENDPOINT")?)
        .token(std::env::var("NETBAIOT_TOKEN")?)
        .event_token(std::env::var("NETBAIOT_EVENT_TOKEN")?)
        .event_address(std::env::var("NETBAIOT_EVENT_ADDRESS")?.parse()?)
        .connect().await?;
    let mut events = client.events().subscribe(EventFilter::default()).await?;
    while let Some(delivery) = events.next().await {
        let delivery = delivery?;
        println!("event {}", delivery.event_id());
        // Process the event durably and idempotently before ACK.
        delivery.ack().await?;
    }
    Ok(())
}

示例依赖 futures-util、netbaiot-client、netbaiot-protocol 和 netbaiot-driver。事件地址与事件令牌必须与 Business RPC 监听及认证配置匹配；生产应用应先完成持久化等业务处理，再 ACK。

4. 连接设备

可使用标准 MQTT 3.1.1、受支持的 MQTT 5.0 配置、分帧 TCP 或已认证 UDP。公网设备 TCP 要求 TLS；UDP 认证不加密载荷。

5. 生产环境准备

使用 netbaiot init --production 生成配置以及独立的设备和管理 TLS 材料。部署前请阅读生产 PKI 文档并配置业务 sink。

netbaiot init --production --domain example.com

命令在当前目录生成 netbaiot.json、私有 CA 层级和独立的设备与管理 TLS 密钥。设备入口默认监听 0.0.0.0:8443，UDP 使用同一端口；非回环管理监听需要独立的 management_tls。Business RPC 使用 business_rpc.listen 和独立的 TLS 配置。

初始化会显示一次新生成的离线 CA 口令；请安全保存，不要写入日志，也不要提供给运行中的网关。仅向相应客户端分发 root-ca.pem 信任锚，证书仍需通过域名校验。基础域名及其一级通配子域名会加入证书；其他域名或 IP 需显式配置。

生成的认证和业务接收地址是本地默认值，部署前必须启动对应服务或修改配置。使用 netbaiot cert reload 更新运行中网关的证书；已有连接继续使用原配置，新握手使用新配置。

运行约束

网关将运行时状态保存在有界内存中，重启后从空状态开始。
EventAccepted 不是业务持久化；消费者必须对 event_id 幂等。
不会为离线设备存储命令。
计划内关机等待必达 ACK；强制退出会丢失待处理事件。
网关为单节点；不支持 MQTT over WebSocket 和共享订阅。

许可

当前 NetbaIoT 版本使用NetbaIoT Commercial Software License，允许 30 天内部非生产评估。生产、托管和再分发需要适用的书面商业授权。历史 AGPL 权利对相应副本继续有效。

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