HowTo: MQTT 直连自有服务器

设备不经过商为云，直接连你自有 MQTT 服务器。打印内容全程不上商为云——满足金融 / 医疗 / 政务对数据自主的硬要求。本指南依据《云打印机对接第三方 MQTT 通信协议》V2.0 编写，覆盖连接与传输安全、主题约定、下发与上报报文、任务结果码与幂等重发规则、服务端状态机。该方案已有国内与海外用户商用运行。
对接协议 V2.0 ｜ 2026-09-27 发布，替代 V1.0（2025-11-08）
本页步骤： 1 服务器与端口 · 2 写入连接参数 · 3 主题与消息流 · 4 下发报文 · 5 上行与状态码 · 6 幂等与重发 · 7 远程配置 · 8 传输加固

1支持的 MQTT 服务器与端口

云打印设备作为 MQTT Client，支持接入以下类型的服务器：

服务器类型明文端口TLS 端口连接参数来源
自建 / 第三方 MQTT18838883Username / Password / ClientID 由客户自行设定（仅此类需配置 TLS 开关与 CA）
阿里云 IoT厂商默认厂商 TLS 端口ProductKey + DeviceName + DeviceSecret（三元组）
腾讯云 IoT Hub厂商默认厂商 TLS 端口ProductId + DeviceName + DeviceSecret（三元组）
电信云及其他按服务商规范请联系商务确认
云平台无需配置传输层安全参数：阿里云 IoT、腾讯云 IoT Hub 的端口、TLS、证书与签名算法均由设备固件按厂商标准协议实现，不提供也不需要 TLS 开关与 CA 配置项；只需在云厂商控制台创建设备，并把三元组信息写入配置工具。下面的 TLS 开关、CA 证书、主机名校验等内容仅适用于自建 / 第三方 MQTT。

适用设备：热敏打印机、标签打印机、打印云盒。如有定制需求（共享订阅、桥接、主题重写等 Broker 特性），请联系商务人员评估。

2写入设备连接参数

使用 PC 端《云打印设备 MQTT 配置工具》，通过 USB 数据线连接设备写入参数，无需设备联网：

  1. 准备好 Broker 的主机域名、端口、账号与密码；建议启用 TLS 并使用 8883 端口
  2. 打印机开机，用 USB 数据线连接 PC
  3. 在配置工具中选择服务器类型（自建 / 第三方 MQTT、阿里云、腾讯云等），填入地址、端口、鉴权信息，以及完整的订阅主题与发布主题字符串
  4. 按需写入附加项：需要接收离线消息时选择「保留离线消息」；Broker 使用自签 / 私有 CA 时另行写入 CA 证书（PEM）

连接参数约定

参数约定
协议版本默认按 MQTT 3.1.1 连接，为全机型基线。MQTT 5.0 仅部分机型支持，需固件与配置工具同时支持并在写入参数时显式选择。两种版本下业务报文、状态码与幂等规则完全一致，详见第 8 步。
ClientID取设备 SN。全 Broker 内必须唯一；字符限定 [A-Za-z0-9_-]，长度 1–30，不得为空。同一个 ClientID 二次上线会互相踢线，请勿重复写号。
Keep Alive建议 ≤ 300 s（推荐 60 s），且应小于链路 NAT / 防火墙的空闲连接超时（企业网络常见 300–900 s）。设备空闲时会自动发送 PINGREQ 保活，4G 网络尤其依赖此机制。
QoS下发与上报均使用 QoS 1，不支持 QoS 2。QoS 1 的语义是「会话存在期间至少送达一次」，不等于离线必达，见第 6 步。
Retain必须为 0。服务端请勿向设备 Retain 打印任务，否则设备每次订阅（含重连后重新订阅）都会重打历史小票。补救：向同一主题发布一条空 payload 的 Retain 消息即可清除已保留的消息。
PayloadUTF-8 JSON（无 BOM），键名大小写敏感。单条建议 ≤ 32 KB；图片 PNG ≤ 60 KB、BMP ≤ 6 KB；二维码内容 ≤ 512 字节。
离线消息
（sen）		默认清除离线消息（sen = 0，适合外卖 / 收银等实时场景）；需要补打漏单时改为保留离线消息（sen = 1），此时 Broker 必须按 ClientID 持久化会话与 QoS 1 队列。注意：sen = 1 依赖 Broker 侧不清除会话，若会话过期时间过短或该 ClientID 在别处重复登录，离线消息仍会丢失——选型为「必须补单」的业务请在应用层保留重发能力。
TLS 启用判定（仅自建 / 第三方 MQTT），满足任一即走加密连接 mqtts://： ① 配置开关 tls = 1；② 端口为 8883 或 443；③ 主机以 mqtts:// / ssl:// / tls:// 开头（scheme 会被自动剥离）。其余情况走明文 mqtt://。
💡 Clean Session：设备默认在连接时清除会话。如需设备继续接收离线期间的消息，请在配置工具写入参数时选择「不清除 Session」。

