10 分钟把门口摄像机写进 Home Assistant：Core 集成复盘

10 分钟把门口摄像机写进 Home Assistant：Core 集成复盘

---

一、升级 HA 之后，我删掉了 HACS 插件

树莓派上的 Home Assistant 升到 2026.6 之后，我在「添加集成」里搜到了 imou——官方文档说，云摄像头可以直接走 Core 内置集成，不必再装 HACS 自定义组件。

我填了开发者平台的 App ID、App Secret，点提交，界面提示成功。

然后设备列表：空的。

手机 App 里门口机在线、能预览。我在论坛翻了两小时，最后发现不是密钥错了，而是 Server region 选成了亚太，国内账号实际应该选 China，API 要走 openapi.lechange.cn。改完区域，两分钟后 camera 实体自己冒出来了。

---

二、Core 集成解决什么，国内网关为什么关键

2.1 从 HACS 到 Core：路径变了，云还是那条云

对比项	HACS 自定义组件（旧路径）	HA 2026.6+ Core 集成
安装	手动下载 / HACS	设置 → 添加集成 → imou
依赖	自行跟进版本	随 HA 升级，内置 pyimouapi
实体	camera / switch / binary_sensor 等（视组件版本）	每通道 Live view SD/HD + Button（PTZ、重启等）
数据刷新	组件实现	云轮询，约 2 分钟
认证	App ID + Secret + API Domain	App ID + Secret + Server region

两条路底层都是 厂商开放平台 HTTP API。Core 集成把「区域 → 网关域名」封装进了配置流；国内用户最容易踩的坑，就是区域与网关不匹配。

2.2 为什么 openapi.lechange.cn 值得单独记

开放平台按区域部署 API 节点。HA 配置里的 Server region 会决定请求打到哪个网关：

Server region（HA 配置流）	典型 API 网关（国内文档常用）
China (cn)	openapi.lechange.cn
Singapore / APAC (sg)	亚太节点（与国内不同）
Europe (eu)	欧洲节点
North America (na)	北美节点

国内注册、国内配网的账号，选错 region 的典型症状：

• 集成添加「成功」，无报错；
• 设备列表 0；
• 开放平台分页接口用国内网关能查到设备，HA 却查不到——因为 HA 在打海外节点。

另外：App 能预览 ≠ 开发者资产池有设备。HA 集成读的是开放平台账号下的设备；设备绑在私人 App 小号上，分页接口也是空的。

2.3 推荐架构

