上周三凌晨两点我盯着日志里那个反复出现的登录失败返回值终于承认自己在这件事上想得太简单了——对接海康威视接口这件事网上的帖子看起来都是三行代码登录、五行代码取流真做起来卡住你的从来不是那几个 API而是端口、字符集、通道号、句柄回收这些看起来跟接口无关的东西。这篇记录的是我把一套海康威视设备接入系统从能跑通做到能上线中间改过的四五个版本、抓过的几十次包、以及最后留下来的那套稳定方案。如果你正准备做海康威视摄像头、NVR、门禁或者视觉控制器的接口对接不管你是 Java、C 还是 Python 技术栈这篇里的选型逻辑、参数含义和排查链路应该都能直接用。1. 先想清楚要对接的是海康的哪一层接口我见过太多项目一开始就选错层。海康的对外能力其实是分层暴露的SDK、ISAPI、RTSP、主动注册这几条路各自解决不同问题选错了后面全是补丁。所以第一步不是写代码是把需求拆成我要控制设备我要拿视频流我要拿结构化数据三件事再分别对应方案。1.1 SDK、ISAPI、RTSP、主动注册四条路的边界设备网络 SDKHCNetSDK是能力最全的那条路登录、预览、回放、云台、布防、参数下发、语音对讲几乎设备的所有功能都能通过它拿到。代价是你要处理它的一套结构体、回调、句柄生命周期还得把动态库跟着程序一起分发跨平台时尤其烦。我这次的核心链路——登录、实时取流、定时回放下载——全是走 SDK。ISAPI是建立在 HTTP 之上的 REST 风格接口返回 XML 或 JSON。它特别适合做配置查询、设备信息读取、抓图、校时、录像检索这类一次请求一次响应的动作。写起来比 SDK 舒服太多用 curl 就能验证不需要加载任何动态库。但它的短板也很明显实时流、批量事件这类长连接场景不是它的主场。RTSP是最省事的取流方式一行地址就能丢给播放器或者 ffmpeg。适合我只要画面不需要控制设备的场景。需要注意的是海康的 RTSP 走的是标准协议但地址里的通道号编法跟 SDK 里的通道号不是一回事这个后面单独说。主动注册设备主动连平台适用于设备在 NAT 后面、平台拿不到设备 IP 的情况。设备侧配置好平台地址后反向建连平台不用去拨号。这条路的配置成本比前三条高涉及平台侧的服务搭建但一旦设备网络环境复杂它是唯一干净的解法。我把这四条路的差别整理成一张表实际选型时对着看会快很多对接方式适合做什么主要代价是否需要分发动态库设备网络 SDK预览、回放、云台、布防、参数下发结构体与句柄管理复杂跨平台部署麻烦需要ISAPI设备信息、能力集、抓图、校时、录像检索长连接与实时流不擅长不需要RTSP纯取流播放、转推到流媒体服务无法控制设备地址编法易踩坑不需要主动注册设备在网络边界之后平台无法直连平台侧要搭注册服务配置链路长视平台实现1.2 我这次为什么最终选了 SDK 打底 ISAPI 补位需求清单是这样的实时预览 16 路、按时间段回放并下载录像片段、云台控制、设备状态巡检。其中下载录像片段和云台控制这两条RTSP 直接做不了ISAPI 能做但回放下载的接口相当绕SDK 有现成的NET_DVR_PlayBackByTime_V40和一套回调。所以 SDK 是底座。但 SDK 有几个动作我实在不想用它做查设备型号和固件版本、查设备支持哪些能力比如支不支持某个码流类型、校时。这几个用 ISAPI 一个 GET 请求就结束了而且返回的 XML 结构清晰比 SDK 里翻结构体字段再拼字符串可读性好太多。于是最终的架构是SDK 负责长连接和流相关的一切ISAPI 负责一次性的查询和配置类动作两者用同一份设备台账IP、端口、账号、通道列表驱动。提示不要因为SDK 能力全就什么都用 SDK 做。SDK 的很多查询接口返回值是 C 结构体字段含义强依赖头文件版本升级一次库就可能对不上。能用 HTTP 拿到的数据优先走 ISAPI。2. 环境准备里最容易被忽略的三件事我第一个版本在开发机上跑得飞快拷到客户的 Linux 服务器上直接报初始化失败。折腾了大半天才明白SDK 的部署有一堆隐式约定文档里写了但很容易被跳过。这一节讲的三件事每一件我都真实栽过。2.1 组件库目录与初始化参数必须显式指定设备网络 SDK 的目录结构里除了主库Windows 下是HCNetSDK.dllLinux 下是libhcnetsdk.so还有一个叫HCNetSDKCom的目录里面是一堆组件库负责音频、解码、转封装这些能力。主库和组件库必须在同一个相对位置缺一个就可能初始化成功但某个功能悄悄失效。我遇到过最隐蔽的一次是预览正常但回放下载出来的文件全是零字节查了半天是转封装组件没加载上。在 Windows 上SDK 会去程序运行目录找组件库一般不用管。Linux 下我建议显式指定别依赖默认搜索路径// C/C 下显式指定组件库路径 NET_DVR_SetSDKInitCfg(NET_SDK_INIT_CFG_SDK_PATH, (void*)/opt/app/hik/HCNetSDKCom); NET_DVR_SetSDKInitCfg(NET_SDK_INIT_CFG_LIBEAY_PATH, (void*)/opt/app/hik/libcrypto.so.1.1); NET_DVR_SetSDKInitCfg(NET_SDK_INIT_CFG_SSLEAY_PATH, (void*)/opt/app/hik/libssl.so.1.1);SetSDKInitCfg必须在NET_DVR_Init之前调用顺序反了不生效。Linux 上还有一个特别容易翻车的点主库依赖的libcrypto、libssl版本跟服务器系统自带的版本经常对不上。判断方法很简单ldd libhcnetsdk.so看有没有not found有的话要么补齐 SDK 目录里自带的版本要么用LD_LIBRARY_PATH把 SDK 目录放到系统路径前面。我一般会写一个启动脚本把这几件事一次性搞定避免每次部署都靠记忆。另外提醒一句32 位和 64 位的库绝对不能混用。Java 项目通过 JNA 加载时如果报找不到指定的模块或者加载后立刻崩八成是位数不匹配而不是路径写错了。用file libhcnetsdk.so确认一下位数再确认 JVM 是 64 位还是 32 位对上了再谈别的。2.2 字符集、时间与时区三个看起来无关却天天出事的地方字符集这一项我在 Linux 上踩的坑最多。设备返回的设备名、通道名大多是 GBK 编码而 Linux 默认 locale 往往是 UTF-8直接当字符串用就会看到一堆乱码最坑的是它不一定报错只是显示成问号或方块等你做数据入库的时候才发现全是脏数据。解决办法是拿到字节数组后显式做一次编码转换别指望 SDK 帮你转干净。// 拿到 SDK 返回的字节数组后按 GBK 解码再按业务需要转 UTF-8 String deviceName new String(rawBytes, GBK).trim();如果系统 locale 本身不是中文环境还会遇到另一个问题SDK 内部处理中文字符时依赖 locale 设置可能出现偶发的转换异常。稳妥做法是在程序启动最早期把 locale 设置好或者干脆全程用字节数组处理文本字段只在展示层做转换。时间这一项看着跟接口无关实际影响巨大。海康设备做录像检索、回放定位、事件时间戳对齐的时候用的都是设备本地时间。如果设备和服务器时间差了哪怕几十秒你按时间段查录像就可能查出空结果——因为你要的那一段在设备看来还不存在或者已经翻页了。我现在养成的习惯是设备接入时先做一次校时之后每隔一段时间做一次巡检校时。ISAPI 的校时接口很好用# 用 Digest 认证把设备时间设置为服务器时间 curl --digest -u admin:yourpassword \ -X PUT http://192.168.1.64/ISAPI/System/time \ -H Content-Type: application/xml \ -d TimetimeModemanual/timeModelocalTime2024-05-20T10:30:00/localTimetimeZoneCST-8:00:00/timeZone/Time时区字段一定要填对写成CST-8:00:00这种格式不要写08:00不然设备可能解析失败或者理解成正时区偏移的方向错误导致时间和预期差 16 个小时。这个格式我第一次写错的时候回放查询直接返回空列表排查了整整一个小时才定位到时区。2.3 端口清单与网络连通性预检海康设备的端口不止一个 8000。做完整对接至少要摸清这几个8000SDK 私有协议端口登录、预览、回放、布防都走它。有些项目会改成其他值接入前一定要从设备配置里确认不要默认就是 8000。554RTSP 端口取流用。可以被修改改过之后地址里要跟着改。80 / 443ISAPI 的 HTTP / HTTPS 端口。设备默认 HTTP 管理端口是 80但也可能被改成 8080 之类。其他业务端口如果走主动注册或国标协议还会涉及平台侧定义的端口。我现在的接入流程里第一步永远是网络预检而不是直接调登录接口。预检脚本做三件事ping 通不通、目标端口 telnet 通不通、HTTP 管理端口能不能返回一个应答。这三件事帮我省掉了无数次怀疑代码有问题结果发现是端口没开的时间浪费。预检项命令示例失败时优先怀疑网络可达ping 192.168.1.64网段、路由、设备是否激活私有协议端口telnet 192.168.1.64 8000端口被改、防火墙、端口未开放RTSP 端口telnet 192.168.1.64 554端口被改、服务未启用HTTP 管理端口curl -I http://192.168.1.64端口被改、只开了 HTTPS注意新出厂的设备有些处于未激活状态此时任何端口都不响应业务请求必须先通过激活流程设置密码。这个在预检阶段就能看出来——网络通但所有端口都不通基本可以往这个方向想。3. 设备登录这一段代码我改了四版才稳定登录是所有后续动作的入口但恰恰是这段看起来最简单的代码我改得最多。第一版只能登单台设备第二版加了异步第三版处理了通道号偏移第四版才把错误处理和状态保持做完整。3.1 NET_DVR_Login_V40 的结构体填充要点登录接口的核心是两个结构体入参的登录信息、出参的设备信息。入参里最容易出问题的是地址字段和端口字段的配合以及异步登录开关。用 Java 通过 JNA 映射时还有一个额外的坑结构体字段顺序和内存对齐必须跟头文件严格一致JNA 自动推导的对齐方式在部分结构体上和 C 编译器不一致会读到错位的数据。// 登录信息结构体字段顺序务必与官方头文件逐字段核对 Structure.FieldOrder({sDeviceAddress, byRes, wPort, sUserName, sPassword, byRes2, bUseAsynLogin, byRes3, byLoginMode, byRes4, byProxyType, byRes5}) public class NET_DVR_USER_LOGIN_INFO extends Structure { public byte[] sDeviceAddress new byte[129]; public byte byRes 0; public short wPort 8000; public byte[] sUserName new byte[64]; public byte[] sPassword new byte[64]; public byte byRes2 0; public byte bUseAsynLogin 0; // 0 同步1 异步 public byte byRes3 0; public byte byLoginMode 0; // 0 私有协议1 ISAPI 登录 public byte byRes4 0; public byte byProxyType 0; public byte byRes5 0; }这里有几个点值得单独说。sDeviceAddress是 129 字节因为要容纳域名如果你填的是 IP也照样要占满这个长度不能只 new 一个刚好够的长度。byLoginMode决定走私有协议还是 ISAPI 登录通道走 SDK 取流就填 0。bUseAsynLogin我建议在批量接入时打开否则 100 台设备串行同步登录光登录就能耗掉几十秒。另外一定要设置连接超时和重连参数不要用默认值// 等待超时 5 秒重试 3 次断线后每隔 10 秒尝试重连一次 sdk.NET_DVR_SetConnectTime(5000, 3); sdk.NET_DVR_SetReconnect(10000, true);这几个参数直接影响的是设备临时抖动时你会不会丢掉句柄。默认超时比较短局域网跨网段的时候经常误判为连接失败。3.2 通道号不是从 1 数起的byStartChan 与 byStartDChan这个坑我称之为海康对接新手必踩第一名。登录成功后拿到的设备信息结构体里有两个关键字段byStartChan和byStartDChan。前者是模拟通道的起始编号后者是数字通道也就是 IP 摄像机的起始编号。不同设备型号、不同接入方式下这两个起始值不一样常见的是 1但也可能是 33、或者别的值。如果你无脑从 1 开始循环调预览在 NVR 上可能一切正常换成另一种设备模型就全黑屏返回的却是通道号错误或干脆没报错但没数据。正确的做法是拿到设备信息后用起始编号加偏移量来算实际通道号。int startChan deviceInfo.struDeviceV30.byStartChan; // 模拟通道起始 int startDChan deviceInfo.struDeviceV30.byStartDChan; // 数字通道起始 // 第 n 路 IP 摄像机从 1 开始计数的实际通道号 int realChannel startDChan (n - 1);还有一个容易混淆的地方RTSP 地址里的通道号跟 SDK 里的通道号又是两套编法。RTSP 的地址是rtsp://用户:密码IP:554/Streaming/Channels/101其中的101第一位是通道号、后两位是码流号。所以通道 1 主码流是101通道 1 子码流是102通道 2 主码流是201。这套编法跟 SDK 的数字通道起始值完全无关写代码的时候千万别混用。3.3 异步登录与登录状态保持批量接入场景下我最后采用的是异步登录加状态机的方式。异步登录会立刻返回真正的登录结果在回调里给出。回调执行在 SDK 内部的线程上绝对不能在回调里做耗时操作否则会卡住 SDK 的其他回调表现为登录成功了但预览接口一直不返回。我的做法是回调里只做一件事把结果丢进队列然后立刻返回由业务线程去消费。登录状态保持这块别指望SetReconnect能搞定一切。它处理的是网络层重连但设备重启、账号被锁、会话超时这些情况需要业务层自己兜。我的做法是维护一个设备状态表每个设备记录登录句柄、最后心跳时间、连续失败次数。定时巡检时对异常设备做登出加重新登录连续失败超过阈值就拉黑并告警避免无意义的疯狂重试把设备账号锁死。提示设备账号有锁定机制短时间内多次密码错误会导致账号被临时锁定。调试阶段一定不要写失败就无限重试的循环我因为这个把测试设备的账号锁过一次等了很久才恢复。4. 实时预览取流从回调拿到裸数据之后怎么办预览接口本身不难难的是拿到流之后的处理。这一节讲讲预览参数到底影响什么以及回调里必须守住的几条规矩。4.1 NET_DVR_PREVIEWINFO 里那几个参数到底影响什么预览入参结构体里有几个字段是需要你主动做决策的字段含义我实际怎么选通道号要预览的通道用上一节算出来的实际通道号码流类型主码流 / 子码流 / 第三码流大屏轮播用子码流存证用主码流连接方式TCP / UDP / 多播 / RTP / RTP over RTSP内网优先 TCP跨网段看丢包情况播放窗口句柄绑定的窗口纯后端服务场景传空用回调取数据阻塞标志取流是否阻塞服务端取流转非阻塞码流类型这个选择特别值得说。主码流分辨率高、码率高16 路主码流同时拉服务器带宽和 CPU 都会抖。我的做法是前端轮播和 AI 分析用子码流只有需要留证的场景才拉主码流。子码流一般 720p 甚至更低但足够看清画面里发生了什么事。这样 16 路子码流的资源占用大概只相当于三四路主码流。连接方式上TCP 稳定但延迟略高UDP 延迟低但丢包时会有花屏。我的经验是内网、交换机质量可靠的环境下 UDP 完全够用跨机房或者有无线链路的场景老老实实上 TCP。另外有一个细节如果你选了 RTP over RTSP 模式SDK 会在本地起一个 RTSP 服务你可以直接用播放器打开本地的那个地址来看画面调试阶段这个技巧特别好用能快速判断是取流有问题还是我自己的解码有问题。4.2 回调线程里的三条铁律取流数据是通过回调函数给你的回调执行在 SDK 的线程里。这个线程只有一个所有设备的数据都从这里出来。我在回调上栽过两次总结出三条必须守住的规矩。第一条回调里不做任何阻塞操作。不写日志文件、不做网络请求、不加锁等待甚至不要在回调里直接做复杂的解码。我的做法是回调里只做内存拷贝把数据丢进一个环形缓冲队列立刻返回。消费端用独立线程池去处理。第二条不要假设回调数据的封装格式。SDK 取到的原始数据是私有封装格式不是裸的 H.264/H.265。你需要用解码库去解或者做转封装。我第一次拿到数据的时候直接按 H.264 起始码去解析结果一个 NAL 单元都找不到浪费了一个下午。后来改成用转封装把私有流转成标准 PS 流再交给 ffmpeg 处理问题就解决了。这里一定要预留数据缓冲因为一帧数据可能分多次回调到达需要自己按封装结构拼接完整。第三条句柄必须有且只有一个释放点。每个预览会返回一个句柄程序退出、通道切换、设备下线都必须释放。我遇到的跑两小时后必崩就是这个原因——异常分支里忘了释放句柄越积越多最后 SDK 内部资源耗尽。现在我的代码里所有句柄都用统一的资源管理器管理注册时登记、释放时注销退出时兜底扫一遍宁可重复释放SDK 会返回失败但不影响也不能漏。// 统一的句柄登记与释放避免异常分支漏释放 public class HandleRegistry { private final MapString, Integer handles new ConcurrentHashMap(); public void register(String key, int handle) { if (handle 0) throw new IllegalStateException(预览句柄无效); handles.put(key, handle); } public void releaseAll() { handles.forEach((key, handle) - { sdk.NET_DVR_StopRealPlay(handle); handles.remove(key); }); } }4.3 不想自己解 PS 流的话RTP over RTSP 是条捷径如果你只想把画面转出去不想啃封装格式有一个省事的方案用 SDK 的 RTP over RTSP 模式取流然后把 SDK 在本地暴露的那个 RTSP 地址交给 ffmpeg 或流媒体服务器去处理。这样解码、转封装、转协议这些活全都交给成熟的工具做你只负责维护 SDK 的连接和句柄。代价是多了一层本地回环转发延迟会有几十毫秒的增加而且本地的 RTSP 端口需要管理好别让多路预览撞端口。对绝大多数我要把海康画面推到网页上看的需求这个方案的性价比高得离谱——我第二个版本就是靠这个思路把开发时间从两周压到了三天。5. 用 ISAPI 补齐 SDK 不好做的事前面说过我把查询类和配置类的动作都交给了 ISAPI。这一节说说实际用起来需要注意什么。5.1 Digest 认证与那几个最常用的资源路径ISAPI 默认用 HTTP Digest 认证不是 Basic。这意味着你不能简单地在请求头里塞一个Authorization: Basic xxx需要先拿 401 响应里的随机数算出摘要再发第二次请求。用 curl 的话加一个--digest就自动搞定写代码的话就要自己实现摘要计算或者找一个支持 Digest 的 HTTP 客户端。常用的资源路径我列一下基本覆盖了八成使用场景GET /ISAPI/System/deviceInfo设备型号、序列号、固件版本GET /ISAPI/System/status设备当前状态GET /ISAPI/System/capabilities能力集判断设备支持什么GET /ISAPI/Streaming/channels所有视频通道列表GET /ISAPI/Streaming/channels/101/picture通道 1 抓图直接返回 JPEGPUT /ISAPI/System/time校时PUT /ISAPI/System/reboot重启设备GET /ISAPI/PTZCtrl/channels/1/continuous云台连续移动抓图接口特别实用。以前我要实现定时抓拍存档得用 SDK 取流再解码再抽帧一套流程下来代码量大还容易内存泄漏。换成 ISAPI 抓图之后一个 GET 请求拿到 JPEG 字节数组直接落盘代码从一百多行缩到十几行稳定性还更好。5.2 用 curl 先验证再写代码我现在的习惯是任何 ISAPI 动作先用 curl 在命令行验证通了再往代码里搬。这个习惯帮我排除了大量到底是接口问题还是我的代码问题的纠缠。# 查设备信息 curl --digest -u admin:yourpassword http://192.168.1.64/ISAPI/System/deviceInfo # 抓一张图存到本地 curl --digest -u admin:yourpassword \ http://192.168.1.64/ISAPI/Streaming/channels/101/picture \ -o snapshot.jpg命令行通了说明网络、认证、权限、路径全都对剩下的只是代码实现问题。命令行不通那问题就在环境层面别急着改代码。这个排查顺序看起来笨但真的很省时间。注意--digest一定要加上不加的话第一次请求会返回 401如果你把 401 当成路径不对去排查会绕很大一圈。看到 401 先想认证看到 403 再想权限。5.3 设备能力集查询别猜直接问设备不同型号、不同固件的海康设备支持的功能差异很大。你以为某个接口能调实际设备根本不支持返回一个不支持的错误。与其靠试错不如直接问设备支持什么。GET /ISAPI/System/capabilities会返回一份能力集清单包含设备支持的视频通道数、码流类型、智能分析能力、存储能力等。我现在在设备接入的第一时间就把能力集拉下来存进台账后续所有功能调用前先查台账不支持的直接跳过并记录。这样避免了很多无意义的失败请求和日志噪音。能力集的返回内容比较长用 XML 解析工具取你需要的那几个节点就行不用全量解析。我一般只关心三件事支持几路视频、支持哪些码流类型、有没有智能分析通道这三个决定了后续功能怎么开关。6. 我踩过的坑按排查链路完整还原这一节不讲结论讲过程。因为实际工作中比知道答案更重要的是知道怎么一步步找到答案。6.1 错误码 7连接失败背后有五种可能登录返回 7第一反应是网络不通但实际排查下来这个错误码对应的原因至少有五种。我的排查顺序是这样的第一步ping 设备 IP通不通。不通就是网络层问题检查网段、路由、设备是否在线。第二步telnet 私有协议端口通不通。网络通但端口不通检查端口是否被改、防火墙是否拦截、设备服务是否启动。第三步确认设备是否处于未激活状态。网络和端口都通但业务请求都不响应很可能就是这个。第四步确认 SDK 版本与设备固件版本是否匹配。老版本 SDK 对接新固件设备或者反过来都可能连接失败。第五步确认是不是被设备拉黑了。短时间内大量失败请求之后有些设备会临时拒绝连接。这个顺序的价值在于先做最容易验证、成本最低的检查。ping 和 telnet 都是几秒钟的事SDK 版本和拉黑这两个判断成本高放在后面。如果一上来就去折腾 SDK 版本很可能方向完全错了。错误码常见含义我的第一反应1用户名或密码错误先确认密码没被改注意别连续重试锁账号2权限不足查这个账号有没有对应通道的操作权限3SDK 未初始化检查初始化是否成功、组件库路径对不对7连接设备失败按上面五步走一遍17参数错误结构体字段填错了重点查通道号和码流类型29命令执行失败设备执行了但失败看设备侧状态46设备不在线设备掉线或未注册到上层72码流类型不支持换主码流或子码流再试提示错误码表一定要以你实际使用的 SDK 版本对应的官方文档为准不同版本同一个码的含义可能微调。上面这张表是我平时用得最多的几个仅供参考遇到不认识的码还是要去翻文档。6.2 能登录但预览黑屏从抓包定位到码流类型这个问题的表现是登录返回句柄正常预览接口也返回成功但回调一直没数据界面全黑。排查过程是这样的。先确认回调到底有没有被触发。我在回调入口加了一行计数打印跑了一分钟发现计数是 0说明连数据都没来。于是把连接方式从 UDP 换成 TCP还是没数据。接着打开抓包工具看网络流量发现设备侧有少量数据包过来说明连接是建立的只是数据量极少。到这里线索就指向设备认为我请求的东西不存在或者请求的东西没数据。我去查设备当前通道的配置发现我要预览的那个通道对应的是数字通道而我传的通道号是按起始值 1 算出来的实际应该是 33 起。改成正确通道号之后数据立刻就来了。这个案例让我记住一件事预览返回成功不代表通道号对。有些设备对错误的通道号不报错只是静默地不推数据。所以排查预览黑屏时通道号一定要作为首要怀疑对象而且在抓包之前就该验证一遍。6.3 跑两小时后必崩句柄泄漏与回调阻塞这个问题的表现是系统上线后能正常运行大约两小时左右进程内存涨到上限被系统杀掉重启后又循环。排查思路是先怀疑内存泄漏但用内存分析工具看下来堆内存增长不明显——说明泄漏的不是 Java 堆是本地内存也就是 SDK 那部分。顺藤摸瓜查句柄。写了一个定时任务把当前登记的所有预览句柄数打印出来发现这个数字在缓慢增长从不下降。说明每次通道切换时旧的句柄没有被释放。回头看代码发现异常分支里有个return提前返回了跳过了后面的释放逻辑。这是典型的资源泄漏写法。修掉之后还不放心又排查了第二个隐患回调里写日志。虽然用的是异步日志框架但队列满了之后会退化成同步写盘回调就被阻塞了。我在回调里加了一个耗时统计果然看到偶发的几十毫秒尖峰。改成回调里只做内存拷贝、日志全部交给下游线程处理之后这个尖峰消失了。这两个问题叠在一起就是两小时才崩的原因——句柄泄漏是慢性病回调阻塞是间歇性发作单独看都不致命凑在一起就把系统拖垮了。7. 上线前必须自己压一遍的几个动作写完能跑通和上线能扛住中间还差几个必须自己做的验证。这些验证不做上线后大概率要在半夜被叫起来。7.1 断线重连与设备重启的演练我会在测试环境做三次破坏性验证拔掉设备网线 30 秒后插回、直接重启设备、把服务器到设备的链路断开一分钟。这三次验证的是不同层面拔网线验证 SDK 的连接保持能力重启设备验证业务层的重新登录逻辑断链路验证超时判定是否合理。判断重连是否成功不能只看接口有没有报错要看数据有没有真的恢复流动。我的判断标准是预览回调的数据计数在恢复后能持续增长。有些情况下接口返回成功但流没有真正恢复只看返回值会误判。另外提醒一点重连不要设计得太激进。设备刚重启时可能还在启动各项服务这时候密集登录只会不断失败还可能触发保护。我一般设置成首次失败后等 10 秒之后指数退避到最长 60 秒一次连续失败到阈值就进告警队列交给人工确认。7.2 多路并发下的资源上限实测16 路预览、8 路回放、加上定时抓图这个组合在开发机上跑得动不代表服务器上跑得动。我的实测方法是逐步加压先 4 路观察 CPU、内存、网络然后 8 路、16 路每次跑够 30 分钟看指标是否平稳。特别关注的是网络带宽主码流 16 路在 4Mbps 码率下就是 64Mbps 的持续流量如果服务器网卡是千兆但还跑着别的业务这个量级就必须提前规划。还有一个容易被忽略的资源是文件句柄。每路连接、每次回放下载都会占用文件描述符系统默认上限往往只有 1024。多路并发加上长时间运行很容易撞到上限表现是莫名其妙的连接失败。上线前把文件描述符上限调高是件五分钟就能做完、但能省掉一整夜排查的事。7.3 日志、录像下载与布防的收尾配置SDK 自己的日志很有用出问题时能对照着看内部到底做了什么。开启方式是在初始化之后调用设置日志的接口指定日志目录和级别。日志级别调到最详细会在高并发下写很多文件建议只在调试期用上线后降到只记录错误。// 打开 SDK 日志级别 3较详细用于问题定位 NET_DVR_SetLogToFile(3, /var/log/hik/sdklog/, TRUE);录像下载这块我用的是按时间段回放加回调写文件的方式。关键点是下载完成后一定要按正确顺序停止回放、释放句柄顺序反了可能导致文件不完整。我会在下载完成后校验文件大小是否大于零、能否被播放器正常打开作为一道自检。前面提过的那次文件全是零字节就是转封装组件没加载导致的加了这道自检之后这类问题在测试阶段就能发现不会带到线上。布防接收设备主动上报的事件是很多项目会漏掉的一环。设备支持在有人形检测、移动侦测、遮挡报警时主动推送消息你需要建立一个长连接接收并处理。这部分要注意的是消息的解析和幂等——同一个事件可能因为重连被重复推送业务侧要做好去重。我的做法是用事件里的时间戳加通道号加事件类型拼一个唯一键处理前先查一下有没有处理过。我在实际使用中最大的体会是海康这套接口的能力其实很全面绝大多数你觉得实现不了的需求翻一遍文档和接口清单都能找到对应能力真正花时间的永远是环境、参数和资源管理这些外围的东西。所以我的建议是——别急着写业务代码先用 curl 和播放器把设备摸熟把它到底支持什么、通道号怎么算、端口开了哪些搞清楚再动手写第一行登录代码。前面多花的这半天后面能省掉好几个通宵。