从「多套客户端」到一套开放能力：乐橙视频监控能力复盘

区域经理在群里要三家店截图，同事在海康客户端、乐橙App、Excel之间切了五次才凑齐。监控开放平台把设备管理、预览、回放、对讲、告警收成一套开放能力，用accessToken鉴权，再经OpenSDK或轻应用嵌进你自己的业务系统。

---

周五四点，巡店截图变成「切五次 App」

区域经理在群里甩了一句：「A 店门口、B 店收银台、C 店后仓，各截一张，十分钟内。」

同事桌上同时亮着三个窗口：海康客户端管一批老店，乐橙 App 管一批新装机，Excel 才是「真正的点位台账」。他先在海康里翻 A 店通道，截图；切到乐橙 App 找 B 店，预览转圈；再回 Excel 对序列号，发现 C 店写的是门店简称，对不上设备 ID；再切回海康补一张；最后又切回乐橙，因为经理补了一句「顺便看下昨晚后仓有没有人进」。

五次切换，三张图，群里还在催。对讲要再开一个客户端，告警红点停在私人手机里，回放还得分「本地卡」和「云录像」两套入口。

这不是运维不熟练。是能力散在多套客户端里：谁在线、谁能看、谁能回放、谁能喊店员、谁该被叫醒，没有同一套开放接口。门店一过三十家，巡店就从「打开 App」变成「打开工具箱」。

【配图 1】 三栏示意：左侧海康客户端预览、中间乐橙 App、右侧 Excel 点位表，箭头标出「切 1～切 5」。

---

监控开放平台是什么

乐橙开放平台 的视频监控能力，不是再做一个「官方 App 的网页版」，而是把摄像机后面的云端能力，按现行 OpenAPI 和组件交给你的系统：

• 你负责：门店组织、角色权限、工单、群通知、自己的 Web / App 壳子。
• 平台负责：设备在线、出流、录像、对讲信令、告警事件，以及客户端播放组件。

对接形态写在开发总览：移动 / 桌面走 OpenSDK ，Web / H5 / 小程序走 轻应用 ，外链分发可走云直播。业务数据（绑定、列表、告警、云存储）走服务端 HTTP，播放和对讲走组件，不要把 appSecret 塞进前端。

一句话：缺的不是再买一台相机，而是把六件事收成闭环，嵌进巡店后台。

---

六大能力闭环：切五次 App，对应缺哪六块

把上面那次巡店拆开，每一次切换都在提醒同一件事------能力没有进你的业务。

闭环	你在业务里要的结果	平台侧怎么接	对应那次「切 App」
1. 设备管理	门店、通道、在线状态一张表，不再靠 Excel	绑定后用 listDeviceDetailsByPage 拉台账	切到 Excel 对序列号
2. 预览	巡店页直接出画、可抓图	OpenSDK 实时预览，或轻应用 imouPlayer type=1	海康 / 乐橙来回切预览
3. 回放	按时间点取证，云录像 / 本地卡同一入口	查片段后走 OpenSDK 回放窗，或轻应用 type=2	经理补问「昨晚后仓」
4. 对讲	值班员对着画面喊店员，不必再开消费端 App	预览建立后再开对讲（OpenSDK 对讲对象 / startTalk()）	想喊人却找不到入口
5. 告警	动检、遮挡、上下线进工单或群，而不是私人红点	setMessageCallback 推到你的 HTTPS	红点在手机，群里没人
6. 开放接入	一套凭证、一种组件选型，能力可复用	accessToken + OpenSDK / 轻应用	整晚都在切客户端

【配图 2】 六块拼图围成圆环：设备管理 → 预览 → 回放 → 对讲 → 告警 → accessToken/组件，中间写「巡店后台」。

选型不必一次上齐。Web 值班墙先轻应用，耗时量级大约 1～7 日，预览、回放、对讲都能盖住；自有巡店 App 再上移动 OpenSDK，延迟更低，但对接按月估。云直播适合「外链看一眼」，对讲不是这条路径的主能力。对照表见开发总览 · 集成方式。

---

接入五步：从注册到第一个画面

对照应用开发主线：获取 token → 绑定设备 → 拉列表 → 预览。告警和对讲叠在预览之后，不要一上来并行五条线。