3主题与消息流

协议约定两类主题，QoS 均为 1：

方向用途QoS
订阅主题（下行）接收打印任务、语音播报消息、命令消息1
发布主题（上行）上报设备状态、打印结果、扫码与按键内容1
⚠️ 订阅主题与发布主题必须不同，且不得互为前缀。若两者配成同一个主题，设备订阅后会收到自己发出的上报报文，并当作下行指令解析（缺少 type 字段 → 上报 code = 208）。这是现场高频错误。

主题命名的几条规则

📌 关于主题名：具体主题字符串随所选 MQTT 服务器类型与设备参数而定。云平台（阿里云 / 腾讯云）的主题由厂商规则推导，自建 Broker 由客户自行规划。完整协议文档（含主题约定、字段定义与状态码全表）可向商务索取。

设备上报数据中的 devicename 为设备 SN（机器码），与应用侧三元组的 DeviceName 或 ClientID 保持一致。

4下行：打印与语音消息字段

MQTT 服务器推送到云打印设备的消息为 UTF-8 编码的 JSON，QoS 1，Retain 0：

字段类型必填说明
iduint32是打印任务 id，范围 0-4294967295。服务端须确保不重复；设备具备防重打能力——同一 id 在不断电情况下只打印一次，重复推送会上报状态 209。注意 id 回绕：自增到上限归零、或使用秒级时间戳时，可能与设备侧防重缓存中的旧 id 撞上
typeint是数据类型 / 打印语言，取值见下表
contentsString / Array / Object是打印内容，结构随 type 变化。优先于 message
messagestring否预留的 HTTP 下载型打印内容 URL，与 contents 二选一
pWidthint否打印纸张宽度（mm）：58（默认）/ 80 / 110
pCopyint否打印份数，默认 1
pTypeint否纸类型（默认 1）：1 连续纸｜2 标签纸｜3 黑标纸｜4 穿孔纸｜8 连续纸（标签指令打印小票）。纸类型为标签时必传
vTypeint否播报类型：-1 无播报｜0 定制语音｜1 固定音「你有新的订单」｜10000 指定语音链接下载播报
vMessagestring否vType = 0 时为 TTS 文本内容（UTF-8）；vType = 10000 时为音频下载 URL
vModeint否0 按队列顺序播报（默认）｜1 立即播报｜2 立即播报并清空待播报队列
gatewaystring否仅 WiFi + 网口版打印云盒：usb 表示转发到本机 USB 打印机；填入 IP（如 192.168.2.11）表示转发到指定局域网网络打印机
expire 规划中uint32否任务有效期，单位「秒」的相对值，自设备受理时刻起算；超过仍未执行则上报 code = 212 并丢弃。缺省 1800；填 0 表示永不过期
force 规划中uint8否强制打印：1 = 跳过设备侧防重，允许同一 id 再次打印；缺省 0。仅用于服务端主动发起的补打 / 重印，常规下发不要带此字段

