企业官网建设流程全解析

第一次在Vue项目里对接海康设备的视频预览，我差点被WebControl插件劝退。需求一句话就说完了：让用户在内网页面里直接看摄像头画面。可真动手才发现，光是把插件装上、把RSA加密那一层打通，就够折腾好几天。这篇文章我把从插件安装、密钥加密到Vue里挂预览窗口的完整链路都整理一遍，重点放在RSA加密避坑上——这个环节网上资料少、报错又很反直觉，值得单独拿出来讲。无论你是接手老项目，还是打算在现有Vue系统里新增视频预览模块，按这个流程走，至少能省下大半天的排查时间。

1. 为什么是WebControl：视频预览方案的取舍

1.1 一个绕不开的现实：浏览器原生放不了RTSP

海康摄像头的视频流走的是RTSP协议，而浏览器压根没有原生支持RTSP的能力。你输入rtsp://192.168.1.64:554/Streaming/Channels/101到Chrome地址栏，结果多半是浏览器提示不认识这个协议。所以做这类项目时，第一件事不是写代码，而是先确定“视频到底通过什么方式投到页面上”。

目前常见的路子有这么几条：要么用海康WebControl插件，要么让后端加一个转流服务把RTSP转成HLS或WebRTC，要么直接买商业的视频云网关。这里面，WebControl插件是最“原教旨”的海康方案，它由海康官方提供，本质上是一个浏览器插件，通过插件的能力去拉RTSP流并解码渲染。

我们当时选它，原因很现实：项目只能跑内网，不允许额外部署转流服务器。HLS转流虽然跨浏览器能力强，但等于在链路上多了一个故障点，维护成本也上去了。设备是海康的，接入端也用海康自家的插件，这是最直接的路径。

1.2 WebControl能干什么，不能干什么

很多人以为WebControl只是用来播放视频，其实它还提供云台控制、抓图、录像回放、语音对讲等一系列能力，具体看你集成的SDK版本和平台后台开放的权限。但它在浏览器兼容性上的限制非常明显：老版本的产品走ActiveX，新一点的版本走NPAPI，而Chrome从45版本之后就把NPAPI禁掉了，Edge、Firefox也陆续跟进。说白了，这个插件天然就不是给现代浏览器准备的。

做个简单对比，大家感受一下选型差异：

那什么时候只能选WebControl？我遇到的情况是：客户明确禁止在内网加任何第三方服务，设备又是海康整套环境，这时候用插件是阻力最小的方案。如果你也在类似约束下，那接下来的内容对你会特别有用。

1.3 和H5方案、流媒体网关相比，插件到底输在哪

插件最大的问题其实不是“技术落后”，而是“使用门槛高”。用户访问页面之前得先下载安装exe，安装后还得重启浏览器，再配置受信任站点，每一样放在C端产品里都是劝退操作。但在内部管理系统里，用户群体固定、浏览器版本可控，这个门槛反而可以被接受。

另外一点容易被忽略：插件的维护责任在自己手上。海康官方对WebControl的更新节奏越来越慢，有些SDK包还停留在几年前，遇到系统新装、浏览器强制升级，插件可能就加载不出来了。所以选插件方案的同时，你一定得想好“如果浏览器升级了怎么办”的退路。我们当时的做法是把推荐浏览器版本写进项目说明，页面加载时做一次环境检测，不满足条件就弹提示引导。

2. 环境准备里的隐形门槛：插件安装、浏览器版本与开发环境协议

2.1 插件安装的正确姿势

先把插件拿到手。海康WebControl插件的安装包一般可以在设备配套光盘、官网下载中心，或者项目交付方提供的资料包里找到。安装时尽量右键“以管理员身份运行”，有些电脑上如果开着杀毒软件，可能会拦截插件的驱动注册，建议安装前先把杀毒软件临时退出，装完再开回来。

安装完成后有一个很容易踩的坑：必须彻底关闭浏览器再重新打开。只是刷新页面不会让插件生效，因为插件注册动作发生在浏览器进程启动时。我第一次集成时就是安装完没重启浏览器，结果页面里一直报“插件未安装”，折腾了快一个小时才发现是这个原因。

另外建议装完插件后先去访问海康提供的插件测试页（或者SDK包里的demo页面），在独立环境里先把插件是否正常跑通验证掉，再进Vue项目排查。不然两边的报错混在一起，很难定位是插件本身的问题，还是代码集成的问题。

