4. 设备管理基础：设备注册、设备凭据与设备元数据
在 ThingsBoard 平台中，设备是数据采集与指令下发的最小实体单元。本章将系统讲解设备注册的三种方式、三种主流设备凭据（Access Token、X.509 证书、MQTT Basic 认证）的配置与适用场景，以及设备元数据的设计与使用规范。掌握这些基础操作，是后续实现设备接入、数据上云和仪表板展示的前提。
4.1 设备注册：三种方式对比
ThingsBoard 支持通过 UI 控制台、REST API 和批量导入三种方式完成设备注册。下表从操作效率、适用场景和自动化程度三个维度进行对比：
| 注册方式 | 操作效率 | 适用场景 | 自动化程度 |
|---|---|---|---|
| UI 控制台 | 单台设备注册，手动填写 | 开发测试、少量设备验证 | 低 |
| REST API | 单台或批量，通过 HTTP 请求 | 自动化运维、CI/CD 集成 | 高 |
| 批量导入（CSV） | 一次导入数百至数千台 | 生产环境大规模设备上线 | 中 |
推荐策略：开发阶段使用 UI 注册 1~5 台设备进行功能验证；进入试产或量产阶段，优先使用 REST API 或 CSV 批量导入，避免人工操作带来的录入错误。
4.2 设备凭据：三种认证机制详解
设备凭据是 ThingsBoard 验证设备身份的唯一凭证。平台内置三种凭据类型，分别对应不同的安全等级和硬件适配需求。
4.2.1 Access Token（令牌认证）
Access Token 是 ThingsBoard 默认且最简单的凭据形式。设备在 MQTT 或 HTTP 连接时，将 Token 直接放入请求中完成认证。
- 生成方式：设备注册后自动生成，也可手动修改为自定义字符串。
- 传输方式：MQTT 连接时放在
password字段；HTTP 请求时放在X-Authorization头或 URL 参数中。 - 安全等级：中等。Token 本身是静态字符串，若被泄露则设备身份可被冒用。
- 适用场景：局域网内部设备、开发测试环境、对安全要求不高的原型项目。
# MQTT 连接示例（使用 Access Token）
mosquitto_pub -h your.thingsboard.cloud -p 1883 \
-t "v1/devices/me/telemetry" \
-u "YOUR_ACCESS_TOKEN" \
-m '{"temperature": 25.6, "humidity": 60}'4.2.2 X.509 证书认证
X.509 证书认证基于非对称加密，设备端持有私钥和证书，ThingsBoard 通过 CA 证书链验证设备身份。这是三种凭据中安全等级最高的方式。
- 核心流程：设备注册时上传证书指纹或完整证书；连接时通过 TLS 握手完成双向认证。
- 优势：私钥不出设备，防泄露；支持证书吊销（CRL）实现设备远程禁用。
- 适用场景：公网部署、金融/能源等高安全行业、需要防篡改和防重放的设备群。
- 注意事项：需要维护 CA 证书体系，设备端需支持 TLS 1.2+ 和证书存储。
常见误区：X.509 认证并非“配置一次永久有效”。证书有有效期（通常 1~5 年），需提前规划证书续期流程，否则到期后设备将无法连接。
4.2.3 MQTT Basic 认证
MQTT Basic 认证使用用户名+密码的组合，在 MQTT 协议的 CONNECT 报文中携带。ThingsBoard 将其映射为设备凭据进行校验。
- 配置方式：在设备凭据中选择“MQTT Basic”，分别设置用户名和密码。
- 与 Access Token 的区别：Access Token 本质上是单字段认证；MQTT Basic 提供双字段（username/password），更符合传统 MQTT 客户端的使用习惯。
- 安全等级：中等。密码以明文传输（除非启用 TLS），建议配合 TLS 加密通道使用。
- 适用场景：已有 MQTT 客户端库且习惯使用用户名/密码认证的团队；需要与第三方 MQTT Broker 兼容的场景。
# MQTT Basic 认证连接示例
mosquitto_pub -h your.thingsboard.cloud -p 1883 \
-t "v1/devices/me/telemetry" \
-u "device_username" \
-P "device_password" \
-m '{"temperature": 25.6}'4.3 设备凭据选择决策流程
下图展示了在项目中选择设备凭据类型的决策路径，帮助你在安全、成本和开发效率之间做出平衡。
4.4 设备元数据：结构化描述与业务标签
设备元数据是附加在设备实体上的键值对（Key-Value）集合，用于描述设备的静态属性、地理位置、运维信息等。元数据不会随时间变化（区别于遥测数据），是设备管理的重要辅助信息。
4.4.1 元数据的典型用途
| 用途分类 | 示例键 | 示例值 | 说明 |
|---|---|---|---|
| 地理位置 | latitude, longitude |
39.9042, 116.4074 |
用于仪表板地图组件定位 |
| 资产归属 | department, owner |
生产一部, 张三 |
设备运维责任划分 |
| 硬件信息 | firmware_version, serial_number |
v2.1.3, SN-2024-001 |
固件升级与资产盘点 |
| 安装信息 | install_date, warranty_end |
2024-06-15, 2027-06-15 |
生命周期管理 |
4.4.2 元数据与凭据的关系
设备元数据与设备凭据是相互独立的两个概念，但在实际项目中常配合使用：
- 凭据：解决“设备是谁”的问题，用于身份认证。
- 元数据：解决“设备是什么、在哪、归谁管”的问题，用于业务描述。
- 最佳实践：不要在元数据中存储敏感信息（如密码、Token），元数据在平台内部以明文存储，不具备加密保护。
元数据设置入口：在设备详情页 → “元数据”选项卡，以 JSON 格式编辑。例如：
{"department": "生产一部", "floor": 3, "area": "A区"}
4.5 设备管理核心流程总览
下图将设备注册、凭据配置和元数据设置串联为完整的设备上线流程，帮助你建立全局视角。
4.6 本章小结
- 设备注册支持 UI、API、CSV 三种方式，生产环境推荐 API 或批量导入。
- 三种设备凭据各有侧重：Access Token 简单快速，X.509 安全等级最高，MQTT Basic 兼容传统客户端。
- 设备元数据用于描述静态属性，不与凭据混淆，不存储敏感信息。
- 设备上线流程应遵循“注册 → 配凭据 → 设元数据 → 上线验证”的顺序，避免遗漏关键步骤。