type 取值

type含义contents 形态
1ESC/POS 指令string（Base64 编码的 ESC 指令）
2CPCLstring
3TSPLstring
4XML 排版string。基础 XML 兼容主流云打印平台；矢量多语言 XML（限 M 后缀机型）支持全球语种与 RTL 排版
5JSON 排版Array（票据）/ Object（标签）
6PNG 图片string：图片 URL 或 Base64 内容
99设备配置管理Object，见第 7 步
100支付结果通知string / Object / Array。用于驱动支付到账播报，具体实现请联系商务确认

打印排版语言（XML 标签、JSON 票据元素、JSON 标签元素）的完整定义见官网开发文档中心与打印排版设计。

示例一：XML 排版（票据，type=4）

{"id":100001,"type":4,"pType":1,"pWidth":58,"pCopy":1,"vType":0,"vMessage":"测试语音", "contents":"<CB>收款小票</CB><BR>商户存根 请妥善保管<BR>--------------------------------<BR>商户名称 示例水果店<BR>交易金额 126.50 元<BR><QR>10058001200047217</QR><BR>--------------------------------<BR>打印时间 2026-09-16 11:02:36<BR>"}

示例二：JSON 排版（票据，type=5）

{"id":100002,"type":5,"pType":1,"pWidth":58,"pCopy":1, "contents":[ {"cont":"云打印 JSON 排版","type":"title"}, {"thead":{"名称":"40%","单价":"25%","数量":"15%","金额":"20%"}, "tbody":[["云打印机（4G/WiFi）",100,1,100],["打印云盒",189,1,189]]}, {"cont":"合计:289 元","size":"11","align":"left"}, {"both_sides":["收款金额","289.00"]}, {"both_sides":["支付方式","微信支付"]}, {"cont":"https://www.sw-aiot.com","type":"qrcode","align":"center","size":"60"}, {"cont":"1","type":"cut"}]}
🔴 请对同一台设备串行发布：MQTT 只在「同一方向、同一会话、飞行窗口内」保证 QoS 1 的顺序。若服务端多实例 / 多线程并发发布，先发的单可能后到，导致打印顺序错乱。建议收到上一条确认（或间隔一小段时间）后再发下一条，单设备建议 ≤ 1 条/秒。
大内容建议走 URL：长内容可改用 message 字段或 contents 中的 https 链接下发，由设备下载后打印。URL 必须使用 https——明文 http 会旁路整套 MQTTS 的安全投入。

5上行：上线报文、设备状态与打印结果

设备上报的数据以 UTF-8 JSON 组装，QoS 1，Retain 0。

5.1 上线报文

设备每次 MQTT 连接成功后统一上报一条上线报文，携带当前打印机状态：状态正常时报 code = 0，存在异常时报对应的打印机状态码。该报文不带 id，属打印机状态类上报，不进入任务状态机。

// 状态正常 {"devicename":"SWP20260730001","code":0} // 缺纸 {"devicename":"SWP20260730001","code":101} // 4G 机型：额外携带卡号信息（imei 15 位、iccid 20 位） {"devicename":"SWP20260730001","code":0,"imei":"123456789012345","iccid":"12345678901234567890"}

上报时机：每次 MQTT 连接成功后上报一次（含首次联网、掉线重连、设备重启）。服务端以收到本报文作为上线信号，而不是「收到任意首条上报」——请勿把扫码 / 按键等事件类上报当作上线信号。

上报字段

字段类型必填说明
devicenamestring是云打印设备 SN（机器码），与 ClientID / DeviceName 一致
iduint32条件打印结果上报时必填；纯状态上报不带本字段（这是区分任务结果与打印机状态的关键）
codeint条件状态码，见下表。状态类与结果类上报必带；事件类上报（扫码、按键）不带
imei / iccidstring否仅 4G 机型，随上线报文上报
scan_contentstring否扫码机型上传的条码 / 二维码内容
keyevent 规划中int否按键事件：1 = 按键按下。仅带按键机型上报

