简介：面向Java开发者的海康威视网络摄像机与NVR二次开发资源包，以实时流/历史流推流、抓图、录像下载、云台控制四大功能为主线，提供在Windows/Linux环境可直接运行和扩展的项目代码。压缩包共256个文件，约39.25MB，其中包含131个XML配置、49个Java源码、25个DLL、23个SO动态库及3个JAR依赖包，另有Vue前端、Shell脚本和SQL脚本，覆盖后端驱动加载、前端预览界面与数据库存储等环节。包内文件按功能模块组织，便于针对实时预览、录像回放、抓图存档、云台操作等场景快速定位对应代码。结合SDK接口说明，可重点学习RTSP/HLS推流、录像检索、多线程下载、断点续传、云台协议适配以及Java与原生动态库交互等实现细节。其中还涉及SDK库的加载路径配置、日志记录与版本兼容性处理，能帮助开发者避开常见环境坑点。已有1163人下载学习，适合安防系统集成、视频平台对接以及需要独立完成设备二次开发的Java工程师参考。
1. Java海康威视SDK二次开发：先把推流链路定下来
做 Java 海康威视 SDK 二次开发的人，十有八九不是冲着研究安防协议来的，而是被一句需求推着走：公司买了一批网络摄像机和 NVR 录像机，要把它们变成业务系统里的实时预览、历史回放，还要能抓图、能下载录像。海康 HCNetSDK 本身是 C 语言接口，Java 侧只能通过 JNA 或 JNI 去调用，真正跑起来你会发现，登录设备并不难，难的是把实时流和历史流稳定推出去——推流中断、通道号写错、浏览器插件装不上，每一步都在消耗排期。这篇按我落过地的链路讲：SDK 初始化、登录取流、转推 RTMP/SRS、历史流回放与录像下载，最后是避坑和存活验证。适合正在做安防集成、视频上云或运维平台的 Java 后端参考。
2. 海康SDK二次开发的前置条件：JNA加载、设备登录与取流通道选择
2.1 先分清直连、NVR转发与RTSP裸流：选错方向后面全返工
网络摄像机自带 RTSP 服务，NVR 本质上是一个录像加转发网关。很多人第一反应是：既然有 RTSP 地址，直接让播放器拉流不就行了？如果只是看单路画面，确实可以。可一旦业务变成“从 NVR 取某一段历史录像、控制倍速播放、抓图、下载证据”，纯 RTSP 地址就绕不过去了——历史流的 URL 参数、时间范围和权限控制都很脆弱。SDK 的角色是给你一个稳定可控的登录态和会话句柄，把设备能力暴露给上层。
我在实际项目里见到的取流方式有三种，选错方向后面基本要返工：
| 方式 | 典型路径 | 适用场景 |
|---|---|---|
| 直接 RTSP 裸流 | rtsp://user:pass@ip:554/Streaming/Channels/101 | 单路实时预览、临时调试 |
| NVR 转发取流 | 通过 NVR 取通道一路的流 | 多路摄像头统一出口、集中布防 |
| SDK 登录后取流 | Java 调 HCNetSDK 登录，再做控制 | 历史回放、抓图、录像下载、设备状态 |
有人在项目里习惯让 NVR 先把录像定期转存到 NAS，再从 NAS 把文件拖回来。这个方案测试环境没问题，生产上会被 NAS 协议兼容性、录像文件切分粒度拖后腿。绕过 SDK 等于把调度粒度限制在文件名级别，想按“今天上午 9 点到 10 点”取一段录像，会非常别扭。NAS 适合做冷备，不适合做业务取流。
2.2 在Linux/Windows下用JNA加载HCNetSDK：库文件放置与登录最小代码
HCNetSDK 在 Windows 下是HCNetSDK.dll，在 Linux 下是libhcnetsdk.so，并且带一大批依赖库，不能只拷一个主库过去。我的做法是建一个专用目录，比如/opt/hik/libs，把 SDK 发布包里的 so 和 dll、依赖库都放进去，启动时通过 JNA 的jna.library.path指定这个目录。
import com.sun.jna.Library; import com.sun.jna.Native; public interface HCNetSDK extends Library { HCNetSDK INSTANCE = Native.load("hcnetsdk", HCNetSDK.class); }上面这段只是加载库，真正的难点是登录结构体。JNA 的Structure要求字段顺序和 C 结构体严格对齐，不同 SDK 版本的结构体会多出保留字段，抄网上的代码前一定要对着 SDK 头文件核对字段。
public class NET_DVR_LOGIN_INFO extends Structure { public int dwSize; public byte[] sDeviceAddress = new byte[129]; public byte[] sLoginName = new byte[128]; public byte[] sPassword = new byte[64]; public short wPort; // 实际还有 byUseTransport、cbLoginResult 等字段，这里省略 } public class NET_DVR_DEVICEINFO_V40 extends Structure { public byte byChanNum; public byte byIPChanNum; // 省略其他字段 }登录调用：
NET_DVR_LOGIN_INFO loginInfo = new NET_DVR_LOGIN_INFO(); loginInfo.writeString("sDeviceAddress", "192.168.1.64"); loginInfo.writeString("sLoginName", "admin"); loginInfo.writeString("sPassword", "yourPassword"); loginInfo.wPort = 8000; loginInfo.dwSize = loginInfo.size(); NET_DVR_DEVICEINFO_V40 deviceInfo = new NET_DVR_DEVICEINFO_V40(); int userId = HCNetSDK.INSTANCE.NET_DVR_Login_V40(loginInfo, deviceInfo); if (userId < 0) { int err = HCNetSDK.INSTANCE.NET_DVR_GetLastError(); System.err.println("登录失败，SDK错误码=" + err); return; }这段代码的逻辑是：NET_DVR_Login_V40成功返回用户 ID，小于 0 就查错误码。地址不要带http://，端口默认 8000，密码不能直接拼在 URL 里。错误码里 17、23、29 是最常见的几种，分别对应账号密码错误、通道不可用、权限不足；真遇到报错先查错误码表，别瞎改参数。
2.3 从设备信息里拿通道数：NVR通道号别写死
很多 NVR 挂了多个摄像头，通道号既有数字通道又有 IP 通道。设备返回的byChanNum和byIPChanNum含义不同：前者是数字通道数，后者是 IP 通道数，具体布局和 NVR 型号强相关。如果只取一路可以写死 1，但要搭平台就必须把这些字段存到数据库，后续所有取流地址从库里读。
int channelCount = deviceInfo.byChanNum; System.out.println("设备数字通道数=" + channelCount); if (deviceInfo.byIPChanNum > 0) { System.out.println("IP通道数=" + deviceInfo.byIPChanNum); }海康录像机的命名规则在这个环节最容易坑人。RTSP 路径里的101不是随便写的：第一位是通道号，第二位固定是 0，第三位是码流类型，101代表第一路主码流，102代表第一路子码流。但部分 NVR 固件的 IP 通道编号和设备面板上的物理通道不一致，拼地址前必须用 SDK 通道列表或设备网页端确认。用 VLC 试地址时，返回 401 不一定是密码错，很可能是取流路径不对，这是新手最容易翻车的地方。
另外，登录成功后要记得初始化 SDK，JVM 退出时调用NET_DVR_Cleanup。很多人漏了这一步，连续登录几次后句柄泄露，服务只能重启。我把初始化放到 Spring 的@PostConstruct，退出清理放到@PreDestroy，这是最基本的卫生习惯。
3. 实时流推流：从RTSP拉流到RTMP/SRS，参数和进程守护一次讲清
3.1 为什么不建议Java直接读码流：推流链路的取舍
海康 SDK 提供实时流回调NET_DVR_RealPlay_V40，Java 可以在回调里拿到码流包，再用 JavaCV 的FFmpegFrameRecorder封装推流。这条链路看起来干净，纯 JVM 语言搞定一切，但我用下来的结论是：实时流超过 4 路就不要再硬撑了。码流回调的线程模型、GC 停顿和 Native 内存释放，很容易让服务看起来活着但没有画面；排查时要同时看 JVM dump 和 SDK 日志，成本很高。
我一般把链路分成两截：Java 只负责 SDK 登录、生成地址、管理并拉起 ffmpeg 进程，ffmpeg 负责拉流转推。好处是 ffmpeg 进程崩溃不会拖垮 JVM，可以单独重启；坏处是要多维护一套进程生命周期，但这点复杂度换稳定性完全值得。推流服务本来就是长时间跑的东西，宁可进程边界清晰一点。
3.2 用SDK登录后拼RTSP地址，再交给ffmpeg推到RTMP
登录成功的设备，可以拼出实时流的 RTSP 地址，常见格式是：
rtsp://admin:yourPassword@192.168.1.64:554/Streaming/Channels/101密码带特殊字符时，直接拼接字符串会让 URL 解析出错，建议用URLEncoder处理后再拼。然后启动一个 ffmpeg 子进程：
ffmpeg -rtsp_transport tcp -stimeout 5000000 \ -i "rtsp://admin:yourPassword@192.168.1.64:554/Streaming/Channels/101" \ -c:v copy -c:a aac -b:a 128k \ -f flv "rtmp://192.168.1.10:1935/live/camera_101"如果源设备输出 H.265，而目标播放器或 FLV 封装不支持 H.265，就不能用-c:v copy，要改成转码：-c:v libx264 -preset veryfast -g 25。H.264 源可以直接 copy，CPU 最低。
Java 侧启动进程要小心管道阻塞：
List<String> cmd = new ArrayList<>(); cmd.add("ffmpeg"); cmd.add("-rtsp_transport"); cmd.add("tcp"); cmd.add("-stimeout"); cmd.add("5000000"); cmd.add("-i"); cmd.add(rtspUrl); cmd.add("-c:v"); cmd.add("copy"); cmd.add("-c:a"); cmd.add("aac"); cmd.add("-b:a"); cmd.add("128k"); cmd.add("-f"); cmd.add("flv"); cmd.add(rtmpUrl); ProcessBuilder pb = new ProcessBuilder(cmd); pb.redirectErrorStream(true); pb.redirectOutput(new File("/logs/ffmpeg_" + channelId + ".log")); Process proc = pb.start();redirectErrorStream(true)很关键，不然 ffmpeg 的 stderr 会积满管道导致进程阻塞。日志写到文件，方便事后确认是不是因为设备断流退出。这样做了之后，ffmpeg 的退出原因基本一目了然。
3.3 关键参数表：TCP传输、超时、GOP和编码器选择
| 参数 | 推荐值 | 作用 |
|---|---|---|
-rtsp_transport | tcp | 用 TCP 拉 RTSP，避免 UDP 丢包花屏 |
-stimeout | 5000000 | 底层 socket 超时 5 秒，源端断流能快速退出 |
-c:v copy | 源为 H.264 | 不转码视频，CPU 最低 |
-c:v libx264 -preset veryfast -g 25 | 源为 H.265 或目标兼容差 | 转 H.264，GOP 固定 25 帧 |
-c:a aac -b:a 128k | 源音频为 G.711 | 转成 FLV/RTMP 标准音频 |
-f flv | 推 RTMP | 封装格式 |
参数别一起堆上去。先判断源编码，再决定要不要转码。判断源编码用ffprobe -show_streams看一眼，或者在海康后台把主码流编码直接改成 H.264，这是让 SRS 推流不稳定问题少一半的土办法。
很多人发现 SRS 推流不稳定就怀疑 SRS 配置，实际上源头丢帧、GOP 太大、RTSP 用 UDP 传输才是主因。我在调试时会把设备端主码流改成 H.264，码率限制 4Mbps，帧率 25，I 帧间隔 50。这样即使 ffmpeg 用 copy 推，关键帧间隔也在播放器可接受范围内。
断线重连不要无脑无限重启：
while (!Thread.currentThread().isInterrupted()) { Process proc = pb.start(); int exitCode = proc.waitFor(); if (exitCode != 0) { log.error("channel {} ffmpeg exited with {}", channelId, exitCode); Thread.sleep(3000); continue; } // 正常退出，可能是手动停止 break; }退出码 0 也可能是主动停止，非 0 最常见的是 139（段错误）和 234（源断开）。连续失败次数超过 5 次就发告警，避免把流媒体服务器和服务日志同时打爆。
4. 历史流回放推流与录像下载：按时间定位、控制播放、抓图存证
4.1 历史流取流：RTSP带时间参数与SDK按时间回放两条路
历史流和实时流的本质区别是多了时间范围。最直接的办法是用历史 RTSP 地址，海康设备常见的格式是：
rtsp://admin:yourPassword@192.168.1.64:554/Streaming/tracks/101?starttime=20240401T100000Z&endtime=20240401T110000Zstarttime和endtime是 UTC 时间，格式固定，中间用T连接，最后带Z。这个地址可以直接交给 ffmpeg 拉流转推，命令和实时流几乎一样，只是把-i参数换成这个地址。注意设备时区：如果按北京时间传，要先转成 UTC，不然回放的总不是你要的那一段。
另一条路是 SDK 按时间回放：调用NET_DVR_PlayBackByTime_V40，传通道号、起止时间，返回回放句柄，后面的暂停、倍速、停止都在这个句柄上操作。业务上如果只是给用户一个起止时间，走前一条路就够了；如果要做录像文件列表展示，再用NET_DVR_FindFile_V40拿文件列表，带文件名回放。
4.2 历史流推流：播放控制接口与转推时的音画同步
按时间回放的代码示意：
NET_DVR_PLAYBACK_CONDITION_V40 cond = new NET_DVR_PLAYBACK_CONDITION_V40(); cond.dwSize = cond.size(); cond.struStartTime.setTime("2024-04-01 10:00:00"); cond.struStopTime.setTime("2024-04-01 11:00:00"); int playHandle = HCNetSDK.INSTANCE.NET_DVR_PlayBackByTime_V40( userId, cond, null, null); if (playHandle < 0) { throw new RuntimeException("启动历史流失败，错误码=" + HCNetSDK.INSTANCE.NET_DVR_GetLastError()); }拿到playHandle后，可以把回放流当作一路源，交给 ffmpeg 拉取或转推。如果走 RTSP 地址方案，SDK 只用来确认通道是否有录像，推流命令不变。
播放控制是历史流推流最容易忽略的部分：暂停时不能只停止喂数据，否则客户端会一直显示缓冲中；正确做法是 SDK 的NET_DVR_PausePlay(playHandle)和NET_DVR_ResumePlay(playHandle)配对调用。倍速播放建议限制在 4 倍以内，超过 8 倍很多设备输出的 GOP 结构异常，copy 转推后画面会突然花一下再恢复。
音画同步方面，ffmpeg 推历史流不要加-re。加了-re会按照文件时间戳匀速读流，等于人为降低倍速；不加-re从 RTSP 拉历史流时，源端会按录像真实时间输出，转推端保持原时间戳就好。
4.3 抓图与录像下载：两个独立的“证据”功能怎么接
抓图是业务方最爱要的功能：报警抓图、门禁抓图、巡检留证。SDK 的NET_DVR_CaptureJPEGPicture是最直接的接口，传用户 ID、通道号、图片参数和保存路径就能拿到 JPEG。
NET_DVR_JPEGPARA jpeg = new NET_DVR_JPEGPARA(); jpeg.wPicSize = 0xff; // 0xff 表示用设备默认分辨率 jpeg.wPicQuality = 1; // 质量档位，一般 0-2 boolean ok = HCNetSDK.INSTANCE.NET_DVR_CaptureJPEGPicture( userId, channel, jpeg, "/data/snapshot/chan_" + channel + ".jpg");wPicSize通常填0xff让设备按当前分辨率抓，wPicQuality建议填 1，既能控制文件大小又不会太糊。夜间抓图是重灾区，红外还没启动或设备还在自动曝光时，抓出来就是黑图。我的做法是抓图前先读设备时间，接口返回后检查文件大小，小于 5KB 就当失败处理，过 3 秒重试一次。
录像下载通常是配合历史流回放句柄做的：先把历史流回放起来，再用NET_DVR_SaveRealData(playHandle, fileName)把数据写到本地。保存下来的是 PS 流，后缀一般是.ps，不是 MP4。要么前端支持 PS 播放，要么用 ffmpeg 转一下封装：
ffmpeg -i record.ps -c:v copy -c:a copy record.mp4这一步必须等回放结束再执行。最常见的错误是回放还没停止就去打开.ps文件，文件头不完整，转出来只有音频或干脆不能播放。进度可以用NET_DVR_GetDownloadPos轮询，存到数据库，而不是让前端干等。
5. 海康SDK二次开发避坑指南：插件提示、通道命名、SRS和抓图权限
这一章集中写我踩过的坑，都是生产环境里能复现的问题，按现象、原因、解决三条来记。
5.1 页面提示“请点击此处下载插件”但装不上：浏览器插件方案已经过时
现象：在海康官方 Web 接入页打开实时预览，页面反复提示“请点击此处下载插件”，下载安装包后安装又提示“安装时请关闭浏览器”；不管 win10 还是 win11 的浏览器，都很难装成功。
原因：海康老方案依赖 ActiveX 或 NPAPI 插件，Chrome 早就禁用了 NPAPI，Windows 下 64 位浏览器也不兼容 32 位插件。这条技术路线已经走到头了。
解决：不要把时间花在兼容插件上。Java 服务端通过 SDK 拿到流，再转推成 RTMP/HLS，前端用 flv.js 或 HLS 播放。页面只播流，不装插件。这个改动看着大，实际就是换成第 3 章那套推流链路，比适配一堆浏览器版本省太多事。
5.2 NVR通道号命名规则看不懂，RTSP地址拼错返回401/404
现象：同一台 NVR，Streaming/Channels/101能出画面，102黑屏；换成201又提示 404。
原因：RTSP 路径里的三位数不是简单自增。第一位是通道号，第二位固定是 0，第三位是码流类型；而且 NVR 的 IP 通道编号和设备面板上的物理通道不一定一致。海康录像机命名规则在不同固件上还有差异，有的型号会省略中间的 0。
解决：不要靠猜。登录 SDK 后从设备信息里读出通道列表，逐个通道测试；或者打开设备网页端的取流地址页面，照抄它自己生成的 URL。排查时先用 VLC 试地址，VLC 能播说明地址没问题，再查代码。返回 401 时第一反应别改密码，先用 ffprobe 看响应是 401 还是 404：401 很可能是路径或权限问题，404 才是地址不存在。
5.3 SRS推流不稳定：先怀疑源端码流，再怀疑服务器
现象：ffmpeg 把海康实时流推到 SRS，播放端看一会儿就卡顿，延迟越来越大；换个播放器又提示不支持 x264。
原因：多数时候不是 SRS 不稳定，而是源端 RTSP 用了 UDP 传输导致丢包，或者 GOP 太长。OBS 推流时显示不支持 x264 的类似问题，本质也是编码参数和封装格式不匹配，到了服务器端就表现为花屏和卡顿。
解决：ffmpeg 拉流强制加-rtsp_transport tcp；码率不要贪高，1080p 监控 4Mbps 足够；如果源编码是 H.265，RTMP/FLV 兼容性差，用-c:v libx264 -preset veryfast -g 25转码。改完之后再观察 SRS 的连接数、带宽和播放器缓冲水位，问题通常就消失了。
5.4 历史流回放快进后花屏，ffmpeg退出码频繁139
现象：历史流普通速度播放正常，倍速一开就花屏，甚至 ffmpeg 直接段错误退出，退出码 139。
原因：部分固件在倍速回放时会跳过一些参考帧，或者输出流的时间戳跳动，直接 copy 封装成 FLV 后播放端解码错乱。
解决：回放推流不要无脑 copy，至少给视频加-c:v libx264 -profile:v main转一道；倍速控制在 4 倍以内；另外把-max_delay设为500000微秒，给音视频同步留一点余量。如果仍然花屏，可以在 SDK 层不用倍速，改成按时间跳转重新拉流，用“播放 2 倍时间范围的长录像”来模拟倍速，播放端体验更稳。
5.5 抓图黑图或返回NET_DVR_NOENOUGHPRI：权限和时机各占一半
现象：抓图接口返回NET_DVR_NOENOUGHPRI，或者返回成功但存了一张全黑 JPEG。
原因：登录用户没有勾选远程抓图权限；或者摄像头在夜间还没完成红外切换，自动曝光也没稳定，立刻抓就是黑图。海康摄像头夜晚不灵敏，很多时候不是设备坏了，是时序问题。
解决：给 SDK 用户分配操作权限；抓图前先查设备时间，夜里抓图时重试间隔放到 3 秒以上；检查文件大小，异常就重抓。抓图接口本身不占用实时流句柄，但部分固件要求有预览会话，抓图超时时先确认主码流通道是否已被其他会话占满。
6. 推流不是启动完就结束：用ffprobe做存活检测与断流自动拉起
6.1 检测RTMP流是否“真活”：ffprobe拉流视角
进程在，不代表流在。ffmpeg 可能卡在底层 socket 上，也可能是 NVR 端会话断开但进程没退出。我一般用 ffprobe 去拉一次 RTMP 流，判断返回结果里是否有视频 codec。
#!/bin/bash stream="rtmp://192.168.1.10:1935/live/camera_101" if timeout 8 ffprobe -v error -print_format json -show_streams "$stream" \ | grep -q '"codec_type": "video"'; then echo "alive" exit 0 else echo "dead" exit 1 fitimeout 8是防止 ffprobe 在流服务器不响应时挂死；只检测进程 PID 不靠谱，因为僵尸进程往往还在。注意 JSON 输出里字段空格在不同 ffprobe 版本会有差异，用grep -q '"codec_type": *"video"'更稳。
检测脚本放进定时任务，每 30 秒跑一次。连续两次失败就把旧进程 kill 掉，清掉 RTMP 残留状态再重新拉起。重试要带熔断：连续 5 次失败后发告警，不要无限循环，否则设备离线时日志会被刷爆。
6.2 端到端延迟验证：别只看ffmpeg日志
ffmpeg 日志只能说明它读到了流，不能说明客户端看到的画面延迟多大。一个我自己常用的土办法：在摄像头画面里放一个有秒针的时钟，推流端拉流抓一帧，播放端也抓一帧，对比两张图上的时间差。差在 1 秒内是正常，超过 3 秒就检查播放器缓存和 SRS 的gop_cache配置。
抓帧命令很简单：
ffmpeg -rtsp_transport tcp -i "$stream" -frames:v 1 /tmp/frame.jpg对严格低延迟的业务，不建议用海康默认码流参数，把 I 帧间隔调到 25、码率固定、关闭 SRS 的gop_cache，延迟能降很多。
这套存活检测和验证逻辑，我现在每个通道任务都会带上。推流服务上线后，宁可多写脚本自己测，也不要等用户反馈“画面不动了”。这个习惯帮我避开了很多次半夜被叫醒，希望帮到你。
本文还有配套的精品资源，点击获取
