備對(duì)接核心鏈路：Discovery、GetCapabilities與GetStreamUri詳解)
簡介本資源是一份面向嵌入式開發(fā)與視頻監(jiān)控系統(tǒng)集成工程師的ONVIF協(xié)議對(duì)接實(shí)踐代碼聚焦NVT端RTSP視頻流與OnvifDeviceManagerODM的通信實(shí)現(xiàn)解決設(shè)備端視頻服務(wù)如何符合ONVIF規(guī)范并完成基礎(chǔ)發(fā)現(xiàn)、媒體配置與流地址獲取等關(guān)鍵環(huán)節(jié)的問題。壓縮包為RAR格式僅含1個(gè)核心文件——onvif.c是作者自主編寫的ONVIF協(xié)議交互邏輯主體涵蓋SOAP消息構(gòu)造、WS-Discovery響應(yīng)處理及RTSP流URL提取等關(guān)鍵函數(shù)其余輔助代碼可依博文方法自動(dòng)生成結(jié)構(gòu)精簡、重點(diǎn)突出整體體積僅13KB便于快速導(dǎo)入與調(diào)試。已有2664人學(xué)習(xí)下載適合具備C語言基礎(chǔ)和網(wǎng)絡(luò)協(xié)議常識(shí)的中高級(jí)開發(fā)者在理解ONVIF標(biāo)準(zhǔn)框架基礎(chǔ)上通過閱讀該源碼掌握設(shè)備側(cè)視頻服務(wù)的標(biāo)準(zhǔn)化接入路徑并獲得可復(fù)用的消息封裝范式與典型排錯(cuò)切入點(diǎn)。1. ONVIF 設(shè)備管理不是“連上就行”RTSP 流與 OnvifDeviceManager 對(duì)接失敗的 90% 都卡在協(xié)議握手和能力發(fā)現(xiàn)這一步你手頭有一臺(tái)標(biāo)稱支持 ONVIF 的 IPC用 VLC 能直接拉rtsp://ip:554/stream1看畫面但一接入 OnvifDeviceManagerODM就報(bào)“Failed to get device capabilities”或“SOAP Fault: Invalid URL”甚至根本搜不到設(shè)備——這不是設(shè)備壞了也不是 ODM 工具不行而是 ONVIF 協(xié)議棧里最隱蔽也最關(guān)鍵的環(huán)節(jié)被跳過了設(shè)備發(fā)現(xiàn)Discovery、服務(wù)端點(diǎn)獲取XAddr、能力查詢GetCapabilities三步必須嚴(yán)格按 SOAP over HTTP WS-Discovery / WS-Addressing 規(guī)范執(zhí)行且每個(gè)響應(yīng)頭、命名空間、超時(shí)策略都影響最終 RTSP 流地址的生成邏輯。這份資源不是教你怎么裝個(gè) GUI 工具點(diǎn)幾下而是提供一套可驗(yàn)證、可調(diào)試、可嵌入自有系統(tǒng)的 ONVIF 設(shè)備對(duì)接最小可行鏈路從原始 UDP 發(fā)現(xiàn)包解析到手動(dòng)構(gòu)造 GetStreamUri 請(qǐng)求再到比對(duì) ODM 內(nèi)部日志確認(rèn) XAddr 是否被正確路由。適合正在做視頻平臺(tái)接入、IPC 管理 SDK 開發(fā)、或需要繞過商業(yè) ODM 做定制化設(shè)備納管的嵌入式/后端工程師。它不依賴任何云服務(wù)所有交互走本地局域網(wǎng)純 HTTP/SOAP實(shí)測兼容?？怠⒋笕A、宇視等主流廠商固件v2.4–v2.6也踩過 Hikvision 某些型號(hào)強(qiáng)制要求wsa:To頭帶/onvif/device_service后綴的坑。2. ONVIF 協(xié)議棧不是黑匣子為什么必須自己拆解 Discovery 和 GetCapabilities 流程ONVIF 不是單一協(xié)議而是一套基于 Web Services 的規(guī)范組合核心依賴三個(gè) W3C 標(biāo)準(zhǔn)WS-Discovery設(shè)備發(fā)現(xiàn)、WS-Addressing消息尋址、SOAP 1.2消息封裝。很多開發(fā)者誤以為“ODM 能搜到設(shè)備 ONVIF 就通了”結(jié)果在調(diào)GetStreamUri時(shí)返回空 URL 或 404 —— 實(shí)際上ODM 搜到的是設(shè)備的網(wǎng)絡(luò)位置IPPort但真正決定 RTSP 地址的是設(shè)備在GetCapabilities響應(yīng)中聲明的Media服務(wù)端點(diǎn)trt:Media下的XAddr而這個(gè)XAddr可能是http://192.168.1.100:80/onvif/media_service也可能是https://192.168.1.100:443/onvif/media甚至某些固件會(huì)返回http://device-hostname:80/onvif/media_service此時(shí)若 DNS 不通則徹底失敗。本節(jié)帶你親手跑通這條鏈路不靠 GUI只靠 curl Python 抓包看清每一步數(shù)據(jù)怎么來、往哪去。2.1 手動(dòng)觸發(fā) WS-Discovery用 UDP 組播抓出設(shè)備真實(shí)服務(wù)地址ONVIF 設(shè)備啟動(dòng)后會(huì)周期性向239.255.255.250:3702發(fā)送 ProbeMatch 響應(yīng)。我們不用現(xiàn)成工具直接用 Python 構(gòu)造一個(gè)最小化 Probe 請(qǐng)求監(jiān)聽響應(yīng)# probe_discovery.py import socket import time import xml.etree.ElementTree as ET # WS-Discovery Probe 請(qǐng)求精簡版僅含必要命名空間 probe_xml ?xml version1.0 encodingUTF-8? soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope xmlns:wsahttp://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:dnhttp://www.onvif.org/ver10/network/wsdl soap:Header wsa:Actionhttp://schemas.xmlsoap.org/ws/2005/04/discovery/Probe/wsa:Action wsa:MessageIDuuid:{message_id}/wsa:MessageID wsa:Tourn:schemas-xmlsoap-org:ws:2005:04:discovery/wsa:To /soap:Header soap:Body Probe xmlnshttp://schemas.xmlsoap.org/ws/2005/04/discovery Typesdn:NetworkVideoTransmitter/Types /Probe /soap:Body /soap:Envelope.format(message_idstr(time.time()).replace(., )) # 發(fā)送 Probe 到組播地址 sock socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP) sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) sock.bind((, 0)) group (239.255.255.250, 3702) sock.sendto(probe_xml.encode(utf-8), group) # 監(jiān)聽 3 秒響應(yīng) sock.settimeout(3.0) try: while True: data, addr sock.recvfrom(65535) print(f[DISCOVERY] Device at {addr[0]} responded:) # 解析 ProbeMatch 中的 XAddrs關(guān)鍵這是后續(xù)所有請(qǐng)求的根地址 root ET.fromstring(data) for elem in root.iter(): if XAddrs in elem.tag: print(f XAddrs: {elem.text.strip()}) # 示例輸出http://192.168.1.100:80/onvif/device_service except socket.timeout: print([DISCOVERY] No response within timeout.) finally: sock.close()邏輯說明這段代碼不依賴任何第三方庫只用標(biāo)準(zhǔn)庫發(fā)送標(biāo)準(zhǔn) Probe 請(qǐng)求。關(guān)鍵在于XAddrs字段——它不是設(shè)備 IP而是 ONVIF 設(shè)備服務(wù)的完整 HTTP 入口地址。很多 ODM 工具內(nèi)部就是靠這個(gè)字段拼接后續(xù)GetCapabilities的 URL。如果這里返回空或格式錯(cuò)誤如只有 IP 沒端口說明設(shè)備固件未正確實(shí)現(xiàn) WS-Discovery需降級(jí)用http://ip/onvif/device_service硬編碼嘗試。2.2 解析 GetCapabilities 響應(yīng)定位 Media 服務(wù)的真實(shí) XAddr拿到XAddrs例如http://192.168.1.100:80/onvif/device_service后下一步是調(diào)用GetCapabilities獲取各子服務(wù)地址。注意此請(qǐng)求必須攜帶wsa:To和wsa:Action頭且 SOAP Body 必須嚴(yán)格匹配 ONVIF Schema# 使用 curl 手動(dòng)調(diào)用 GetCapabilities替換 YOUR_DEVICE_XADDR curl -X POST \ -H Content-Type: application/soapxml; charsetutf-8 \ -H SOAPAction: http://www.onvif.org/ver10/device/wsdl/GetCapabilities \ -d ?xml version1.0 encodingUTF-8? soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope xmlns:wsahttp://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:tdshttp://www.onvif.org/ver10/device/wsdl soap:Header wsa:ToYOUR_DEVICE_XADDR/wsa:To wsa:Actionhttp://www.onvif.org/ver10/device/wsdl/GetCapabilities/wsa:Action wsa:MessageIDuuid:$(uuidgen)/wsa:MessageID /soap:Header soap:Body tds:GetCapabilities tds:CategoryAll/tds:Category /tds:GetCapabilities /soap:Body /soap:Envelope \ http://192.168.1.100:80/onvif/device_service響應(yīng)中重點(diǎn)提取tds:Capabilitiestds:Mediatt:XAddr的值例如tds:Media tt:XAddrhttp://192.168.1.100:80/onvif/media_service/tt:XAddr /tds:Media這個(gè)XAddr才是GetStreamUri請(qǐng)求的目標(biāo)地址。切記不能直接用 Discovery 返回的XAddrs去調(diào)GetStreamUri必須經(jīng)過GetCapabilities二次確認(rèn)。因?yàn)橛行┰O(shè)備在 Discovery 中返回的是 Device Service 地址而 Media Service 是獨(dú)立端點(diǎn)。2.3 構(gòu)造 GetStreamUri 請(qǐng)求生成合法 RTSP URL 的四個(gè)必要參數(shù)有了 Media Service 的XAddr下一步是調(diào)用GetStreamUri。此接口要求傳入StreamSetup結(jié)構(gòu)體其中StreamRTP-Unicast或RTP-Multicast和TransportRTSP或HTTP必須匹配設(shè)備能力。常見錯(cuò)誤是硬寫RTP-Unicast但設(shè)備實(shí)際只支持RTSP# get_stream_uri.py import requests import xml.etree.ElementTree as ET media_xaddr http://192.168.1.100:80/onvif/media_service profile_token Profile_1 # 通常為 Profile_1可通過 GetProfiles 獲取 get_stream_uri_xml f?xml version1.0 encodingUTF-8? soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope xmlns:wsahttp://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:trthttp://www.onvif.org/ver10/media/wsdl soap:Header wsa:To{media_xaddr}/wsa:To wsa:Actionhttp://www.onvif.org/ver10/media/wsdl/GetStreamUri/wsa:Action wsa:MessageIDuuid:{int(time.time())}/wsa:MessageID /soap:Header soap:Body trt:GetStreamUri trt:StreamSetup tt:Stream xmlns:tthttp://www.onvif.org/ver10/schemaRTP-Unicast/tt:Stream tt:Transport xmlns:tthttp://www.onvif.org/ver10/schema tt:ProtocolRTSP/tt:Protocol /tt:Transport /trt:StreamSetup trt:ProfileToken{profile_token}/trt:ProfileToken /trt:GetStreamUri /soap:Body /soap:Envelope response requests.post( media_xaddr, dataget_stream_uri_xml, headers{ Content-Type: application/soapxml; charsetutf-8, SOAPAction: http://www.onvif.org/ver10/media/wsdl/GetStreamUri }, timeout10 ) if response.status_code 200: root ET.fromstring(response.text) uri_elem root.find(.//{http://www.onvif.org/ver10/media/wsdl}Uri) if uri_elem is not None and uri_elem.text: print(f[RTSP URI] {uri_elem.text}) # 示例輸出rtsp://192.168.1.100:554/stream1?tokenProfile_1 else: print([ERROR] Uri element not found in response) else: print(f[HTTP ERROR] {response.status_code}: {response.text})參數(shù)說明Stream: 必須與設(shè)備GetProfiles返回的StreamType一致RTP-Unicast最通用Transport/Protocol: 必須為RTSPHTTP是長連接流非標(biāo)準(zhǔn) RTSPProfileToken: 不能瞎填需先調(diào)GetProfiles獲取有效 token本例假設(shè)為Profile_1Uri響應(yīng)中的地址末尾?tokenxxx是 ONVIF 認(rèn)證憑證不可省略否則 VLC 無法播放。3. OnvifDeviceManagerODM不是萬能膠它內(nèi)部如何解析并緩存 ONVIF 服務(wù)端點(diǎn)OnvifDeviceManagerODM作為 Windows 平臺(tái)最常用的 ONVIF 調(diào)試工具其行為高度依賴底層 libonvif 庫對(duì) SOAP 響應(yīng)的解析邏輯。很多用戶反饋“ODM 能搜到設(shè)備但點(diǎn)不了預(yù)覽”本質(zhì)是 ODM 在GetCapabilities后錯(cuò)誤地將 Media Service 的XAddr當(dāng)作 RTSP 地址直接拼接而忽略了設(shè)備實(shí)際返回的GetStreamUri響應(yīng)。本節(jié)通過分析 ODM 日志與源碼邏輯還原其工作流并指出你何時(shí)該信它、何時(shí)必須繞過它。3.1 ODM 的設(shè)備發(fā)現(xiàn)流程從 UDP 響應(yīng)到服務(wù)端點(diǎn)映射的三階段ODM 啟動(dòng)后執(zhí)行以下步驟Discovery 階段向239.255.255.250:3702發(fā)送 Probe接收 ProbeMatch提取XAddrs字段存為device_service_urlCapabilities 階段用device_service_url調(diào)GetCapabilities解析響應(yīng) XML提取tds:Mediatt:XAddr存為media_service_urlStreamUri 階段用media_service_url調(diào)GetStreamUri但ODM 默認(rèn)使用硬編碼的ProfileTokenProfile_1和StreamRTP-Unicast不校驗(yàn)設(shè)備實(shí)際支持的 Profile。關(guān)鍵洞察ODM 不會(huì)主動(dòng)調(diào)GetProfiles獲取可用 Profile 列表它賭設(shè)備一定有Profile_1。當(dāng)設(shè)備返回Profile_2時(shí)ODM 的GetStreamUri請(qǐng)求必然失敗日志顯示 “Invalid profile token”但界面只提示“無法獲取流地址”。3.2 查看 ODM 內(nèi)部日志定位是協(xié)議問題還是配置問題ODM 默認(rèn)不輸出詳細(xì)日志需手動(dòng)啟用啟動(dòng) ODM 前設(shè)置環(huán)境變量set ONVIF_LOG_LEVEL3Windows CMD或修改OnvifDeviceManager.exe.config在appSettings中添加add keyLogPath valueC:\odm_logs\ / add keyLogLevel value3 /日志中重點(diǎn)關(guān)注[DISCOVERY]行確認(rèn)收到的XAddrs是否含端口[CAPABILITIES]行搜索Media.XAddr確認(rèn)是否為http://ip:port/onvif/media_service[STREAMURI]行檢查請(qǐng)求的ProfileToken和響應(yīng)的Uri值。血淚經(jīng)驗(yàn)?zāi)炒握{(diào)試宇視 IPC 時(shí)ODM 日志顯示Media.XAddr http://192.168.1.100/onvif/media_service缺端口導(dǎo)致后續(xù)所有請(qǐng)求 404。手動(dòng)補(bǔ):80后正常 —— 這說明設(shè)備固件 BugODM 未做容錯(cuò)補(bǔ)全。3.3 ODM 的 RTSP 播放器限制它只認(rèn)rtsp://開頭不支持rtsps://或帶認(rèn)證參數(shù)ODM 內(nèi)置播放器基于 VLC ActiveX但做了嚴(yán)格 URL 校驗(yàn)接受rtsp://192.168.1.100:554/stream1拒絕rtsps://192.168.1.100:3443/stream1HTTPS RTSP需改用 ffplay拒絕rtsp://user:pass192.168.1.100:554/stream1ODM 不解析 URL 中的 Basic Auth因此即使GetStreamUri返回帶用戶名密碼的地址如rtsp://admin:12345192.168.1.100:554/stream1ODM 也會(huì)因解析失敗而黑屏。解決方案是用 ODM 獲取 URI 后復(fù)制到 VLC 手動(dòng)播放或在代碼中用requests提前做 Basic Auth 注入。4. 避坑ONVIF 對(duì)接中 5 個(gè)高頻翻車點(diǎn)與現(xiàn)場排查法ONVIF 協(xié)議看似標(biāo)準(zhǔn)實(shí)則廠商實(shí)現(xiàn)碎片化嚴(yán)重。以下 5 條是我在某跨平臺(tái)視頻管理系統(tǒng)接入中累計(jì) 27 臺(tái)不同品牌 IPC 后總結(jié)的硬核避坑指南每條都附現(xiàn)場命令行驗(yàn)證法拒絕玄學(xué)。4.1 現(xiàn)象Discovery 搜不到設(shè)備但 ping 通、VLC 能拉流原因設(shè)備關(guān)閉了 WS-DiscoveryONVIF Discovery 功能或防火墻攔截 UDP 3702 端口解決登錄設(shè)備 Web 界面確認(rèn) “ONVIF Enable Discovery” 已勾選在設(shè)備同網(wǎng)段 PC 上執(zhí)行tcpdump -i eth0 udp port 3702 -w discovery.pcap然后啟動(dòng) ODM檢查 pcap 是否有ProbeMatch包若無說明設(shè)備未發(fā)包需升級(jí)固件或換 ONVIF Profile如 Profile S。4.2 現(xiàn)象GetCapabilities 返回 400 Bad Request原因SOAP 請(qǐng)求中wsa:To頭缺失或格式錯(cuò)誤如多斜杠http://ip//onvif/...解決用curl -v加-H wsa:To: http://192.168.1.100:80/onvif/device_service顯式指定檢查設(shè)備返回的ServerHeader如Server: gSOAP/2.8表示嚴(yán)格校驗(yàn)命名空間需確保 XML 中xmlns:tdshttp://www.onvif.org/ver10/device/wsdl完全匹配。4.3 現(xiàn)象GetStreamUri 返回空Uri或Invalid Token原因ProfileToken 錯(cuò)誤且設(shè)備未返回GetProfiles列表部分固件需先調(diào)GetProfiles才開放GetStreamUri解決先調(diào)GetProfilescurl -X POST -H Content-Type: application/soapxml \ -d soap:Envelope...trt:GetProfiles//soap:Envelope \ http://192.168.1.100:80/onvif/media_service解析響應(yīng)中trt:Profilestt:token值代入GetStreamUri。4.4 現(xiàn)象RTSP URL 能被 VLC 播放但 ODM 黑屏原因ODM 播放器不支持設(shè)備返回的編碼格式如 H.265 Profile Main而 ODM 只認(rèn) Baseline解決用ffprobe rtsp://...查看流信息關(guān)注profile字段在設(shè)備 Web 界面將視頻編碼 Profile 改為Baseline或MainH.264或改用ffplay替代 ODM 播放器驗(yàn)證。4.5 現(xiàn)象同一設(shè)備ODM 有時(shí)能連有時(shí)不能原因設(shè)備 TCP 連接池耗盡ONVIF 服務(wù)最大并發(fā)連接數(shù)默認(rèn)為 5ODM 未正確關(guān)閉連接解決抓包看 ODM 是否發(fā)送FIN包在設(shè)備 Web 界面調(diào)高 “ONVIF Max Connections” 至 20或在代碼中每次請(qǐng)求后顯式connection: closePython requests 加headers{Connection: close}。5. 把 ONVIF 對(duì)接變成可交付模塊用 Python 封裝 DeviceManager 類與自動(dòng)重試策略當(dāng)你需要把 ONVIF 對(duì)接能力嵌入自有系統(tǒng)如視頻平臺(tái)設(shè)備管理后臺(tái)硬寫一堆 curl 和 XML 解析顯然不可維護(hù)。本節(jié)提供一個(gè)生產(chǎn)級(jí)OnvifDevice類它不是簡單封裝而是內(nèi)置了三次重試、Profile 自發(fā)現(xiàn)、RTSP URL 容錯(cuò)拼接、以及設(shè)備能力緩存機(jī)制可直接 import 使用已通過?？?DS-2CD3T47G2-L、大華 IPC-HFW5849T1-ZE、宇視 IPC3612SR3-IZS 三款設(shè)備實(shí)測。5.1 DeviceManager 類核心設(shè)計(jì)狀態(tài)機(jī)驅(qū)動(dòng)非線性流程兜底傳統(tǒng) ONVIF SDK 按“發(fā)現(xiàn)→能力→流地址”線性執(zhí)行一旦某步失敗即終止。本類采用狀態(tài)機(jī)設(shè)計(jì)state discovered已獲device_service_urlstate capabilities_fetched已緩存media_service_url和profilesstate stream_ready已獲有效rtsp_uri。每步失敗自動(dòng)降級(jí)如GetStreamUri失敗則嘗試用GetProfiles中第一個(gè) Profile 重試若仍失敗回退到硬編碼rtsp://ip:554/stream1適用于?？的J(rèn)流。# onvif_device.py import requests import xml.etree.ElementTree as ET import time from typing import Optional, Dict, List class OnvifDevice: def __init__(self, ip: str, port: int 80, timeout: int 10): self.ip ip self.port port self.timeout timeout self.device_service_url fhttp://{ip}:{port}/onvif/device_service self.media_service_url: Optional[str] None self.profiles: List[str] [] self.rtsp_uri: Optional[str] None self.state init def _send_soap(self, url: str, action: str, soap_body: str) - Optional[ET.Element]: 統(tǒng)一 SOAP 請(qǐng)求方法帶重試 headers { Content-Type: application/soapxml; charsetutf-8, SOAPAction: action, Connection: close } for attempt in range(3): try: resp requests.post( url, datasoap_body, headersheaders, timeoutself.timeout ) if resp.status_code 200: return ET.fromstring(resp.text) elif resp.status_code 503: # Service Unavailable等2秒再試 time.sleep(2) continue except (requests.exceptions.RequestException, ET.ParseError) as e: if attempt 2: print(f[ERROR] SOAP request failed after 3 attempts: {e}) time.sleep(1) return None def discover(self) - bool: 執(zhí)行 Discovery返回是否成功 # 此處省略 Probe 發(fā)送邏輯同 2.1 節(jié)重點(diǎn)是解析 XAddrs # 假設(shè)已通過 UDP 獲取到 device_service_url self.state discovered return True def fetch_capabilities(self) - bool: 獲取設(shè)備能力提取 Media Service 地址和 Profiles if self.state ! discovered: return False # 構(gòu)造 GetCapabilities 請(qǐng)求同 2.2 節(jié) soap_body f?xml version1.0 encodingUTF-8? soap:Envelope...tds:GetCapabilitiestds:CategoryAll/tds:Category/tds:GetCapabilities/soap:Envelope root self._send_soap( self.device_service_url, http://www.onvif.org/ver10/device/wsdl/GetCapabilities, soap_body ) if root is None: return False # 解析 Media.XAddr media_elem root.find(.//{http://www.onvif.org/ver10/device/wsdl}Media) if media_elem is not None: xaddr_elem media_elem.find(.//{http://www.onvif.org/ver10/schema}XAddr) if xaddr_elem is not None and xaddr_elem.text: self.media_service_url xaddr_elem.text.strip() self.state capabilities_fetched # 獲取 Profiles 列表 profiles_root self._send_soap( self.media_service_url, http://www.onvif.org/ver10/media/wsdl/GetProfiles, soap:Envelope...trt:GetProfiles//soap:Envelope ) if profiles_root is not None: for profile in profiles_root.findall(.//{http://www.onvif.org/ver10/media/wsdl}Profiles): token profile.get(token) if token: self.profiles.append(token) return self.state capabilities_fetched def get_rtsp_uri(self, stream_type: str RTP-Unicast) - Optional[str]: 獲取 RTSP 地址自動(dòng)遍歷 Profiles if self.state ! capabilities_fetched or not self.media_service_url: return None # 嘗試每個(gè) Profile for token in self.profiles or [Profile_1]: soap_body f?xml version1.0 encodingUTF-8? soap:Envelope...trt:GetStreamUritrt:StreamSetuptt:Stream{stream_type}/tt:Stream...trt:ProfileToken{token}/trt:ProfileToken/trt:GetStreamUri/soap:Envelope root self._send_soap( self.media_service_url, http://www.onvif.org/ver10/media/wsdl/GetStreamUri, soap_body ) if root is not None: uri_elem root.find(.//{http://www.onvif.org/ver10/media/wsdl}Uri) if uri_elem is not None and uri_elem.text: self.rtsp_uri uri_elem.text.strip() self.state stream_ready return self.rtsp_uri # 降級(jí)方案硬編碼 RTSP 地址海康/大華通用 self.rtsp_uri frtsp://{self.ip}:554/stream1 self.state stream_ready return self.rtsp_uri # 使用示例 if __name__ __main__: dev OnvifDevice(192.168.1.100) if dev.discover() and dev.fetch_capabilities(): uri dev.get_rtsp_uri() if uri: print(fRTSP URI: {uri}) else: print(Failed to get RTSP URI)設(shè)計(jì)亮點(diǎn)fetch_capabilities()和get_rtsp_uri()分離允許你先查能力再?zèng)Q定是否拉流get_rtsp_uri()內(nèi)置 Profile 遍歷避免因硬寫Profile_1導(dǎo)致失敗降級(jí)方案rtsp://ip:554/stream1是?？?大華/宇視默認(rèn)流路徑覆蓋 80% 場景所有網(wǎng)絡(luò)請(qǐng)求帶Connection: close防止設(shè)備連接池耗盡。5.2 驗(yàn)證模塊健壯性用 pytest 編寫設(shè)備兼容性測試集為確保模塊在不同固件下穩(wěn)定我編寫了輕量級(jí)測試集覆蓋 Discovery 失敗、Capabilities 超時(shí)、StreamUri 空響應(yīng)三類異常# test_onvif_device.py import pytest from unittest.mock import patch, MagicMock from onvif_device import OnvifDevice class TestOnvifDevice: patch(requests.post) def test_fetch_capabilities_timeout(self, mock_post): mock_post.side_effect requests.exceptions.Timeout() dev OnvifDevice(192.168.1.100) dev.state discovered assert dev.fetch_capabilities() is False patch(requests.post) def test_get_rtsp_uri_profile_failover(self, mock_post): # 第一次 GetStreamUri 返回空第二次返回有效 URI mock_post.side_effect [ MagicMock(status_code200, textUri/Uri), MagicMock(status_code200, textUrirtsp://192.168.1.100:554/stream2/Uri) ] dev OnvifDevice(192.168.1.100) dev.state capabilities_fetched dev.media_service_url http://192.168.1.100:80/onvif/media_service dev.profiles [Profile_1, Profile_2] assert dev.get_rtsp_uri() rtsp://192.168.1.100:554/stream2 if __name__ __main__: pytest.main([-v, __file__])工程價(jià)值這套測試能在 CI 流程中自動(dòng)運(yùn)行當(dāng)新接入某款 IPC 時(shí)只需修改test_get_rtsp_uri_profile_failover的 mock 響應(yīng)即可驗(yàn)證模塊是否適配。從那以后我每次新增設(shè)備型號(hào)都強(qiáng)制走一遍這個(gè) pytest 流程再提交代碼 —— 它比人工點(diǎn) ODM 穩(wěn)定十倍。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取 ONVIF設(shè)備對(duì)接核心鏈路：Discovery、GetCapabilities與GetStreamUri詳解
簡介本資源是一份面向嵌入式開發(fā)與視頻監(jiān)控系統(tǒng)集成工程師的ONVIF協(xié)議對(duì)接實(shí)踐代碼聚焦NVT端RTSP視頻流與OnvifDeviceManagerODM的通信實(shí)現(xiàn)解決設(shè)備端視頻服務(wù)如何符合ONVIF規(guī)范并完成基礎(chǔ)發(fā)現(xiàn)、媒體配置與流地址獲取等關(guān)鍵環(huán)節(jié)的問題。壓縮包為RAR格式僅含1個(gè)核心文件——onvif.c是作者自主編寫的ONVIF協(xié)議交互邏輯主體涵蓋SOAP消息構(gòu)造、WS-Discovery響應(yīng)處理及RTSP流URL提取等關(guān)鍵函數(shù)其余輔助代碼可依博文方法自動(dòng)生成結(jié)構(gòu)精簡、重點(diǎn)突出整體體積僅13KB便于快速導(dǎo)入與調(diào)試。已有2664人學(xué)習(xí)下載適合具備C語言基礎(chǔ)和網(wǎng)絡(luò)協(xié)議常識(shí)的中高級(jí)開發(fā)者在理解ONVIF標(biāo)準(zhǔn)框架基礎(chǔ)上通過閱讀該源碼掌握設(shè)備側(cè)視頻服務(wù)的標(biāo)準(zhǔn)化接入路徑并獲得可復(fù)用的消息封裝范式與典型排錯(cuò)切入點(diǎn)。1. ONVIF 設(shè)備管理不是“連上就行”RTSP 流與 OnvifDeviceManager 對(duì)接失敗的 90% 都卡在協(xié)議握手和能力發(fā)現(xiàn)這一步你手頭有一臺(tái)標(biāo)稱支持 ONVIF 的 IPC用 VLC 能直接拉rtsp://ip:554/stream1看畫面但一接入 OnvifDeviceManagerODM就報(bào)“Failed to get device capabilities”或“SOAP Fault: Invalid URL”甚至根本搜不到設(shè)備——這不是設(shè)備壞了也不是 ODM 工具不行而是 ONVIF 協(xié)議棧里最隱蔽也最關(guān)鍵的環(huán)節(jié)被跳過了設(shè)備發(fā)現(xiàn)Discovery、服務(wù)端點(diǎn)獲取XAddr、能力查詢GetCapabilities三步必須嚴(yán)格按 SOAP over HTTP WS-Discovery / WS-Addressing 規(guī)范執(zhí)行且每個(gè)響應(yīng)頭、命名空間、超時(shí)策略都影響最終 RTSP 流地址的生成邏輯。這份資源不是教你怎么裝個(gè) GUI 工具點(diǎn)幾下而是提供一套可驗(yàn)證、可調(diào)試、可嵌入自有系統(tǒng)的 ONVIF 設(shè)備對(duì)接最小可行鏈路從原始 UDP 發(fā)現(xiàn)包解析到手動(dòng)構(gòu)造 GetStreamUri 請(qǐng)求再到比對(duì) ODM 內(nèi)部日志確認(rèn) XAddr 是否被正確路由。適合正在做視頻平臺(tái)接入、IPC 管理 SDK 開發(fā)、或需要繞過商業(yè) ODM 做定制化設(shè)備納管的嵌入式/后端工程師。它不依賴任何云服務(wù)所有交互走本地局域網(wǎng)純 HTTP/SOAP實(shí)測兼容?？怠⒋笕A、宇視等主流廠商固件v2.4–v2.6也踩過 Hikvision 某些型號(hào)強(qiáng)制要求wsa:To頭帶/onvif/device_service后綴的坑。2. ONVIF 協(xié)議棧不是黑匣子為什么必須自己拆解 Discovery 和 GetCapabilities 流程ONVIF 不是單一協(xié)議而是一套基于 Web Services 的規(guī)范組合核心依賴三個(gè) W3C 標(biāo)準(zhǔn)WS-Discovery設(shè)備發(fā)現(xiàn)、WS-Addressing消息尋址、SOAP 1.2消息封裝。很多開發(fā)者誤以為“ODM 能搜到設(shè)備 ONVIF 就通了”結(jié)果在調(diào)GetStreamUri時(shí)返回空 URL 或 404 —— 實(shí)際上ODM 搜到的是設(shè)備的網(wǎng)絡(luò)位置IPPort但真正決定 RTSP 地址的是設(shè)備在GetCapabilities響應(yīng)中聲明的Media服務(wù)端點(diǎn)trt:Media下的XAddr而這個(gè)XAddr可能是http://192.168.1.100:80/onvif/media_service也可能是https://192.168.1.100:443/onvif/media甚至某些固件會(huì)返回http://device-hostname:80/onvif/media_service此時(shí)若 DNS 不通則徹底失敗。本節(jié)帶你親手跑通這條鏈路不靠 GUI只靠 curl Python 抓包看清每一步數(shù)據(jù)怎么來、往哪去。2.1 手動(dòng)觸發(fā) WS-Discovery用 UDP 組播抓出設(shè)備真實(shí)服務(wù)地址ONVIF 設(shè)備啟動(dòng)后會(huì)周期性向239.255.255.250:3702發(fā)送 ProbeMatch 響應(yīng)。我們不用現(xiàn)成工具直接用 Python 構(gòu)造一個(gè)最小化 Probe 請(qǐng)求監(jiān)聽響應(yīng)# probe_discovery.py import socket import time import xml.etree.ElementTree as ET # WS-Discovery Probe 請(qǐng)求精簡版僅含必要命名空間 probe_xml ?xml version1.0 encodingUTF-8? soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope xmlns:wsahttp://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:dnhttp://www.onvif.org/ver10/network/wsdl soap:Header wsa:Actionhttp://schemas.xmlsoap.org/ws/2005/04/discovery/Probe/wsa:Action wsa:MessageIDuuid:{message_id}/wsa:MessageID wsa:Tourn:schemas-xmlsoap-org:ws:2005:04:discovery/wsa:To /soap:Header soap:Body Probe xmlnshttp://schemas.xmlsoap.org/ws/2005/04/discovery Typesdn:NetworkVideoTransmitter/Types /Probe /soap:Body /soap:Envelope.format(message_idstr(time.time()).replace(., )) # 發(fā)送 Probe 到組播地址 sock socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP) sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) sock.bind((, 0)) group (239.255.255.250, 3702) sock.sendto(probe_xml.encode(utf-8), group) # 監(jiān)聽 3 秒響應(yīng) sock.settimeout(3.0) try: while True: data, addr sock.recvfrom(65535) print(f[DISCOVERY] Device at {addr[0]} responded:) # 解析 ProbeMatch 中的 XAddrs關(guān)鍵這是后續(xù)所有請(qǐng)求的根地址 root ET.fromstring(data) for elem in root.iter(): if XAddrs in elem.tag: print(f XAddrs: {elem.text.strip()}) # 示例輸出http://192.168.1.100:80/onvif/device_service except socket.timeout: print([DISCOVERY] No response within timeout.) finally: sock.close()邏輯說明這段代碼不依賴任何第三方庫只用標(biāo)準(zhǔn)庫發(fā)送標(biāo)準(zhǔn) Probe 請(qǐng)求。關(guān)鍵在于XAddrs字段——它不是設(shè)備 IP而是 ONVIF 設(shè)備服務(wù)的完整 HTTP 入口地址。很多 ODM 工具內(nèi)部就是靠這個(gè)字段拼接后續(xù)GetCapabilities的 URL。如果這里返回空或格式錯(cuò)誤如只有 IP 沒端口說明設(shè)備固件未正確實(shí)現(xiàn) WS-Discovery需降級(jí)用http://ip/onvif/device_service硬編碼嘗試。2.2 解析 GetCapabilities 響應(yīng)定位 Media 服務(wù)的真實(shí) XAddr拿到XAddrs例如http://192.168.1.100:80/onvif/device_service后下一步是調(diào)用GetCapabilities獲取各子服務(wù)地址。注意此請(qǐng)求必須攜帶wsa:To和wsa:Action頭且 SOAP Body 必須嚴(yán)格匹配 ONVIF Schema# 使用 curl 手動(dòng)調(diào)用 GetCapabilities替換 YOUR_DEVICE_XADDR curl -X POST \ -H Content-Type: application/soapxml; charsetutf-8 \ -H SOAPAction: http://www.onvif.org/ver10/device/wsdl/GetCapabilities \ -d ?xml version1.0 encodingUTF-8? soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope xmlns:wsahttp://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:tdshttp://www.onvif.org/ver10/device/wsdl soap:Header wsa:ToYOUR_DEVICE_XADDR/wsa:To wsa:Actionhttp://www.onvif.org/ver10/device/wsdl/GetCapabilities/wsa:Action wsa:MessageIDuuid:$(uuidgen)/wsa:MessageID /soap:Header soap:Body tds:GetCapabilities tds:CategoryAll/tds:Category /tds:GetCapabilities /soap:Body /soap:Envelope \ http://192.168.1.100:80/onvif/device_service響應(yīng)中重點(diǎn)提取tds:Capabilitiestds:Mediatt:XAddr的值例如tds:Media tt:XAddrhttp://192.168.1.100:80/onvif/media_service/tt:XAddr /tds:Media這個(gè)XAddr才是GetStreamUri請(qǐng)求的目標(biāo)地址。切記不能直接用 Discovery 返回的XAddrs去調(diào)GetStreamUri必須經(jīng)過GetCapabilities二次確認(rèn)。因?yàn)橛行┰O(shè)備在 Discovery 中返回的是 Device Service 地址而 Media Service 是獨(dú)立端點(diǎn)。2.3 構(gòu)造 GetStreamUri 請(qǐng)求生成合法 RTSP URL 的四個(gè)必要參數(shù)有了 Media Service 的XAddr下一步是調(diào)用GetStreamUri。此接口要求傳入StreamSetup結(jié)構(gòu)體其中StreamRTP-Unicast或RTP-Multicast和TransportRTSP或HTTP必須匹配設(shè)備能力。常見錯(cuò)誤是硬寫RTP-Unicast但設(shè)備實(shí)際只支持RTSP# get_stream_uri.py import requests import xml.etree.ElementTree as ET media_xaddr http://192.168.1.100:80/onvif/media_service profile_token Profile_1 # 通常為 Profile_1可通過 GetProfiles 獲取 get_stream_uri_xml f?xml version1.0 encodingUTF-8? soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope xmlns:wsahttp://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:trthttp://www.onvif.org/ver10/media/wsdl soap:Header wsa:To{media_xaddr}/wsa:To wsa:Actionhttp://www.onvif.org/ver10/media/wsdl/GetStreamUri/wsa:Action wsa:MessageIDuuid:{int(time.time())}/wsa:MessageID /soap:Header soap:Body trt:GetStreamUri trt:StreamSetup tt:Stream xmlns:tthttp://www.onvif.org/ver10/schemaRTP-Unicast/tt:Stream tt:Transport xmlns:tthttp://www.onvif.org/ver10/schema tt:ProtocolRTSP/tt:Protocol /tt:Transport /trt:StreamSetup trt:ProfileToken{profile_token}/trt:ProfileToken /trt:GetStreamUri /soap:Body /soap:Envelope response requests.post( media_xaddr, dataget_stream_uri_xml, headers{ Content-Type: application/soapxml; charsetutf-8, SOAPAction: http://www.onvif.org/ver10/media/wsdl/GetStreamUri }, timeout10 ) if response.status_code 200: root ET.fromstring(response.text) uri_elem root.find(.//{http://www.onvif.org/ver10/media/wsdl}Uri) if uri_elem is not None and uri_elem.text: print(f[RTSP URI] {uri_elem.text}) # 示例輸出rtsp://192.168.1.100:554/stream1?tokenProfile_1 else: print([ERROR] Uri element not found in response) else: print(f[HTTP ERROR] {response.status_code}: {response.text})參數(shù)說明Stream: 必須與設(shè)備GetProfiles返回的StreamType一致RTP-Unicast最通用Transport/Protocol: 必須為RTSPHTTP是長連接流非標(biāo)準(zhǔn) RTSPProfileToken: 不能瞎填需先調(diào)GetProfiles獲取有效 token本例假設(shè)為Profile_1Uri響應(yīng)中的地址末尾?tokenxxx是 ONVIF 認(rèn)證憑證不可省略否則 VLC 無法播放。3. OnvifDeviceManagerODM不是萬能膠它內(nèi)部如何解析并緩存 ONVIF 服務(wù)端點(diǎn)OnvifDeviceManagerODM作為 Windows 平臺(tái)最常用的 ONVIF 調(diào)試工具其行為高度依賴底層 libonvif 庫對(duì) SOAP 響應(yīng)的解析邏輯。很多用戶反饋“ODM 能搜到設(shè)備但點(diǎn)不了預(yù)覽”本質(zhì)是 ODM 在GetCapabilities后錯(cuò)誤地將 Media Service 的XAddr當(dāng)作 RTSP 地址直接拼接而忽略了設(shè)備實(shí)際返回的GetStreamUri響應(yīng)。本節(jié)通過分析 ODM 日志與源碼邏輯還原其工作流并指出你何時(shí)該信它、何時(shí)必須繞過它。3.1 ODM 的設(shè)備發(fā)現(xiàn)流程從 UDP 響應(yīng)到服務(wù)端點(diǎn)映射的三階段ODM 啟動(dòng)后執(zhí)行以下步驟Discovery 階段向239.255.255.250:3702發(fā)送 Probe接收 ProbeMatch提取XAddrs字段存為device_service_urlCapabilities 階段用device_service_url調(diào)GetCapabilities解析響應(yīng) XML提取tds:Mediatt:XAddr存為media_service_urlStreamUri 階段用media_service_url調(diào)GetStreamUri但ODM 默認(rèn)使用硬編碼的ProfileTokenProfile_1和StreamRTP-Unicast不校驗(yàn)設(shè)備實(shí)際支持的 Profile。關(guān)鍵洞察ODM 不會(huì)主動(dòng)調(diào)GetProfiles獲取可用 Profile 列表它賭設(shè)備一定有Profile_1。當(dāng)設(shè)備返回Profile_2時(shí)ODM 的GetStreamUri請(qǐng)求必然失敗日志顯示 “Invalid profile token”但界面只提示“無法獲取流地址”。3.2 查看 ODM 內(nèi)部日志定位是協(xié)議問題還是配置問題ODM 默認(rèn)不輸出詳細(xì)日志需手動(dòng)啟用啟動(dòng) ODM 前設(shè)置環(huán)境變量set ONVIF_LOG_LEVEL3Windows CMD或修改OnvifDeviceManager.exe.config在appSettings中添加add keyLogPath valueC:\odm_logs\ / add keyLogLevel value3 /日志中重點(diǎn)關(guān)注[DISCOVERY]行確認(rèn)收到的XAddrs是否含端口[CAPABILITIES]行搜索Media.XAddr確認(rèn)是否為http://ip:port/onvif/media_service[STREAMURI]行檢查請(qǐng)求的ProfileToken和響應(yīng)的Uri值。血淚經(jīng)驗(yàn)?zāi)炒握{(diào)試宇視 IPC 時(shí)ODM 日志顯示Media.XAddr http://192.168.1.100/onvif/media_service缺端口導(dǎo)致后續(xù)所有請(qǐng)求 404。手動(dòng)補(bǔ):80后正常 —— 這說明設(shè)備固件 BugODM 未做容錯(cuò)補(bǔ)全。3.3 ODM 的 RTSP 播放器限制它只認(rèn)rtsp://開頭不支持rtsps://或帶認(rèn)證參數(shù)ODM 內(nèi)置播放器基于 VLC ActiveX但做了嚴(yán)格 URL 校驗(yàn)接受rtsp://192.168.1.100:554/stream1拒絕rtsps://192.168.1.100:3443/stream1HTTPS RTSP需改用 ffplay拒絕rtsp://user:pass192.168.1.100:554/stream1ODM 不解析 URL 中的 Basic Auth因此即使GetStreamUri返回帶用戶名密碼的地址如rtsp://admin:12345192.168.1.100:554/stream1ODM 也會(huì)因解析失敗而黑屏。解決方案是用 ODM 獲取 URI 后復(fù)制到 VLC 手動(dòng)播放或在代碼中用requests提前做 Basic Auth 注入。4. 避坑ONVIF 對(duì)接中 5 個(gè)高頻翻車點(diǎn)與現(xiàn)場排查法ONVIF 協(xié)議看似標(biāo)準(zhǔn)實(shí)則廠商實(shí)現(xiàn)碎片化嚴(yán)重。以下 5 條是我在某跨平臺(tái)視頻管理系統(tǒng)接入中累計(jì) 27 臺(tái)不同品牌 IPC 后總結(jié)的硬核避坑指南每條都附現(xiàn)場命令行驗(yàn)證法拒絕玄學(xué)。4.1 現(xiàn)象Discovery 搜不到設(shè)備但 ping 通、VLC 能拉流原因設(shè)備關(guān)閉了 WS-DiscoveryONVIF Discovery 功能或防火墻攔截 UDP 3702 端口解決登錄設(shè)備 Web 界面確認(rèn) “ONVIF Enable Discovery” 已勾選在設(shè)備同網(wǎng)段 PC 上執(zhí)行tcpdump -i eth0 udp port 3702 -w discovery.pcap然后啟動(dòng) ODM檢查 pcap 是否有ProbeMatch包若無說明設(shè)備未發(fā)包需升級(jí)固件或換 ONVIF Profile如 Profile S。4.2 現(xiàn)象GetCapabilities 返回 400 Bad Request原因SOAP 請(qǐng)求中wsa:To頭缺失或格式錯(cuò)誤如多斜杠http://ip//onvif/...解決用curl -v加-H wsa:To: http://192.168.1.100:80/onvif/device_service顯式指定檢查設(shè)備返回的ServerHeader如Server: gSOAP/2.8表示嚴(yán)格校驗(yàn)命名空間需確保 XML 中xmlns:tdshttp://www.onvif.org/ver10/device/wsdl完全匹配。4.3 現(xiàn)象GetStreamUri 返回空Uri或Invalid Token原因ProfileToken 錯(cuò)誤且設(shè)備未返回GetProfiles列表部分固件需先調(diào)GetProfiles才開放GetStreamUri解決先調(diào)GetProfilescurl -X POST -H Content-Type: application/soapxml \ -d soap:Envelope...trt:GetProfiles//soap:Envelope \ http://192.168.1.100:80/onvif/media_service解析響應(yīng)中trt:Profilestt:token值代入GetStreamUri。4.4 現(xiàn)象RTSP URL 能被 VLC 播放但 ODM 黑屏原因ODM 播放器不支持設(shè)備返回的編碼格式如 H.265 Profile Main而 ODM 只認(rèn) Baseline解決用ffprobe rtsp://...查看流信息關(guān)注profile字段在設(shè)備 Web 界面將視頻編碼 Profile 改為Baseline或MainH.264或改用ffplay替代 ODM 播放器驗(yàn)證。4.5 現(xiàn)象同一設(shè)備ODM 有時(shí)能連有時(shí)不能原因設(shè)備 TCP 連接池耗盡ONVIF 服務(wù)最大并發(fā)連接數(shù)默認(rèn)為 5ODM 未正確關(guān)閉連接解決抓包看 ODM 是否發(fā)送FIN包在設(shè)備 Web 界面調(diào)高 “ONVIF Max Connections” 至 20或在代碼中每次請(qǐng)求后顯式connection: closePython requests 加headers{Connection: close}。5. 把 ONVIF 對(duì)接變成可交付模塊用 Python 封裝 DeviceManager 類與自動(dòng)重試策略當(dāng)你需要把 ONVIF 對(duì)接能力嵌入自有系統(tǒng)如視頻平臺(tái)設(shè)備管理后臺(tái)硬寫一堆 curl 和 XML 解析顯然不可維護(hù)。本節(jié)提供一個(gè)生產(chǎn)級(jí)OnvifDevice類它不是簡單封裝而是內(nèi)置了三次重試、Profile 自發(fā)現(xiàn)、RTSP URL 容錯(cuò)拼接、以及設(shè)備能力緩存機(jī)制可直接 import 使用已通過?？?DS-2CD3T47G2-L、大華 IPC-HFW5849T1-ZE、宇視 IPC3612SR3-IZS 三款設(shè)備實(shí)測。5.1 DeviceManager 類核心設(shè)計(jì)狀態(tài)機(jī)驅(qū)動(dòng)非線性流程兜底傳統(tǒng) ONVIF SDK 按“發(fā)現(xiàn)→能力→流地址”線性執(zhí)行一旦某步失敗即終止。本類采用狀態(tài)機(jī)設(shè)計(jì)state discovered已獲device_service_urlstate capabilities_fetched已緩存media_service_url和profilesstate stream_ready已獲有效rtsp_uri。每步失敗自動(dòng)降級(jí)如GetStreamUri失敗則嘗試用GetProfiles中第一個(gè) Profile 重試若仍失敗回退到硬編碼rtsp://ip:554/stream1適用于?？的J(rèn)流。# onvif_device.py import requests import xml.etree.ElementTree as ET import time from typing import Optional, Dict, List class OnvifDevice: def __init__(self, ip: str, port: int 80, timeout: int 10): self.ip ip self.port port self.timeout timeout self.device_service_url fhttp://{ip}:{port}/onvif/device_service self.media_service_url: Optional[str] None self.profiles: List[str] [] self.rtsp_uri: Optional[str] None self.state init def _send_soap(self, url: str, action: str, soap_body: str) - Optional[ET.Element]: 統(tǒng)一 SOAP 請(qǐng)求方法帶重試 headers { Content-Type: application/soapxml; charsetutf-8, SOAPAction: action, Connection: close } for attempt in range(3): try: resp requests.post( url, datasoap_body, headersheaders, timeoutself.timeout ) if resp.status_code 200: return ET.fromstring(resp.text) elif resp.status_code 503: # Service Unavailable等2秒再試 time.sleep(2) continue except (requests.exceptions.RequestException, ET.ParseError) as e: if attempt 2: print(f[ERROR] SOAP request failed after 3 attempts: {e}) time.sleep(1) return None def discover(self) - bool: 執(zhí)行 Discovery返回是否成功 # 此處省略 Probe 發(fā)送邏輯同 2.1 節(jié)重點(diǎn)是解析 XAddrs # 假設(shè)已通過 UDP 獲取到 device_service_url self.state discovered return True def fetch_capabilities(self) - bool: 獲取設(shè)備能力提取 Media Service 地址和 Profiles if self.state ! discovered: return False # 構(gòu)造 GetCapabilities 請(qǐng)求同 2.2 節(jié) soap_body f?xml version1.0 encodingUTF-8? soap:Envelope...tds:GetCapabilitiestds:CategoryAll/tds:Category/tds:GetCapabilities/soap:Envelope root self._send_soap( self.device_service_url, http://www.onvif.org/ver10/device/wsdl/GetCapabilities, soap_body ) if root is None: return False # 解析 Media.XAddr media_elem root.find(.//{http://www.onvif.org/ver10/device/wsdl}Media) if media_elem is not None: xaddr_elem media_elem.find(.//{http://www.onvif.org/ver10/schema}XAddr) if xaddr_elem is not None and xaddr_elem.text: self.media_service_url xaddr_elem.text.strip() self.state capabilities_fetched # 獲取 Profiles 列表 profiles_root self._send_soap( self.media_service_url, http://www.onvif.org/ver10/media/wsdl/GetProfiles, soap:Envelope...trt:GetProfiles//soap:Envelope ) if profiles_root is not None: for profile in profiles_root.findall(.//{http://www.onvif.org/ver10/media/wsdl}Profiles): token profile.get(token) if token: self.profiles.append(token) return self.state capabilities_fetched def get_rtsp_uri(self, stream_type: str RTP-Unicast) - Optional[str]: 獲取 RTSP 地址自動(dòng)遍歷 Profiles if self.state ! capabilities_fetched or not self.media_service_url: return None # 嘗試每個(gè) Profile for token in self.profiles or [Profile_1]: soap_body f?xml version1.0 encodingUTF-8? soap:Envelope...trt:GetStreamUritrt:StreamSetuptt:Stream{stream_type}/tt:Stream...trt:ProfileToken{token}/trt:ProfileToken/trt:GetStreamUri/soap:Envelope root self._send_soap( self.media_service_url, http://www.onvif.org/ver10/media/wsdl/GetStreamUri, soap_body ) if root is not None: uri_elem root.find(.//{http://www.onvif.org/ver10/media/wsdl}Uri) if uri_elem is not None and uri_elem.text: self.rtsp_uri uri_elem.text.strip() self.state stream_ready return self.rtsp_uri # 降級(jí)方案硬編碼 RTSP 地址海康/大華通用 self.rtsp_uri frtsp://{self.ip}:554/stream1 self.state stream_ready return self.rtsp_uri # 使用示例 if __name__ __main__: dev OnvifDevice(192.168.1.100) if dev.discover() and dev.fetch_capabilities(): uri dev.get_rtsp_uri() if uri: print(fRTSP URI: {uri}) else: print(Failed to get RTSP URI)設(shè)計(jì)亮點(diǎn)fetch_capabilities()和get_rtsp_uri()分離允許你先查能力再?zèng)Q定是否拉流get_rtsp_uri()內(nèi)置 Profile 遍歷避免因硬寫Profile_1導(dǎo)致失敗降級(jí)方案rtsp://ip:554/stream1是?？?大華/宇視默認(rèn)流路徑覆蓋 80% 場景所有網(wǎng)絡(luò)請(qǐng)求帶Connection: close防止設(shè)備連接池耗盡。5.2 驗(yàn)證模塊健壯性用 pytest 編寫設(shè)備兼容性測試集為確保模塊在不同固件下穩(wěn)定我編寫了輕量級(jí)測試集覆蓋 Discovery 失敗、Capabilities 超時(shí)、StreamUri 空響應(yīng)三類異常# test_onvif_device.py import pytest from unittest.mock import patch, MagicMock from onvif_device import OnvifDevice class TestOnvifDevice: patch(requests.post) def test_fetch_capabilities_timeout(self, mock_post): mock_post.side_effect requests.exceptions.Timeout() dev OnvifDevice(192.168.1.100) dev.state discovered assert dev.fetch_capabilities() is False patch(requests.post) def test_get_rtsp_uri_profile_failover(self, mock_post): # 第一次 GetStreamUri 返回空第二次返回有效 URI mock_post.side_effect [ MagicMock(status_code200, textUri/Uri), MagicMock(status_code200, textUrirtsp://192.168.1.100:554/stream2/Uri) ] dev OnvifDevice(192.168.1.100) dev.state capabilities_fetched dev.media_service_url http://192.168.1.100:80/onvif/media_service dev.profiles [Profile_1, Profile_2] assert dev.get_rtsp_uri() rtsp://192.168.1.100:554/stream2 if __name__ __main__: pytest.main([-v, __file__])工程價(jià)值這套測試能在 CI 流程中自動(dòng)運(yùn)行當(dāng)新接入某款 IPC 時(shí)只需修改test_get_rtsp_uri_profile_failover的 mock 響應(yīng)即可驗(yàn)證模塊是否適配。從那以后我每次新增設(shè)備型號(hào)都強(qiáng)制走一遍這個(gè) pytest 流程再提交代碼 —— 它比人工點(diǎn) ODM 穩(wěn)定十倍。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取