上行报文判定顺序

上报报文没有显式的类型字段，服务端请自上而下、命中即停地判定：

  1. 含 keyevent → 按键事件（设备事件，不进任务状态机）
  2. 含 scan_content → 扫码事件（设备事件，不进任务状态机）
  3. 含 code 且带 id → 任务结果（走任务状态机）
  4. 含 code 不带 id → 打印机状态（只更新打印机状态）
  5. 含 imei / iccid → 4G 机型上线信息（不进状态机）

注：4G 机型的上线报文同时带 code 与 imei / iccid，应按第 4 条（打印机状态）处理。第 5 条仅用于兼容不含 code 的存量上线报文。

状态码一览

码段规则——按「是否携带任务 id」划分：2xx 为任务结果，上报必带 id；1xx 为打印机状态，上报不带 id，只说明这台打印机当前的硬件状态，不改变任何任务状态；0 为成功，是唯一跨两类的特殊码（带 id 时表示该任务打印成功，不带 id 时表示打印机从异常恢复正常）。

任务结果码（带 id）

code含义处理建议
0成功终态。任务打印完成，关闭任务
201缺少 id补齐 id
202缺少 type补齐 type
203type 无效取值仅限 1 / 2 / 3 / 4 / 5 / 6 / 99 / 100
204缺少 contents / message二者必须存在一个
205message 无效例如 URL 不是标准 http(s) 链接
206下载错误连续下载失败（重试 6 次）；建议为下载类任务设置 ≥ 60 s 超时
207任务长度超出缓冲区缩小 Payload（建议 ≤ 32 KB）或改用 URL 方式
208内容格式错误contents 结构与 type 不匹配
209重复任务同 id 已打印过；属正常防重，服务端据此确认幂等
210 规划中受阻，已排队等待非终态。任务已受理但无法立即出票（缺纸 / 开盖 / 过热，或前方仍有未出票任务）。停止重推，等待设备恢复后自动补打并上报终态；可提示商户「请装纸」。不代表异常，不应据此告警
211 规划中设备忙，队列已满非终态。本地队列已满，任务未被接收。退避 15 / 30 / 60 s 后用同一 id 重发
212 规划中任务过期被丢弃终态。自受理起超过 expire 秒（缺省 1800）仍未执行。不要重发；如需补单，重新生成内容并用新 id
213 规划中硬件故障，打印放弃终态。缺纸 / 开盖等待超过 30 分钟，或出现不可恢复故障。不要重发，转告警或人工处理

两个超时的优先级：213 优先于 212。设备侧硬件等待上限为 1800 s，会先于 expire 触发；因此在缺纸 / 开盖这类最常见的受阻场景里，先到达终态的是 213。201–209 为已落地固件的既有错误码，编号保持不变；新增的任务执行状态码自 210 起顺序分配。

打印机状态码（不带 id）

code含义处理建议
100未知错误 / 通信异常重试；连续出现需现场排查网络
101打印机缺纸通知商户装纸；恢复后设备上报 0（不带 id）
102打印机开盖同上
103打印机过热等待降温，勿连续重发
107设备离线（遗嘱消息专用）仅由 Broker 代发的遗嘱消息产生，表示设备已与 Broker 断开。设备不会主动上报此码；收到主动上报的 107 请忽略并记录日志
109打印机未连接 / 连接失败（打印云盒类机型）云盒未检测到打印机（打印机未接入、未上电，或数据线未插好）。请检查打印机供电与数据线连接；恢复接入后设备上报 0（不带 id）
🔴 不要拿 109 判断设备在线状态。109 表示「打印机没接上」，云盒本身仍在线、仍在正常收发消息。判断云盒 / 联网模组自身是否离线，请依据 Keep Alive 超时或遗嘱消息（code = 107），三者不可混用。

上报样例

