简介：这是一套基于Java与海康威视SDK二次开发的网络摄像头与门禁系统项目源码，面向计算机相关专业的毕业设计、课程设计学生以及需要集成视频监控与门禁功能的开发者。项目围绕设备注册登录、局域网设备发现、门禁人员与人脸信息管理、门禁卡与人脸下发、事件布防上传（含照片）、摄像机RTSP与SDK推流、当前帧获取等核心场景展开，可帮助读者快速理解海康SDK的调用方式与门禁业务集成思路。资源包共223个文件，以174个Java源码为主体，辅以zbak备份、jar依赖、yml与xml配置、Dockerfile及说明文档，整体约1.53MB，结构清晰便于按模块查阅。目前已有203人学习。源码经过测试，涵盖设备、用户、卡片、报警等分层实现，适合作为二次开发参考模板，在此基础上扩展功能或完成课题设计。
1. Java 接海康威视 SDK：从 RTSP 地址到门禁联动，一套能跑通的二次开发路径
很多做毕业设计或课程设计的同学，第一次拿到海康威视网络摄像头和门禁一体机时，都会卡在同一个地方：设备能 ping 通，浏览器能登录，但一写 Java 代码就不知道从哪下手。标题里的「Java 与海康威视 SDK 二次开发」，本质上就是解决这件事——用 Java 调用海康设备网络 SDK，把摄像头的实时预览、抓图、录像和门禁的刷卡事件、远程开门串成一套可演示、可扩展的系统。它适合三类人：需要交毕业设计的学生、要做课程设计 demo 的开发者、以及想快速验证门禁与视频联动方案的工程师。热词里反复出现的「海康威视网络摄像头设置 rtsp 地址」「海康威视 SDK 下载」说明大家最缺的不是 Java 基础，而是设备侧和 SDK 侧的对接经验。这一章先把整体链路讲清楚，后面几章再逐层拆开。
海康 SDK 二次开发的核心链路其实不复杂：设备通过 SDK 的 NET_DVR_Login_V40 登录，拿到 userId 后，预览用 NET_DVR_RealPlay_V40 或 NET_DVR_PlayBackByTime_V40，抓图用 NET_DVR_CaptureJPEGPicture，门禁事件用 NET_DVR_SetDVRMessageCallBack_V50 注册回调，远程开门用 NET_DVR_ControlGateway。Java 不能直接调 C 的 DLL，所以中间必须有一层 JNA 或 JNI。常见做法是 JNA，因为它不用写 C 代码，接口映射直观，适合课程设计这种周期短、要快速出效果的项目。RTSP 地址则是另一条路，适合只做视频预览、不碰门禁控制的场景，格式一般是 rtsp://用户名:密码@IP:554/Streaming/Channels/101，主码流 101，子码流 102。两条路各有边界，后面会细说。
2. 环境搭建与 SDK 对接：JNA 映射海康 DLL 的最小可运行工程
2.1 为什么选 JNA 而不是 JNI
海康威视设备网络 SDK 提供的是 Windows 下的 HCNetSDK.dll 和 Linux 下的 libhcnetsdk.so，接口是标准 C 导出函数。Java 调 C 有两条路：JNI 需要写 C 桥接层、编译动态库，对毕业设计来说太重；JNA 用 Java 接口直接映射 C 函数，只要方法名和参数类型对得上就能调，省掉编译环节。我一般会选 JNA，原因是调试快、代码量少，出问题能直接在 Java 层打日志。代价是性能略低，但门禁和摄像头这种低频调用场景完全够用。需要注意，JNA 映射结构体时要特别小心内存对齐，海康的结构体里有大量 DWORD 和 BYTE 数组，字段顺序错一个，登录就会返回失败，而且错误码往往不直观。
2.2 工程依赖与目录结构
先建一个 Maven 工程，pom.xml 里加 JNA 依赖。版本用 5.x 即可，不要追最新，稳定优先。
<dependency> <groupId>net.java.dev.jna</groupId> <artifactId>jna</artifactId> <version>5.13.0</version> </dependency>SDK 的库文件按平台放：Windows 下把 HCNetSDK.dll、HCCore.dll、PlayCtrl.dll 以及 HCNetSDKCom 文件夹放到项目根目录的 lib/win 下；Linux 下放 libhcnetsdk.so、libhccore.so、libPlayCtrl.so 和 HCNetSDKCom 目录到 lib/linux。启动时通过jna.library.path指定路径，不要硬编码绝对路径，否则换机器就翻车。
java -Djna.library.path=./lib/win -jar your-app.jar参数说明：jna.library.path是 JNA 搜索动态库的目录，多个目录用分号（Windows）或冒号（Linux）分隔。HCNetSDKCom 是 SDK 的组件目录，必须和主库在同一级，否则预览会报「组件加载失败」。
2.3 用 JNA 定义 HCNetSDK 接口
下面是最小接口定义，只包含登录、注销、错误码三个方法，先跑通再扩展。
import com.sun.jna.Library; import com.sun.jna.Native; import com.sun.jna.Pointer; import com.sun.jna.Structure; public interface HCNetSDK extends Library { HCNetSDK INSTANCE = Native.load("HCNetSDK", HCNetSDK.class); // 初始化 SDK，返回 true 表示成功 boolean NET_DVR_Init(); // 登录设备，返回 userId，-1 表示失败 int NET_DVR_Login_V40(Structure loginInfo, Structure deviceInfo); // 注销设备 boolean NET_DVR_Logout(int userId); // 获取最后一次错误码 int NET_DVR_GetLastError(); // 释放 SDK boolean NET_DVR_Cleanup(); }逻辑说明：Native.load的第一个参数是库名，不带扩展名，JNA 会自动补 .dll 或 .so。NET_DVR_Login_V40的两个参数都是结构体指针，Java 侧要用Structure子类映射。参数说明：loginInfo 对应 NET_DVR_USER_LOGIN_INFO，包含 IP、端口、用户名、密码；deviceInfo 对应 NET_DVR_DEVICEINFO_V40，是输出参数，登录成功后里面会有通道数、序列号等信息。错误码用NET_DVR_GetLastError拿，常见 1 是用户名密码错，7 是连接失败，29 是设备不支持。
2.4 登录结构体的字段映射
结构体映射是 JNA 接海康最容易出问题的地方。下面给出 NET_DVR_USER_LOGIN_INFO 的关键字段。
public class NET_DVR_USER_LOGIN_INFO extends Structure { public byte[] sDeviceAddress = new byte[129]; // 设备 IP public byte byUseTransport; // 是否走私有协议 public short wPort; // 端口，默认 8000 public byte[] sUserName = new byte[64]; // 用户名 public byte[] sPassword = new byte[64]; // 密码 public int bUseAsynLogin; // 是否异步登录 @Override protected List<String> getFieldOrder() { return Arrays.asList("sDeviceAddress", "byUseTransport", "wPort", "sUserName", "sPassword", "bUseAsynLogin"); } }逻辑说明：getFieldOrder必须和 C 结构体字段顺序完全一致，否则内存错位。参数说明：sDeviceAddress 是 129 字节，填 IP 后剩余补 0；wPort 默认 8000，不是 HTTP 的 80；bUseAsynLogin 设 0 走同步，设 1 走异步回调。填字符串时用System.arraycopy或getBytes后拷贝，不要直接赋值，否则长度不对。
3. 网络摄像头接入：RTSP 地址、预览与抓图的三种落地方式
3.1 RTSP 地址的拼接规则与验证
海康网络摄像头的 RTSP 地址有固定格式，主码流和子码流区别很大。主码流分辨率高、码率高，适合录像；子码流分辨率低，适合多路预览。格式如下：
| 码流类型 | 地址格式 | 说明 |
|---|---|---|
| 主码流 | rtsp://admin:密码@IP:554/Streaming/Channels/101 | 通道 1 主码流 |
| 子码流 | rtsp://admin:密码@IP:554/Streaming/Channels/102 | 通道 1 子码流 |
| 通道 2 主码流 | rtsp://admin:密码@IP:554/Streaming/Channels/201 | 多通道 NVR |
验证方法：用 VLC 打开「媒体」→「打开网络串流」，粘贴地址。如果 VLC 能播，Java 侧用 JavaCV 或 VLCJ 也能播。注意密码里如果有 @ 或 :，要先做 URL 编码，否则地址解析会错。这一步是很多人的血泪经验：代码没问题，地址里特殊字符没转义，排查半天。
3.2 用 SDK 做实时预览的最小代码
如果不想走 RTSP，直接用 SDK 预览更可控，还能顺便拿码流做分析。
// 登录成功后拿到 userId int userId = HCNetSDK.INSTANCE.NET_DVR_Login_V40(loginInfo, deviceInfo); if (userId < 0) { System.out.println("登录失败，错误码：" + HCNetSDK.INSTANCE.NET_DVR_GetLastError()); return; } // 设置预览参数 NET_DVR_PREVIEWINFO previewInfo = new NET_DVR_PREVIEWINFO(); previewInfo.lChannel = 1; // 通道号，从 1 开始 previewInfo.dwStreamType = 0; // 0 主码流，1 子码流 previewInfo.dwLinkMode = 0; // 0 TCP，1 UDP previewInfo.hPlayWnd = null; // 不显示窗口，只取流 // 启动预览，返回预览句柄 int playHandle = HCNetSDK.INSTANCE.NET_DVR_RealPlay_V40(userId, previewInfo, null, null); if (playHandle < 0) { System.out.println("预览失败，错误码：" + HCNetSDK.INSTANCE.NET_DVR_GetLastError()); }逻辑说明：NET_DVR_RealPlay_V40的第三个参数是回调函数，传 null 表示不处理码流；如果要抓图或推流，需要传回调。参数说明：lChannel 对应设备通道，NVR 下 1 到 N；dwStreamType 选 0 主码流画质好但占带宽，选 1 子码流适合多路；dwLinkMode 选 0 TCP 稳定，选 1 UDP 延迟低但可能丢包。失败时先看错误码，再检查通道号是否超出设备实际通道数。
3.3 抓图保存到本地
抓图用NET_DVR_CaptureJPEGPicture，指定保存路径即可。
NET_DVR_JPEGPARA jpegPara = new NET_DVR_JPEGPARA(); jpegPara.wPicSize = 0; // 0 表示按设备当前分辨率 jpegPara.wPicQuality = 0; // 0 最好，1 较好，2 一般 boolean ok = HCNetSDK.INSTANCE.NET_DVR_CaptureJPEGPicture( userId, 1, jpegPara, "D:/capture/test.jpg"); if (!ok) { System.out.println("抓图失败，错误码：" + HCNetSDK.INSTANCE.NET_DVR_GetLastError()); }逻辑说明：抓图是同步操作，返回 true 表示文件已写入。参数说明：第二个参数是通道号；wPicSize 设 0 用设备默认分辨率，也可以设 1 表示 4CIF；wPicQuality 数值越小质量越高、文件越大。注意路径要用正斜杠或双反斜杠，单反斜杠在 Java 字符串里是转义符，会报路径不存在。
4. 门禁系统对接：刷卡事件回调与远程开门
4.1 门禁事件回调的注册方式
门禁和摄像头最大的区别是「事件驱动」。刷卡、开门、关门都是设备主动上报，Java 侧要注册回调函数。海康 SDK 用NET_DVR_SetDVRMessageCallBack_V50或NET_DVR_SetDVRMessageCallBack_V30注册。
// 定义回调实现 public class DoorCallback implements HCNetSDK.FMSGCallBack { @Override public void invoke(int lCommand, NET_DVR_ALARMER alarmer, Pointer alarmInfo, int dwBufLen) { // 0x5002 是门禁事件 if (lCommand == 0x5002) { NET_DVR_ACS_ALARM_INFO info = new NET_DVR_ACS_ALARM_INFO(alarmInfo); info.read(); System.out.println("卡号：" + new String(info.struAcsEventInfo.sCardNo).trim()); System.out.println("事件类型：" + info.dwMajor); } } } // 注册回调 DoorCallback callback = new DoorCallback(); HCNetSDK.INSTANCE.NET_DVR_SetDVRMessageCallBack_V50(0, callback, null);逻辑说明：回调里lCommand区分事件类型，0x5002 是门禁主机报警，0x5003 是门禁事件。参数说明：NET_DVR_ACS_ALARM_INFO结构体里struAcsEventInfo包含卡号、工号、门号；dwMajor是主事件类型，1 是刷卡，2 是门磁。回调线程是 SDK 内部线程，不要在里面做耗时操作，否则会丢事件。常见做法是把事件丢到阻塞队列，另起线程处理。
4.2 远程开门的调用与权限校验
远程开门用NET_DVR_ControlGateway，需要先登录门禁设备。
// lGatewayIndex 门号，从 1 开始；dwControlType 1 表示开门 boolean ok = HCNetSDK.INSTANCE.NET_DVR_ControlGateway(userId, 1, 1); if (!ok) { System.out.println("开门失败，错误码：" + HCNetSDK.INSTANCE.NET_DVR_GetLastError()); }逻辑说明：开门是即时操作，返回 true 表示指令已下发，不代表门一定开了。参数说明：lGatewayIndex 对应门禁控制器的门号，单门控制器就是 1；dwControlType 1 开门，2 关门，3 常开，4 常闭。权限校验要在业务层做，比如只有管理员角色才能调这个接口，SDK 本身不校验。
4.3 门禁与摄像头联动的实现思路
联动逻辑：刷卡事件触发后，抓一张现场图，存到数据库，同时记录卡号和抓图路径。实现上，回调里拿到卡号后，调用抓图接口，把图片路径和卡号一起写库。注意抓图和回调不要在同一个线程，否则抓图耗时会导致后续事件丢失。我一般用ArrayBlockingQueue做缓冲，消费者线程负责抓图和写库。
5. 避坑与排查：海康 SDK 二次开发最常见的 5 个翻车点
5.1 登录返回 -1 但错误码是 0
现象：NET_DVR_Login_V40返回 -1，但NET_DVR_GetLastError返回 0。原因：结构体字段顺序或类型不对，SDK 读到了错误的内存，但没触发错误码。解决：逐字段核对getFieldOrder，特别是 byte 数组长度和 short/int 的顺序。用Structure.toString()打印结构体内容，和 C 头文件对比。
5.2 预览成功但抓图失败
现象：NET_DVR_RealPlay_V40返回句柄正常，NET_DVR_CaptureJPEGPicture返回 false。原因：抓图需要设备支持 JPEG 抓图，部分老型号只支持 BMP；或者通道号传错。解决：先确认设备型号是否支持 JPEG 抓图，再检查通道号是否和预览一致。错误码 23 表示「设备不支持该操作」。
5.3 回调收不到门禁事件
现象：注册回调后刷卡，Java 侧没有任何输出。原因：回调注册在登录之前，或者回调对象被 GC 回收。解决：回调必须在登录成功后注册；回调对象要用静态变量或成员变量持有，不能是局部变量，否则 JVM 回收后回调就断了。
5.4 Linux 下加载 .so 报「找不到依赖库」
现象：Native.load抛 UnsatisfiedLinkError，提示 libhcnetsdk.so 找不到。原因：libhcnetsdk.so 依赖 libhccore.so 和系统库，jna.library.path只指定了主库目录，依赖库没找到。解决：把 HCNetSDKCom 目录和所有 .so 放同一目录，并在启动脚本里加LD_LIBRARY_PATH。
5.5 多路预览时内存暴涨
现象：同时预览 8 路以上，Java 进程内存持续上涨。原因：每路预览都创建了回调缓冲，没有及时释放。解决：预览结束后调NET_DVR_StopRealPlay停止，再调NET_DVR_Logout注销；回调里的Pointer不要长期持有，用完即弃。
6. 进阶技巧：用事件队列把门禁与抓图做成可扩展的联动模块
如果只是交课程设计，前面几章已经够用。但如果想让这套东西在答辩时更有说服力，或者真的用到小项目里，建议把门禁事件和抓图做成一个独立模块。我的习惯是定义一个DoorEvent类，包含卡号、时间、门号、抓图路径，然后用BlockingQueue解耦回调和业务处理。回调只负责把事件对象入队，消费者线程负责抓图、写库、推送。这样即使抓图慢，也不会丢事件。
public class DoorEvent { private String cardNo; private Date eventTime; private int gateIndex; private String imagePath; // getter/setter 省略 } // 回调里只入队 private static BlockingQueue<DoorEvent> queue = new LinkedBlockingQueue<>(1000); // 消费者线程 new Thread(() -> { while (true) { DoorEvent event = queue.take(); // 抓图 String path = "D:/capture/" + event.getCardNo() + "_" + System.currentTimeMillis() + ".jpg"; HCNetSDK.INSTANCE.NET_DVR_CaptureJPEGPicture( userId, 1, jpegPara, path); event.setImagePath(path); // 写库或推送 saveToDb(event); } }).start();参数说明：队列容量设 1000 是经验值，太小会丢事件，太大占内存。抓图路径用卡号加时间戳，避免重名。saveToDb里建议用批量插入，单条插入在事件密集时会拖慢消费者。验证方法：连续刷 50 张卡，看数据库记录数和抓图文件数是否一致，如果少了，就是队列满了或者消费者线程挂了。
还有一个技巧是给回调加一层「事件过滤」。海康门禁事件里有很多类型，比如门磁、按钮、报警，如果只关心刷卡，就在回调里判断dwMajor == 1再入队，减少无效处理。这个判断放在回调里做，比放在消费者里做更省资源。最后提醒一句：SDK 的初始化和清理要成对出现，NET_DVR_Init在应用启动时调一次，NET_DVR_Cleanup在退出时调一次，中间反复 init 会导致资源泄漏。我吃过这个亏，程序跑一天后预览全挂，重启才好。希望帮到你。
本文还有配套的精品资源，点击获取
