简介：这份 ONVIF JAVA SDK 面向从事网络摄像头接入、视频监控平台开发及物联网设备集成的 Java 工程师，帮助开发者快速理解并实现 ONVIF 协议的核心交互流程。资源包共 1157 个文件，以 1147 个 Java 源码为主体，辅以 5 个 jar 依赖库、Gradle 构建脚本及少量配置与批处理文件，整体约 2.32MB，结构紧凑、便于直接导入工程调试。ONVIF 本质是 UDP 发现、HTTP 传输与 XML 字段解析的组合，技术门槛并不高，难点在于字段繁多、细节琐碎；SDK 已覆盖协议全部功能，Demo 仅演示核心能力，复杂场景需读者自行研读源码扩展。目前已有 656 人学习下载，适合希望掌握设备发现、媒体配置、PTZ 控制等典型场景的中高级开发者，通过阅读源码与依赖库可快速搭建可运行的 ONVIF 客户端原型，并在此基础上按需裁剪与二次开发。
1. ONVIF JAVA SDK：把网络摄像头的发现、取流、云台控制一次跑通
手里拿到一个ONVIF JAVA SDK.zip，第一反应往往是：这东西到底能不能直接连上我手头那台网络摄像头？答案取决于它有没有把 ONVIF 的 SOAP 协议、WS-Discovery 发现、媒体配置、PTZ 控制这几块封装成可调用的 Java 类。ONVIF 本身是一套基于 SOAP over HTTP 的设备互操作规范，网络摄像头、NVR、编码器只要标了 ONVIF Profile S，理论上就能被统一发现、取 RTSP 地址、抓快照、控云台。这个 SDK 的价值就在于省掉你手写 SOAP 信封、拼 XML、处理鉴权的重复劳动。它适合做安防平台对接、视频巡检工具、边缘盒子集成的 Java 开发者，也适合想快速验证一台摄像头 ONVIF 能力是否完整的测试人员。下面按「先跑通发现、再取流、再控云台、最后避坑」的顺序拆。
2. 环境准备与设备发现：从 WS-Discovery 到拿到设备服务地址
2.1 依赖与工程结构确认
拿到 zip 先别急着写业务代码，第一步是解压看目录。常见结构是lib/放 jar 包、src/放示例、docs/放接口说明。ONVIF 的 Java 实现通常依赖几个基础库：处理 SOAP 的 JAX-WS 或 Apache CXF、解析 XML 的 dom4j 或 JAXB、以及可选的日志门面。如果你用 Maven，先把本地 jar 装进仓库，或者直接systemscope 引用，但更推荐install:install-file装进本地仓库，避免路径写死。
# 把 SDK 里的核心 jar 装进本地 Maven 仓库，坐标按实际 pom 或文件名调整 mvn install:install-file \ -Dfile=lib/onvif-java-sdk.jar \ -DgroupId=com.example.onvif \ -DartifactId=onvif-sdk \ -Dversion=1.0.0 \ -Dpackaging=jar这段命令的作用是把不在中央仓库的 jar 变成 Maven 可解析的依赖。-Dfile指向实际 jar 路径，-DgroupId和-DartifactId建议和 SDK 文档保持一致，否则后续 import 会找不到类。装完后在pom.xml里加对应依赖即可。如果 SDK 自带pom.xml，直接mvn install更省事。
2.2 WS-Discovery 发现局域网设备
ONVIF 设备发现走的是 WS-Discovery，本质是往组播地址239.255.255.250:3702发一个 SOAP 探测消息，设备单播回应自己的服务地址。SDK 一般会封装成DeviceDiscovery之类的类。下面是一个典型调用：
// 创建发现器，指定超时和网卡（多网卡机器必须指定，否则可能发错网段） DeviceDiscovery discovery = new DeviceDiscovery(3000); discovery.setNetworkInterface("eth0"); // Windows 下可能是 "以太网" 或网卡描述 List<DeviceInfo> devices = discovery.discover(); for (DeviceInfo info : devices) { // 设备服务地址，后续所有 SOAP 请求都发往这个 endpoint System.out.println("Endpoint: " + info.getEndpoint()); System.out.println("Types: " + info.getTypes()); System.out.println("Scopes: " + info.getScopes()); }逻辑说明：3000是等待设备回应的毫秒数，局域网里一般 2 到 3 秒够用，跨网段或设备多时调到 5000。setNetworkInterface是多网卡环境下的关键参数，不指定时 JVM 可能选到虚拟网卡或未连接网卡，导致一个设备都发现不了。getEndpoint返回的是设备服务入口，形如http://192.168.1.64/onvif/device_service，后面取能力、取媒体配置都要用它。getScopes里通常带设备名称和硬件型号，可以用来区分同网段多台设备。
如果发现列表为空，先确认摄像头和电脑在同一二层网络、组播没被交换机隔离、防火墙放行 UDP 3702。很多「发现不到」的玄学问题其实是 Windows 防火墙默认拦了入站组播回应。
2.3 手动指定地址绕过发现
生产环境里设备 IP 往往是固定的，没必要每次组播发现。SDK 一般支持直接构造设备服务客户端：
// 跳过发现，直接用已知 endpoint 建立设备服务连接 DeviceService deviceService = new DeviceService( "http://192.168.1.64/onvif/device_service", "admin", "password123" ); // 拉取设备能力，确认支持 Media 和 PTZ DeviceCapabilities caps = deviceService.getCapabilities(); System.out.println("Media: " + caps.getMediaEndpoint()); System.out.println("PTZ: " + caps.getPtzEndpoint());参数说明：构造函数三个参数分别是设备服务地址、用户名、密码。ONVIF 鉴权默认走 WS-Security UsernameToken，密码在 SOAP 头里做 digest，不是明文。getCapabilities返回的Media和PTZ地址是后续操作的入口，如果某个字段为空，说明这台设备不支持对应 Profile，别硬调。常见做法是先把能力拉全，再决定走哪条业务分支。
3. 取流与媒体配置：拿到 RTSP 地址并区分主辅码流
3.1 获取媒体 Profile 列表
ONVIF 把每路码流抽象成 Media Profile，一个 Profile 绑定一套视频编码、分辨率、帧率参数。取 RTSP 地址前必须先拿到 Profile 的 token。
// 基于设备服务创建媒体服务客户端 MediaService mediaService = new MediaService( caps.getMediaEndpoint(), "admin", "password123" ); // 获取所有媒体配置，通常至少有一个主码流 Profile List<MediaProfile> profiles = mediaService.getProfiles(); for (MediaProfile p : profiles) { System.out.println("Token: " + p.getToken()); System.out.println("Name: " + p.getName()); // 编码信息：H264 / H265，分辨率，帧率 System.out.println("Encoding: " + p.getVideoEncoder().getEncoding()); System.out.println("Resolution: " + p.getVideoEncoder().getResolution()); }逻辑说明：getProfiles返回的列表里，token是后续取流和改配置的唯一标识，name通常是「mainStream」「subStream」这类可读名。getVideoEncoder里的编码格式决定你后面用 FFmpeg 拉流时要不要转码。如果列表里只有一个 Profile，说明这台设备只暴露一路码流，多路取流的需求就得靠 NVR 或设备本身的多通道能力。
3.2 取 RTSP 地址并验证
拿到 token 后取流地址：
// 用主码流 token 取 RTSP URI String token = profiles.get(0).getToken(); StreamUri uri = mediaService.getStreamUri(token, "RTSP"); System.out.println("RTSP: " + uri.getUri()); // 常见返回形如： // rtsp://192.168.1.64:554/Streaming/Channels/101?transportmode=unicast参数说明：getStreamUri第二个参数是传输协议，一般填RTSP，部分 SDK 要求填RTP-Unicast。返回的 URI 里带transportmode=unicast表示单播，多客户端同时拉流时注意设备并发上限，低端摄像头通常只支持 2 到 4 路并发。拿到地址后别急着写播放器，先用 FFmpeg 或 VLC 验证：
# 用 ffprobe 验证 RTSP 地址是否可拉流，只探测不转码 ffprobe -rtsp_transport tcp -i "rtsp://192.168.1.64:554/Streaming/Channels/101" -show_streams-rtsp_transport tcp强制走 TCP，避免 UDP 丢包导致的画面花屏。如果 ffprobe 能打印出 H264 流信息，说明 ONVIF 取到的地址是有效的；如果超时，检查用户名密码是否在 URI 里需要单独带、设备是否限制了并发连接数。
3.3 主辅码流的选择策略
实际项目里我一般主码流用于录像和 AI 分析，辅码流用于预览和多路轮巡。主码流分辨率高、码率大，辅码流通常是 D1 或 720p、码率几百 K。切换方式就是换一个 Profile 的 token 再取一次 StreamUri。如果 SDK 支持修改 VideoEncoderConfiguration，还可以动态调分辨率和码率，但要注意：改配置会触发设备重新协商，正在拉流的客户端会断几秒，生产环境别在业务高峰期调。
4. 云台控制与事件订阅：PTZ 连续移动和报警抓图
4.1 PTZ 连续移动与停止
云台控制是 ONVIF 里比较容易翻车的一块，因为不同厂商对 PTZ 速度范围和方向定义有差异。标准做法是先取 PTZ 配置，再发连续移动命令，最后必须发停止命令。
// 创建 PTZ 服务客户端 PtzService ptzService = new PtzService( caps.getPtzEndpoint(), "admin", "password123" ); // 取第一个 PTZ 配置的 token String ptzToken = ptzService.getConfigurations().get(0).getToken(); // 向右连续移动，速度范围通常 -1.0 到 1.0 ptzService.continuousMove(ptzToken, 0.5f, 0.0f, 0.0f); // 业务等待，实际项目里用异步或定时器控制时长 Thread.sleep(2000); // 必须显式停止，否则云台会一直转 ptzService.stop(ptzToken, true, true);逻辑说明：continuousMove三个速度参数分别是 Pan（左右）、Tilt（上下）、Zoom（变倍），取值-1.0到1.0，0表示该轴不动。stop的两个布尔参数分别控制 Pan/Tilt 停止和 Zoom 停止，都传true最稳妥。血泪经验：忘记调stop会导致云台撞限位或一直转，调试时务必在finally块里补停止。部分设备对速度值不敏感，传0.1和1.0转速一样，这是固件实现差异，不是 SDK 问题。
4.2 事件订阅与报警抓图
ONVIF 事件走 WS-Notification，设备在移动侦测、遮挡报警时推送消息。SDK 一般封装成事件订阅接口：
// 创建事件服务并订阅，指定回调地址和订阅时长 EventService eventService = new EventService( caps.getEventsEndpoint(), "admin", "password123" ); eventService.subscribe("http://192.168.1.100:8080/onvif/callback", 600); // 回调侧解析消息，判断是否为移动侦测 public void onEvent(EventMessage msg) { if (msg.getTopic().contains("Motion")) { // 触发抓图：先取快照 URI，再 HTTP GET 下载 String snapshotUri = mediaService.getSnapshotUri(profileToken); // 用 HttpClient 下载图片并落盘 } }参数说明：subscribe第一个参数是你本地接收通知的 HTTP 地址，必须是设备能访问到的 IP，不能写localhost；第二个参数是订阅有效期，单位秒，到期前要续订。回调侧解析时注意 topic 命名各厂商不统一，常见做法是匹配关键字而不是全等。抓图走getSnapshotUri拿 JPEG 地址，再用普通 HTTP 客户端下载，别用 SOAP 去拉图片。
5. 避坑与排查：鉴权、超时、编码、并发四类高频问题
5.1 鉴权失败但密码明明是对的
现象：调用任何接口都返回401 Unauthorized或 SOAP FaultNotAuthorized。原因：ONVIF 的 WS-Security UsernameToken 对密码做 digest 时依赖设备时间，设备时间和服务器时间偏差超过几分钟就会鉴权失败；另外部分设备要求密码不能含特殊字符。解决：先校准设备 NTP 时间，再把密码改成纯字母数字测试，确认是时间问题还是字符问题。常见做法是在代码里捕获 SOAP Fault 后打印完整响应体，别只看异常消息。
5.2 发现得到但取能力超时
现象：WS-Discovery 能列出设备，但getCapabilities卡住直到超时。原因：设备服务地址返回的是 IPv6 或另一个网段地址，而你的机器路由不可达；也可能是设备只允许 HTTPS。解决：打印 endpoint 确认协议和 IP，手动用浏览器或 curl 访问该地址看是否响应；如果是 HTTPS 且证书自签，需要在 SDK 里配置信任所有证书或导入设备证书。
5.3 RTSP 地址取到了但拉流花屏
现象：ffprobe 能连上，但画面卡顿、花屏、绿屏。原因：UDP 传输丢包，或主码流码率超过网络带宽。解决：拉流时强制 TCP，命令加-rtsp_transport tcp；如果还花，换辅码流 Profile 降低码率。另外检查摄像头编码是否为 H265，部分老播放器不支持，需要转码。
5.4 多路并发拉流后设备无响应
现象：单路正常，开到第三路时设备 Web 界面都打不开。原因：低端摄像头 CPU 和网络处理能力有限，ONVIF 信令和 RTSP 流共用资源，并发一高就假死。解决：控制并发数，预览用辅码流，录像用 NVR 拉主码流而不是每路都从摄像头直取；必要时在代码里加连接池和重试退避。
注意：调试 PTZ 时一定要在
finally里补stop，我见过云台转到限位后齿轮打滑的案例，返修成本比多写一行代码高得多。
6. 进阶技巧：用抓包和日志把 ONVIF 交互变成可观测的黑匣子
ONVIF 出问题时，光看 Java 异常很难定位，因为异常往往只告诉你「SOAP Fault」，不告诉你设备到底嫌哪里不对。我一般会同时开三样东西：SDK 的 SOAP 日志、tcpdump 抓包、设备 Web 界面。SDK 如果基于 CXF，可以打开LoggingInInterceptor和LoggingOutInterceptor，把请求和响应的完整 XML 打到日志里。下面是一个开启日志的典型配置：
// CXF 客户端开启 SOAP 日志，打印完整请求响应 XML Client client = ClientProxy.getClient(deviceService.getPort()); client.getInInterceptors().add(new LoggingInInterceptor()); client.getOutInterceptors().add(new LoggingOutInterceptor());逻辑说明：LoggingInInterceptor打印设备返回的 SOAP 响应，LoggingOutInterceptor打印你发出去的请求。打开后能看到 WS-Security 头、SOAP Body 里的具体参数，对照 ONVIF 规范就能判断是参数名写错还是设备不支持。抓包用tcpdump -i eth0 -A port 80 or port 554，能看到 HTTP SOAP 和 RTSP 交互的原始报文，适合排查「SDK 说成功但设备没动作」这类问题。
验证方法上，我习惯按这个顺序走一遍：先 WS-Discovery 确认设备在线，再getCapabilities确认 Profile 支持，再getProfiles确认码流数量，再getStreamUri加 ffprobe 确认可拉流，最后 PTZ 移动加停止确认可控。每一步都留日志，哪一步断了一眼就能看出来。参数边界方面，超时别低于 3000ms，PTZ 速度别长期给满值，事件订阅有效期别超过设备上限（常见 600 秒），并发拉流数别超过设备标称值。
从那以后我每次接新摄像头，都强制先跑一遍「发现→能力→Profile→取流→PTZ」五步验证脚本，把结果存成日志再写业务代码。这样后面出问题，至少知道是设备本身不支持还是代码写错了。希望帮到你。
本文还有配套的精品资源，点击获取
