ZKTeco F18无法执行DATA UPDATE等命令及无/devicecmd响应问题排查

问题背景 #

我用Spring Boot开发自定义AMDS（考勤管理设备服务器），与ZKTeco F18（固件8.0.4）集成时，设备能正常通过/iclock/getrequest接口轮询服务器，但发送CMD=DATA UPDATE USERINFO或CMD=RESTART这类命令后，设备既不执行操作，也没有向服务器的/devicecmd接口发送POST响应，无任何确认信息返回。

已尝试操作 #

• 发送格式符合要求的命令：

  ***ID=1298&CMD=DATA UPDATE USERINFO PIN=108 Name=STEPHEN Privilege=0
  ***
  

• 重启设备与服务器
• 确保命令格式包含ID=和CMD=字段
• 确认设备网络连接正常、轮询功能正常

问题1：设备为何无法执行DATA UPDATE或RESTART命令？ #

• 检查命令包裹格式：ZKTeco设备要求命令必须用***包裹，但首尾的***必须单独占一行，如果你的命令结尾***和内容在同一行，设备会判定为无效格式。正确写法：

  ***
  ID=1298&CMD=DATA UPDATE USERINFO PIN=108 NAME=STEPHEN PRIVILEGE=0
  ***
  

• 注意参数大小写：8.0.4固件对参数名大小写敏感，比如Privilege要写成PRIVILEGE，Name改成NAME，统一用大写测试。
• 先完成设备认证：部分F18固件要求服务器先通过CMD=AUTH完成认证，才能执行RESTART、USERINFO更新这类敏感命令。先发送认证命令：

  ***
  ID=1298&CMD=AUTH PWD=你的设备管理密码
  ***
  

• 补充必要参数：该版本的DATA UPDATE USERINFO命令可能需要额外参数，比如CARDNO（无卡填0）、FingerCount，补全后再尝试：

  ***
  ID=1298&CMD=DATA UPDATE USERINFO PIN=108 NAME=STEPHEN PRIVILEGE=0 CARDNO=0 FINGERCOUNT=0
  ***
  

问题2：轮询正常但发送命令后无/devicecmd POST请求的原因？ #

• 命令未被正确解析：如果命令格式错误（比如***位置不对、参数有误），设备会直接丢弃命令，不会返回响应。可以抓包确认服务器发送的命令是否完整到达设备，以及设备是否有返回包。
• 服务器响应格式错误：设备在/iclock/getrequest轮询时，服务器返回的命令必须是纯文本格式，不能包含HTML标签、JSON结构或多余字符。如果Spring Boot接口返回的是JSON或带额外响应头的内容，设备无法识别命令，自然不会触发/devicecmd回调。
• 设备回调配置未生效：检查设备端的“上传设置”，确认已开启“命令确认”选项，且回调地址正确指向服务器的/devicecmd接口。部分F18设备需要手动在设备端配置服务器回调路径，不能仅依赖轮询接口返回命令。

问题3：ZKTeco F18（固件8.0.4）是否有特定配置步骤或固件特性导致该问题？ #

• 必须开启主动上传模式：8.0.4版本固件默认可能关闭主动回调功能，需要在设备端进入“通讯设置”，开启“主动上传”，并设置上传事件包含“命令响应”。
• 固件限制：该版本对DATA UPDATE命令的发送频率有严格限制，短时间内重复发送相同命令会被拦截；同时RESTART命令需要设备处于空闲状态（无用户操作、无正在进行的考勤记录）才能执行。
• 网络端口限制：F18默认用TCP 80端口与服务器通讯，确保服务器防火墙或NAT配置允许设备IP访问/devicecmd接口端口，且服务器接受设备发起的POST请求。

内容的提问来源于stack exchange，提问作者NDUNG'U STEPHEN MUIRU