// 上线报文（4G 机型） {"devicename":"dev1","code":0,"imei":"123456789012345","iccid":"12345678901234567890"} // 打印机状态上报：缺纸 {"devicename":"dev1","code":101} // 打印任务结果上报：任务 123456789 打印成功 {"devicename":"dev1","id":123456789,"code":0} // 扫码内容上传 {"devicename":"dev1","scan_content":"abcd1234"} // 按键事件上报（规划中） {"devicename":"dev1","keyevent":1}

6任务幂等与超时重发

规则说明
幂等防重打同一 SN 下，设备在上电周期内对同一个 id 只打印一次，重复下发将上报 code = 209。这是防止网络重发导致重复出票的首要防线
防重会失效设备重启 / 断电后防重记录会清空，同一 id 可能再次打印。请勿把设备侧防重当作业务去重的唯一手段
结果确认服务端应以设备上报的「带 id 且 code = 0」作为打印成功的最终确认。MQTT 5.0 下的原因码不反映打印结果，业务成败一律以 JSON 中的 code 为准
重发沿用原 id超时未确认、或收到 211 需要重发时，必须沿用原来的 id——换新 id 会绕过设备侧防重，直接导致重复出票
可换新 id 的情形（仅一种）收到终态失败（212 / 213）后确实需要补打，此时应重新生成内容并使用新 id，按一笔新业务处理
QoS 1 ≠ 离线必达QoS 1 保证的是「会话存在期间至少送达一次」。设备离线期间下发的任务，Broker 不会替你保存；只有同时满足 sen = 1 且 Broker 已开启会话持久化，离线消息才会在设备以同一 ClientID 重连后补发。因此无论 sen 取何值，服务端都必须实现超时重发——离线队列只是「更早送到」的优化，不是可靠性的保证
断线感知设备掉线可由 Broker 代发的遗嘱消息感知（code = 107），但存在最长约 Keep Alive × 1.5 的判定延迟，属事后确认而非实时告警。建议同时保留「Keep Alive × 1.5 内未收到任何上报」作为兜底判离线手段

建议的服务端任务状态机

状态进入条件应当做不应当做
PENDING已下发起算等待超时（建议 30 s）；等待回执并发下发多条抢占队列
WAITING收到 210停止重推；提示商户「请装纸 / 请合盖」；按 expire 设兜底超时换 id 重发（会重复出票）
RETRY超时 / 收到 211指数退避（15 / 30 / 60 s）后用同一 id重发，最多 3 次立即无限重试、换新 id
DONE收到 0归档；可清除该 id 的异常提示—
FAILED212 / 213归档并告警；确需补打则重新生成内容 + 新 id用原 id 重发
UNKNOWN3 次重发仍无回执标记未知并转人工；不要再自动重发换新 id 盲发（可能重复出票）
关于 210 的上报边界 规划中：210 只在任务受阻时上报，不是每笔任务都报——正常任务不打任何受理回执，打印完成后直接回 code = 0。因此服务端对「已下发但长时间无回执」的任务，请按超时处理，不要因为没收到受理回执就判定失败。
三条最容易踩的红线：
  • 任何重试都必须沿用原 id。QoS 1 会重复投递，换 id 是绕过设备防重、造成重复出票的主要成因。
  • 不要无限等待。210 是中间态，服务端仍应以 expire 为上限自行关闭任务，避免业务单据长期悬挂。
  • 打印机状态 ≠ 任务结果。101 / 102 / 103 / 109 不带 id，只说明「这台打印机现在缺纸 / 未连接」，不能据此判定某一单是成功还是失败。

7远程配置管理（type = 99）

云打印设备支持通过云端远程设置音量、重启打印机、设置默认指令模式等：

