Home Assistant 集成（HACS）

云瞰现已提供官方 Home Assistant 自定义集成。它是一个薄客户端，通过云瞰服务器常规 API 通信，把服务器能力映射成 Home Assistant 原生实体、媒体浏览器和服务——所有录制、检测和账号逻辑都留在服务器端。

以自定义仓库方式在你的 Home Assistant HACS 里打开本仓库。

你能得到什么

• 摄像头：原生 WebRTC（低延迟，HLS 兜底）+ JPEG 快照——画面预览卡、区域仪表盘、导出 HomeKit、camera.snapshot。
• 检测传感器（每相机）：人、车、动物、包裹、人脸、跌倒、婴儿哭声、移动——并带上识别到的姓名 / 车牌。
• 对象计数传感器 + 识别人名 / 车牌传感器。
• 开关：AI 检测、录像、逐特性检测开关、PTZ 自动追踪——外加挂在 hub 上的服务器级检测开关。
• 设备页控件：刷新快照与 PTZ 方向按钮、PTZ 预置位下拉、喊话输入框。
• 设备触发器与动作用于自动化，另附开箱即用的通知蓝图。
• 媒体浏览器浏览录像、事件与快照，全程经 Home Assistant 自身鉴权代理。

前置要求

• Home Assistant 2024.11 或更新（原生 WebRTC 摄像头需要）。
• 一台可访问的云瞰服务器——填它的主入口地址（nginx 入口，通常端口 23406）。
• 一个云瞰账号。PTZ、检测开关和喊话需要 管理员 账号；查看用任意账号即可。

通过 HACS 安装

1. 1

   在 HACS 中打开

   点击上方 在 HACS 中打开 按钮（或在 HACS 里点右上角三点菜单 → 自定义仓库，填入仓库地址，类别选 *Integration*）。

2. 2

   安装并重启

   在 HACS 里搜索 Yunkan 安装，然后重启 Home Assistant。

3. 3

   添加集成

   进入 设置 → 设备与服务 → 添加集成 → Yunkan，填入服务器地址。接下来 Home Assistant 会打开云瞰的登录页，用你平时的方式登录后点「授权」，下一节有详细说明。

连接方式：跳到云瞰点一下授权

新版集成不再问你要密码。添加集成时只填云瞰服务器地址，Home Assistant 会打开云瞰的登录页，你用平时的方式登录（密码、验证码、通行密钥、单点登录都行），确认无误后点「授权」。云瞰把一枚专用令牌交给 Home Assistant，密码始终留在你自己这边。

• 开着二次验证的账号照样能连 —— 登录那一步是在云瞰自己的页面上完成的，验证码输在那里。
• 随时可以断开 —— 平台配置 → API Token 里能看到这枚令牌（名字带着 Home Assistant），删掉它，集成立刻失去访问权限。想恢复就在 Home Assistant 里重新走一遍授权。
• 较旧的云瞰服务器没有授权页 —— 集成会自动退回到填用户名和密码，和以前一样。这种方式连不上开着二次验证的账号，先把服务器升级到新版。

免费档 vs Pro

摄像头、快照、事件、传感器、媒体浏览器和 PTZ 在任意云瞰服务器上都能用。AI 检测 和 喊话 是 Pro 功能；免费档下这些操作会弹升级提示，而不是静默失败。