上周三凌晨两点，我盯着日志里那个反复出现的登录失败返回值，终于承认自己在这件事上想得太简单了——对接海康威视接口这件事，网上的帖子看起来都是"三行代码登录、五行代码取流"，真做起来，卡住你的从来不是那几个 API，而是端口、字符集、通道号、句柄回收这些"看起来跟接口无关"的东西。这篇记录的是我把一套海康威视设备接入系统从能跑通做到能上线，中间改过的四五个版本、抓过的几十次包、以及最后留下来的那套稳定方案。如果你正准备做海康威视摄像头、NVR、门禁或者视觉控制器的接口对接，不管你是 Java、C++ 还是 Python 技术栈，这篇里的选型逻辑、参数含义和排查链路应该都能直接用。

1. 先想清楚要对接的是海康的哪一层接口

我见过太多项目一开始就选错层。海康的对外能力其实是分层暴露的，SDK、ISAPI、RTSP、主动注册这几条路各自解决不同问题，选错了后面全是补丁。所以第一步不是写代码，是把需求拆成"我要控制设备""我要拿视频流""我要拿结构化数据"三件事，再分别对应方案。

1.1 SDK、ISAPI、RTSP、主动注册四条路的边界

设备网络 SDK（HCNetSDK）是能力最全的那条路，登录、预览、回放、云台、布防、参数下发、语音对讲，几乎设备的所有功能都能通过它拿到。代价是你要处理它的一套结构体、回调、句柄生命周期，还得把动态库跟着程序一起分发，跨平台时尤其烦。我这次的核心链路——登录、实时取流、定时回放下载——全是走 SDK。

ISAPI是建立在 HTTP 之上的 REST 风格接口，返回 XML 或 JSON。它特别适合做配置查询、设备信息读取、抓图、校时、录像检索这类"一次请求一次响应"的动作。写起来比 SDK 舒服太多，用 curl 就能验证，不需要加载任何动态库。但它的短板也很明显：实时流、批量事件这类长连接场景不是它的主场。

RTSP是最省事的取流方式，一行地址就能丢给播放器或者 ffmpeg。适合"我只要画面，不需要控制设备"的场景。需要注意的是海康的 RTSP 走的是标准协议，但地址里的通道号编法跟 SDK 里的通道号不是一回事，这个后面单独说。

主动注册（设备主动连平台）适用于设备在 NAT 后面、平台拿不到设备 IP 的情况。设备侧配置好平台地址后反向建连，平台不用去拨号。这条路的配置成本比前三条高，涉及平台侧的服务搭建，但一旦设备网络环境复杂，它是唯一干净的解法。

我把这四条路的差别整理成一张表，实际选型时对着看会快很多：

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.dll，Linux 下是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 '<Time><timeMode>manual</timeMode><localTime>2024-05-20T10:30:00</localTime><timeZone>CST-8:00:00</timeZone></Time>'

时区字段一定要填对，写成CST-8:00:00这种格式，不要写+08:00，不然设备可能解析失败或者理解成正时区偏移的方向错误，导致时间和预期差 16 个小时。这个格式我第一次写错的时候，回放查询直接返回空列表，排查了整整一个小时才定位到时区。

2.3 端口清单与网络连通性预检

海康设备的端口不止一个 8000。做完整对接至少要摸清这几个：

• 8000：SDK 私有协议端口，登录、预览、回放、布防都走它。有些项目会改成其他值，接入前一定要从设备配置里确认，不要默认就是 8000。
• 554：RTSP 端口，取流用。可以被修改，改过之后地址里要跟着改。
• 80 / 443：ISAPI 的 HTTP / HTTPS 端口。设备默认 HTTP 管理端口是 80，但也可能被改成 8080 之类。
• 其他业务端口：如果走主动注册或国标协议，还会涉及平台侧定义的端口。

我现在的接入流程里，第一步永远是网络预检，而不是直接调登录接口。预检脚本做三件事：ping 通不通、目标端口 telnet 通不通、HTTP 管理端口能不能返回一个应答。这三件事帮我省掉了无数次"怀疑代码有问题结果发现是端口没开"的时间浪费。

注意：新出厂的设备有些处于"未激活"状态，此时任何端口都不响应业务请求，必须先通过激活流程设置密码。这个在预检阶段就能看出来——网络通但所有端口都不通，基本可以往这个方向想。

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 里那几个参数到底影响什么

预览入参结构体里有几个字段是需要你主动做决策的：

码流类型这个选择特别值得说。主码流分辨率高、码率高，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 Map<String, 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 抓图，直接返回 JPEG
• PUT /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 版本，很可能方向完全错了。

提示：错误码表一定要以你实际使用的 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 和播放器把设备摸熟，把它到底支持什么、通道号怎么算、端口开了哪些搞清楚，再动手写第一行登录代码。前面多花的这半天，后面能省掉好几个通宵。