Java 对接海康 ISUP 协议：无固定 IP 人脸考勤机数据回传实战

简介：这份资源是面向Java开发者的海康威视ISUP通信Demo包，重点解决人脸考勤机在无固定IP、IP频繁变化场景下与后台系统稳定通信的难题，适用于企业考勤、校园与医院等动态网络环境下的集成开发。压缩包共约2000个文件，整体40.74MB，以810个class、16个java源码、22个dll动态库、10个lib依赖库及若干xml、conf配置与sample示例为主，另含少量js、exe、log等辅助文件，构成一套可直接参考运行的工程结构。资源中JavaISUPDemo项目展示了ISUP协议下设备寻址、身份验证与数据收发的基本流程，并兼顾C#开发者的调用习惯，便于跨技术栈理解接口设计。目前已有1155人学习下载，适合需要快速打通海康人脸考勤机动态IP通信、借鉴现成通信策略与排错思路的中高级开发者参考。

1. 没有固定 IP 的人脸考勤机，怎么把打卡数据稳定收上来

厂区门口那台人脸考勤机装完才发现，它拿的是 4G 卡或者挂在客户内网 DHCP 后面，IP 每天变，端口也不通。你想用 SDK 主动去连它，连不上；想让它往你服务器推数据，它又没公网地址。这个标题讲的正是这种场景：用 JAVA 写一套基于海康威视 ISUP（原 EHome）协议的接入 demo，让设备主动向平台注册并保持长连接，人脸考勤记录顺着这条链路回传。ISUP 的核心思路是设备侧主动出站，平台侧只暴露一个固定端口，设备 IP 变不变都无所谓。适合做考勤对接、门禁数据采集、多网点设备统一接入的 Java 后端工程师，也适合手里有海康人脸考勤机但被网络卡住的集成商。下面按我实际落地的顺序，把协议、依赖、注册、回传、排错讲透。

2. ISUP 协议与 JAVA 侧选型：为什么不用 SDK 直连

2.1 ISUP 和主动轮询的本质差别

海康设备接入常见两条路。一条是设备网络 SDK（HCNetSDK）直连，你拿到设备 IP、端口、账号密码，调NET_DVR_Login_V40登录，再拉考勤记录。这条路在设备有固定 IP 或至少同网段可达时最省事，但标题场景里设备 IP 不固定，这条路直接废掉。另一条就是 ISUP，设备作为客户端，主动连到你的平台，注册成功后维持一条 TCP 长连接，平台通过这条连接下发指令、接收事件。

ISUP 的报文结构是海康私有的，包头带协议版本、消息类型、序列号、设备标识等字段，后面跟具体消息体。设备注册时上报设备序列号、型号、固件版本，平台侧要维护一张「序列号 → 连接通道」的映射表。之后设备上报考勤事件，平台从对应通道读出来解析。关键点在于：平台不需要知道设备 IP，只需要一个公网可达的监听端口，设备侧配置里填平台地址和端口即可。

选型上，Java 侧一般用 Netty 做 TCP 服务端，因为 ISUP 是长连接、二进制协议、需要心跳保活和粘包拆包处理，Netty 的ByteToMessageDecoder和IdleStateHandler正好覆盖这些需求。纯ServerSocket也能写，但连接数一多、心跳一乱，维护成本陡增。

2.2 依赖与工程骨架

我一般用 Maven 建一个独立模块，核心依赖就 Netty 和 JSON 解析。海康官方没有公开的 Java ISUP 服务端 SDK，网上流传的 demo 多是 C++ 或 C# 版本，Java 侧需要自己按协议文档实现编解码。所以工程里要留一个protocol包专门放报文定义。

<!-- pom.xml 关键依赖 --> <dependencies> <!-- Netty：TCP 服务端、编解码、心跳 --> <dependency> <groupId>io.netty</groupId> <artifactId>netty-all</artifactId> <version>4.1.100.Final</version> </dependency> <!-- JSON：解析设备上报的考勤数据体 --> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson2</artifactId> <version>2.0.47</version> </dependency> <!-- 日志：排查协议问题时必须能看到原始字节 --> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>2.0.9</version> </dependency> </dependencies>

依赖说明：Netty 版本选 4.1.x 稳定线即可，不用追最新；fastjson2 用于解析考勤记录里的 JSON 体，如果设备上报的是二进制结构体，则改用 ByteBuf 手动读；日志一定要开 DEBUG，协议对接阶段看不到原始字节基本没法排错。工程骨架建议分四层：server（Netty 启动与通道管理）、protocol（报文编解码）、handler（注册、心跳、考勤事件处理）、service（业务落库）。