第一步：注册开发者，创建应用

打开 open.imou.com 注册，按实际终端创建应用（H5 / 移动 / Web / PC）。在控制台「我的应用」拿走 appId、appSecret。个人版可先用约 10 路接入和 1 Mbps 带宽把链路跑通，额度以控制台为准。

成功：控制台能看到应用信息，密钥只放服务端环境变量。

失败兜底：密钥进了前端仓库，先轮换再继续。

第二步：现行签名，换 accessToken

请求一律 POST https://openapi.lechange.cn/openapi/{method}。签名按现行开发规范：time + nonce + appSecret 拼原始串，password = SHA-256(appSecret) 小写 hex，再 Base64(HMAC-SHA256(原始串, password))。查阅文档时跳过「旧版本协议」栏目。

accessToken 有效期约 3 天，expireTime 单位是秒；超过约 2 天再请求会拿到新 token，新旧可并行。遇到 TK1002 再刷新，不要每个业务请求都打一次。

成功：标准案例算出 xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=，再调 accessToken 返回 code=0，token 以 At_ 开头。

失败兜底：SN1001 先对标准案例；SN1002 校时；SN1005 换 nonce。

第三步：设备进开发者账号，列表当台账

设备必须绑在开发者账号 下：用乐橙 App 登录该账号添加，或走 OpenSDK Demo。部分新设备不能只靠 HTTP bindDevice，要结合客户端 SDK，见应用开发 · 设备绑定。

列表只用现行 listDeviceDetailsByPage，看 deviceStatus / channelStatus 是否 online，把 deviceId、channelId 和门店编码写进你自己的表。Excel 退成导入源，不再是运行时真相。

成功：分页能看到刚绑的设备，在线状态和 App 一致。

失败兜底：列表一直 0 台，先查是不是绑到了私人乐橙号。

第四步：选轻应用还是 OpenSDK

你的壳子	走哪条	关键凭证	文档
巡店 Web / 中台 / 小程序	轻应用	服务端用管理员 At_ 调 getKitToken，前端只拿约 2 小时的 Kt_	轻应用组件
自有 Android / iOS / 桌面客户端	OpenSDK	服务端下发设备详情与播放参数，客户端用播放窗 / 回放窗 / 对讲	OpenSDK 组件

getKitToken 的 type（0 全权限 / 1 预览 / 2 回放 / 6 云台）和播放器的 type（1 直播 / 2 录播）不是同一套枚举，别抄串。宫格默认先 streamId=1（标清），别六路同时拉高清把带宽打满。

成功：单路出画，延迟量级对得上文档（轻应用约 2～3 秒，OpenSDK 约 1～2 秒）。

失败兜底：黑屏先查设备是否在线、播放 token 是不是误塞了 At_。

第五步：回放、对讲、告警接进同一页

预览通了再叠三件事，仍然是同一套凭证：

1. 回放 ：按时间查云录像或本地卡片段，轻应用切 type=2，OpenSDK 走回放窗口。
2. 对讲 ：先有预览再 startTalk() / 初始化对讲对象；浏览器要麦克风权限。
3. 告警 ：setMessageCallback 订 alarm（需要上下线再加 deviceStatus），推到公网 HTTPS，先回 HTTP 200 再异步派单 。轮询列表只适合对账，不适合当值守主路径。流程见平台主动推送。

成功：巡店页能看、能拖时间轴、能喊店员；遮挡或动检能进你的群，而不是只亮 App 红点。

失败兜底：回调多次不回 200，平台会停推，修好后重新登记。

【配图 3】 五步泳道：控制台 → 签名/Token → 设备台账 → 组件选型 → 预览/回放/对讲/告警。

---

代码与流程（先跑通鉴权壳）

门店摄像机 ──绑定──► 开发者账号
                      │
                      ▼
              accessToken (At_，约 3 天)
                      │
        ┌─────────────┼──────────────┐
        ▼             ▼              ▼
 listDeviceDetails   getKitToken    setMessageCallback
 ByPage              / OpenSDK      (alarm, deviceStatus)
        │             │              │
        └──────► 轻应用 imouPlayer / OpenSDK 播放窗
                 预览 · 回放 · 对讲     │
                                       ▼
                                 你的 HTTPS → 工单 / 群

