平台显示 SUCCESS,为什么 6 台门禁仍下发失败

同一批门禁授权,平台命令记录一片绿色 SUCCESS,响应正文却都是 returnCode: 500。这不是矛盾:前者表示命令响应传输成功,后者才是接入端返回的业务失败。真正尚未拿到的,是接入程序到设备这一段原始错误。

🎧 文章导读

先把四种“成功”拆开

这次有 6 台门禁无法下发人员通行权限。页面、查询接口、消息平台和接入端分别使用不同状态,混在一句“下发成功”里就会误判。

观察层 实际状态 能说明什么
浏览器请求 HTTP 成功 请求得到响应,不代表授权成功
执行记录查询 业务查询成功 查到了记录,不代表记录结果为成功
授权执行状态 失败 业务系统已保存本次执行失败
平台外层 SUCCESS / SENDMESSAGE_SUCCESS 命令响应传输流程成功
接入端内层 returnCode=500 设备操作业务失败

代表性回包去掉设备标识后,关键结构如下:

1
2
3
4
5
6
7
8
{
"commandResponseCode": "success",
"commandResponse": {
"returnCode": 500,
"returnMsg": "设备操作异常: unknown"
},
"msg": "SENDMESSAGE_SUCCESS."
}

这里的 500 是命令正文中的业务码,不是 HTTP 500。绿色平台状态和内层业务失败可以同时成立。

门禁授权命令的去程与回程
图 1:页面状态来自整条回程链路,接入程序到设备的执行细节仍需单独取证。

能登录人脸机 Web 也不能补齐这段证据。它只证明当前电脑到设备 Web 服务可达,不能证明接入程序所在主机到设备控制通道可用,更不能证明 addUser 已执行成功。

同人员对照,缩小范围但不提前结案

为了排除人员参数和照片问题,原记录选取了同一人员在两组设备上的任务:营地目标设备全部失败,另一台仓库设备成功。两条任务使用同一接入端、同一服务方法,照片 Base64 长度和摘要相同,数据库保存的非照片参数除设备编号外一致,有效期也覆盖测试时间。

这组对照说明:至少不能用一个统一的“照片为空”“人员参数非法”或“该接入端完全不可用”解释全部现象,排查重点应转向设备相关差异。

但它仍不是严格证明:

  • 两次测试相隔约 42 分钟,不是同时执行,间歇性连接问题尚未排除。
  • 比较的是数据库任务参数,不是最终网络报文;执行时还会补充接入端信息。
  • 后续复制的所谓“失败命令”仍带着成功记录的编号和设备编号,不能拿这段重复文本证明两次实际下发报文完全一致。

因此,严谨结论是“同一组已保存人员参数在另一设备上被接受”,而不是“我方链路完全没有问题”。

平台状态与业务结果的分层判断
图 2:每一层只回答自己的问题,外层成功不能替代内层业务结果。

代码里发现问题,也不等于找到本次根因

排查过程中还看到几处值得单独修复或继续核实的实现:

  1. 批量远程开门实现没有逐设备检查业务返回,最后可能直接返回成功,所以页面“下发成功”不足以证明门已打开。
  2. 开门弹窗还会查询校验方式并轮询门状态,“先成功后报错”可能来自另一个独立请求。
  3. 某处性别转换使用了读取系统属性的 API,而不是解析整数的 API;但成功与失败任务都没有携带对应字段,不能把它认定为本次原因。
  4. 设备在线状态的计算依赖状态上报和编号匹配,不能把它当成控制通道健康检查。
  5. 物联网调用正常返回业务失败时,不一定自动回退到直连网关。

这些问题影响可观测性或潜在正确性,却没有一个能直接解释当前 6 台设备的全部证据。把它们写进“待办”比写成“根因”更有用。

下一步不是再试一次,而是补齐设备侧日志

当前断点已经清楚:系统收到了接入端业务失败回包,但还没有接入程序到人脸机这一段原始执行日志。下一步应先定位接入程序及部署主机,再选一台失败设备核对:

  • 接入配置中映射的实际地址、控制端口、序列号和登录配置;
  • 对应时间窗内 userManager/addUser 的失败步骤,以及原始 SDK 或协议错误码;
  • 与成功设备的型号、固件、连接和登录状态差异;
  • 在日志可观测后,保持人员参数不变,对失败与成功设备做接近时间的对照测试。

还要先把平台失败记录的命令 ID 与具体设备逐一关联。当前同批 6 条失败响应不能直接按顺序指定给某台设备;不同系统的原始时间也应保留,时钟未核实前不要自行换算成确定时间。

远程开门是否实际动作,需要现场单独确认;查询校验方式的独立 HTTP 500 和批量开门结果传播问题,也应作为另一条缺陷链处理,不与授权业务 500 混为一谈。

运维取证本身也要避免制造新问题

原记录里,MQS 回包位于 INFO 日志,只搜 ERROR 或堆栈会漏掉;部分日志被工具识别为二进制,需要相应文本匹配选项。按未索引的授权字段筛选并排序曾造成慢查询,后续改为已知主键或有限主键范围定位。

这些细节和门禁协议无关,却决定排查能否继续。证据不足时,最有价值的交付不是一句“设备问题”,而是一份可交接的协查材料:失败时间窗、接入端标识、同批命令、内外层状态、成功对照,以及尚待核实的设备映射。

这次故障尚未定位最终根因,也没有执行代码修复或生产数据调整。已经确认的是状态语义和证据断点:平台绿色 SUCCESS 只说明外层响应成功,6 台门禁的业务失败要继续向接入程序和设备侧追。

延伸阅读


本文根据 2026 年 10 月 28 日工程笔记及当时截图整理。人员、设备编号、网关标识和内部地址已脱敏;截图只代表当时平台状态,本次整理未登录生产平台或接入主机。