简介面向需要对接中控考勤机的Java开发者这份demo压缩包包含源码与配套文档重点解决考勤数据读取、考勤人员新增与调动等二次开发需求适合有Java基础、正在搭建或改造企业考勤系统的技术人员。压缩包整体约37.77MB内容覆盖Java与中控考勤机API的调用方式、TCP/IP网络通信机制、返回数据如XML/JSON的解析处理以及数据库操作等核心模块文档部分对通信协议和API参数给出了具体说明便于对照阅读对于希望快速掌握硬件交互的开发者尤其友好。目前已有258人学习。资源还围绕异常处理、测试调试、项目结构与版本控制、数据安全等实践要点展开帮助开发者避开常见问题。通过阅读文档并结合demo源码可以掌握从建立连接、采集数据到维护员工信息的完整流程进而构建自动化、可维护的考勤管理功能。1. 考勤机 Java 二次开发:中控 demo 先跑通,再谈改业务老板把一台中控考勤机丢到我工位上,说新员工录不进指纹,让我一周内把打卡数据接进公司人资系统。这就是「考勤机 Java 二次开发」这个需求最常见的开场:设备已经在墙上,软件体系还没接上。拆开中控Java二次开发demo.zip,里面是厂商给的 SDK、示例 Java 工程和一堆 dll/so 本地库。它解决的不是设备屏幕怎么点,而是 Java 程序怎么在局域网里跟设备握手、拉取打卡记录、下发人员模板。适合刚接触设备对接的 Java 后端,也适合想评估协议风险的老团队。我习惯先把 demo 完整跑一遍再动手改结构,因为中控这台机器的很多坑,只有真机连上才会暴露。很多教程喜欢先给你吹一遍 SDK 有多强大,我写这份笔记的习惯是先把目录打开,告诉你哪些文件有用、哪些文件可以放着不管。整份资源解压之后,真正能帮到你的是三个部分:src 下的示例代码、lib 下的本地库与 SDK jar、doc 下的接口说明。后面几章我会按「包结构 → 通信链路 → 跑通流程 → 排坑 → 验证技巧」往下推演,每个环节都说清参数和踩坑。这样你拿到手的是能直接照着操作的经验,不是一份看完还要自己去试错的摘要。2. demo 包结构和通信链路:从 SDK 方法到 4370 端口2.1 拆包:src、lib、doc 和那台设备的默认端口我拆过好几版中控考勤机的二次开发包,大部分发布包的目录差别不大。src目录下通常是几个演示类,命名一般很直白,比如ConnectDemo、GetAttendanceDemo、SetUserDemo;lib目录下是厂商封装好的 jar 以及对应不同平台的本地库,Windows 上常见的是zkemclient.dll和zkemclient.jar,Linux 上则是对应的.so文件;doc目录里一般是接口参数对照表和协议说明文档。这份 demo 里的 Java 代码,本质上只是把厂商 C 暴露出来的接口做了一层 JNA/JNI 封装,所以你会发现代码风格跟平时写的 Spring Boot 服务完全不一样,很多方法名直接是对着 C 函数翻译过来的。比如你大概率会看到connect、getUserInfo、getAttendanceRecord这一串名字。别被命名劝退,这些方法对应设备上的具体操作,不是抽象业务概念。中控设备的 Java SDK 和标准 Java 库最大的区别就在于,它没有把「设备」再抽象成服务,而是把每个能力直接暴露成函数。你用的时候要清楚自己调的是哪个底层动作,不然很容易把getUserInfo当成getAttendanceRecord用。设备通信这一层,中控的考勤机一般默认走 TCP 端口 4370。这个端口号不是随便定的,它是中控设备固件里写死的服务端口,相当于设备自己开了一个监听 socket。你用 telnet 连一下 4370 端口,只要没有立刻断掉,说明设备网络是通的。另外,部分新固件还开放了 UDP 15110 端口做设备发现,用于在局域网里广播查找设备,但真正传数据还是走 4370 的 TCP。整个 demo 的配置参数也绕不开这几个值:设备 IP、设备端口、通讯密码。通讯密码这个字段很多新手会忽略,默认设备上是0,也就是不校验。一旦你在设备面板上设置了通讯密码,所有 SDK 调用都必须带上对应的 int 密码值,否则设备会直接拒绝应答。这个密码不是 Web 管理后台的登录密码,是设备上的「通讯设置」里的口令,很多人把这两个搞混,导致连接状态一直飘红。2.2 通信协议骨架:握手包、命令码和数据区要理解 demo 代码在干什么,得先知道中控设备的数据包大概长什么样。我没法把厂商完整协议文档贴出来,只讲最关键的部分:一次完整的数据交换,通常由握手包开始。客户端连上 4370 端口后,先发一个固定格式的握手请求,设备返回 ACK;之后客户端再发具体的命令包,设备处理完返回对应数据包。这个机制有点像 HTTP 里的 Keep-Alive,连接保持住以后,后续的数据交互会快很多。所以 demo 里通常会有一个全局的连接对象,而不是每读一次记录就重新建立一个 socket。新建连接的开销不算大,但中控设备的服务端有时候处理不过来频繁的新连接,会导致握手超时。我一般会在生产代码里维护一个设备连接池,或者至少在程序生命周期内复用一个连接。如果你们的业务量不大,单台设备并发很低,那一个长连接完全够用。命令包内部基本是三段式:命令头、命令码、数据区。命令码决定这个包是查询、设置还是删除;数据区放具体的参数,比如用户 ID、指纹模板、时间范围。demo 源码里一般不会直接让你组装这些二进制,而是封装成一两个方法,你调用的时候只需要传入设备 IP 和参数。但理解命令码会让你在排查问题时更有方向。比如你调用getAttendanceRecord拿到一堆记录,返回的数据其实分了好几段,前一段是记录条数,后面每一段才是单条打卡记录。如果不按这个结构解析,就会看到一串乱码或者只取到第一条。SDK 底层还有一个容易被忽略的行为:它默认开了批量读取和缓存。中控设备内部有 flash 存储,打卡记录先存在设备本地,SDK 读取时会把本地缓存全部拉出来。所以你在 demo 里看到「先读记录、再清除设备标记」这个流程,不是随便写的,而是为了防止同一批记录被重复读取。清除操作一般叫clearAttendanceData或markAttendanceAsRead,有的固件要用clearData参数区分全量删除和已读标记。这个动作在生产环境必须做成可配置的,否则一不留神就把设备里的考勤原始数据删了。为了让你对协议有个直观认识,我贴一段抓包时常见的数据交互序列。这不是要你照着实现协议,而是方便你理解后面的代码为什么要这么写:客户端 - 设备: [握手包] 02 00 00 00 ... 设备 - 客户端: [ACK] 00 00 ... 客户端 - 设备: [查询命令] GET /get_attendance ... 设备 - 客户端: [数据包] 记录条数 记录体...实际数据会比这个复杂,但逻辑骨架没变。我每次拿到新固件都会先抓一次这个序列,确认需求里的接口调用方式和 demo 一致,再动手写业务代码。这个方法老套但很稳,能避开很多协议描述文档里「不明确」的坑。2.3 Java 代码怎么把协议串起来:一个长连接对象走天下demo 里所有示例程序的主流程几乎是同一个套路。以读考勤记录为例,先创建客户端对象,调用connect(ip, port)建立连接;连接成功后再调用数据查询方法;查询完成后最后调用disconnect()释放连接。这个三角环看起来简单,但很多同学把disconnect()放进了finally块里,结果每次查询都重新建连,在高频轮询场景下把设备搞得不稳定。我建议参考 demo 里的写法:程序启动时连接一次,整个服务生命周期内复用;服务停止时再断开。如果你担心连接断了,可以做一个心跳线程,每隔 30 秒调用一次getDeviceTime或者计算设备在线状态。中控设备的并发能力很有限,别像调 MySQL 一样调考勤机,设备最多同时维持几个连接,再多就会拒包。这一章的技术点,说白了就一句话:你拿到 demo 后先别急着改代码,先把连接、读取、断开这个链路跑通,看 TCP 4370 端口上的数据交互是否正常。协议细节可以后面慢慢抠,链路必须一次跑通,否则后面写的所有业务代码都悬在空中。3. 跑通 demo 的完整操作:JDK 配置、设备 IP 与第一次读卡3.1 环境准备:JDK、本地库与网络检查三件套我在 Windows 和 Linux 上都跑过这个 demo,先说你最快能跑通的环境配置。JDK 版本建议先别用太新的,如果你用的包是几年前发布的,本地库可能只做了 32 位版本,那就要配 32 位 JDK。这一点很容易踩,后面避坑章节再展开。环境准备我一般分三步。第一步,确认 JDK 已安装并配置好环境变量。用命令行检查:java -version javac -version如果你看到java指向的是 JDK 8,而javac是另一个版本,说明 PATH 里混进了多个 JRE,先把多余的删掉。中控的 demo 编译目标通常是 JDK 8,用更高版本编译问题不大,但运行时可能因为模块化限制遇到报错,所以最好是装一个干净 JDK 8。如果你手头只有高版本 JDK,也不是不能用,只是遇到问题时优先怀疑这个环境差异。第二步,把本地库目录加入java.library.path。最直接的办法是在启动命令里显式指定:java -Djava.library.path./lib -cp ./lib/zkemclient.jar:./src DemoRunnerWindows 上注意路径分隔符是分号,Linux 上是冒号。如果忽略这一步,程序通常会报UnsatisfiedLinkError或者加载不到 dll。网络上有不少人卡在这一步,以为是包坏了,其实只是没把路径告诉 JVM。你可以在代码里用下面这个片段,打印实际加载路径确认:System.out.println(System.getProperty(java.library.path));第三步,确认设备网络可达。中控考勤机一般用固定 IP,现场经常是 192.168.1.x 网段。先做一次 ping,再看 4370 端口通不通:ping 192.168.1.201 telnet 192.168.1.201 4370telnet 能连上但没输出,别慌,这是正常的。设备是在等你发握手包,你用Ctrl]再输入quit退出即可。这一步能帮你快速区分「网络不通」和「SDK 调用有问题」。有些网络环境下,ping 会丢包,但 TCP 端口能连上,那说明设备本身是活的,只是网络质量不好,后续用长连接反而更稳。3.2 配置设备连接参数:IP、端口、通讯密码的优先级demo 里一般会有一个Global类或者config.properties文件,集中放设备连接参数。你把它改成现场设备的真实值就够了。重点是理解这几个参数的优先级:SDK 构造函数里的参数、连接方法里的参数、配置文件里的参数,不同版本的包优先级不同。我见过一个坑:配置文件里写的 IP 是对的,但代码里new ZKClient(192.168.1.201, 4370)这条语句把 IP 写死成了另一台设备。所以排查的时候先看代码里有没有写死的 IP,再看配置。参数扫描顺序我会这样来:先看 demo 启动入口,再看资源文件,最后看启动脚本。很多同学只改配置文件,没看启动脚本里的-D参数,结果启动脚本重新覆盖了配置。连接参数表我这里放一份,方便你对照:参数典型值说明设备 IP192.168.1.201设备面板可查,或通过 UDP 搜索端口4370中控设备默认 TCP 端口通讯密码0设备通讯设置里的口令,默认为 0连接超时3000ms建议显式设置,默认值可能过长通讯密码这块我要多说一句:如果你在设备面板上设置了「通讯密码」,而 SDK 里没传,表现不是直接报错,而是握手超时。你可能会在日志里看到连接建立成功,但后续所有命令都没有回应。这算中控设备比较有迷惑性的一个设计,因为它不区分「密码错误」和「命令超时」。排查时我一般首先把通讯密码改成 0,然后重启设备,确认是不是密码问题。3.3 跑通最小读取流程:连接、取记录、清标记环境准备好了,参数配完了,现在正式跑一遍读取流程。下面的代码是我把 demo 里的调用链简化后的模板,实际包里类名可能不一样,但方法名基本能对上。我先说明一下,下面这段不是照着你刚拆的 zip 原样抄的,而是把 demo 里最核心的一条调用链抽出来,再补上生产里必写的参数。你拿到包以后,照着类名对一下就能找到对应位置。public class AttendanceReader { public static void main(String[] args) throws Exception { // 加载本地库,Windows 下是 zkemclient.dll System.loadLibrary(zkemclient); // 选择实现类,不同版本的包类名有差异 ZKClient client new ZKClient(); // 建立 TCP 连接,第三个参数是通讯密码 boolean connected client.connect( 192.168.1.201, // 设备 IP 4370, // 设备端口 0 // 通讯密码,默认 0 ); if (!connected) { System.err.println(连接失败,先查网络和通讯密码); return; } // 读取所有考勤记录,返回 List 或 byte[] ListAttendanceRecord records client.getAttendanceRecord(); for (AttendanceRecord r : records) { System.out.println(r.getUserNo() , r.getTime()); } // 清除设备端的已读标记,避免下次重复读到 boolean cleared client.clearAttendanceData(); if (!cleared) { System.err.println(已读标记清除失败,小心重复数据); } // 释放连接 client.disconnect(); } }这段代码有四个关键点。第一,System.loadLibrary加载的是本地库,库文件必须放在java.library.path能找到的目录。第二,connect方法返回的boolean只代表 TCP 握手是否完成,不代表设备数据是否可用。第三,getAttendanceRecord一次性返回全部记录,如果数据量大,要考虑内存和解析效率。第四,clearAttendanceData这一步,生产环境必须先备份再执行,最好做成定时任务而不是每次启动都清。我用这个简化流程跑通的第一个中控设备,总共只花了十几分钟,但中间卡在本地库加载上卡了半小时。所以后面我把这些坑单独抽成一章,每一条都是真金白银试出来的。3.4 读出来的时间怎么解析:时区、时间戳和日期格式demo 打印出来的时间往往是一串数字,中控设备返回的通常是 Unix 时间戳,单位可能是秒也可能是毫秒,跟你实际看到的时间会差上 8 小时。原因很简单,设备固件默认按 UTC 存储。你要想正确解析,得自己补上时区偏移。下面这个代码片段是我在项目里一直在用的解析方式:SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); sdf.setTimeZone(TimeZone.getTimeZone(Asia/Shanghai)); long timeSeconds records.get(0).getTime(); // 单位可能是秒 System.out.println(sdf.format(new Date(timeSeconds * 1000L)));如果你发现打印出来还是不对,先确认getTime()返回值的单位。有的固件升级后会把单位从秒改成毫秒,你要是再乘一次1000日期就炸了。我一般会在解析前先打一条原始值,人工核对之后再把运算逻辑固定下来。这一步看起来多,但能省掉后面所有时间相关的脏数据排查。4. 中控二次开发避坑清单:五个翻车现场与排查顺序4.1 现象:加载本地库报UnsatisfiedLinkError,程序直接启动失败第一次跑 demo 的时候,我在System.loadLibrary这一行看到UnsatisfiedLinkError,第一反应是包被我解压坏了。重新解压一遍,还是报错。原因:这台考勤机 SDK 里的 dll 只有 32 位版本,而我用的是 64 位 JDK。JVM 数位不匹配导致系统拒绝加载动态库。解决:换 32 位 JDK,或者把整个项目移到装有 32 位 JRE 的老机器上。如果必须用 64 位环境,就得找厂商要 64 位版本的本地库。这个在 demo 包里没写明,很容易一上来就卡住。我现在拿到包的第一件事,就是看本地库文件的位数,用命令查一下:file lib/zkemclient.dll file lib/libzkemclient.so输出里会直接显示PE32还是PE32。看到PE32就乖乖配 32 位 JDK,别跟它较劲。4.2 现象:connect 返回 true,但getAttendance一直在阻塞状态,最后超时连接时握手正常,但发数据请求后没有任何响应。日志里看不出异常,因为 SDK 内部把超时吞掉了。原因:比较常见的是设备的「通讯密码」校验不通过,设备收到命令后直接丢弃;第二个可能是设备连接数已满,有些旧型号最多只允许两个连接。还有一个隐蔽原因:设备面板锁屏了,导致命令无法响应。解决:先检查设备端是否设置了密码,把connect的第三个参数改成对应值。然后重启设备,让它释放所有旧连接。最后在设备设置里关闭「自动锁屏」或调长休眠时间。顺序别反过来,先解决连接数问题再排查密码,能省很多时间。另外,如果你是用无线模块连接的设备,信号不稳也会造成这种现象,这时哪怕 IP 能 ping 通,命令也没法完整送达。4.3 现象:能读到考勤记录,但记录时间和实际差了好几个小时设备返回的 Unix 时间戳转换后比本地时间多了 8 小时。如果你只做简单展示,这个问题还能忍,但要做考勤统计就会漏算。原因:中控设备内部存储的默认时区是 UTC,中国环境需要加 8 小时。demo 代码里通常没有做时区换算,直接把整型时间戳丢给你。解决:读取后统一用亚洲/上海时区解析,前面 3.4 小节给过代码。还有一点,设备本身的时间可能不准,因为中控考勤机没有内置 RTC 电池,断电久了时间会走偏。生产环境要做设备校时,启动同步时可以调一次setDeviceTime,把服务器当前时间下发到设备。这样的话,你拿到的时间戳才具备业务分析价值。4.4 现象:Windows 上跑得好好的,部署到 Linux 服务器上连不上设备开发机上测试正常,一放到 CentOS 上就握手失败。检查网络没问题,4370 端口也通。原因:Linux 机器上缺少对应的.so本地库,或者java.library.path没有包含.so所在目录。SDK 的本地库文件并不通用,Windows 的.dll和 Linux 的.so不能互换。解决:把lib目录整个打进部署包,启动参数里加上-Djava.library.path/opt/app/lib。还需要确认.so文件的执行权限是否为 755。我当时就是卡在权限上,文件存在但没执行权限,加载不到。chmod 755 /opt/app/lib/*.so然后再启动 Java 进程。如果还报错,用ldd查一下.so依赖的系统库是不是齐的:ldd /opt/app/lib/libzkemclient.so缺了libstdc或者别的运行库,直接装对应的系统包就行。4.5 现象:读到的打卡时间是一串负数或者 0这种数据看着不像正常时间,通常出现在你绕过 SDK、自己拼二进制包去读设备的时候。中控的数据区长度是固定的,如果你读错了偏移量,拿到的就是错位后的数据。原因:你这边的数据包封包长度不对,厂家固件返回了错误的偏移。也可能是设备里的记录时间字段本身为空,比如手动补录的异常记录。解决:先用 Wireshark 抓 4370 端口的数据包,对比 demo 正常运行时和你的程序运行时返回码的差异。特别留意设备返回的数据包头中的「记录条数」字段,如果条数与实际不符,后续解析全乱。我建议在生产代码里把原始字节流也留一份日志,排查时直接看 hex dump,比看实体类里转换后的字段直接得多。如果你用的不是官方 SDK 而是自己解析协议,那更要留原始包,因为解包逻辑错一段,后面全错。上面五条算是中控考勤机接入排查里最集中的问题源。它们有个共同特点:报错都不直接,要么卡住,要么静默丢弃,要么给你一个能跑但明显错的结果。所以我把「抓包」放进常规排查动作,而不是等出问题才想起它。5. 进阶技巧:用抓包数据反向验证 demo,再改造成定时同步服务5.1 对照 demo 行为,验证自己的连接是否属于同一种握手demo 跑通不代表你理解了它。我常用的验证方法,是把 demo 和你的程序分别连同一台设备,在运行机器上用 Wireshark 抓 4370 端口的数据流。两者的握手包、命令码应该高度相似,只是数据区内容不同。如果差异很大,说明你的连接在某个中间环节被修改或代理改写了。抓包前注意两点:一是只抓 TCP 端口 4370 的数据,不要全盘抓,不然数据量太大;二是用捕获过滤器限定tcp.port 4370,这样定位问题最快。我一般对比三次握手之后第一个应用数据包的字节流,如果前几个字节对不上,基本可以断定协议版本不同,需要用厂商较新的 SDK。这个验证动作十分钟内能完成,但能帮你省掉后面一拆包就乱码的麻烦。5.2 改造 demo 的第二个动作:把读取逻辑放进定时任务demo 里是一次性读到完、读完就断开,生产环境不能这么写。一般做法是每分钟或每五分钟轮询一次,把这期间新增的考勤记录同步到数据库。轮询逻辑注意要加锁,防止上一次同步还没结束、下一次轮询又启动。我一般会在代码里放一个布尔标志位,开始同步时置位,同步结束释放。如果设备响应慢,还能提前发现超时。private boolean syncing false; public synchronized void syncFromDevice() { if (syncing) { return; } syncing true; try { // 连接设备并读取增量记录 // 写入数据库后,再调用 clearAttendanceData } finally { syncing false; } }定时任务建议用ScheduledExecutorService,不用引入太重框架。每次执行时,如果连接已经断开,就重新connect一次。连接对象在同步任务里保持独立,比多个任务共享一个连接更安全。最后再提一个细节:拿到 demo 后先别急着删里面的注释和测试类。那个ConnectDemo之类的入口,留着它,就是你排查问题的基准程序。我现在的习惯是,任何一次中控设备接入,都先让 demo 原封不动跑通,再在它旁边开一个自己的模块,两边对照着改。从那以后,我每次对接中控设备,都会强制走一遍同样的流程:先在 4370 端口上抓十分钟包,再决定要不要改底层协议。这个习惯帮我省掉了很多「明明连上却拿不到数据」的扯皮。希望帮到你。本文还有配套的精品资源点击获取