简介这是一套基于 Java 与 Spring Boot 封装的 ONVIF 协议 SDK面向从事视频监控、IPC 设备对接的后端开发者帮助其跳过 SOAP 协议与设备鉴权的底层细节快速完成摄像头接入。包内提供 TestController.java 示例演示如何调用 SDK 接口覆盖获取 Authorization、token 列表、截图 URL、流地址、预置位以及云台控制启停、设备自动发现与预置位跳转等九项常用能力。资源共 48 个文件以 38 个 xml 配置、3 个 java 源码、2 个 class 与 2 个 properties 为主另含 jar 依赖与工程配置文件压缩包约 10.52MB可直接导入 IDE 运行调试。目前已有 300 人学习下载适合需要快速验证 ONVIF 设备对接、研究 SOAP 通信流程或二次封装 SDK 的开发者参考。1. 拿到 onvif-sdk 压缩包后先别急着解压它能替你省掉哪几周的协议对接如果你做过 IPC网络摄像机对接大概率经历过这种场面设备就在局域网里但你要先翻遍 ONVIF 的 WSDL手写 SOAP 信封处理 WS-Security 的 PasswordDigest再对着 DeviceIO、Media、PTZ、Imaging 几个服务来回切。一个「获取 RTSP 流地址」的需求光认证和命名空间就能耗掉两三天。这份 onvif-sdk 就是冲这个场景来的——它把 ONVIF 的 SOAP 通信、鉴权、设备发现、媒体配置、云台控制全部封进 Java 库外面只留一层接近业务语义的接口配一个TestController.java当调用样例。压缩包里是标准的 Maven 工程结构pom.xml、src/main、target外加onvif-sdk-dzp-0.0.1-SNAPSHOT-jar-with-dependencies.jar这个带依赖的胖包以及demo、lib目录。demo文件夹调用的是库TestController.java对应示例。它适合两类人一类是 Spring Boot 项目里要快速接入 ONVIF 设备的后端另一类是想读一份能跑通的 ONVIF Java 实现来理解协议流程的人。目前它覆盖九个能力获取 Authorization、获取 token 列表、获取截图 url、获取流地址、获取预置位、云台控制启动、云台控制停止、设备自动发现、预置位跳转。下面按「怎么跑起来 → 每个接口怎么调 → 坑在哪 → 怎么验证」推一遍。2. 把 jar 和源码接进 Spring Boot依赖、配置与第一个可跑通的调用2.1 先看清工程结构与两种接入方式解压后先别改代码把目录扫一遍。pom.xml是构建入口src/main下是 SDK 源码target里已经躺着一个onvif-sdk-dzp-0.0.1-SNAPSHOT-jar-with-dependencies.jar。这个胖包把 ONVIF 依赖的 SOAP 栈、XML 解析、HTTP 客户端都打进去了意味着你有两条路可走。第一条是源码依赖把src/main作为模块或直接拷进你的工程改起来方便适合要扩展接口或调超时参数的人。第二条是 jar 依赖把胖包丢进本地仓库或lib目录用systemscope 或install后正常引用适合只想调接口、不想碰协议细节的人。demo目录和TestController.java是给你对照的别跳过——它决定了你调用时参数怎么传。常见做法是先用 jar 跑通确认设备能连上、能拿到流地址再决定要不要读源码。因为 ONVIF 的报错信息经常藏在 SOAP Fault 里直接读源码定位比盲调快得多。2.2 用 pom.xml 把依赖装进本地仓库如果你走 jar 路线最稳的方式是先把胖包装进本地 Maven 仓库避免systemscope 带来的打包遗漏。在压缩包根目录执行# 把带依赖的胖包装进本地仓库groupId/artifactId 按你工程实际引用改 mvn install:install-file \ -Dfileonvif-sdk-dzp-0.0.1-SNAPSHOT-jar-with-dependencies.jar \ -DgroupIdcom.dzp.onvif \ -DartifactIdonvif-sdk \ -Dversion0.0.1-SNAPSHOT \ -Dpackagingjar这条命令做三件事指定要安装的 jar 文件、给它一个坐标groupId/artifactId/version、声明打包类型。坐标必须和你pom.xml里dependency写的完全一致否则编译期就报找不到符号。装完之后在业务工程的pom.xml里加对应依赖即可。参数上要注意-Dversion里的SNAPSHOT是原包名带的别自作主张改成 release否则引用时对不上。如果你走源码路线这一步跳过直接把模块加进modules。2.3 在 application.yml 里管住设备地址与凭据ONVIF 调用离不开三样东西设备 IP或完整 service URL、用户名、密码。硬编码在TestController里能跑但一换设备就得改代码。我一般抽到配置里onvif: device: ip: 192.168.1.64 username: admin password: your_password # 部分设备 ONVIF 端口不是 80按实际改 port: 80 timeout: connect: 3000 read: 5000ip和port决定 SOAP 请求打到哪username/password参与 WS-Security 的 PasswordDigest 计算错一个字符就是 401 或 SOAP Fault。connect/read超时建议显式设ONVIF 设备在弱网或忙时响应很慢默认无限等会把线程池拖死。这些值最终注入到调用 SDK 的 Service 里TestController只负责收请求、转调用。2.4 第一个调用从 TestController 看接口长什么样TestController.java是理解整套 SDK 的钥匙。它用 Spring Boot 的RestController暴露 HTTP 接口内部注入 SDK 的服务类。典型结构是这样RestController RequestMapping(/onvif) public class TestController { Autowired private OnvifDeviceService deviceService; // SDK 封装的服务名称以实际源码为准 // 获取设备能力与媒体信息是后续拿流地址的前置 GetMapping(/device/info) public Object deviceInfo(RequestParam String ip) { // 内部会完成 Authorization 与 GetCapabilities return deviceService.getDeviceInfo(ip); } // 获取 RTSP 流地址 GetMapping(/stream/url) public Object streamUrl(RequestParam String ip, RequestParam String profileToken) { return deviceService.getStreamUri(ip, profileToken); } }逻辑上Controller 只做参数接收和结果返回真正的 SOAP 组装、鉴权头、XML 解析都在 SDK 服务里。profileToken这个参数很关键——ONVIF 的媒体配置是按 profile 组织的你得先拿到 token 列表才能拿流地址、截图 URL、预置位。参数说明ip定位设备profileToken定位媒体配置两者缺一不可。第一次跑建议先调设备信息接口确认连通再调 token 列表最后才拿流地址顺序反了会拿到空结果。3. 九个能力逐个落地鉴权、token、流地址、预置位与云台控制3.1 获取 Authorization 与 token 列表一切调用的前置ONVIF 的鉴权不是简单的 Basic Auth而是 WS-Security 的 UsernameToken密码要用 Nonce、Created 时间戳做 SHA1 摘要。SDK 把这一步封成了「获取 Authorization」。你不需要手写摘要但要知道它依赖设备时间——设备时间和服务器差太多摘要校验会失败这是后面避坑章要展开的点。拿到 Authorization 后第一件正事是获取 token 列表。ONVIF 里 token 分好几种ProfileToken媒体配置、VideoSourceToken、PtzConfigurationToken。SDK 的 token 列表接口一般返回媒体 profile 集合。调用顺序// 1. 建立设备连接并完成鉴权 OnvifDevice device deviceService.connect(ip, username, password); // 2. 拉取媒体 profile token 列表 ListProfile profiles device.getMediaProfiles(); for (Profile p : profiles) { // token 是后续所有媒体操作的钥匙 System.out.println(p.getToken() - p.getName()); }逻辑说明connect内部完成 Authorization 和能力协商getMediaProfiles发GetProfilesSOAP 请求解析返回的trt:Profiles节点。参数上token是字符串别拿name去当 token 用——很多设备两者不同混用会报「Profile not found」。这一步拿到的 token 要缓存起来后面流地址、截图、预置位都靠它。3.2 获取流地址与截图 URL媒体服务的两个高频接口流地址是视频监控对接的核心产出。ONVIF 的GetStreamUri返回一个 RTSP URL里面通常带?transportudp或tcp。SDK 封装后大致这样调// 用前面拿到的 profileToken 换 RTSP 流地址 String rtspUrl device.getStreamUri(profileToken); // 常见返回形如 rtsp://192.168.1.64:554/Streaming/Channels/101?transportudp System.out.println(rtspUrl);逻辑说明SDK 组装GetStreamUri请求StreamSetup里指定RTP-Unicast和传输协议。参数上传输协议选 UDP 延迟低但丢包选 TCP 稳定但延迟略高内网一般 UDP 够用跨网段建议 TCP。截图 URL 走的是GetSnapshotUri返回一个 HTTP 地址直接 GET 就能拿到 JPEG// 截图 URL 同样是 profile 级操作 String snapshotUrl device.getSnapshotUri(profileToken);注意截图 URL 返回的是「地址」不是「图片字节」你要自己发 HTTP 请求去取。有些设备截图接口需要再带一次鉴权SDK 不一定帮你处理取图失败先看是不是 401。3.3 预置位与云台控制PTZ 服务的启动、停止与跳转云台控制是 ONVIF 里最容易「玄学」的部分因为不同厂商对 PTZ 指令的响应差异很大。SDK 提供了云台控制启动、停止、预置位获取、预置位跳转四件事。先看预置位// 获取当前设备已配置的预置位列表 ListPreset presets device.getPresets(profileToken); for (Preset preset : presets) { System.out.println(preset.getToken() - preset.getName()); }逻辑说明GetPresets返回预置位 token 和名称token 用于跳转。参数上预置位是绑定在 PTZ 配置上的如果设备没配 PTZ 或 profile 不含 PTZ这里会返回空或报错。云台控制启动与停止本质是发ContinuousMove和Stop// 启动指定方向和速度x/y 为 -1.0 ~ 1.0 的归一化值 device.ptzMove(profileToken, 0.5, 0.0, 0.0); // 向右转速度 0.5 // 停止必须显式调用否则设备会一直转 device.ptzStop(profileToken);参数说明x是水平方向正值向右y是垂直方向正值向上z是变焦。速度范围各厂商不完全一致常见是 -1 到 1。启动后一定要配对调用停止很多新手只发启动不发停止摄像头转到限位才停血泪经验。预置位跳转用GotoPreset传预置位 token 即可适合快速切到固定视角。3.4 设备自动发现WS-Discovery 怎么用、什么时候别用设备自动发现走的是 WS-Discovery通过 UDP 组播发Probe设备回ProbeMatch。SDK 封装后一般是一行调用// 触发一次局域网设备发现超时时间按网络规模调 ListDeviceInfo devices deviceService.discover(3000);逻辑说明SDK 往239.255.255.250:3702发组播收集响应并解析出设备地址。参数上超时太短会漏设备太长会阻塞3000ms 是常见折中。注意自动发现依赖组播跨网段、云服务器、容器网络里基本收不到响应这种场景别用发现直接配 IP。发现到的设备仍需单独鉴权发现不等于已授权。4. 避坑与排查ONVIF 对接里最容易翻车的五件事4.1 鉴权失败先查设备时间再查密码摘要现象调用任何接口都返回 401 或 SOAP Fault「Sender not authorized」。原因WS-Security 的 PasswordDigest 依赖设备与调用方的时间差超过设备允许窗口常见 5 分钟就校验失败其次是密码含特殊字符没转义。解决先校准设备 NTP 或手动对时再确认密码原文没被 URL 编码或截断。SDK 若支持关闭时间校验仅限内网调试别带到生产。4.2 拿到空 token 列表profile 没建或媒体服务没开现象getMediaProfiles返回空集合。原因设备没配置媒体 profile或 ONVIF 的 Media 服务未启用或账号权限不足。解决登录设备 Web 后台确认 ONVIF 已开启、账号有媒体权限部分设备需要先在后台建一个视频配置。别在代码里死循环重试先确认设备侧状态。4.3 流地址能拿到但拉不到流传输协议与端口现象GetStreamUri返回了 RTSP 地址但播放器连不上。原因返回的地址带transportudp而网络屏蔽了 UDP或 RTSP 端口不是 554。解决把传输协议改成 TCP 再试确认 554 端口可达。这一步和 SDK 无关是网络与播放器配置问题别在 SDK 里找原因。4.4 云台只转不停Stop 没发或 profile 不含 PTZ现象调用启动后摄像头一直转。原因没配对调用停止或该 profile 的 PTZ 配置为空导致 Stop 无效。解决启动和停止成对出现最好加超时兜底确认 profile 绑定了 PTZ 配置。这是最典型的翻车点建议在业务层封装一个「转 N 秒后自动停」。4.5 自动发现收不到设备组播被挡或跨网段现象discover返回空。原因调用方和设备不在同一广播域或防火墙挡了 UDP 3702 组播。解决同网段直连测试跨网段改用固定 IP 配置别依赖发现。容器和云主机环境基本可以放弃组播发现。5. 验证与进阶用 curl 和日志确认每一步再决定要不要读源码跑通不代表调对。我习惯在每一层都留验证点。第一层是 HTTP 入口用 curl 直接打TestController暴露的接口确认参数和返回# 先验证设备信息接口确认鉴权与连通 curl http://localhost:8080/onvif/device/info?ip192.168.1.64 # 再验证流地址接口profileToken 换成上一步拿到的真实值 curl http://localhost:8080/onvif/stream/url?ip192.168.1.64profileTokenProfile_1返回里如果 RTSP 地址完整、token 非空说明链路通了。第二层是 SOAP 报文把 SDK 的日志级别调到 DEBUG看发出的 XML 里Security头和GetStreamUri的命名空间对不对。ONVIF 的命名空间前缀各厂商实现有差异SDK 解析失败时日志里的原始 XML 是唯一的黑匣子。第三层是设备侧。同一台设备用 ONVIF Device Manager 之类的工具连一下能连上说明设备没问题连不上就是设备配置或网络。这一步能帮你快速区分「SDK 的锅」和「设备的锅」。进阶用法上如果你要扩展接口读src/main里的服务实现比改胖包靠谱。重点看三处鉴权头怎么拼、SOAP 请求怎么发、响应怎么解析。常见做法是照着已有接口的模式加新方法复用同一套连接和鉴权逻辑别另起一套 HTTP 客户端。参数上超时和重试策略建议抽成配置不同设备响应速度差很多写死容易在弱网设备上翻车。从那以后我每次接新设备都强制走一遍「对时 → 鉴权 → token → 流地址 → 截图 → 云台启停」的完整链路任何一步返回异常就先停在那一步查不带着问题往下走。这套顺序帮我省掉了大量来回猜的时间。希望帮到你。本文还有配套的精品资源点击获取