服务端签名壳（Node.js，对齐现行规范，密钥不要出网）：

const crypto = require('crypto');

function calcSign(time, nonce, appSecret) {
  const raw = `time:${time},nonce:${nonce},appSecret:${appSecret}`;
  const password = crypto.createHash('sha256').update(appSecret, 'utf8').digest('hex');
  return crypto.createHmac('sha256', password).update(raw, 'utf8').digest('base64');
}

// 标准案例：time=1706511734, nonce=f5a1ae2d-c09c-4d39-a744-83a5c2c653c2
// appSecret=test123456789test123456789
// 应得 sign = xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=

async function callOpenApi(method, appId, appSecret, params = {}) {
  const time = Math.floor(Date.now() / 1000);
  const nonce = crypto.randomUUID();
  const res = await fetch(`https://openapi.lechange.cn/openapi/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      system: { ver: '1.0', appId, time, nonce, sign: calcSign(time, nonce, appSecret) },
      id: crypto.randomUUID(),
      params,
    }),
  });
  const json = await res.json();
  if (!json.result || json.result.code !== '0') {
    throw new Error(`${method} ${json.result?.code} ${json.result?.msg}`);
  }
  return json.result.data;
}

// 1) 换管理员 token
const { accessToken } = await callOpenApi('accessToken', process.env.IMOU_APP_ID, process.env.IMOU_APP_SECRET, {});

// 2) 设备台账（字段以现行文档为准）
const page = await callOpenApi('listDeviceDetailsByPage', process.env.IMOU_APP_ID, process.env.IMOU_APP_SECRET, {
  token: accessToken,
  page: 1,
  pageSize: 20,
  source: 'bindAndShare',
});

轻应用前端只收短时 kitToken，不要把 appSecret 或管理员 At_ 写进页面：

const player = new imouPlayer({
  id: 'root',
  width: 800,
  height: 400,
  deviceId: 'YOUR_DEVICE_ID',
  channelId: 0,
  token: kitToken, // Kt_... 由服务端 getKitToken 签发
  type: 1,         // 1 直播预览；回放改 2 并带 beginTime / endTime
  streamId: 1,
  WasmLibPath: '/',
});
player.play();
// 对讲：player.startTalk();  结束：player.stopTalk();

OpenSDK 侧把解码、渲染、对讲留在组件里，你的 App 只做门店列表和权限。Android / iOS 的窗口类名、初始化顺序以OpenSDK 组件和官方 Demo 为准，这里不展开私有信令。

---

联调会踩的坑

现象	常见根因	先做什么
SN1001，标准案例也对不上	签名不是现行 HMAC-SHA256	用文档固定入参算出 xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=
listDeviceDetailsByPage 一直空	设备在私人乐橙号，不在开发者账号	App 换开发者账号重绑，或走 SDK Demo
播放器黑屏 / Unexpected token <	前端误用 At_，或 WasmLib 路径指到了 HTML	播放器用 Kt_；WasmLibPath 指到 public
对讲无声或 2004	还没出预览，或浏览器没麦克风权限	先 play() 再 startTalk()，检查权限
告警 App 有、业务没有	只轮询、或回调没回 200	改推送模式，先 200 再入队；停推后重新 setMessageCallback
六宫格卡成幻灯片	全开高清，或页面没 destroy()	宫格用标清；切页销毁实例

画面进了你的后台，不等于谁都能看。子账户授权、按门店裁剪通道、kitToken 短时签发，都是你的责任。开放平台把流和事件给你，合规和权限还在业务侧。

---

把客户端收进自己的系统

那次「切五次 App」省下的不是再装一个客户端，而是区域经理要截图时，同事不用离开巡店页。设备管理、预览、回放、对讲、告警，加上 accessToken 和 OpenSDK / 轻应用这一套开放接入，六块齐了，巡店才从工具箱变回一个按钮。

只想在乐橙 App 里看自家两台机的，不必上这一套。已经在用停维护栏目接口的项目，先迁到现行 OpenAPI，再叠加页面。

能力清单和适用场景以产品页为准：视频监控开放能力。

乐橙开放平台 把摄像机的设备、直播、回放、对讲和告警，按开放接口交给开发者自己的应用。注册、创建应用、领取试用额度，从这里开始：https://open.imou.com