2.2 开发环境为什么建议用localhost

插件初始化正常工作的前提，是页面协议和插件服务地址协议一致。举个例子，当你的Vue页面跑在http://localhost:8080，而后端平台接口跑在http://192.168.1.20:8000时，浏览器会认为这是跨域的HTTP资源，通常可以正常拉取；但如果页面跑在https://localhost:8080，后端还是HTTP接口，那问题就来了——现代浏览器会直接拦截“混合内容”请求，插件初始化时拿不到服务地址，日志里会看到连接被拒绝或初始化失败。

所以开发阶段我建议直接用HTTP，不要开HTTPS。并且项目里配置devServer代理，把后端接口统一代理到本地，这样页面请求都是同源的，能规避掉一大半跨域问题。vue.config.js里类似这样写：

devServer: { proxy: { '/platform': { target: 'http://192.168.1.20:8000', changeOrigin: true } } }

如果你是在内网调试，后端地址是固定的IP，代理配置写好之后基本不用再动。

2.3 浏览器兼容的内核问题

既然选了WebControl，就别指望能在新版本Chrome里顺利跑起来。我们实际项目里用的是360浏览器的兼容模式（也就是IE内核），或者某些定制版Chromium内核浏览器，它们在插件加载上比原版Chrome宽容一些。

这里有一个经验：项目组内部必须统一浏览器版本，不然就会出现你这里调通了、同事那边黑屏的尴尬局面。最稳妥的做法是在登录页做一次环境检测，用JS判断插件对象是否存在，不存在就给出一个“下载安装包 + 使用说明 + 推荐浏览器版本”的引导页面。虽然体验上多了一步，但对内网项目来说，比让用户自己瞎折腾强太多。

3. Vue工程接入WebControl：依赖引入与初始化时机

3.1 在index.html里按顺序引入jquery和webcontrol.js

海康WebControl的JS-SDK不像npm包那样可以直接npm install，它的官方文件就是一个webcontrol.js或类似命名的脚本，需要手动引入。而且这个SDK底层依赖jQuery，所以必须先引入jQuery，再引入webcontrol.js，顺序不能反，否则控制台会报$ is not defined或者WebControl is not defined。

我通常直接在public/index.html里加：

<script src="/libs/jquery.min.js"></script> <script src="/libs/webcontrol.js"></script>

把这两个文件放在public/libs目录下，打包时Vue CLI会自动把它们原样复制到dist根目录，不会经过webpack处理，省去很多路径和编译兼容问题。注意别把它们放到src/assets里再import，那样会走一遍webpack的模块解析，可能和插件脚本里的全局变量声明方式冲突。

3.2 组件中初始化WebControl的时机

初始化动作建议放在mounted之后，并且要用一个nextTick或者短暂的延时，确保DOM已经渲染完成。因为后面创建预览窗口时，需要把窗口附加到一个具体的div元素上，如果div还没渲染出来，SDK会找不到挂载点。

下面这段代码是我们项目中验证过能跑通的骨架，简化了一些业务逻辑：

let wc = null let windowId = null async function initWebControl(divRef) { wc = new WebControl({ rtspPort: 554, appKey: 'your_app_key', secret: 'your_secret', useLoader: 'load.js' }) await wc.initPlugin() const sessionId = await loginByRsa() await wc.login({ sessionId }) windowId = await wc.createWindow({ width: '100%', height: '100%' }) await wc.attachViewer({ windowId, viewer: divRef }) }

注意不同SDK版本的接口参数可能会有细微差别，我这边写的是多个项目里跑通过的常见写法，如果你的SDK包里login、createWindow的入参不太一样，以你们拿到的官方demo为准。核心的顺序逻辑是通用的：初始化插件、登录平台、创建窗口、绑定容器、发起预览。

3.3 初始化失败的表现与处理

插件初始化失败时，常见的有三种现象：

第一种是控制台直接报WebControl is not defined，这说明webcontrol.js没加载成功，或者加载顺序有问题。先看浏览器Network面板里这个脚本是否返回200，再看控制台是否有jQuery报错。

第二种是报类似initPlugin error或抛出异常，多半是插件没装、装了没重启浏览器，或者浏览器内核不支持NPAPI插件。这时候只能回到第一步去排查环境。

