DBX MQTT 控制台优化全解析订阅配置管理、No Local 与 WebDAV/GitHub 同步契约【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx本文基于仓库内 docs/mqtt-console-optimization-requirements.md需求文档 v1.3展开系统讲解 DBX 桌面端 MQTT 控制台如何从页面入口 Topic 树混为一体的旧形态重构为左侧仅导航、右侧统一管理订阅配置的新架构并深入剖析订阅配置数据模型Topic Filter / QoS / No Local / Enabled、自动恢复规则、消息收发视觉优化以及 WebDAV / GitHub 项目同步中 MQTT 订阅的独立同步契约与安全边界。读完本文你将掌握 DBX 中 MQTT 订阅配置的完整生命周期新建、启用、停用、删除、编辑、它与运行中订阅的状态区分以及同步快照在旧版本兼容与明确清空之间的精确语义设计。一、背景与目标为什么 MQTT 订阅需要持久化与同步MQTT Broker 通常只负责消息路由不提供客户端订阅配置的持久化管理。DBX 中保存的 Topic Filter、QoS、No Local、启用状态都属于本地配置如果没有纳入项目同步在重装系统、更换设备或恢复项目时极易丢失。这正是本次优化的出发点。本次优化的核心目标可以归纳为七条左侧全局侧栏只保留 MQTT 控制台入口不再承载订阅管理职责右侧控制台成为全部订阅配置的统一管理入口支持只保存配置、不立即订阅即保存备用配置支持启用、停用、编辑和删除订阅配置改善 Topic 列表与消息方向的视觉辨识度WebDAV、GitHub 项目同步必须包含 MQTT 订阅配置同步订阅配置不依赖同步密码/敏感信息选项同时不得泄露认证秘密。需要特别强调的是这份文档不仅是设计草案而是作为开发基线。文档第十六节实现状态明确说明核心功能已按本文档完成仅剩少量后续完善项。二、现状问题旧架构的十二处痛点2.1 控制台侧的既有问题旧实现中MQTT 控制台节点同时承担页面入口和 Topic 父节点两个职责由此衍生出一系列交互与视觉问题MQTT 控制台节点既是页面入口又是 Topic 父节点职责混杂单击控制台节点时容易触发展开/折叠而不是打开页面MQTT Topic 没有右键功能左侧 Topic 树与右侧控制台分别加载、缓存订阅数据数据源不统一控制台订阅或取消订阅后侧栏没有同步刷新保存订阅与当前订阅两个概念没有明确区分保存配置后会直接订阅无法仅保存备用配置MQTT 通配符订阅与实际消息 Topic 容易混淆多个 Topic 行之间没有明显边界Topic 字体较小、颜色较淡可读性差接收消息缺少背景色与控制台底色难以区分已有控制台标签页可能无法响应外部目标 Topic 的变化。2.2 同步侧的现状不是顺带支持而是正式契约从数据结构看MQTT 的savedTopics当前保存在连接的externalConfig中现有同步逻辑可能已经间接携带 MQTT 订阅。但文档明确指出这种间接携带存在明显不足MQTT 订阅没有成为明确、独立的同步契约缺少针对 WebDAV、GitHub 的 MQTT 订阅往返测试无法区分旧快照没有订阅字段和用户明确清空全部订阅两种语义新增的enabled状态尚未纳入同步兼容规则MQTT 认证信息位于externalConfig必须确认不会因同步订阅而泄露密码、证书私钥等敏感信息下载快照采用连接元数据替换方式必须明确 MQTT 订阅的覆盖规则。因此本次需求不是简单假设现有同步已经支持而是将 MQTT 订阅同步正式定义为必须保障的功能。三、整体信息架构左侧只导航右侧管一切3.1 左侧全局侧栏纯导航重构后左侧连接树只保留MQTT 连接 └─ MQTT 控制台对应的硬性要求不在MQTT 控制台节点下展开 Topic单击节点直接打开或切换到对应 MQTT 控制台不在左侧提供新建、刷新、启用、停用、删除订阅等功能不再维护 MQTT Topic 的侧栏数据快照不再需要 MQTT Topic 右键菜单。一句话概括左侧全局侧栏仅负责页面导航不参与订阅状态管理。这一改动同时解决了原问题 2单击误触发展开和问题 3无右键菜单——Topic 相关的所有操作都收敛到右侧控制台。3.2 右侧 MQTT 控制台唯一业务入口右侧控制台作为 MQTT 业务操作和状态展示的唯一入口其布局示意如下┌──────────────────────────────────────────────────────────┐ │ MQTT 控制台 刷新连接 清空消息 │ ├────────────────────┬─────────────────────────────────────┤ │ 订阅配置 │ 当前过滤器device//status │ │ [ 新建] [刷新] │ │ │ [搜索订阅配置] │ 消息列表 │ │ │ │ │ ● device/# │ │ │ ○ device//status ├─────────────────────────────────────┤ │ ! system/events/# │ 发布消息 │ └────────────────────┴─────────────────────────────────────┘右侧订阅区域统一负责新建订阅配置、编辑订阅配置、启用订阅、停用订阅、删除订阅配置、刷新订阅状态、搜索订阅配置、选择消息过滤器、展示 QoS、展示 No Local、展示订阅状态与错误信息。四、概念澄清订阅配置、过滤器、发布 Topic 与实际消息 Topic文档用整整一章来纠正四个容易混淆的概念这直接关系界面文案与用户心智4.1 订阅配置Saved Subscription一条持久化的订阅配置包含四个字段Topic Filter QoS No Local Enabled关键语义配置可以保存但不启用。界面主标题建议统一使用订阅配置。4.2 订阅过滤器Topic Filter允许使用 MQTT 通配符例如device//status device/# system/events/#界面中不要把订阅过滤器描述成Broker 上全部存在的 Topic——过滤器是模式不是实际 Topic 列表。4.3 发布 Topic发布消息必须使用具体 Topic不能包含或#device/001/control4.4 实际消息 Topic接收或发送消息时展示的是实际 Topicdevice/001/status device/002/status例如当前过滤器为device//status消息列表同时展示device/001/status与device/002/status是完全正常的 MQTT 匹配行为不是数据不一致——这一点必须在界面上清晰传达避免用户误判为 Bug。五、订阅配置数据模型一份配置三个状态文档建议的数据结构如下interface MqttSavedTopic { topic: string; qos: MqttQoS; noLocal?: boolean; enabled: boolean; }字段含义字段含义topicMQTT Topic Filterqos请求的订阅 QoSnoLocal是否禁止 Broker 将本客户端发布的消息转发回来enabled是否启用、立即订阅并在重连时自动恢复兼容规则enabled缺失 →truenoLocal缺失 →false。Topic Filter 大小写敏感不得转换大小写。这一模型在仓库中已有完整落地。前端类型定义位于 apps/desktop/src/types/mqtt.tsMqttSavedTopic的enabled字段注释明确写着 Whether the topic is restored and subscribed when the connection opens且定义为可选字段enabled?: boolean。对应的 Rust 类型在 crates/dbx-types/src/mqtt.rs其中MqttSavedTopic通过#[serde(default default_saved_topic_enabled)]将缺失的enabled默认解析为true与文档兼容规则完全一致pub struct MqttSavedTopic { pub topic: String, #[serde(default)] pub qos: MqttQoS, #[serde(default)] pub no_local: bool, #[serde(default default_saved_topic_enabled)] pub enabled: bool, } fn default_saved_topic_enabled() - bool { true }同时MqttConnectionConfig中saved_topics字段对应 JSON 中的savedTopics使用#[serde(default, skip_serializing_if Vec::is_empty)]说明空订阅列表不会进入序列化输出这为同步快照中空列表 明确清空的语义区分提供了底层支持。5.1 自动恢复规则只恢复 enabled 的配置建立或恢复 MQTT 连接时enabled true自动发送订阅请求enabled false只保留配置不发送订阅请求恢复订阅时必须使用原有 Topic Filter、QoS 和 No Local。这一规则在 Rust 客户端 crates/dbx-core/src/admin/mqtt/client.rs 的new_with_backend中有精确实现客户端初始化时从config.saved_topics过滤出enabled的条目构建desired_subscriptions期望订阅集合并同步构建no_local_topics集合let desired_subscriptions saved_topic_configs .iter() .filter(|saved| saved.enabled) .map(|saved| (saved.topic.clone(), saved.qos)) .collect();重连后restore_desired_subscriptions()会遍历desired_subscriptions跳过已有 pending 操作的 Topic携带no_local标志重新入队订阅请求——这正是恢复订阅时必须使用原有 Topic Filter、QoS 和 No Local的实现保证。六、新建订阅配置模态弹窗与完整校验6.1 交互形式采用与 Redis 新增操作一致的模态弹出对话框不使用新标签页、内联展开卡片或侧栏右键表单。入口位于右侧订阅配置栏的 新建按钮。6.2 弹窗布局┌────────────── 新建订阅配置 ──────────────┐ │ │ │ Topic Filter │ │ [ device//status ] │ │ 支持单层通配符 和多层通配符 # │ │ │ │ QoS │ │ [ QoS 0 ▼ ] │ │ │ │ □ 禁止本地转发No Local │ │ │ │ ☑ 启用订阅 │ │ 保存后立即订阅重新连接时自动恢复 │ │ │ │ [取消] [保存] │ └──────────────────────────────────────────┘主按钮统一使用保存不再固定使用创建并订阅。6.3 启用订阅的单一开关开启启用订阅时保存订阅配置 → 当前已连接则立即发送订阅请求 → 以后重新连接自动恢复订阅。关闭时只保存订阅配置 → 当前不发送订阅请求 → 以后重新连接不自动订阅。设计要点是使用单一启用订阅选项避免同时提供立即订阅和自动订阅两个开关产生复杂组合。6.4 Topic Filter 校验规则必填自动去除首尾空格不允许包含空字符必须独占一个层级#必须独占最后一个层级不允许重复保存相同 Topic Filter输入框按 Enter 可以提交。有效示例device//status device/# system/events无效示例device device/#/status device/abc#6.5 QoS 选项使用下拉框三个等级与说明QoS 0 — 最多一次 QoS 1 — 至少一次 QoS 2 — 恰好一次默认值保持当前行为建议使用 QoS 0。从源码看Rust 侧MqttQoS枚举AtMostOnce/AtLeastOnce/ExactlyOnce在 crates/dbx-types/src/mqtt.rs 中默认值为AtMostOnce与建议默认值一致。6.6 提交状态机点击保存后按序执行禁用表单避免重复提交按钮显示保存中…先持久化配置如果启用则等待 Broker 订阅确认成功后关闭弹窗刷新右侧订阅配置列表自动选中新配置显示成功反馈。分支语义只保存未启用配置不发送 MQTT 订阅请求状态显示未启用订阅失败配置仍可保存状态显示订阅失败保留 Broker 返回的错误信息用户可稍后重试或停用。从客户端实现看订阅请求通过queue_subscribe_request入队并携带add_to_desired标志只有用户主动发起的订阅add_to_desired true才会在 SUBACK 成功后写入desired_subscriptions、no_local_topics与saved_topic_configs见complete_subscribe_ack这与保存配置与运行订阅分离的模型一一对应。七、No LocalMQTT 5.0 专属的订阅选项禁止本地转发对应 MQTT 5.0 的No Local订阅选项。要求如下保存配置时持久化noLocal启用和恢复订阅时携带noLocal订阅配置列表中展示NL或No Local标记MQTT 5.0 允许设置MQTT 3.1 和 MQTT 3.1.1 禁用禁用时提示仅 MQTT 5.0 支持。提示说明文案开启后Broker 不会将当前客户端自己发布的匹配消息再次转发给该客户端。源码侧客户端subscribe方法对协议版本做了硬校验if no_local !matches!(self.config.protocol_version, super::types::MqttProtocolVersion::V5) { return Err(MQTT 3.x 不支持 No Local 订阅选项.to_string()); }结合 crates/dbx-types/src/mqtt.rs 中的MqttProtocolVersion枚举V3 / V4 / V5默认 V5可以确认 No Local 仅在 v5 后端rumqttc v5 的Filter下启用。八、订阅状态与操作启用、停用、删除、编辑的完整闭环8.1 状态定义订阅配置至少包含五种界面状态已订阅 未启用 订阅中 订阅失败 连接已断开示例含图标、QoS、NL 展示● device//status QoS 1 NL 已订阅 ○ device//alarm QoS 0 未启用 ◌ system/events/# QoS 1 订阅中 ! audit/# QoS 1 订阅失败8.2 启用对未启用配置执行启用将enabled更新为true当前连接可用时立即订阅后续重新连接自动恢复状态由未启用变为订阅中最终变为已订阅或订阅失败。8.3 停用对启用配置执行停用当前已经订阅时发送取消订阅请求将enabled更新为false保留 Topic Filter、QoS 和 No Local 配置后续重新连接不自动订阅。停用 取消当前订阅但保留配置客户端complete_unsubscribe_ack中可以看到对应实现UNSUBACK 成功后从subscriptions、granted_subscriptions、desired_subscriptions三组集合中移除该 Topic并删除no_local_topics标记同时把saved_topic_configs中对应配置的enabled置为false——配置本身Topic/QoS/NoLocal被完整保留。8.4 删除如果当前已经订阅先取消订阅删除本地保存配置从订阅配置列表移除。删除 取消当前订阅并永久删除配置删除前需要确认。8.5 编辑允许编辑Topic Filter、QoS、No Local、启用状态。如果修改正在启用的配置处理顺序为取消旧订阅保存新配置使用新配置重新订阅。失败时应提供明确错误避免旧配置和新配置同时处于不确定状态。客户端queue_subscribe_request中的幂等保护与此呼应——同一 Topic 存在进行中的订阅操作时直接返回主题 xxx 的订阅操作正在处理中请稍后再试防止并发操作破坏状态一致性。九、订阅列表视觉优化紧凑列表、树形引导线与状态配色9.1 行布局采用紧凑列表 行间分隔线不使用大量独立卡片行高3236px 水平内边距8px Topic 字号13px 或 text-sm 分隔线border-b border-border/50示例● device//status QoS 1 NL ──────────────────────────────── ○ device//alarm QoS 0 ──────────────────────────────── ! system/events/# QoS 1 NL未选中时也必须能区分每一条订阅。9.2 字体规范Topic Filter 主文字使用font-mono font-medium text-[13px] 或 text-sm text-foreground/90辅助文字使用text-xs text-muted-foreground避免 Topic 主文字使用过小或过淡的样式。9.3 分组与订阅节点如果使用树形结构▾ device/ / status QoS 1 NL alarm QoS 0分组节点使用展开/文件夹图标、font-semibold、不显示 QoS 和 No Local完整订阅节点使用状态图标、等宽字体、展示 QoS / No Local / 启用状态提供编辑、启用、停用、删除操作如果一个节点既是完整订阅又存在子节点应同时展示展开按钮和订阅状态。9.4 树形引导线增加低对比度引导线增强层级可读性device │ ├─ production │ ├─ status │ └─ alarm └─ test └─ status9.5 行状态样式状态样式普通bg-transparent、text-foreground/90、border-b border-border/50悬停hover:bg-muted/60选中bg-primary/10、border-l-2 border-l-primary、text-primary未启用text-muted-foreground订阅中bg-amber-500/5、border-l-2 border-l-amber-400订阅失败bg-destructive/5、border-l-2 border-l-destructive状态不能只通过颜色表达还需要状态文字或图标兼顾色弱与无障碍需求。9.6 辅助标签右侧显示QoS 0 / QoS 1 / QoS 2、NL、已订阅、未启用。要求标签不能挤压 Topic 主文字Topic 过长时省略ellipsis悬停显示完整 TopicNL悬停显示完整含义。十、消息列表视觉优化方向必须多维表达10.1 接收消息靠左显示浅蓝色背景蓝色左边线显示接收标签。bg-blue-50/70 dark:bg-blue-950/30 border-l-2 border-blue-40010.2 发送消息靠右显示浅绿色背景绿色右边线显示发送标签。bg-emerald-50/70 dark:bg-emerald-950/30 border-r-2 border-emerald-40010.3 消息方向表达原则方向同时通过四种方式表达左右对齐、发送/接收标签、不同方向边线、不同背景色。不能只依赖颜色——这与订阅状态不能只通过颜色表达是同一设计原则在消息区的延续。从消息数据结构看前端 apps/desktop/src/types/mqtt.ts 的MqttMessage带有direction?: MqttMessageDirectionsent | receivedRust 侧MqttMessage也有对应的direction字段默认Received说明方向信息从事件循环记录消息起就贯穿始终前端渲染可直接依赖。十一、其他交互细节11.1 刷新订阅配置刷新按钮位于右侧订阅配置区域。刷新后保留当前选择当前选择不存在时切换到全部消息不重复创建订阅不清空消息缓冲区。11.2 搜索订阅配置支持按照完整 Topic Filter 搜索搜索结果保留必要的树形上下文或临时切换为扁平列表清除搜索后恢复原展开状态。11.3 选择未启用配置点击未启用配置时可以查看和编辑配置消息区域可以显示该过滤器已有的历史消息不应暗示当前正在接收新消息明确显示该订阅尚未启用。十二、状态管理右侧控制台是唯一状态所有者右侧 MQTT 控制台作为唯一状态所有者维护以下九类状态Broker 连接状态已保存订阅配置当前有效订阅当前选择的过滤器启用和停用状态订阅请求状态订阅错误消息列表发布面板状态。左侧连接树不再维护 MQTT Topic Tree。设计上必须严格区分三组概念已保存配置 已启用配置 Broker 已确认订阅不能将这三个状态合并为一个列表状态。从 Rust 客户端可以清晰看到这三组状态的物理对应saved_topic_configs已保存配置含禁用项、desired_subscriptions已启用、期望恢复的配置、subscriptionsBroker 通过 SUBACK 确认的当前订阅连接断开时清空。broker_info()返回的subscription_count计算的是subscriptions.len()即只统计 Broker 已确认的订阅而非保存的配置数。十三、WebDAV 与 GitHub 同步MQTT 订阅的独立同步契约13.1 同步范围WebDAV 和 GitHub 项目同步必须包含每个 MQTT 连接的全部订阅配置connectionId Topic Filter QoS No Local Enabled需要同步已启用配置、未启用配置、QoS、No Local、启用状态、空订阅列表。不需要同步当前选中的过滤器、Topic 树展开状态、当前订阅中/订阅失败等临时运行状态、MQTT 消息缓存、已发布或已接收的消息历史、当前连接在线状态。13.2 与连接的关联订阅配置必须通过稳定的connectionId与 MQTT 连接关联。下载同步快照后连接存在恢复该连接对应的订阅配置连接不存在由同步快照恢复连接及其订阅配置非 MQTT 连接忽略 MQTT 订阅数据不得把一个 MQTT 连接的订阅错误应用到另一个连接。13.3 同步快照结构用字段存在性表达语义建议在同步快照中将 MQTT 订阅定义为明确字段而不是只依赖externalConfig.savedTopicsinterface MqttSubscriptionSyncEntry { connectionId: string; subscriptions: MqttSavedTopic[]; } interface SyncSnapshot { // 其他现有字段 mqttSubscriptions?: MqttSubscriptionSyncEntry[]; }这一建议已完整落地到仓库。在 crates/dbx-core/src/persistence/cloud_sync.rs 中SyncSnapshot结构体新增了mqtt_subscriptions: OptionVecMqttSubscriptionSyncEntry字段并带有#[serde(default)]标记与明确注释Nonemeans this is a legacy snapshot that predates MQTT subscription sync and must not clear local subscriptions when applied旧快照应用时不得清空本地订阅。配套的MqttSubscriptionSyncEntry含connection_id与subscriptions与MqttSubscriptionSyncTopic含topic、qos、no_local、enabled其中qos默认atmostonce、enabled默认true均为 camelCase 序列化与前端类型一一对应。关键语义设计mqttSubscriptions 缺失 旧版本快照不修改本地 MQTT 订阅配置 mqttSubscriptions 存在但某连接 subscriptions 为空 明确清空该连接的全部订阅配置该设计解决了旧快照没有字段和用户明确删除全部订阅无法区分的问题——这是同步功能中最容易踩坑的歧义点。externalConfig.savedTopics仍可作为本地连接配置的存储位置但同步快照必须具有明确、可测试的 MQTT 订阅契约。在cloud_sync.rs中可以看到两条对应路径extract_mqtt_subscriptions上传时从external_config的savedTopics提取并校验后写入快照以及apply_mqtt_subscriptions下载时将快照中的订阅写回连接的external_config[savedTopics]对于不包含该字段的旧快照则走preserve_local_mqtt_subscriptions_for_legacy_snapshot将本地savedTopics原样保留。13.4 上传规则上传到 WebDAV 或 GitHub 时从持久化存储读取最新 MQTT 订阅配置包含所有已启用和未启用配置不读取仅存在于页面内、尚未保存的表单内容删除的配置不能继续出现在新快照中上传成功提示中显示 MQTT 同步摘要例如同步完成3 个 MQTT 连接18 条订阅配置WebDAV 自动上传也必须包含最新订阅配置。13.5 下载规则下载快照前保持现有全局下载确认增加 MQTT 订阅变化摘要明确提示匹配连接中将新增、更新或删除多少条订阅配置例如MQTT 订阅配置将发生变化 新增 5 条更新 2 条删除 1 条下载应用规则本轮沿用现有快照方向语义下载时以远端快照为准仅当快照明确包含 MQTT 订阅字段时覆盖本地配置旧快照不包含该字段时保留本地 MQTT 订阅整个下载应用过程必须是原子的数据校验失败时不允许部分写入。13.6 已连接状态下下载下载同步快照时如果 MQTT 连接当前已打开不应静默取消或新增运行中的订阅先更新持久化配置明确提示重新连接后应用新的订阅配置当前运行连接保持现状直到用户重新连接立即应用作为后续可选增强本轮默认不做自动运行时协调。这样设计可以避免同步下载过程中突然停止或增加消息接收防止用户侧消息流意外中断。13.7 冲突策略不做 Topic 级自动合并本轮遵循现有项目同步的上传/下载方向不单独实现 Topic 级双向自动合并上传本地快照覆盖远端快照下载远端快照覆盖对应本地配置下载前展示变化摘要并确认。文档给出了明确的工程理由简单求并集会导致已删除的订阅重新出现。如果未来需要自动双向合并必须增加updatedAt、deletedAt或删除墓碑、设备/版本标识三类元数据在没有版本和删除记录前不采用自动合并。13.8 安全边界订阅是元数据认证是秘密MQTT 订阅配置不是敏感凭据因此无论是否开启同步敏感信息订阅配置都必须同步Topic Filter、QoS、No Local、Enabled 属于普通元数据。但以下信息不得因订阅同步而以明文泄露MQTT 用户密码客户端私钥私钥密码Token其他认证密钥。证书、私钥文件路径属于设备相关配置不应被当作订阅数据同步覆盖到其他设备。具体要求WebDAV 未启用敏感信息同步时订阅仍同步但认证秘密必须清除GitHub 同步继续遵循现有快照加密要求MQTTexternalConfig的秘密清理必须专门验证不能只验证其他 MQ 类型如 RabbitMQ、RocketMQ。存储层对此有专门的保障在 crates/dbx-core/src/persistence/storage.rs 中save_connection_mqtt_saved_topics只更新目标连接的externalConfig[savedTopics]字段配套测试save_connection_mqtt_saved_topics_updates_only_target_and_preserves_secrets明确验证了仅更新目标且保留 secrets从单测层面保证写入订阅配置不会触碰或覆盖认证秘密。13.9 数据校验下载时对每条订阅配置校验connectionId存在且指向 MQTT 连接Topic Filter 格式有效Topic Filter 不重复QoS 值合法No Local 类型合法Enabled 类型合法MQTT 3.1 和 MQTT 3.1.1 下收到noLocal true时不得静默错误启用。若快照中存在非法 MQTT 订阅数据下载整体失败本地订阅配置保持不变显示具体连接和 Topic Filter 错误不允许只恢复部分订阅。13.10 版本兼容兼容规则汇总旧订阅缺少 enabled → true 旧订阅缺少 noLocal → false 旧快照缺少 mqttSubscriptions → 保留本地订阅 新快照明确 subscriptions: [] → 清空对应连接订阅新版快照被不支持 MQTT 同步的旧版应用读取时应遵循现有快照版本兼容策略不得静默损坏远端快照。13.11 同步后的界面刷新下载成功后重新加载连接配置刷新右侧 MQTT 订阅配置列表当前选择仍存在时保留选择当前选择已被远端删除时切换到全部消息已连接实例提示重新连接未连接实例在下次连接时恢复enabled true的订阅。十四、代码改动范围从需求到落地的文件级映射文档第十四章给出了具体的改动范围原文声明本章仅作为后续实施范围但从实现状态看核心功能已完成。结合当前仓库结构可以梳理出与需求一一对应的实现文件14.1 左侧连接树apps/desktop/src/stores/connectionStore.tsMQTT 连接下只创建MQTT 控制台节点移除侧栏 Topic Tree 加载与转换逻辑不再默认展开 MQTT Topic。apps/desktop/src/components/sidebar/SidebarTreeRuntimeHost.vue单击 MQTT 控制台节点直接打开控制台移除 MQTT Topic 节点展开逻辑与导航分支。14.2 MQTT 控制台组件apps/desktop/src/components/mqtt/MqttAdminConsole.vue唯一订阅管理入口承载新建弹窗、编辑/启用/停用/删除操作、QoS/No Local/Enabled 与运行状态展示、搜索与刷新、消息样式优化、标签页目标过滤器变化响应。apps/desktop/src/components/mqtt/TopicTreeNode.vue建议重构为MqttSubscriptionTreeNode.vue增加行间分隔线与树形引导线、提升字体可读性、区分分组与订阅节点、展示 QoS/No Local/启用状态。建议新增MqttSubscriptionDialog.vue新建与编辑订阅配置的模态弹窗负责 Topic Filter 校验、QoS、No Local 与启用状态设置。仓库中apps/desktop/src/components/mqtt/目录下实际存在MqttAdminConsole.vue、TopicTreeNode.vue、MqttPublishDialog.vue并配套__tests__下的MqttAdminConsolePause.spec.ts、MqttAdminConsolePayloadSearch.spec.ts、MqttPublishDialog.spec.ts等测试印证控制台组件与测试基建已经落地。14.3 数据类型与后端apps/desktop/src/types/mqtt.tsMqttSavedTopic增加enabled补充订阅运行状态与同步类型。crates/dbx-core/src/admin/mqtt/client.rs区分保存配置、启用、停用、删除与当前已确认订阅连接恢复时仅恢复enabled true的配置。crates/dbx-core/src/storage.rs提供完整保存、读取和替换 MQTT 订阅配置的能力保证同步应用的原子性。14.4 云同步crates/dbx-core/src/cloud_sync.rs实际路径crates/dbx-core/src/persistence/cloud_sync.rs明确定义 MQTT 订阅同步字段mqttSubscriptions实现导入导出、兼容、校验和摘要规则验证 MQTT 敏感信息清理。apps/desktop/src/components/editor/EditorSettingsDialog.vueWebDAV/GitHub 下载前展示 MQTT 变化摘要下载后提示重新连接。14.5 标签页状态apps/desktop/src/stores/queryStore.ts简化 MQTT 控制台打开逻辑确保已有标签页响应目标过滤器变化移除不再需要的侧栏 Topic 跳转逻辑。十五、验收标准速览文档共列出 54 条验收标准可归纳为六个维度页面结构1-4MQTT 连接下只显示MQTT 控制台、节点不再展开 Topic、单击直接打开/切换页面、侧栏不保存 Topic 快照。新建订阅配置5-13模态弹窗、主按钮保存、关闭启用订阅仅保存、开启则立即订阅、重连自动恢复、历史数据缺enabled按启用处理。订阅操作14-19启用/停用/删除/编辑四类操作闭环、Topic Filter 重复或格式错误不能保存、订阅失败保留配置与错误信息。No Local20-23可保存/恢复/同步MQTT 5.0 可设置3.1/3.1.1 禁用列表显示NL。视觉24-36行间分隔、字号不小于 13px、分组与订阅节点区别、树形引导线、状态多维表达、消息方向多维表达且明暗主题均清晰。同步37-54WebDAV/GitHub 上传包含全部订阅、未开启敏感信息同步时订阅仍同步且密码/私钥不进明文快照、旧快照不清空本地、空列表可清空、非法数据整体失败、已连接实例不静默变更运行订阅、下载前展示增删改数量、上传-下载-上传后数据稳定。十六、实现状态与后续完善根据文档第十六节已完成左侧仅保留 MQTT 控制台入口订阅配置统一在右侧控制台管理使用模态弹窗新建和编辑订阅支持仅保存、启用、停用、删除、QoS、No Local 和 Enabled订阅配置与当前运行订阅分离历史配置缺少 Enabled 时兼容为启用Topic 树、状态、QoS、No Local、选中态和消息收发方向完成视觉区分WebDAV/GitHub 快照增加 MQTT 订阅专属字段支持启用和未启用配置同步并兼容旧快照MQTT 密码不进入普通同步快照同步下载校验非法订阅数据并保留本地原子性。后续可继续完善同步设置页面增加 MQTT 新增、更新、删除数量摘要及请重新连接提示增加 WebDAV/GitHub 上传—下载—再次上传的自动化回归测试连续往返后订阅数据保持稳定、不发生字段丢失。结语MQTT 控制台优化需求v1.3展示了一条完整的产品化路径从交互架构收敛左侧导航化、右侧业务化到数据模型精确化保存配置 / 启用配置 / Broker 确认订阅三态分离再到同步契约显式化mqttSubscriptions字段的存在性即语义。其中用字段缺失表达旧快照、用空数组表达明确清空的同步设计以及订阅是元数据、认证是秘密的安全边界对任何需要为消息中间件客户端做配置持久化与项目同步的设计者都有直接参考价值。当前仓库中前端类型apps/desktop/src/types/mqtt.ts、Rust 类型crates/dbx-types/src/mqtt.rs、MQTT 客户端crates/dbx-core/src/admin/mqtt/client.rs与云同步实现crates/dbx-core/src/persistence/cloud_sync.rs已构成需求到实现的完整闭环可作为后续阅读与二次开发的起点。【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DBX MQTT 控制台优化全解析：订阅配置管理、No Local 与 WebDAV/GitHub 同步契约
DBX MQTT 控制台优化全解析订阅配置管理、No Local 与 WebDAV/GitHub 同步契约【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx本文基于仓库内 docs/mqtt-console-optimization-requirements.md需求文档 v1.3展开系统讲解 DBX 桌面端 MQTT 控制台如何从页面入口 Topic 树混为一体的旧形态重构为左侧仅导航、右侧统一管理订阅配置的新架构并深入剖析订阅配置数据模型Topic Filter / QoS / No Local / Enabled、自动恢复规则、消息收发视觉优化以及 WebDAV / GitHub 项目同步中 MQTT 订阅的独立同步契约与安全边界。读完本文你将掌握 DBX 中 MQTT 订阅配置的完整生命周期新建、启用、停用、删除、编辑、它与运行中订阅的状态区分以及同步快照在旧版本兼容与明确清空之间的精确语义设计。一、背景与目标为什么 MQTT 订阅需要持久化与同步MQTT Broker 通常只负责消息路由不提供客户端订阅配置的持久化管理。DBX 中保存的 Topic Filter、QoS、No Local、启用状态都属于本地配置如果没有纳入项目同步在重装系统、更换设备或恢复项目时极易丢失。这正是本次优化的出发点。本次优化的核心目标可以归纳为七条左侧全局侧栏只保留 MQTT 控制台入口不再承载订阅管理职责右侧控制台成为全部订阅配置的统一管理入口支持只保存配置、不立即订阅即保存备用配置支持启用、停用、编辑和删除订阅配置改善 Topic 列表与消息方向的视觉辨识度WebDAV、GitHub 项目同步必须包含 MQTT 订阅配置同步订阅配置不依赖同步密码/敏感信息选项同时不得泄露认证秘密。需要特别强调的是这份文档不仅是设计草案而是作为开发基线。文档第十六节实现状态明确说明核心功能已按本文档完成仅剩少量后续完善项。二、现状问题旧架构的十二处痛点2.1 控制台侧的既有问题旧实现中MQTT 控制台节点同时承担页面入口和 Topic 父节点两个职责由此衍生出一系列交互与视觉问题MQTT 控制台节点既是页面入口又是 Topic 父节点职责混杂单击控制台节点时容易触发展开/折叠而不是打开页面MQTT Topic 没有右键功能左侧 Topic 树与右侧控制台分别加载、缓存订阅数据数据源不统一控制台订阅或取消订阅后侧栏没有同步刷新保存订阅与当前订阅两个概念没有明确区分保存配置后会直接订阅无法仅保存备用配置MQTT 通配符订阅与实际消息 Topic 容易混淆多个 Topic 行之间没有明显边界Topic 字体较小、颜色较淡可读性差接收消息缺少背景色与控制台底色难以区分已有控制台标签页可能无法响应外部目标 Topic 的变化。2.2 同步侧的现状不是顺带支持而是正式契约从数据结构看MQTT 的savedTopics当前保存在连接的externalConfig中现有同步逻辑可能已经间接携带 MQTT 订阅。但文档明确指出这种间接携带存在明显不足MQTT 订阅没有成为明确、独立的同步契约缺少针对 WebDAV、GitHub 的 MQTT 订阅往返测试无法区分旧快照没有订阅字段和用户明确清空全部订阅两种语义新增的enabled状态尚未纳入同步兼容规则MQTT 认证信息位于externalConfig必须确认不会因同步订阅而泄露密码、证书私钥等敏感信息下载快照采用连接元数据替换方式必须明确 MQTT 订阅的覆盖规则。因此本次需求不是简单假设现有同步已经支持而是将 MQTT 订阅同步正式定义为必须保障的功能。三、整体信息架构左侧只导航右侧管一切3.1 左侧全局侧栏纯导航重构后左侧连接树只保留MQTT 连接 └─ MQTT 控制台对应的硬性要求不在MQTT 控制台节点下展开 Topic单击节点直接打开或切换到对应 MQTT 控制台不在左侧提供新建、刷新、启用、停用、删除订阅等功能不再维护 MQTT Topic 的侧栏数据快照不再需要 MQTT Topic 右键菜单。一句话概括左侧全局侧栏仅负责页面导航不参与订阅状态管理。这一改动同时解决了原问题 2单击误触发展开和问题 3无右键菜单——Topic 相关的所有操作都收敛到右侧控制台。3.2 右侧 MQTT 控制台唯一业务入口右侧控制台作为 MQTT 业务操作和状态展示的唯一入口其布局示意如下┌──────────────────────────────────────────────────────────┐ │ MQTT 控制台 刷新连接 清空消息 │ ├────────────────────┬─────────────────────────────────────┤ │ 订阅配置 │ 当前过滤器device//status │ │ [ 新建] [刷新] │ │ │ [搜索订阅配置] │ 消息列表 │ │ │ │ │ ● device/# │ │ │ ○ device//status ├─────────────────────────────────────┤ │ ! system/events/# │ 发布消息 │ └────────────────────┴─────────────────────────────────────┘右侧订阅区域统一负责新建订阅配置、编辑订阅配置、启用订阅、停用订阅、删除订阅配置、刷新订阅状态、搜索订阅配置、选择消息过滤器、展示 QoS、展示 No Local、展示订阅状态与错误信息。四、概念澄清订阅配置、过滤器、发布 Topic 与实际消息 Topic文档用整整一章来纠正四个容易混淆的概念这直接关系界面文案与用户心智4.1 订阅配置Saved Subscription一条持久化的订阅配置包含四个字段Topic Filter QoS No Local Enabled关键语义配置可以保存但不启用。界面主标题建议统一使用订阅配置。4.2 订阅过滤器Topic Filter允许使用 MQTT 通配符例如device//status device/# system/events/#界面中不要把订阅过滤器描述成Broker 上全部存在的 Topic——过滤器是模式不是实际 Topic 列表。4.3 发布 Topic发布消息必须使用具体 Topic不能包含或#device/001/control4.4 实际消息 Topic接收或发送消息时展示的是实际 Topicdevice/001/status device/002/status例如当前过滤器为device//status消息列表同时展示device/001/status与device/002/status是完全正常的 MQTT 匹配行为不是数据不一致——这一点必须在界面上清晰传达避免用户误判为 Bug。五、订阅配置数据模型一份配置三个状态文档建议的数据结构如下interface MqttSavedTopic { topic: string; qos: MqttQoS; noLocal?: boolean; enabled: boolean; }字段含义字段含义topicMQTT Topic Filterqos请求的订阅 QoSnoLocal是否禁止 Broker 将本客户端发布的消息转发回来enabled是否启用、立即订阅并在重连时自动恢复兼容规则enabled缺失 →truenoLocal缺失 →false。Topic Filter 大小写敏感不得转换大小写。这一模型在仓库中已有完整落地。前端类型定义位于 apps/desktop/src/types/mqtt.tsMqttSavedTopic的enabled字段注释明确写着 Whether the topic is restored and subscribed when the connection opens且定义为可选字段enabled?: boolean。对应的 Rust 类型在 crates/dbx-types/src/mqtt.rs其中MqttSavedTopic通过#[serde(default default_saved_topic_enabled)]将缺失的enabled默认解析为true与文档兼容规则完全一致pub struct MqttSavedTopic { pub topic: String, #[serde(default)] pub qos: MqttQoS, #[serde(default)] pub no_local: bool, #[serde(default default_saved_topic_enabled)] pub enabled: bool, } fn default_saved_topic_enabled() - bool { true }同时MqttConnectionConfig中saved_topics字段对应 JSON 中的savedTopics使用#[serde(default, skip_serializing_if Vec::is_empty)]说明空订阅列表不会进入序列化输出这为同步快照中空列表 明确清空的语义区分提供了底层支持。5.1 自动恢复规则只恢复 enabled 的配置建立或恢复 MQTT 连接时enabled true自动发送订阅请求enabled false只保留配置不发送订阅请求恢复订阅时必须使用原有 Topic Filter、QoS 和 No Local。这一规则在 Rust 客户端 crates/dbx-core/src/admin/mqtt/client.rs 的new_with_backend中有精确实现客户端初始化时从config.saved_topics过滤出enabled的条目构建desired_subscriptions期望订阅集合并同步构建no_local_topics集合let desired_subscriptions saved_topic_configs .iter() .filter(|saved| saved.enabled) .map(|saved| (saved.topic.clone(), saved.qos)) .collect();重连后restore_desired_subscriptions()会遍历desired_subscriptions跳过已有 pending 操作的 Topic携带no_local标志重新入队订阅请求——这正是恢复订阅时必须使用原有 Topic Filter、QoS 和 No Local的实现保证。六、新建订阅配置模态弹窗与完整校验6.1 交互形式采用与 Redis 新增操作一致的模态弹出对话框不使用新标签页、内联展开卡片或侧栏右键表单。入口位于右侧订阅配置栏的 新建按钮。6.2 弹窗布局┌────────────── 新建订阅配置 ──────────────┐ │ │ │ Topic Filter │ │ [ device//status ] │ │ 支持单层通配符 和多层通配符 # │ │ │ │ QoS │ │ [ QoS 0 ▼ ] │ │ │ │ □ 禁止本地转发No Local │ │ │ │ ☑ 启用订阅 │ │ 保存后立即订阅重新连接时自动恢复 │ │ │ │ [取消] [保存] │ └──────────────────────────────────────────┘主按钮统一使用保存不再固定使用创建并订阅。6.3 启用订阅的单一开关开启启用订阅时保存订阅配置 → 当前已连接则立即发送订阅请求 → 以后重新连接自动恢复订阅。关闭时只保存订阅配置 → 当前不发送订阅请求 → 以后重新连接不自动订阅。设计要点是使用单一启用订阅选项避免同时提供立即订阅和自动订阅两个开关产生复杂组合。6.4 Topic Filter 校验规则必填自动去除首尾空格不允许包含空字符必须独占一个层级#必须独占最后一个层级不允许重复保存相同 Topic Filter输入框按 Enter 可以提交。有效示例device//status device/# system/events无效示例device device/#/status device/abc#6.5 QoS 选项使用下拉框三个等级与说明QoS 0 — 最多一次 QoS 1 — 至少一次 QoS 2 — 恰好一次默认值保持当前行为建议使用 QoS 0。从源码看Rust 侧MqttQoS枚举AtMostOnce/AtLeastOnce/ExactlyOnce在 crates/dbx-types/src/mqtt.rs 中默认值为AtMostOnce与建议默认值一致。6.6 提交状态机点击保存后按序执行禁用表单避免重复提交按钮显示保存中…先持久化配置如果启用则等待 Broker 订阅确认成功后关闭弹窗刷新右侧订阅配置列表自动选中新配置显示成功反馈。分支语义只保存未启用配置不发送 MQTT 订阅请求状态显示未启用订阅失败配置仍可保存状态显示订阅失败保留 Broker 返回的错误信息用户可稍后重试或停用。从客户端实现看订阅请求通过queue_subscribe_request入队并携带add_to_desired标志只有用户主动发起的订阅add_to_desired true才会在 SUBACK 成功后写入desired_subscriptions、no_local_topics与saved_topic_configs见complete_subscribe_ack这与保存配置与运行订阅分离的模型一一对应。七、No LocalMQTT 5.0 专属的订阅选项禁止本地转发对应 MQTT 5.0 的No Local订阅选项。要求如下保存配置时持久化noLocal启用和恢复订阅时携带noLocal订阅配置列表中展示NL或No Local标记MQTT 5.0 允许设置MQTT 3.1 和 MQTT 3.1.1 禁用禁用时提示仅 MQTT 5.0 支持。提示说明文案开启后Broker 不会将当前客户端自己发布的匹配消息再次转发给该客户端。源码侧客户端subscribe方法对协议版本做了硬校验if no_local !matches!(self.config.protocol_version, super::types::MqttProtocolVersion::V5) { return Err(MQTT 3.x 不支持 No Local 订阅选项.to_string()); }结合 crates/dbx-types/src/mqtt.rs 中的MqttProtocolVersion枚举V3 / V4 / V5默认 V5可以确认 No Local 仅在 v5 后端rumqttc v5 的Filter下启用。八、订阅状态与操作启用、停用、删除、编辑的完整闭环8.1 状态定义订阅配置至少包含五种界面状态已订阅 未启用 订阅中 订阅失败 连接已断开示例含图标、QoS、NL 展示● device//status QoS 1 NL 已订阅 ○ device//alarm QoS 0 未启用 ◌ system/events/# QoS 1 订阅中 ! audit/# QoS 1 订阅失败8.2 启用对未启用配置执行启用将enabled更新为true当前连接可用时立即订阅后续重新连接自动恢复状态由未启用变为订阅中最终变为已订阅或订阅失败。8.3 停用对启用配置执行停用当前已经订阅时发送取消订阅请求将enabled更新为false保留 Topic Filter、QoS 和 No Local 配置后续重新连接不自动订阅。停用 取消当前订阅但保留配置客户端complete_unsubscribe_ack中可以看到对应实现UNSUBACK 成功后从subscriptions、granted_subscriptions、desired_subscriptions三组集合中移除该 Topic并删除no_local_topics标记同时把saved_topic_configs中对应配置的enabled置为false——配置本身Topic/QoS/NoLocal被完整保留。8.4 删除如果当前已经订阅先取消订阅删除本地保存配置从订阅配置列表移除。删除 取消当前订阅并永久删除配置删除前需要确认。8.5 编辑允许编辑Topic Filter、QoS、No Local、启用状态。如果修改正在启用的配置处理顺序为取消旧订阅保存新配置使用新配置重新订阅。失败时应提供明确错误避免旧配置和新配置同时处于不确定状态。客户端queue_subscribe_request中的幂等保护与此呼应——同一 Topic 存在进行中的订阅操作时直接返回主题 xxx 的订阅操作正在处理中请稍后再试防止并发操作破坏状态一致性。九、订阅列表视觉优化紧凑列表、树形引导线与状态配色9.1 行布局采用紧凑列表 行间分隔线不使用大量独立卡片行高3236px 水平内边距8px Topic 字号13px 或 text-sm 分隔线border-b border-border/50示例● device//status QoS 1 NL ──────────────────────────────── ○ device//alarm QoS 0 ──────────────────────────────── ! system/events/# QoS 1 NL未选中时也必须能区分每一条订阅。9.2 字体规范Topic Filter 主文字使用font-mono font-medium text-[13px] 或 text-sm text-foreground/90辅助文字使用text-xs text-muted-foreground避免 Topic 主文字使用过小或过淡的样式。9.3 分组与订阅节点如果使用树形结构▾ device/ / status QoS 1 NL alarm QoS 0分组节点使用展开/文件夹图标、font-semibold、不显示 QoS 和 No Local完整订阅节点使用状态图标、等宽字体、展示 QoS / No Local / 启用状态提供编辑、启用、停用、删除操作如果一个节点既是完整订阅又存在子节点应同时展示展开按钮和订阅状态。9.4 树形引导线增加低对比度引导线增强层级可读性device │ ├─ production │ ├─ status │ └─ alarm └─ test └─ status9.5 行状态样式状态样式普通bg-transparent、text-foreground/90、border-b border-border/50悬停hover:bg-muted/60选中bg-primary/10、border-l-2 border-l-primary、text-primary未启用text-muted-foreground订阅中bg-amber-500/5、border-l-2 border-l-amber-400订阅失败bg-destructive/5、border-l-2 border-l-destructive状态不能只通过颜色表达还需要状态文字或图标兼顾色弱与无障碍需求。9.6 辅助标签右侧显示QoS 0 / QoS 1 / QoS 2、NL、已订阅、未启用。要求标签不能挤压 Topic 主文字Topic 过长时省略ellipsis悬停显示完整 TopicNL悬停显示完整含义。十、消息列表视觉优化方向必须多维表达10.1 接收消息靠左显示浅蓝色背景蓝色左边线显示接收标签。bg-blue-50/70 dark:bg-blue-950/30 border-l-2 border-blue-40010.2 发送消息靠右显示浅绿色背景绿色右边线显示发送标签。bg-emerald-50/70 dark:bg-emerald-950/30 border-r-2 border-emerald-40010.3 消息方向表达原则方向同时通过四种方式表达左右对齐、发送/接收标签、不同方向边线、不同背景色。不能只依赖颜色——这与订阅状态不能只通过颜色表达是同一设计原则在消息区的延续。从消息数据结构看前端 apps/desktop/src/types/mqtt.ts 的MqttMessage带有direction?: MqttMessageDirectionsent | receivedRust 侧MqttMessage也有对应的direction字段默认Received说明方向信息从事件循环记录消息起就贯穿始终前端渲染可直接依赖。十一、其他交互细节11.1 刷新订阅配置刷新按钮位于右侧订阅配置区域。刷新后保留当前选择当前选择不存在时切换到全部消息不重复创建订阅不清空消息缓冲区。11.2 搜索订阅配置支持按照完整 Topic Filter 搜索搜索结果保留必要的树形上下文或临时切换为扁平列表清除搜索后恢复原展开状态。11.3 选择未启用配置点击未启用配置时可以查看和编辑配置消息区域可以显示该过滤器已有的历史消息不应暗示当前正在接收新消息明确显示该订阅尚未启用。十二、状态管理右侧控制台是唯一状态所有者右侧 MQTT 控制台作为唯一状态所有者维护以下九类状态Broker 连接状态已保存订阅配置当前有效订阅当前选择的过滤器启用和停用状态订阅请求状态订阅错误消息列表发布面板状态。左侧连接树不再维护 MQTT Topic Tree。设计上必须严格区分三组概念已保存配置 已启用配置 Broker 已确认订阅不能将这三个状态合并为一个列表状态。从 Rust 客户端可以清晰看到这三组状态的物理对应saved_topic_configs已保存配置含禁用项、desired_subscriptions已启用、期望恢复的配置、subscriptionsBroker 通过 SUBACK 确认的当前订阅连接断开时清空。broker_info()返回的subscription_count计算的是subscriptions.len()即只统计 Broker 已确认的订阅而非保存的配置数。十三、WebDAV 与 GitHub 同步MQTT 订阅的独立同步契约13.1 同步范围WebDAV 和 GitHub 项目同步必须包含每个 MQTT 连接的全部订阅配置connectionId Topic Filter QoS No Local Enabled需要同步已启用配置、未启用配置、QoS、No Local、启用状态、空订阅列表。不需要同步当前选中的过滤器、Topic 树展开状态、当前订阅中/订阅失败等临时运行状态、MQTT 消息缓存、已发布或已接收的消息历史、当前连接在线状态。13.2 与连接的关联订阅配置必须通过稳定的connectionId与 MQTT 连接关联。下载同步快照后连接存在恢复该连接对应的订阅配置连接不存在由同步快照恢复连接及其订阅配置非 MQTT 连接忽略 MQTT 订阅数据不得把一个 MQTT 连接的订阅错误应用到另一个连接。13.3 同步快照结构用字段存在性表达语义建议在同步快照中将 MQTT 订阅定义为明确字段而不是只依赖externalConfig.savedTopicsinterface MqttSubscriptionSyncEntry { connectionId: string; subscriptions: MqttSavedTopic[]; } interface SyncSnapshot { // 其他现有字段 mqttSubscriptions?: MqttSubscriptionSyncEntry[]; }这一建议已完整落地到仓库。在 crates/dbx-core/src/persistence/cloud_sync.rs 中SyncSnapshot结构体新增了mqtt_subscriptions: OptionVecMqttSubscriptionSyncEntry字段并带有#[serde(default)]标记与明确注释Nonemeans this is a legacy snapshot that predates MQTT subscription sync and must not clear local subscriptions when applied旧快照应用时不得清空本地订阅。配套的MqttSubscriptionSyncEntry含connection_id与subscriptions与MqttSubscriptionSyncTopic含topic、qos、no_local、enabled其中qos默认atmostonce、enabled默认true均为 camelCase 序列化与前端类型一一对应。关键语义设计mqttSubscriptions 缺失 旧版本快照不修改本地 MQTT 订阅配置 mqttSubscriptions 存在但某连接 subscriptions 为空 明确清空该连接的全部订阅配置该设计解决了旧快照没有字段和用户明确删除全部订阅无法区分的问题——这是同步功能中最容易踩坑的歧义点。externalConfig.savedTopics仍可作为本地连接配置的存储位置但同步快照必须具有明确、可测试的 MQTT 订阅契约。在cloud_sync.rs中可以看到两条对应路径extract_mqtt_subscriptions上传时从external_config的savedTopics提取并校验后写入快照以及apply_mqtt_subscriptions下载时将快照中的订阅写回连接的external_config[savedTopics]对于不包含该字段的旧快照则走preserve_local_mqtt_subscriptions_for_legacy_snapshot将本地savedTopics原样保留。13.4 上传规则上传到 WebDAV 或 GitHub 时从持久化存储读取最新 MQTT 订阅配置包含所有已启用和未启用配置不读取仅存在于页面内、尚未保存的表单内容删除的配置不能继续出现在新快照中上传成功提示中显示 MQTT 同步摘要例如同步完成3 个 MQTT 连接18 条订阅配置WebDAV 自动上传也必须包含最新订阅配置。13.5 下载规则下载快照前保持现有全局下载确认增加 MQTT 订阅变化摘要明确提示匹配连接中将新增、更新或删除多少条订阅配置例如MQTT 订阅配置将发生变化 新增 5 条更新 2 条删除 1 条下载应用规则本轮沿用现有快照方向语义下载时以远端快照为准仅当快照明确包含 MQTT 订阅字段时覆盖本地配置旧快照不包含该字段时保留本地 MQTT 订阅整个下载应用过程必须是原子的数据校验失败时不允许部分写入。13.6 已连接状态下下载下载同步快照时如果 MQTT 连接当前已打开不应静默取消或新增运行中的订阅先更新持久化配置明确提示重新连接后应用新的订阅配置当前运行连接保持现状直到用户重新连接立即应用作为后续可选增强本轮默认不做自动运行时协调。这样设计可以避免同步下载过程中突然停止或增加消息接收防止用户侧消息流意外中断。13.7 冲突策略不做 Topic 级自动合并本轮遵循现有项目同步的上传/下载方向不单独实现 Topic 级双向自动合并上传本地快照覆盖远端快照下载远端快照覆盖对应本地配置下载前展示变化摘要并确认。文档给出了明确的工程理由简单求并集会导致已删除的订阅重新出现。如果未来需要自动双向合并必须增加updatedAt、deletedAt或删除墓碑、设备/版本标识三类元数据在没有版本和删除记录前不采用自动合并。13.8 安全边界订阅是元数据认证是秘密MQTT 订阅配置不是敏感凭据因此无论是否开启同步敏感信息订阅配置都必须同步Topic Filter、QoS、No Local、Enabled 属于普通元数据。但以下信息不得因订阅同步而以明文泄露MQTT 用户密码客户端私钥私钥密码Token其他认证密钥。证书、私钥文件路径属于设备相关配置不应被当作订阅数据同步覆盖到其他设备。具体要求WebDAV 未启用敏感信息同步时订阅仍同步但认证秘密必须清除GitHub 同步继续遵循现有快照加密要求MQTTexternalConfig的秘密清理必须专门验证不能只验证其他 MQ 类型如 RabbitMQ、RocketMQ。存储层对此有专门的保障在 crates/dbx-core/src/persistence/storage.rs 中save_connection_mqtt_saved_topics只更新目标连接的externalConfig[savedTopics]字段配套测试save_connection_mqtt_saved_topics_updates_only_target_and_preserves_secrets明确验证了仅更新目标且保留 secrets从单测层面保证写入订阅配置不会触碰或覆盖认证秘密。13.9 数据校验下载时对每条订阅配置校验connectionId存在且指向 MQTT 连接Topic Filter 格式有效Topic Filter 不重复QoS 值合法No Local 类型合法Enabled 类型合法MQTT 3.1 和 MQTT 3.1.1 下收到noLocal true时不得静默错误启用。若快照中存在非法 MQTT 订阅数据下载整体失败本地订阅配置保持不变显示具体连接和 Topic Filter 错误不允许只恢复部分订阅。13.10 版本兼容兼容规则汇总旧订阅缺少 enabled → true 旧订阅缺少 noLocal → false 旧快照缺少 mqttSubscriptions → 保留本地订阅 新快照明确 subscriptions: [] → 清空对应连接订阅新版快照被不支持 MQTT 同步的旧版应用读取时应遵循现有快照版本兼容策略不得静默损坏远端快照。13.11 同步后的界面刷新下载成功后重新加载连接配置刷新右侧 MQTT 订阅配置列表当前选择仍存在时保留选择当前选择已被远端删除时切换到全部消息已连接实例提示重新连接未连接实例在下次连接时恢复enabled true的订阅。十四、代码改动范围从需求到落地的文件级映射文档第十四章给出了具体的改动范围原文声明本章仅作为后续实施范围但从实现状态看核心功能已完成。结合当前仓库结构可以梳理出与需求一一对应的实现文件14.1 左侧连接树apps/desktop/src/stores/connectionStore.tsMQTT 连接下只创建MQTT 控制台节点移除侧栏 Topic Tree 加载与转换逻辑不再默认展开 MQTT Topic。apps/desktop/src/components/sidebar/SidebarTreeRuntimeHost.vue单击 MQTT 控制台节点直接打开控制台移除 MQTT Topic 节点展开逻辑与导航分支。14.2 MQTT 控制台组件apps/desktop/src/components/mqtt/MqttAdminConsole.vue唯一订阅管理入口承载新建弹窗、编辑/启用/停用/删除操作、QoS/No Local/Enabled 与运行状态展示、搜索与刷新、消息样式优化、标签页目标过滤器变化响应。apps/desktop/src/components/mqtt/TopicTreeNode.vue建议重构为MqttSubscriptionTreeNode.vue增加行间分隔线与树形引导线、提升字体可读性、区分分组与订阅节点、展示 QoS/No Local/启用状态。建议新增MqttSubscriptionDialog.vue新建与编辑订阅配置的模态弹窗负责 Topic Filter 校验、QoS、No Local 与启用状态设置。仓库中apps/desktop/src/components/mqtt/目录下实际存在MqttAdminConsole.vue、TopicTreeNode.vue、MqttPublishDialog.vue并配套__tests__下的MqttAdminConsolePause.spec.ts、MqttAdminConsolePayloadSearch.spec.ts、MqttPublishDialog.spec.ts等测试印证控制台组件与测试基建已经落地。14.3 数据类型与后端apps/desktop/src/types/mqtt.tsMqttSavedTopic增加enabled补充订阅运行状态与同步类型。crates/dbx-core/src/admin/mqtt/client.rs区分保存配置、启用、停用、删除与当前已确认订阅连接恢复时仅恢复enabled true的配置。crates/dbx-core/src/storage.rs提供完整保存、读取和替换 MQTT 订阅配置的能力保证同步应用的原子性。14.4 云同步crates/dbx-core/src/cloud_sync.rs实际路径crates/dbx-core/src/persistence/cloud_sync.rs明确定义 MQTT 订阅同步字段mqttSubscriptions实现导入导出、兼容、校验和摘要规则验证 MQTT 敏感信息清理。apps/desktop/src/components/editor/EditorSettingsDialog.vueWebDAV/GitHub 下载前展示 MQTT 变化摘要下载后提示重新连接。14.5 标签页状态apps/desktop/src/stores/queryStore.ts简化 MQTT 控制台打开逻辑确保已有标签页响应目标过滤器变化移除不再需要的侧栏 Topic 跳转逻辑。十五、验收标准速览文档共列出 54 条验收标准可归纳为六个维度页面结构1-4MQTT 连接下只显示MQTT 控制台、节点不再展开 Topic、单击直接打开/切换页面、侧栏不保存 Topic 快照。新建订阅配置5-13模态弹窗、主按钮保存、关闭启用订阅仅保存、开启则立即订阅、重连自动恢复、历史数据缺enabled按启用处理。订阅操作14-19启用/停用/删除/编辑四类操作闭环、Topic Filter 重复或格式错误不能保存、订阅失败保留配置与错误信息。No Local20-23可保存/恢复/同步MQTT 5.0 可设置3.1/3.1.1 禁用列表显示NL。视觉24-36行间分隔、字号不小于 13px、分组与订阅节点区别、树形引导线、状态多维表达、消息方向多维表达且明暗主题均清晰。同步37-54WebDAV/GitHub 上传包含全部订阅、未开启敏感信息同步时订阅仍同步且密码/私钥不进明文快照、旧快照不清空本地、空列表可清空、非法数据整体失败、已连接实例不静默变更运行订阅、下载前展示增删改数量、上传-下载-上传后数据稳定。十六、实现状态与后续完善根据文档第十六节已完成左侧仅保留 MQTT 控制台入口订阅配置统一在右侧控制台管理使用模态弹窗新建和编辑订阅支持仅保存、启用、停用、删除、QoS、No Local 和 Enabled订阅配置与当前运行订阅分离历史配置缺少 Enabled 时兼容为启用Topic 树、状态、QoS、No Local、选中态和消息收发方向完成视觉区分WebDAV/GitHub 快照增加 MQTT 订阅专属字段支持启用和未启用配置同步并兼容旧快照MQTT 密码不进入普通同步快照同步下载校验非法订阅数据并保留本地原子性。后续可继续完善同步设置页面增加 MQTT 新增、更新、删除数量摘要及请重新连接提示增加 WebDAV/GitHub 上传—下载—再次上传的自动化回归测试连续往返后订阅数据保持稳定、不发生字段丢失。结语MQTT 控制台优化需求v1.3展示了一条完整的产品化路径从交互架构收敛左侧导航化、右侧业务化到数据模型精确化保存配置 / 启用配置 / Broker 确认订阅三态分离再到同步契约显式化mqttSubscriptions字段的存在性即语义。其中用字段缺失表达旧快照、用空数组表达明确清空的同步设计以及订阅是元数据、认证是秘密的安全边界对任何需要为消息中间件客户端做配置持久化与项目同步的设计者都有直接参考价值。当前仓库中前端类型apps/desktop/src/types/mqtt.ts、Rust 类型crates/dbx-types/src/mqtt.rs、MQTT 客户端crates/dbx-core/src/admin/mqtt/client.rs与云同步实现crates/dbx-core/src/persistence/cloud_sync.rs已构成需求到实现的完整闭环可作为后续阅读与二次开发的起点。【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考