2.3 平台侧监听端口的配置要点

设备侧 ISUP 配置里要填平台 IP 和端口，这个端口必须在公网或设备可达的网络里开放。常见做法是平台部署在一台有固定公网 IP 的服务器上，监听一个端口，比如 7660。注意这个端口是设备主动连进来的，不是你去连设备，所以防火墙只需放行入站。

# 服务器上确认端口监听与防火墙放行（以常见 Linux 为例） # 查看端口是否已被占用 ss -lntp | grep 7660 # 放行入站 TCP 7660（firewalld 示例） firewall-cmd --permanent --add-port=7660/tcp firewall-cmd --reload

参数说明：端口选 7660 只是习惯，实际用哪个都行，但要和设备侧配置完全一致；如果平台在云服务器上，安全组也要放行同一端口；设备侧填的平台地址如果是域名，要确保设备能解析，很多考勤机 DNS 配置不全，建议直接填 IP。

3. Netty 服务端最小可跑通实现：注册、心跳、考勤回传

3.1 启动类与通道初始化

先让服务端能起来、能接受设备连接。这一步不解析业务，只保证 TCP 通。

// IsupServer.java：Netty 服务端启动 public class IsupServer { private final int port; public IsupServer(int port) { this.port = port; } public void start() throws InterruptedException { EventLoopGroup boss = new NioEventLoopGroup(1); EventLoopGroup worker = new NioEventLoopGroup(); try { ServerBootstrap b = new ServerBootstrap(); b.group(boss, worker) .channel(NioServerSocketChannel.class) .childHandler(new ChannelInitializer<SocketChannel>() { @Override protected void initChannel(SocketChannel ch) { ChannelPipeline p = ch.pipeline(); // 心跳：60 秒没读到数据就判定空闲，触发事件 p.addLast(new IdleStateHandler(60, 0, 0)); // 自定义解码器：处理 ISUP 粘包拆包 p.addLast(new IsupDecoder()); p.addLast(new IsupEncoder()); // 业务处理器：注册、心跳、考勤事件 p.addLast(new IsupHandler()); } }); ChannelFuture f = b.bind(port).sync(); System.out.println("ISUP server started on port " + port); f.channel().closeFuture().sync(); } finally { boss.shutdownGracefully(); worker.shutdownGracefully(); } } public static void main(String[] args) throws InterruptedException { new IsupServer(7660).start(); } }

逻辑说明：IdleStateHandler(60, 0, 0)表示 60 秒内没读到任何数据就触发userEventTriggered，在 handler 里可以主动关闭连接或发心跳探测。ISUP 设备通常会自己发心跳，但平台侧也要有超时清理，否则死连接会堆积。IsupDecoder负责把字节流按协议长度字段切成完整报文，IsupEncoder负责把平台下发的指令编码成设备能识别的格式。

3.2 解码器：处理粘包拆包与报文头

ISUP 报文头里一般有长度字段，解码器先读头、再按长度读体。下面是一个简化骨架，实际字段偏移要按你拿到的协议文档对齐。

// IsupDecoder.java：按长度字段拆包 public class IsupDecoder extends ByteToMessageDecoder { // 最小报文头长度，按协议文档填，这里假设 20 字节 private static final int HEADER_LENGTH = 20; @Override protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) { // 头都不够，等下次数据 if (in.readableBytes() < HEADER_LENGTH) { return; } in.markReaderIndex(); // 跳过部分头字段，读到长度字段（偏移按文档） in.skipBytes(16); int bodyLength = in.readInt(); // 体还没到齐，重置读指针等下次 if (in.readableBytes() < bodyLength) { in.resetReaderIndex(); return; } // 读完整报文 byte[] body = new byte[bodyLength]; in.readBytes(body); out.add(new IsupMessage(body)); } }

逻辑说明：markReaderIndex和resetReaderIndex是处理半包的关键，数据没到齐就回退，等下一次decode调用。长度字段的偏移量必须和协议文档一致，填错会导致永远解不出报文，表现为连接建立但没有任何业务数据。参数上HEADER_LENGTH和skipBytes的数值是最容易翻车的地方，建议先用 Wireshark 抓一次设备注册报文，对照字节确认。