第三种是初始化成功，但后续登录报“用户未认证”之类的错误，这个大概率是RSA加密链路出了问题，也就是文章后面重点展开的部分。

4. RSA加密链路：后端加密、前端登录的坑全在这

4.1 密钥从哪来：appKey和secret的获取

先搞清楚密钥体系。接入海康平台时，会在平台后台创建一个应用，拿到一对凭据：appKey和secret。appKey相当于应用的用户名，可以直接出现在前端；但secret相当于密码，一旦泄露，任何人都能冒充你的应用去调用平台接口。

很多教程为了省事，直接教你把secret明文写在new WebControl()的配置里。开发调试的时候可以这么干，但放到生产环境就是安全事故。因为前端代码是公开的，只要用户打开开发者工具，就能在源码里看到你的明文密钥。正确处理方式是把secret放在后端，由后端生成加密串，前端只拿加密结果。

当然，内网项目有时候迫于工期选择前端直接加密，我也理解，但至少做到“secret不硬编码在仓库里”，而是通过环境变量注入，打包时再替换，这样即便前端代码被拿到，也看不出真实的secret值。

4.2 加密结构拆解：secret、时间戳与公钥

海康的RSA加密规则和普通网站的登录加密不太一样，它不是简单地把密码用公钥加密就完事，而是要求把secret和一个当前时间戳拼在一起，再用平台提供的RSA公钥加密。时间戳的作用是防重放攻击，平台收到请求后会解密，校验里面的时间戳和当前时间是否匹配，超时就会拒绝。

我接触到的接入文档里，常见的拼接格式类似下面这种：

secret_1612345678901

前面是secret，后面跟下划线和13位毫秒时间戳，然后用平台公钥做RSA加密，把加密后的密文和appKey、timestamp一起提交给后端。

可能你会问，为什么还要单独传一个timestamp？因为平台服务端需要知道你是用哪个时间戳去加密的，它解密后才能拿这个时间和当前时间对比。如果只传密文，它也得解密之后才知道时间戳，逻辑上没问题，但校验前就必须先解密成功。所以一般明文传一份时间戳，密文里再带一份，双保险。

4.3 jsencrypt分段加密的正确写法

前端做RSA加密，最常用的库是jsencrypt，原因是API简单、用起来快。但它有一个明显的坑：默认的encrypt方法不支持超过密钥长度限制的长文本。RSA加密本身能处理的明文长度受密钥位数限制，1024位公钥最多加密117字节，2048位公钥最多加密245字节。

如果你的secret本身不长，通常不会触发这个问题。但有些项目里secret加上时间戳、再加上盐值后，长度很容易逼近或超过117字节，这时候直接调用encrypt会返回false或加密结果不完整，后端解密出来是乱码或空串。

一个通用的分段加密函数长这样：

import JSEncrypt from 'jsencrypt' export function encryptLong(publicKey, plainText, keyLength = 1024) { const encryptor = new JSEncrypt() encryptor.setPublicKey(publicKey) const maxLength = Math.ceil(keyLength / 8) - 11 const inputLen = plainText.length let offset = 0 let result = '' while (inputLen - offset > 0) { const length = Math.min(inputLen - offset, maxLength) result += encryptor.encrypt(plainText.substr(offset, length)) offset += maxLength } return result }

注意，分段加密之后的结果是一段拼接起来的base64字符串，后端拿到后需要按同样的分段规则去解密。所以如果你后端用的语言写RSA解密的工具人不懂“前端分段加密”这个逻辑，很可能解密出来只有第一段是完整内容，后面都丢了。解决方法是和后端提前约定好：密文是分段加密的结果，解密时也要分段解。

4.4 时间戳类型和填充方式：两个最容易翻车的地方

时间戳这个坑特别隐蔽。我们有一次调联调，始终报“时间戳校验失败”，查了很久，最后发现是前端加密时用的是Date.now()，返回13位毫秒时间戳，但提交给后端接口时写的是Math.floor(Date.now() / 1000)，返回10位秒级时间戳。加密用的和提交用的不是同一个值，后端自然校验不通过。

正确做法是保留一个变量，加密和提交都用它：

