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 功能；免費版下這些操作會彈升級提示，而不是靜默失敗。