flowchart TB
  subgraph Prep["接入前验收"]
    DEV["开发者平台 appId/appSecret"]
    BIND["设备绑定开发者主账号"]
    LDP["listDeviceDetailsByPage 验收"]
  end
  subgraph HA["Home Assistant 2026.6+"]
    CFG[&#34;添加集成 imou<br/>region=China&#34;]
    CAM[&#34;camera.live_view_sd / hd&#34;]
    BTN[&#34;button.ptz_* / restart&#34;]
  end
  subgraph Cloud[&#34;国内 API 网关&#34;]
    API[&#34;openapi.lechange.cn&#34;]
  end
  DEV --> BIND --> LDP
  LDP --> CFG
  CFG --> API
  API --> CAM
  API --> BTN

边界：

• Core 集成当前以 camera + button 为主，毫秒级动检自动化不要只依赖 2 分钟轮询——需要另接消息回调（后文进阶）。
• 列表接口用现行 listDeviceDetailsByPage，勿用文档「旧版本协议、不再维护」里的 deviceList 方法。
• 局域网低延迟预览：ONVIF/RTSP 可与云集成并存。

---

三、国内路径一步步走

Step 0 · 接入前：用分页接口验收资产池

HA 集成之前，先用脚本确认「开发者账号里真有这台机子」：

// scripts/verify-device-pool.js
import crypto from 'node:crypto';
import { randomUUID } from 'node:crypto';
import 'dotenv/config';

function sign(time, nonce, secret) {
  const raw = `time:${time},nonce:${nonce},appSecret:${secret}`;
  return crypto.createHash('md5').update(raw, 'utf8').digest('hex');
}

async function platformCall(method, params = {}) {
  const time = Math.floor(Date.now() / 1000);
  const nonce = randomUUID();
  const body = {
    system: {
      ver: '1.0',
      appId: process.env.APP_ID,
      sign: sign(time, nonce, process.env.APP_SECRET),
      time,
      nonce,
    },
    id: randomUUID(),
    params,
  };
  const res = await fetch(`${process.env.OPENAPI_BASE}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (json.result?.code !== '0') throw new Error(`[${json.result.code}] ${json.result.msg}`);
  return json.result.data;
}

const { accessToken } = await platformCall('accessToken', {});
const page = await platformCall('listDeviceDetailsByPage', {
  token: accessToken,
  pageSize: 20,
  page: 1,
  source: 'bindAndShare',
});

for (const dev of page.deviceList ?? []) {
  console.log({
    deviceId: dev.deviceId,
    deviceStatus: dev.deviceStatus,
    ability: dev.channelList?.[0]?.channelAbility ?? dev.deviceAbility,
  });
}
console.log('count', page.deviceList?.length ?? 0);

.env（国内验收示例）：

APP_ID=your_app_id
APP_SECRET=your_app_secret
# 国内网关 — 与 HA Server region=China 对应
OPENAPI_BASE=https://openapi.lechange.cn/openapi

踩坑 1：deviceList 长度 0 → 换开发者主账号绑定，或控制台 / bindDevice 把设备挂进资产池。

踩坑 2：SN1005 → 每次请求新 nonce，五分钟内勿重复。

---

Step 1 · 开发者平台准备（约 10 分钟）

① 在摄像头厂商「开发者开放平台」注册，创建应用 → appId、appSecret
② 设备 App 配网后，绑定到开发者主账号（非私人小号）
③ 上一步脚本 listDeviceDetailsByPage 能查到 deviceId 且 online
④ 记下：国内 HA 集成 region 选 China，网关 openapi.lechange.cn

密钥只放 HA 的 secrets.yaml，不要写进 Git：

# secrets.yaml（示例键名，按集成表单实际字段调整）
imou_app_id: "your_app_id"
imou_app_secret: "your_app_secret"

---

Step 2 · HA Core 集成配置

设置 → 设备与服务 → 添加集成 → 搜索 imou
App ID     ← 控制台应用详情
App secret ← 同上
Server region ← 国内账号选 China

配置流示意（字段名以你 HA 版本为准）：

# configuration entry（由 UI 写入 .storage，此处仅作理解）
imou:
  app_id: !secret imou_app_id
  app_secret: !secret imou_app_secret
  region: cn   # China → 请求 openapi.lechange.cn 区域节点

提交成功后，集成卡片应列出账号下设备；每路通道常见实体：

camera.xxx_live_view_sd
camera.xxx_live_view_hd
button.xxx_ptz_up / ptz_down / ptz_left / ptz_right   # 视 PTZ 能力
button.xxx_restart

踩坑 3：region 选 sg 或 eu，国内账号 → 列表空。改 China 后等一轮轮询（约 2 分钟）或重启集成。

踩坑 4：Invalid App ID or App secret → 核对 appId/appSecret 是否来自与 region 匹配的开放平台站点；复制时勿带空格。

---

Step 3 · 验收直播与按钮

开发者工具 → 状态，搜 camera.：

# 实体 ID 因设备名而异
camera.door_live_view_sd
camera.door_live_view_hd

Dashboard 加 Picture Entity 或 Live View。若转圈：

□ 分页接口 deviceStatus = online
□ Server region = China（国内）
□ 账号直播/接口配额未用尽
□ HA 日志无 sign / token 错误

PTZ 按钮灰色 → 查分页返回的 deviceAbility / channelAbility 是否含 PT、PTZ；枪机无云台属正常。

---

Step 4 · 第一条自动化（基于 camera 实体）

Core 集成以直播与按钮为主；做「有人开灯」若尚无 binary_sensor，可先用 手动 script + 语音 验证链路，或叠加回调（Step 5）。

# 语音「看门口」— 验证 camera 实体可用
script:
  show_door:
    alias: 看门口
    sequence:
      - service: camera.play_stream
        target:
          entity_id: camera.door_live_view_hd
        data:
          media_player: media_player.living_room

若你仍保留 HACS 旧组件且暴露了 binary_sensor，动检自动化可继续用；Core 与 HACS 勿对同一 appId 重复配置，否则 API 配额双倍消耗。

automation:
  - id: porch_light_on_motion
    alias: 门口动检开灯
    mode: single
    trigger:
      - platform: state
        entity_id: binary_sensor.door_motion_alarm
        to: "on"
    condition:
      - condition: sun
        after: sunset
        before: sunrise
    action:
      - service: light.turn_on
        target:
          entity_id: light.porch
      - delay: "00:05:00"
      - service: light.turn_off
        target:
          entity_id: light.porch

---

Step 5 · 动检要快 → 消息回调补一层

Core 集成 2 分钟轮询不适合门铃级联动。需要 setMessageCallback 把 videoMotion / online 推到桥接，再转 MQTT 给 HA：

// 平台侧（Node 示例）— 先取 accessToken
await platformCall('setMessageCallback', {
  token,
  status: 'on',
  callbackUrl: 'https://your-bridge.example.com/platform/events',
  callbackFlag: 'alarm,deviceStatus',
  basePush: '2',
});

# HA — MQTT 触发
automation:
  - alias: 移动侦测推手机
    trigger:
      - platform: mqtt
        topic: home/camera/DOOR_SERIAL/alarm
    condition:
      - condition: template
        value_template: "{{ trigger.payload_json.msgType == 'videoMotion' }}"
    action:
      - service: notify.mobile_app_phone
        data:
          title: 门口有动静
          message: "{{ now().strftime('%H:%M') }}"

回调 必须公网 HTTPS + 200 先返回，否则平台会停推。

---

Step 6 · 端到端 Checklist

□ 开发者应用已创建，设备在开发者主账号资产池
□ listDeviceDetailsByPage（国内网关）≥1 且 online
□ HA 添加 imou 集成，Server region = China
□ camera.live_view_sd 或 hd 能出画
□ secrets 未进 Git
□ （可选）setMessageCallback + MQTT 补实时告警

---

四、配额、延迟、排错

4.1 API 配额

每个 App ID 有每月免费 API 调用额度（官方文档常见表述为约 3 万次量级，以控制台为准）。Core 集成每 2 分钟轮询设备列表与在线状态，设备越多、Dashboard 多路直播越多，消耗越快。

建议：
· 测试/生产勿重复添加同一 appId 的多个集成实例
· 多路预览墙优先 SD 实体，HD 按需点开
· 配额异常时查控制台「资源管理」

4.2 Core vs HACS vs ONVIF

路径	适合
Core 集成	新装 HA 2026.6+，要官方维护、配置流简单
HACS 组件	需要 Core 尚未并入的 switch/sensor 等能力
ONVIF/RTSP	局域网低延迟，与云集成可并存

4.3 国内网关排错速查

现象	常见原因	处理
集成成功，设备 0	region 非 China / 设备未绑开发者账号	改 region；bindDevice
Invalid App ID	密钥错或区域与账号不匹配	核对控制台凭证
连接超时	网关与 region 不一致	国内用 China + lechange.cn 域
按钮不可用	设备离线或无 PTZ	查能力集
动检自动化不触发	仅 Core 无 motion sensor	加回调或 HACS 组件
配额飙涨	重复集成 + 多路 HD	合并实例，减直播路数

4.4 安全

• appSecret 仅 HA 主机本地 + secrets.yaml。
• 回调日志里的设备序列号、告警类型做脱敏。
• 自动化推手机前与家人确认监控范围。

---

五、小结

家庭摄像头进 Home Assistant，2026.6 之后优先试 Core 内置集成：配置流里填 App ID / Secret，国内账号 Server region 选 China，底层走 openapi.lechange.cn 区域节点——这一步错了，后面全是空列表。

我的最短路径已经固定成：

开发者平台注册 → 设备进资产池 → listDeviceDetailsByPage 验收
→ HA 添加 imou（region=China）→ camera 出画 → 自动化 / 回调

LAN 看直播、云端做管控，两条路可以并存。先跑通一个 camera 实体，比囤十个插件更有用。

以上为个人实践记录；集成字段与 API 参数以 Home Assistant 官方集成文档 及所接入平台的现行在线文档为准。