RunMQTT 将设备身份与 Topic 规则分开管理。这样可以让凭证保持最小权限，也便于在设备规模扩大后审查访问范围。
策略模板
一个模板代表一种设备角色，例如只读看板、现场传感器、网关或指令服务。同一模板下的设备使用相同的 Topic 策略，但不会共享凭证。
每条策略包含：
- Topic Filter；
- 发布、订阅或双向权限；
- 可选的说明，便于后续审查。
Topic Filter 设计
Topic 应使用稳定的层级结构，先表达归属范围，再表达数据类型：
tenants/acme/sites/shanghai/devices/sensor-42/telemetry
tenants/acme/sites/shanghai/devices/sensor-42/state
tenants/acme/sites/shanghai/devices/sensor-42/commands
+ 只匹配一层，# 会匹配剩余的整棵 Topic 树。# 应仅用于可信网关或后端服务身份。
建议为遥测和指令分别设置规则。负责上报遥测的传感器通常不需要发布指令；只订阅状态的看板也通常不需要设备级发布权限。
设备凭证
将控制台中的 MQTT 用户名和密码直接填入客户端。用户名格式为 <broker-id>/<device-name>，密码就是原始设备密钥，无需额外计算。
每台设备都有独立的连接凭证。凭证只属于一个 Broker 和一份策略模板。删除设备身份不会改变账户登录，也不会影响其他设备。在设备详情中使用重置密码，可为同一身份生成新密码；详见故障排查。
即使多个测试客户端使用同一设备密钥，也应为每个并发连接使用不同的 Client ID。Broker 会将同时在线的 Client ID 分别计入连接数。
安全发布流程
- 先用最小 Topic 范围创建模板。
- 从模板创建一台测试设备。
- 验证允许的发布与订阅操作。
- 验证超出范围的 Topic 会被拒绝。
- 确认策略符合预期后，再添加生产设备。
共享模板的变更可能影响所有关联设备。调整通配符时，应像审查应用权限变更一样谨慎。
一个传感器与一个后端服务
在 Broker 中创建两个模板，先添加以下策略，再创建设备：
| 模板 | Topic Filter | 权限 |
|---|---|---|
sensor-42 | devices/sensor-42/telemetry | 发布 |
sensor-42 | devices/sensor-42/commands | 订阅 |
backend | devices/+/telemetry | 订阅 |
backend | devices/+/commands | 发布 |
分别从两个模板创建设备，每个客户端使用自己的凭证。先让后端订阅 devices/+/telemetry，再让传感器向 devices/sensor-42/telemetry 发布。下发指令时反转方向。每次都等待订阅成功后再发布。
后端可以收到匹配范围内所有传感器的遥测，sensor-42 模板只授权这台传感器的路径。如果另一台设备也挂到同一模板，它会获得相同权限；模板名称和 Client ID 不会自动隔离设备，也不会替换主题变量。其他设备应配置对应范围的策略。
过滤器匹配与权限检查
- 主题区分大小写，
demo/hello、Demo/hello和/demo/hello不同。 - 发布只能使用不含通配符的具体主题。订阅过滤器中的
+必须独占一层，#必须独占最后一层。 devices/+/telemetry匹配devices/sensor-42/telemetry，不匹配devices/sensor-42/status或devices/site-a/sensor-42/telemetry。- 过滤器只授予权限，客户端仍需发送 SUBSCRIBE。先订阅精确的授权过滤器；某个具体主题被允许，不代表范围更大的订阅也被允许。
- 删除较窄规则后，广泛的
#授权可能仍保留访问权限。检查模板内全部规则，而不只是最近一次修改。
可用模板内的策略测试或 ACL Linter做本地检查，再用真实客户端验证允许和拒绝的操作。拒绝测试也不要发送敏感数据。组内消费使用实际主题权限，客户端格式见共享订阅。
命名与变更
设备名称接受 1–40 个 ASCII 字母、数字、连字符或下划线。Broker 和模板名称接受 2–80 个字符，策略过滤器最多 180 个字符。这些是表单约束，不代表支持任意主题或流量速率。
删除模板前，应先移除关联设备。删除设备会撤销该身份，不会取消 Broker 订阅。替换凭证和验证实际访问权限的步骤见故障排查。
重置设备密码
打开设备详情页或凭证侧栏，点击重置密码，阅读提示并确认。新密码默认隐藏，可以按需显示或复制。更新所有使用该设备的客户端，再用新密码重新连接，验证允许的发布和订阅。
旧密码会立即无法用于新连接。用户名、设备名称、Client ID 和模板策略保持不变。已有连接可能持续在线，直到重新连接；重置密码不保证立即踢掉在线连接。请验证旧密码无法建立新连接。
如果 RunMQTT 无法确认重置结果，不要假设旧密码仍有效。重新加载凭证；若没有可用密码，再次重置并部署最新值。避免在多个窗口同时重置。