3.3 注册与心跳处理

设备连上来第一件事是注册，平台要记录序列号和通道的对应关系。

// IsupHandler.java：注册、心跳、考勤事件分发 public class IsupHandler extends SimpleChannelInboundHandler<IsupMessage> { // 序列号 -> 通道，实际项目放 Redis 或 ConcurrentHashMap private static final Map<String, Channel> DEVICE_CHANNELS = new ConcurrentHashMap<>(); @Override protected void channelRead0(ChannelHandlerContext ctx, IsupMessage msg) { int type = msg.getType(); switch (type) { case 0x01: // 注册 String sn = msg.getDeviceSn(); DEVICE_CHANNELS.put(sn, ctx.channel()); System.out.println("device registered: " + sn); // 回注册应答，具体报文按协议构造 ctx.writeAndFlush(IsupMessage.registerAck(sn)); break; case 0x02: // 心跳 ctx.writeAndFlush(IsupMessage.heartbeatAck()); break; case 0x03: // 考勤事件上报 handleAttendance(msg); break; default: System.out.println("unknown msg type: " + type); } } private void handleAttendance(IsupMessage msg) { // 解析考勤体：工号、时间、比对结果、抓拍图路径等 String json = new String(msg.getBody(), StandardCharsets.UTF_8); System.out.println("attendance: " + json); // 落库或投递到业务队列 } @Override public void userEventTriggered(ChannelHandlerContext ctx, Object evt) { if (evt instanceof IdleStateEvent) { // 超时未收到数据，关闭连接，等待设备重连 ctx.close(); } } }

逻辑说明：注册成功后把sn → channel存起来，后续平台要主动下发指令（比如远程开门、同步人员）时，通过这个映射找到通道。心跳应答必须回，否则部分设备会认为平台掉线而断开重连。考勤事件体里通常包含工号、打卡时间、比对方式、抓拍图 URL 或二进制，解析方式取决于设备上报格式，建议先打印原始字节再定解析逻辑。

3.4 设备侧配置与联调顺序

设备侧在「平台接入」或「ISUP/EHome」菜单里填平台地址、端口、设备序列号。联调顺序我一般这样走：先确认服务器端口能通，再启动服务端看设备是否连上来，再看注册报文是否解析成功，最后才验证考勤回传。每一步都要看日志，不要跳步。

4. 人脸考勤数据解析与落库：字段、图片、去重

4.1 考勤事件体的常见字段

设备上报的考勤事件一般包含：工号（employeeNo）、姓名、打卡时间（时间戳或字符串）、比对结果（成功/失败）、比对方式（人脸/卡/密码）、抓拍图片。不同型号字段名有差异，要以实际报文为准。解析时先转成 JSON 或按结构体偏移读，再映射到业务表。

// AttendanceParser.java：解析考勤体并落库 public class AttendanceParser { public void parseAndSave(byte[] body) { String json = new String(body, StandardCharsets.UTF_8); JSONObject obj = JSON.parseObject(json); AttendanceRecord r = new AttendanceRecord(); r.setEmployeeNo(obj.getString("employeeNo")); r.setName(obj.getString("name")); // 时间字段可能是秒级时间戳，也可能是 yyyy-MM-dd HH:mm:ss r.setPunchTime(parseTime(obj.get("punchTime"))); r.setVerifyMode(obj.getInteger("verifyMode")); r.setSuccess(obj.getBooleanValue("success")); // 抓拍图一般是 base64 或 URL，按需存储 r.setCaptureImage(obj.getString("captureImage")); // 去重：同一人同一秒只存一条 if (!exists(r.getEmployeeNo(), r.getPunchTime())) { save(r); } } private boolean exists(String employeeNo, Date punchTime) { // 实际用数据库唯一索引或 Redis 去重 return false; } private Date parseTime(Object v) { // 兼容时间戳与字符串两种格式 return new Date(); } private void save(AttendanceRecord r) { // 落库逻辑 } }

逻辑说明：去重很关键，设备在网络抖动时可能重复上报同一条记录，建议在数据库对「工号 + 打卡时间」建唯一索引，或者用 Redis 做短时去重。抓拍图如果走 base64，报文会很大，解码器要确认长度字段能覆盖，否则会被截断。时间字段格式不统一是常见坑，解析前先打印原始值确认。

4.2 图片与大数据体的处理