命令contents 结构说明
volume{"cmd":"volume","value":1}音量设置：0 静音｜1 低音量｜2 中音量｜3 大音量
reboot{"cmd":"reboot"}系统重启
label_cmd{"cmd":"label_cmd","print":"tspl"}默认标签指令（针对图片或 JSON 打印）：tspl（默认）/ cpcl / zpl
print_cmd{"cmd":"print_cmd","cmd":"tspl"}设置打印机默认语言：tspl / cpcl / esc
cycle_broadcast 规划中{"cmd":"cycle_broadcast","tts_list":["文本1","文本2"],"interval":30,"loop_count":0}仅语音机型：空闲时循环广播。tts_list 最多 10 条；loop_count = 0 表示持续播放。需确认固件支持
{"id":12345678,"type":99,"contents":{"cmd":"volume", "value":1}}
命令与打印共用一条队列、按序执行。reboot / volume 等命令会排在已积压的打印任务之后才执行——队列较长时表现为「命令延迟生效」。请避免在批量下发打印任务的同时下发时效性命令。

带扫码功能的产品还可上报扫码内容（设备事件，不带 code）：

{"devicename":"dev1","scan_content":"abcd1234"}

带按键的机型按下按键时上报按键事件 规划中。该事件属设备事件，不是任务结果，因此不带 code；最小上报间隔 1 秒，长按不连发；设备未连接 Broker 时按键不上报（不缓存、不补发）。

🔴 1 秒去重窗口挡不住 QoS 1 的重传。QoS 1 在确认丢失时由客户端重传，重传间隔按指数退避（典型 5 / 10 / 20 s），远大于 1 秒，且报文体与新事件完全一致。若只用 1 秒窗口去重，一次按键会被当成两次。推荐做法：以「设备 SN + 业务动作」为键缓存最近一次处理时间，窗口 ≥ 60 s。

8传输加固、排错与验收

启用 MQTTS 与认证模式

项目说明
启用方式自建 / 第三方 MQTT 场景，将配置中的 tls 置为 1，连接 URI 为 mqtts://{Url}:{Port}，推荐端口 8883。云平台（阿里云 / 腾讯云）由厂商标准协议决定，无此开关
建议强制启用明文模式下账号密码与打印内容（订单、金额、收件人信息）均以明文经过网络，不满足多数客户的合规要求
认证模式单向 TLS + 账号密码（当前标准做法）。双向 TLS（mTLS / 设备证书）、PSK 预共享密钥当前不支持，如需请走定制
证书下发启用 TLS 不等于必须下发 CA。设备内置公共根证书库（覆盖 Let's Encrypt、DigiCert、GlobalSign、GoDaddy、Google Trust Services、Amazon Trust Services 等），公共 CA 签发的证书开机即连，无需任何证书操作。仅当 Broker 使用自签 / 私有 CA 时才需下发该 CA——该写入能力仅部分机型支持，仅接受 PEM 格式、单张、≤ 4 KB
🔴 内置证书库与自定义 CA 互斥：一旦写入自定义 CA，内置公共根证书库即停止生效，设备只信任写入的那一张。之后若 Broker 换回公共 CA 签发的证书将握手失败，需清空已写入的 CA 才能恢复。排查 TLS 握手失败时，请先确认设备里有没有写入过 CA。

服务端证书要求

项目要求
TLS 版本≥ TLS 1.2，不支持 SSL 3.0 / TLS 1.0 / TLS 1.1
公钥算法RSA ≤ 2048 位，或 ECDSA P-256
签名算法SHA-256 及以上
主机名校验证书 CN 或 SAN 必须匹配设备填写的地址（设备以此做 SNI 与主机名校验）
IP 直连若地址填的是 IP，服务器证书必须带 SAN:IP，仅有 CN 会校验失败
有效期建议 ≤ 2 年；建议到期前 30 天启动轮换，到期后设备将无法连接
吊销检查不支持 CRL / OCSP，泄漏风险请通过更换 CA + 重新写号处理
设备侧保持证书校验：放弃主机名校验会使链路退化为「可被中间人」，等同于明文。设备侧不提供跳过校验的绕过模式，请务必保证证书与填写的地址匹配。TLS 握手失败时设备不会回落明文（安全红线），而是按指数退避重试（5 s → 10 s → 30 s → 60 s → 300 s 封顶）。