const timestamp = String(Date.now()) const plainText = `${yourSecret}_${timestamp}` const encryptedSecret = encryptLong(publicKey, plainText) // 提交时传 timestamp，给后端校验用 const params = { appKey, timestamp, encryptedSecret }

另一个坑是RSA填充方式。jsencrypt默认走的是RSA_PKCS1_PADDING，但有些平台的后端用的是OAEPPadding或者RSA/ECB/OAEPWithSHA-256AndMGF1Padding，加解密双方对不上，结果就是后端解出来是乱码，或者直接抛异常。如果你的项目遇到“加密成功但登录失败，后端说解密异常”，先别急着改前端代码，去和后端确认一下他们用的填充算法。

如果确认后端是OAEP，用jsencrypt就搞不定了，需要换成jsrsasign。示例：

import { KEYUTIL, KJUR, hextob64 } from 'jsrsasign' function encryptByOAEP(publicKeyPem, plainText) { const key = KEYUTIL.getKey(publicKeyPem) const enc = KJUR.crypto.Cipher.encrypt(plainText, key, 'RSA/ECB/OAEPWithSHA-256AndMGF1Padding') return hextob64(enc) }

说到底，RSA加密不是一个前端单方面就能搞定的事，它必须和后端、甚至和平台SDK协商一致。所有网上找的代码只能当参考，最终要以你们项目实际的接口文档为准。

4.5 登录成功后如何把session交给WebControl

RSA加密的目的，是为了换取一个合法的登录凭证。后端拿到前端提交的加密串并校验通过后，会返回一个sessionId或登录token。注意，这里有两种做法：

第一种，前端把这个sessionId传给WebControl SDK的login方法，由SDK去访问平台接口。这种情况比较简洁，后端其实已经不是核心参与者，而是帮你做了一次“代理加密”或“代理转发”。

第二种，后端自己去和平台交互，登录成功后返回给前端一个已经授权的播放地址，前端直接用WebControl播放该地址，这种情况下SDK的login方法可以跳过。

我们项目里用的是第一种，因为这样路由跳转、权限校验都统一走后端，前端逻辑最简单。这里还是要提醒一下：无论哪种方式，都不要自己在前端拼一堆加密逻辑后把明文secret发给后端，那样RSA就白做了。

5. 预览功能的完整流程：从创建窗口到清理销毁

5.1 获取预览地址

登录成功后，下一步就是拿到摄像头的预览地址。预览地址可以通过后端接口获取，也可以在拿到设备信息后按规则拼接，前者更稳妥，因为地址里可能包含账号密码，由后端拼接可以避免把凭据暴露到前端。

一个典型的RTSP预览地址长这样：

rtsp://admin:password@192.168.1.64:554/Streaming/Channels/101

末尾的101含义是：第一个1代表通道号，01代表主码流，如果是102就是子码流。主码流清晰度高、占用带宽大，适合大屏展示；子码流清晰度低但流畅，适合网格多画面监控。前端可以做成一个“流畅/高清”切换按钮，本质是切换不同的码流地址。

在开发阶段注意别把预览地址打太多日志，尤其别让日志把RTSP地址里的密码也打出来，否则一旦日志被截图或者上传，等于把设备凭据公开了。

5.2 创建窗口和绑定容器

拿到预览地址后，创建视频窗口的套路是固定的：先创建窗口、再把窗口挂载到页面div、最后启动预览。挂载的那个div必须预留明确的宽高，否则插件渲染时会拿到0宽高，画面自然显示不出来。

多路预览也一样，每一路都申请一个独立的windowId，然后各自绑定不同的div，最后分别调用startPreview。需要注意，插件能同时创建的窗口数是有限制的，具体看版本，有的是16路，有的是32路。超出限制时插件会报“超出最大连接数”，这时候要么分批展示，要么降级用HLS方案。

5.3 黑屏、白屏和“窗口出来了但没画面”的逐个排查

预览阶段遇到最多的，就是窗口创建成功但画面黑屏。遇到这种情况，我通常按这个顺序排查：

先看容器div的宽高。有时候div被v-if控制，视频开始播放时div还没渲染出来；有时候div是空的，子元素把高度撑出来了，但插件播放器渲染的是canvas或activex控件，需要父容器有固定高度。最省事的办法是给视频容器一个绝对定位，设置width: 100%; height: 100%，并且保证它的父级也设置了高度。