抓拍图如果直接塞在考勤事件里，单条报文可能几百 KB，Netty 默认的接收缓冲区可能不够。需要在ServerBootstrap里调大SO_RCVBUF，或者让设备配置只上报图片 URL，平台再单独去拉。我一般优先让设备上报 URL，平台侧异步下载，避免长连接被大报文拖慢。

// 调大接收缓冲区，应对大报文 b.childOption(ChannelOption.SO_RCVBUF, 1024 * 1024) .childOption(ChannelOption.SO_KEEPALIVE, true);

参数说明：SO_RCVBUF设 1MB 是经验值，太大浪费内存，太小会丢包；SO_KEEPALIVE打开 TCP 层保活，配合应用层心跳双保险。如果设备只能上报 base64 图片，解码器的长度字段要用 4 字节 int，别用 short，否则超过 65535 字节就溢出。

5. 对接 ISUP 最容易翻车的五个地方

5.1 设备注册后立刻断开

现象：设备连上来，注册报文也收到了，但几秒内连接被设备主动断开，反复重连。原因通常是平台没有回注册应答，或者应答报文格式不对，设备认为平台不合法。解决：对照协议文档构造注册应答，字段顺序、长度、校验位都要一致，先用抓包工具对比设备期望的应答格式。

5.2 解码器读不出完整报文

现象：连接正常，日志里能看到字节到达，但业务层收不到任何消息。原因多是长度字段偏移填错，或者字节序搞反（大端小端）。解决：抓一次设备注册报文，逐字节对照协议文档，确认长度字段的位置和字节序，ByteBuf默认大端，如果设备是小端要手动order(ByteOrder.LITTLE_ENDIAN)。

5.3 心跳超时导致连接被清理

现象：连接维持几分钟后掉线，设备重新注册。原因是平台侧IdleStateHandler超时时间设得太短，或者设备心跳间隔比平台超时还长。解决：先抓包确认设备心跳间隔，平台超时时间设为心跳间隔的 2 到 3 倍，比如设备 30 秒一次心跳，平台设 90 秒。

5.4 考勤记录重复入库

现象：同一个人同一时间出现两条甚至多条记录。原因是设备重传或网络抖动导致重复上报，平台没有去重。解决：数据库对「工号 + 打卡时间」建唯一索引，插入时捕获冲突忽略；或者用 Redis 对消息 ID 做短时去重，窗口设 5 分钟。

5.5 多设备序列号冲突或映射丢失

现象：两台设备注册后，平台只认到一台，或者指令下发到了错误的设备。原因是序列号映射用了普通 Map 但没处理重连覆盖，或者设备序列号配置重复。解决：映射表用ConcurrentHashMap，重连时用新通道覆盖旧通道并关闭旧连接；设备序列号必须唯一，部署前核对。

6. 进阶：用通道映射做远程指令下发与连接自愈

跑通考勤回传只是第一步，ISUP 真正的价值在于平台可以随时通过长连接给设备下发指令，比如远程同步人员、手动补传记录、远程开门。实现方式就是前面维护的sn → channel映射，找到通道后按协议构造指令报文写回去。

// 远程下发指令：按序列号找到通道并发送 public boolean sendCommand(String deviceSn, IsupMessage cmd) { Channel ch = DEVICE_CHANNELS.get(deviceSn); if (ch == null || !ch.isActive()) { // 设备不在线，记录待下发任务，等注册后再推 return false; } ch.writeAndFlush(cmd); return true; }

连接自愈方面，设备断线重连是常态，平台侧要做两件事：一是channelInactive时清理映射，二是设备重新注册时覆盖旧通道。如果业务对实时性要求高，可以在设备离线时把指令存到队列，注册成功后立即补发。

验证方法上，我习惯用一个模拟客户端脚本冒充设备，按协议发注册和考勤报文，确认平台解析和落库都正常，再上真机。这样能把协议问题和设备问题分开，省很多来回。

# 模拟设备连接（用 nc 快速验证端口通不通） nc -vz 平台IP 7660

最后说个我踩过的坑：早期我没做通道清理，设备重连后旧通道还挂在 Map 里，指令发到了已经断开的连接上，业务侧一直报「下发成功」但设备没反应，查了半天才发现是映射没更新。后来养成习惯，channelInactive里第一件事就是按通道反查序列号并移除。对接这类长连接协议，连接状态管理比协议解析更容易出玄学问题，日志一定要打全。希望帮到你。

本文还有配套的精品资源，点击获取