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["添加集成 imou<br/>region=China"] CAM["camera.live_view_sd / hd"] BTN["button.ptz_* / restart"] end subgraph Cloud["国内 API 网关"] API["openapi.lechange.cn"] end DEV --> BIND --> LDP LDP --> CFG CFG --> API API --> CAM API --> BTN

边界：

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

三、国内路径一步步走

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

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

javascript 复制代码

// 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（国内验收示例）：

bash 复制代码

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 分钟）

text 复制代码

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

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

yaml 复制代码

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

Step 2 · HA Core 集成配置

text 复制代码

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

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

yaml 复制代码

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

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

text 复制代码

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.：

yaml 复制代码

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

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

text 复制代码

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

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

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

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

yaml 复制代码

# 语音「看门口」--- 验证 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 配额双倍消耗。

yaml 复制代码

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：

javascript 复制代码

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

yaml 复制代码

# 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

text 复制代码

□ 开发者应用已创建，设备在开发者主账号资产池
□ 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 多路直播越多，消耗越快。

text 复制代码

建议：
· 测试/生产勿重复添加同一 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 区域节点------这一步错了，后面全是空列表。

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

text 复制代码

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

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

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

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