设备出网需要放行的目标

设备只做出站连接，不开放任何入站端口，因此无需公网 IP、无需在防火墙上做端口映射。请在设备的出口策略上放行：

协议 / 端口用途说明
TCP 1883 / 8883MQTT / MQTTS 长连接到 Broker 的连接，按实际配置端口放行（启用 TLS 时为 8883）。是全程持续占用的长连接
TCP 80 / 443内容下载 / 在线更新使用 URL 方式下发打印内容，或固件与语音包在线更新时才需要。URL 必须使用 https
最常见的现场现象：同一台设备、同一个 Broker，1883 明文能连上，改成 8883 加密就连不上，报 cert verify failed —— 多数是设备本地时间未同步，而不是证书本身有问题。设备没有掉电保持的实时时钟，上电后需先完成校时；若网络出口策略不允许设备访问互联网的校时服务，TLS 证书有效期校验就会失败。此时设备尚未连上 Broker，Broker 侧不会留下任何连接记录，排查方向在设备侧网络的出口策略，而不是 Broker。

排错速查

现象可能原因与处理
TLS 握手失败 / cert verify failed① 设备时间未同步 → 放行校时出口；② 下发的 CA 与签发服务器证书的 CA 不一致 → 重新导出正确的根 / 中间 CA；③ 地址与证书 CN/SAN 不匹配 → 用域名连接并确保 SAN 包含该域名
IP 直连握手失败证书缺少 SAN:IP → 改用域名，或重新签发带 subjectAltName=IP:… 的证书
CA 无法写入 / 工具拒绝① 传了 DER / PFX → 转 PEM；② 文件 > 4 KB → 换 RSA-2048 根；③ 传的是服务器证书而非 CA → 导出签发者证书
换回公共证书后反而连不上设备内残留自定义 CA，内置公共根证书库已被停用 → 用配置工具执行「清除 CA」动作后重连
设备频繁上下线ClientID 重复 → 检查写号清单，SN 必须唯一且 ≤ 30 字符
连接被立即断开 / 无 CONNACK查 Broker 日志中的 CONNACK 返回码：4 = 用户名或密码错误、5 = 未授权、2 = ClientID 被拒。这些错误仅存在于 Broker 侧，设备不会通过 MQTT 上报
设备在线、上报正常，但收不到任何下发① Broker ACL 拒绝该 ClientID 订阅下行主题（SUBACK 0x80）；② 服务端发布到的主题与写入设备的订阅主题不一致（区分大小写）→ 逐字符核对两个主题字符串
周期性掉线（间隔规律）Keep Alive 大于链路 NAT / 防火墙空闲超时，连接被中间设备回收 → 将 Keep Alive 调至 60 s 或低于出口 NAT 超时
设备连不上且换设备表现不一致该机型不支持写入自定义 CA，写入未生效，设备仍只用内置库校验，私有 CA 必然失败 → 改用公共 CA 签发的证书

验收清单

⚠️ 建议的安全加固项（由客户在自有 Broker 侧实施）：
  • TLS 加密传输（MQTTS / 8883），使用公共 CA 签发的服务端证书
  • Broker ACL：按设备 SN 限定可读写的主题
  • 通信与任务审计日志留存
  • 每设备独立凭证，杜绝 SN 仿冒
  • 数据落在客户自有数据中心

商为可协助：

⚡ 评估 MQTT 直连方案？联系商务 sw@sw-aiot.com 或拨打 0755-23003730
© 2026 商为科技 · MQTT 直连 HowTo ｜ 对接协议 V2.0（2026-09-27，替代 V1.0）· 本页为操作指引，完整规范以商务提供的最新版协议文档为准
海外站 · 新加坡节点 (EN)
延伸阅读：MQTT 直连能力总览 · 平台集成总览 · 开发文档中心 · 打印排版设计