再看预览地址是否带认证信息。有些RTSP地址不带username/password，或者携带的账号权限不足，插件会一直尝试连接但拉不到流，界面表现就是黑屏或转圈。可以用VLC播放器在本地先试一下这个地址，确认能播，再回前端排查。

然后看码流格式。部分老摄像头不支持H.265，但SDK默认请求主码流是H.265，插件又没启用硬解码，就会黑屏。这时换成子码流（H.264）试试，如果子码流能出画面，基本可以断定是解码能力的问题。

最后检查浏览器兼容模式。如果页面跑在“极速模式”，插件可能加载不出来，切换成“兼容模式”再试。这个和新版本Chrome的处境类似，插件不行就是不支持现代浏览器的安全策略，没有前端代码层面的解决办法，只能引导用户换环境。

5.4 离开页面时的销毁顺序

销毁顺序搞反，是另一个高频坑。正确的销毁顺序是：先停止预览，再关闭窗口，再登出，最后销毁插件实例。如果直接调销毁方法而不停止预览，插件进程可能残留，Windows任务管理器里能看到一个叫WebControl的进程一直在跑，再次进入页面时会初始化非常慢，甚至直接失败。

Vue3组合式API里可以这样写：

onBeforeUnmount(async () => { try { if (windowId) { await wc.stopPreview({ windowId }) await wc.closeWindow({ windowId }) } await wc.logout() await wc.destroy() } catch (e) { console.warn('销毁失败，插件可能已释放过') } })

注意包一层try/catch，因为有的SDK版本里重复调用销毁方法会直接抛异常，但在我们项目里表现是无所谓，可以忽略，只要保证“stopPreview在closeWindow之前”就行。

6. 生产部署与维护：证书、白名单和长期运行

6.1 HTTPS与HTTP的协议错位问题

生产环境部署时，最容易遇到的是页面HTTPS、插件服务HTTP的协议错位。浏览器会拦截HTTPS页面发起的HTTP请求，导致插件初始化时连不上后端。解决思路有两种：全部统一到HTTPS，或者全部统一到HTTP。

内网项目如果没有正规证书，可以用自签名证书，但浏览器会报警告；很多项目为了省事直接允许HTTP访问，这也是可以的，前提是内网环境足够安全。如果必须走HTTPS，最好让后端平台也配置上HTTPS，保证前端页面、接口、插件服务三端协议一致。

6.2 地址白名单与受信任站点

为了让插件能正常加载和调用，浏览器通常需要把平台地址加入“受信任站点”，或者单独对插件添加白名单。不同内核浏览器的位置不一样：IE浏览器是在“Internet选项—安全—受信任的站点”里添加；360浏览器兼容模式需要在“安全设置”里调整ActiveX控件启用选项，并且把站点加到自定义白名单。

这个配置对普通用户来说很不友好，可以在首次进入页面时写一个引导弹窗，把配置步骤一页一页展示出来。虽然体验一般，但确实能减少大量“为什么我这看不了”的工单。另外一个比较实用的技巧是，将插件SDK的域名也加入“兼容性视图”设置，避免浏览器用错误的文档模式渲染页面。

6.3 长期运行的资源释放与降级方案

浏览器长期开着监控页面，内存占用会逐渐上涨，尤其是32位浏览器进程，更容易接近内存上限。给页面加一个“释放资源”按钮，点击后只停止预览不退出登录，用户重新打开某一路视频时再恢复预览，能有效降低内存压力。另外，在监听页面不可见的地方，也可以做一个自动隐藏视频窗口的操作，减少插件渲染开销。

如果你已经预见到项目将来要迁移到H5方案，我个人的建议是：在业务层做一层“视频组件”的抽象，把WebControl的调用包在组件内部，对外只暴露start(),stop(),switchStream()这几个方法。这样以后切换到HLS或WebRTC方案时，只需要重写这个组件内部，上层业务代码不用动。

最后再分享一个维护阶段的小经验：把插件版本、SDK文件版本、推荐浏览器版本、平台服务版本这四个信息做成检查清单，每次出问题先核对这四个版本是否匹配。我们项目里好几次线上故障，最后定位出来的原因都特别简单——有人换了浏览器正式版，或者某台机器重装了系统后用了旧版插件。版本对齐了，至少能少走一半弯路。