# Home Assistant OS 加载项部署

Home Assistant OS 或 HA Supervised 用户,通过加载项(Add-on)方式一键装云瞰。云瞰提供两个加载项:`yunkan`(CPU 通用版)和 `yunkan-openvino`(Intel iGPU 加速版)。

## 1. 适用范围

> **⚠️ 仅 amd64 架构**
>
> 云瞰加载项目前只发布 amd64 镜像。**Raspberry Pi(armv7/aarch64)/ HA Green / HA Yellow 等 ARM 主机不支持**。Intel NUC / 小主机 / x86 PC 装 HA OS 才能用。

| 加载项 | 适用硬件 | 推理速度 |
| --- | --- | --- |
| **yunkan** | 任何 amd64 HA OS 主机 | 纯 CPU |
| **yunkan-openvino** | Intel CPU + 核显(11 代+ Iris Xe / N100 / N305) | iGPU 加速,推荐 |

> **ℹ️ 只能装一个**
>
> 两个加载项端口完全相同(都是 23406/23880/24214/24215/23515),**不能同时启用**。Intel 机型选 yunkan-openvino,其它选 yunkan。

## 2. 添加云瞰仓库

**推荐方式:一键跳转。** 在能访问 HA 的设备上打开本页,点下方徽章,`my.home-assistant.io` 会自动找到你的 HA 并预填仓库地址,确认即可。

[![添加到 Home Assistant](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fmrtian2016%2Fyunkan-hassio-addons)

首次点击会要求填入你的 HA 地址(如 `http://homeassistant.local:8123`),后续会记住。如果跳转失败或没装 My Home Assistant 组件,使用下方手动方式。

**手动方式:**

1. **进入加载项商店**

   HA 网页 → 设置(Settings) → 加载项(Add-ons) → 加载项商店(Add-on Store)

2. **添加自定义仓库**

   右上角三点菜单 → 仓库(Repositories) → 粘贴下方 URL → 添加(Add)

3. **粘贴这个 URL**

   下面整段地址,直接复制粘贴:

```text
https://github.com/mrtian2016/yunkan-hassio-addons
```

添加后页面会刷新,加载项商店底部会多出 "Yunkan" 一栏,里面有 `yunkan` 和 `yunkan-openvino` 两个卡片。

## 3. 安装并启动

1. **选变体**

   Intel 机型点 `yunkan-openvino`,其它点 `yunkan`

2. **安装**

   右下角 "安装(Install)" 按钮,等下载完成(镜像 ~700MB,首次几分钟)

3. **配置(可选)**

   "配置(Configuration)" 标签页:默认设置即可工作;有特殊需求(自定义端口、时区)在这调

4. **启动**

   "信息(Info)" 标签页 → "启动(Start)" 按钮

5. **开启自启动 + Watchdog**

   下方两个开关都打开:"启动时启动" + "Watchdog";确保 HA 主机重启或加载项崩溃自动拉起

6. **打开网页**

   侧边栏会出现 "云瞰" 入口(或访问 `http://<HA 主机IP>:23406/`)进入 [Setup 向导](/docs/quickstart)

## 4. 数据持久化

加载项数据自动放到 HA 的 `/share/yunkan/` 目录(录像、数据库、模型、115 cookies 都在这)。这个目录:

- **HA OS 备份会带上** — Supervisor → Backups 做整机备份会包含 `/share/`,云瞰数据跟着走
- **外部 SMB 可访问** — HA 默认 Samba 加载项映射 `/share/`,可以从电脑/NAS 浏览录像文件
- **升级不会丢** — 加载项升级只换镜像,/share 持久化数据保留

## 5. 升级

云瞰加载项走 HA 加载项标准升级流程:HA 检测到新版本会通知(右下角 + 设置 → 加载项 → 当前加载项 → 上方黄色横条),点 "更新" 即可。不需要也不要装 yunkan-updater sidecar。

## 6. 常见问题

> **ℹ️ 我的是 Raspberry Pi 装的 HA,怎么办?**
>
> RPi 是 ARM 架构,云瞰加载项目前不支持。买个二手 Intel mini PC(N100 / 11 代 NUC 等)装 HA OS 是常见解。或者只装 HA OS 在 RPi,云瞰单独装在另一台 x86 机器上,两端通过 [MQTT 桥接](/docs/automation#home-assistant-%E6%A1%A5%E6%8E%A5)联动。

> **ℹ️ iGPU 加速没生效(yunkan-openvino 变体)**
>
> 加载项 config 已写好 `devices: [/dev/dri:/dev/dri:rwm]`,理论上自动透传。失败原因常见:host 没核显(查 HA Supervisor → Host system → CPU 是不是 Intel)、HA OS 内核不支持机型 iGPU。回退到 yunkan(CPU)变体仍可工作。

> **⚠️ 切变体不要直接覆盖装**
>
> 想从 yunkan 切到 yunkan-openvino(反之亦然):先卸载旧的(数据保留在 /share/yunkan/) → 装新的 → 启动后会复用 /share 里的旧数据,无需重新设置。同时启用两个会端口冲突。

---

来源:https://yun-kan.com/ja/docs/install-ha-addon