随时重现难以捕捉的 MQTT 故障
MQTT 故障往往依赖多个客户端、特定的消息顺序和精确时序。Replay 保存这段流程，在你的 Broker 上重新运行，并显示预期结果是否仍然成立。
- 作者:
- Mqttable
- 更新:
本页目录10 个章节
加载中...
/docs/engineer/replay
MQTT 故障往往依赖多个客户端、特定的消息顺序和精确时序。Replay 保存这段流程，在你的 Broker 上重新运行，并显示预期结果是否仍然成立。
加载中...
有些 MQTT 故障只会在多个客户端按照特定顺序连接、发布和响应时出现。手工重复这段流程，很难确认修复是否真正有效。
本文通过内置 Demo 展示 Replay 如何重新运行同一段流程并检查结果。即使没有安装 Mqttable，也可以通过正文和截图了解完整过程；已经安装的读者可以跟着操作。
Replay Scenario 是一组已保存的 MQTT 客户端动作，可以来自 Trace、Mqttable 导出的 TraceGrid CSV、PCAP 证据或内置 Demo。一个 Scenario 可以协调多个客户端，并保留或调整来源中的动作时序。
Dry Run 会解析目标、客户端、凭据、步骤、时序和安全设置，但不会发送 Replay 流量。运行后，Run Trace 会记录 Replay 客户端实际发送和收到的报文。Replay Check 可以把其中一项重要结果保存下来，让下一次运行自动判断它是否满足要求。
本文使用的 Demo 有 89 条来源记录。Mqttable 将它们转换为 39 个可执行 MQTT 步骤，涉及 7 个客户端和 8 个出站 PUBLISH Topic。Broker 响应和收到的 PUBLISH 会保留为证据，不会重复变成发送动作。
如果要跟着操作，需要准备：
截图使用 Replay Docs Demo · mqtt://127.0.0.1:3883，这是一个只监听回环地址、允许匿名访问的 Broker。如果还没有目标，可以先完成 MQTT 快速入门，或阅读 Broker 与 Connection。
内置 Replay Demo 是可信的特殊场景。无需登录或购买 Pro，也可以打开、配置、Dry Run 并完整运行 Demo。自己创建的 Free Scenario 最多可以运行 15 个可执行 Replay Step。
Replay 可以接收 Mqttable 导出的 TraceGrid CSV，也可以把内置 Demo 打开为已保存的 Scenario。
Mqttable 会把演示 TraceGrid CSV 回放打开为一个 Scenario 标签。此时还没有发送 MQTT 流量。如果 Demo 已经存在，试用演示会打开已保存的版本，不会覆盖修改。
Scenario 打开后，详情默认展开。运行前先查看来源事实：
来源、目标、执行设置、检查和结果视图都属于同一个 Replay Scenario。
打开目标选择器。Mqttable 会列出已保存的 Broker，并在选择前显示 Endpoint 详情。
目标选择必须明确，因为 Run Replay 会连接到这个 Broker 并发送真实 MQTT 流量。
如果列表为空，请先回到 Connections 创建测试 Broker，再重新打开 Replay。目标还需要至少一个已启用的 MQTT 客户端，否则 Dry Run 会提示添加或启用目标 MQTT 客户端。
选择配置。Options 决定身份、凭据、时序和 Broker 副作用。修改任何执行输入后，都要重新 Dry Run。
常规区域选择 Scenario 和目标；客户端会话区域决定哪些身份和凭据会连接 Broker。
选项 | Demo 默认值 | 作用 |
|---|---|---|
名称 | 演示 TraceGrid CSV 回放 | 只修改已保存 Scenario 的名称。 |
目标 | 当前选择的测试目标 | 决定哪个 Broker 接收 Replay 流量。 |
生成安全的 Replay Client ID | 开启 | 为来源 Client ID 生成隔离且确定的 ID。普通测试应保持开启。 |
复用捕获的 Client ID | 关闭 | 使用原始身份，可能断开同 Client ID 的在线客户端，或改变持久 Session。 |
Replay Client ID 模板 | 产品默认模板 | 控制隔离 ID 的生成方式。默认模板可以区分来源，又不会占用原始身份。 |
凭据策略 | 缺少时回退到所选目标 | 来源客户端没有匹配凭据时使用目标凭据。严格模式要求每个客户端都有匹配凭据。 |
在同一设置页中向下滚动，继续检查执行防护和 Topic 改写。
执行防护限制副作用和发送节奏；Topic 改写可以把完整 MQTT 生命周期移入测试命名空间。
选项 | 行为 |
|---|---|
以非 retained 发送 | 运行时清除 Retain，避免测试替换 Broker 的 retained state。 |
首次失败即停止 | 第一个 MQTT 动作失败后停止，不继续执行只完成一部分的流程。 |
保持采集时序 | 保留证据中的时间偏移，也是 Demo 的默认选择。 |
立即发送 | 忽略来源间隔，由最大发布速率限制每秒 PUBLISH 数量。 |
缩放采集时序 | 使用时序倍率调整速度。2.0 表示两倍速度，0.5 表示一半速度。 |
压缩空闲间隔 | 保持动作顺序，但把超过最大空闲间隔的停顿缩短。 |
Topic 改写规则 | 为 Publish、Subscribe 或 Unsubscribe 匹配并替换 Topic，支持 $1、$2 和
|
普通 Scenario 使用缩放和压缩时序需要 Pro。可信的内置 Demo 无需登录即可使用。第一次运行保持 Demo 默认设置，然后选择关闭。
选择试运行。Mqttable 会解析当前来源、目标、Options、凭据、客户端身份和安全设置，但不会连接 Replay 客户端，也不会发送 Replay 流量。
完成后选择详情，折叠 Scenario 摘要，为结果区留出更多纵向空间。折叠状态会在当前应用 Session 中保持，也能跨 LiveView 更新恢复；它不会修改 Scenario 或 Dry Run 结果。
折叠详情后，可以同时看到就绪状态、目标、计划规模、客户端、时长、影响和注意事项。
Dry Run 通过后，运行 Replay才会可用。如果修改目标、来源、客户端身份、凭据、防护、时序或 Topic 规则，当前结果就会失效，需要重新 Dry Run。
如果 Dry Run 被阻断，先处理第一条 blocker。常见原因包括没有目标、Broker 不可达、凭据无效、Client ID 冲突或 Scenario 设置不安全。
选择运行 Replay。Demo 会连接隔离客户端，按顺序执行 MQTT 动作，记录 Broker 响应和收到的消息，然后断开连接。
查看结果时保持详情折叠。Run Trace 是这一次执行的证据，不是普通应用日志。
Run Trace 显示本次执行的完整结果，包括生命周期计数、状态、过滤器和实际捕获的 MQTT 报文。
生命周期计数说明执行了多少动作，每一行说明具体发生了什么。发送 PUBLISH 只能证明 Replay 客户端发出了命令；匹配的 RECV PUBLISH 才能证明订阅客户端收到了消息。
Run Trace 保存在进程内。重启 Mqttable 或清理旧 Run Session 可能移除它；Scenario 和已保存的检查仍会保留。
把 Run Trace 过滤到 demo/replay/final/commands/gw/restart-pump，找到发送命令和匹配的接收 PUBLISH。右键 RECV PUBLISH 行，选择添加投递检查。
投递检查从真实接收证据开始，并且 Mqttable 能把它关联到产生结果的 Replay PUBLISH 步骤。
打开检查 → 管理，查看已保存的契约。
检查会保存精确的投递条件，同时保留可以继续检查的 Run Trace 证据。
CONNACK、SUBACK、PUBACK、UNSUBACK 和 PINGRESP 等协议响应由对应 Replay Step 检查，交付检查负责业务结果。还可以从 Replay 客户端的 SEND SUBSCRIBE 行创建精确的订阅计数检查。
关闭检查对话框，再次选择运行 Replay。添加或编辑检查不会改变 MQTT 执行指纹；只要执行输入没有变化，已经通过的 Dry Run 仍然有效。
运行结束后展开详情，同时查看检查摘要和 Run Trace 结果。
Scenario 完成和 Check 判定是两个结果：已完成确认执行结束，PASS 确认已保存的投递条件满足。
Replay 会分开显示执行状态与 PASS / FAIL 检查结果：
熟悉 Demo 后，可以从以下证据创建自己的 Scenario：
Replay 复现语义级 MQTT 行为，包括客户端动作、Session 生命周期、时序、协议期望和选定的业务结果。它不会复现完全相同的 TCP 分片、网络抖动或 Broker 内部状态。
使用时保持这些边界：
可信的内置 Demo 无需账户即可运行全部 39 个步骤和所有发送节奏。自己创建的 Free Scenario 最多可以保留三个标签、运行 15 个可执行 Replay Step，并使用立即发送或保持采集时序。Pro 会解除这些深度限制，并提供缩放和压缩时序。