接入总览与设备认证
本指南面向集成商工程师与设备端开发者，说明如何把设备接入加加云桥。从协议、认证到指令下发，把设备端需要实现的全部内容讲清楚。
一、接入方式选型
平台当前通过 MQTT 协议接入设备，支持两种形态：
形态一：直连 形态二：网关代理
┌────────┐ MQTT ┌────────┐ ┌────────┐ ┌────────┐
│ 设备 A │ ──────▶ │ │ │ 网关 │ ──MQTT──▶│ │
├────────┤ │ 平台 │ ├────────┤ 代为上报 │ 平台 │
│ 设备 B │ ──────▶ │ │ │ 子设备 xN│ ──现场──▶│ │
└────────┘ └────────┘ └────────┘ 总线/串口 └────────┘
每台设备自己连平台 只有网关连平台，子设备经网关转发| 直连设备 | 网关 + 子设备 | |
|---|---|---|
| 适用场景 | 设备有网络能力、数量不多 | 现场设备多、协议异构、无独立联网能力 |
| 谁连接平台 | 每台设备各自连接 | 仅网关建立一条 MQTT 连接 |
| 数据归属 | 设备自己的令牌 | 网关报文里的外部 ID |
| 参考章节 | 《直连设备协议》 | 《网关设备协议》 |
混合使用完全允许：一个租户里可以既有直连设备，又有网关带子设备。
二、接入信息从哪里拿
| 项目 | 获取方式 |
|---|---|
| Access Token | 平台「设备台账」创建设备后弹窗显示；之后在设备详情页随时可查 |
| MQTT 地址与端口 | 公有云 SaaS：cloudbridge.qiuhuasoft.top:1883；私有部署向平台管理员获取 |
| 平台 REST API 地址 | 与 Web 端同源，见《API 概览》 |
三、设备认证
平台内置 MQTT Broker，认证规则刻意保持极简：
| 连接参数 | 填什么 |
|---|---|
| 用户名（UserName） | 设备的 Access Token |
| 密码（Password） | 留空（平台不校验密码） |
| Client ID | 自定义，建议用令牌或设备 ID，每台设备唯一 |
| Keep Alive | 建议不超过 120 秒 |
认证失败的三种原因（对外表现完全一致）
平台在以下情况拒绝连接，且返回相同的失败原因（用户名或密码错误）：
- 令牌填写错误；
- 令牌对应的设备不存在（未在平台建档）；
- 设备所属租户已被平台停用。
统一失败提示是有意设计：不向设备端泄露"租户被停用"等平台内部状态。排查时请按这三种可能逐一检查，优先核对令牌与设备建档。
会话与顶线
- MQTT 会话按 Client ID 识别：两台设备若使用相同的 Client ID，后连的会把先连的顶下线，表现为设备频繁掉线重连——务必保证 Client ID 唯一；
- 令牌等同设备身份，泄露后可在设备详情页重新生成（生成后旧令牌立即失效，需同步更新设备端）。
四、主题总览
| 主题 | 方向 | 用途 | 详见 |
|---|---|---|---|
v1/devices/me/telemetry | 设备 → 平台 | 直连设备遥测上报 | 直连设备协议 |
v1/devices/me/attributes | 设备 → 平台 | 直连设备属性上报 | 直连设备协议 |
v1/devices/{token}/rpc/request/{requestId} | 平台 → 设备 | 直连设备接收下行指令 | 设备 RPC |
v1/gateway/connect | 网关 → 平台 | 子设备上线通知 | 网关设备协议 |
v1/gateway/disconnect | 网关 → 平台 | 子设备下线通知 | 网关设备协议 |
v1/gateway/telemetry | 网关 → 平台 | 子设备遥测上报 | 网关设备协议 |
v1/gateway/attributes | 网关 → 平台 | 子设备属性上报 | 网关设备协议 |
v1/gateway/rpc/{token} | 平台 → 网关 | 网关接收下发指令 | 设备 RPC |
五、上报的通用规则
以下规则对直连与网关两种通道同样适用：
| 规则 | 说明 |
|---|---|
| 报文格式 | 一律为 UTF-8 JSON；解析失败的报文被静默丢弃，设备端不会收到错误回执 |
| 时间戳 | 毫秒级 Unix 时间戳；报文未带时按平台收到的时间记录 |
| 字段命名 | 平台不转换字段名，上报什么名字就展示什么名字——定下后不要改 |
| 类型一致 | 同一字段名保持同一数据类型，混用会按不同类型分开存储 |
| QoS | 建议发布使用 QoS 1（至少一次），在可靠性与开销间平衡 |
| 配额 | 每条报文计入租户的每日消息配额；配额耗尽后当天报文被丢弃 |
六、数据在平台侧的处理
报文到达平台后并非直接写库，而是经过消息总线异步处理：
MQTT 报文 → Broker 解析/认证/配额 → 消息总线 → 消费者
├─ 遥测：InfluxDB 历史 + PG 最新值快照
├─ 属性：属性表合并最新值
├─ 状态：上线/下线落库
└─ 规则评估：命中 → 产生告警理解这一点有两个实际意义：
- 上报成功 ≠ 立即可查：数据经过毫秒到秒级延迟后才会出现在页面上；
- 设备端无需等待回执：上报通道是单向的，发布完成即可继续采集。
七、开发前检查清单
下一步：按设备形态选择《直连设备协议》或《网关设备协议》。